Runtime Builtins

The following procedures are available in the Gerbil runtime, in addition to all core Scheme and Gambit primitives.

MOP

See the Guide for an introduction to Gerbil's object system. These procedures provide the meta-object protocol.

make-object

(make-object class fields) -> object

  class  := type-descriptor; the class of the constructed object
  fields := the number of fields in the object

Creates an object with class class and fields fields.

object?

(object? obj) -> boolean

  obj := any object

Returns true if obj is an object instance.

object-type

(object-type obj) -> type

  obj := any object

Returns the class of an object; obj must be an object instance.

type-descriptor?

(type-descriptor? obj) -> boolean

  obj := any object

:::

Returns true if obj is a runtime type descriptor.

struct-type?

(struct-type? obj) -> boolean

  obj := any object

:::

Returns true if obj is a struct type descriptor.

class-type?

(class-type? obj) -> boolean

  obj := any object

Returns true if obj is a class type descriptor.

struct-subtype?

(struct-subtype? a b) -> boolean

  a, b := type-descriptor

Returns true if b is a struct subtype of a; a and b must be type descriptors.

This procedures checks the inheritance chain of b; b is a struct subtype of a if it is included in b's inheritance chain.

class-subtype?

(class-subtype? a b) -> boolean

  a, b := type-descriptor

Returns true if b is a class subtype of a; a and b must be type descriptors.

This procedures checks the linearized mixin list of b; b is a class subtype of a if it is included in b's mixins.

direct-instance?

(direct-instance? klass obj) -> boolean

  klass := type-descriptor

Returns true if obj is an immediate instance of klass.

struct-instance?

(struct-instance? klass obj) -> boolean

  klass := type-descriptor
  obj   := any object

Returns true if obj is a struct instance of klass.

This procedures checks the inheritance chain of obj's type; obj is a struct instance of klass if it is an object and its type is includes klass in its inheritance chain.

direct-struct-instance?

(direct-struct-instance? klass obj) -> boolean

  klass := type-descriptor
  obj   := any object

Same as (direct-instance? klass obj).

class-instance?

(class-instance? klass obj) -> boolean

  klass := type-descriptor
  obj   := any object

Returns true if obj is a class instance of klass.

This procedures checks the linearized mixin list of obj's type; obj is a class instance of klass if it is an object and its type is includes klass in its mixin list.

direct-class-instance?

(direct-class-instance? klass obj) -> boolean

  klass := type-descriptor
  obj   := any object

Same as (direct-instance? klass obj).

make-struct-type

(make-struct-type id super fields name plist ctor [field-names = #f]) -> type-descriptor

  id          := symbol; the type id
  super       := type-descriptor or #f; the struct type to inherit from
  fields      := fixnum; number of (new) fields in the type
  name        := symbol; the (displayed) type name
  plist       := alist; type properties
  ctor        := symbol or #f; id of constructor method
  field-names := list of symbols or #f; (displayed) field names

plist elements:
 (transparent: . boolean) ; controls whether the object is transparent
                            in equality and printing
 (final: . boolean)       ; controls whether the class if final
 (print: field ...)       ; printable field names
 (equal: field ...)       ; equality comparable field names

Creates a new struct type descriptor.

make-struct-predicate

(make-struct-predicate klass) -> procedure

  klass := type-descriptor

:::

Creates a struct instance predicate for instances of klass.

make-struct-field-accessor

(make-struct-field-accessor klass field) -> procedure

  klass := type-descriptor
  field := fixnum

Creates a klass instance accessor for field field (relative to super).

make-struct-field-mutator

(make-struct-field-mutator klass field) -> procedure

  klass := type-descriptor
  field := fixnum

Creates a klass instance mutator for field field (relative to super).

make-struct-field-unchecked-accessor

(make-struct-field-unchecked-accessor klass field) -> procedure

  klass := type-descriptor
  field := fixnum

Like make-struct-field-accessor, but the accessor is unchecked.

make-struct-field-unchecked-mutator

(make-struct-field-unchecked-mutator klass field) -> procedure

  klass := type-descriptor
  field := fixnum

Like make-struct-field-mutator, but the mutator is unchecked.

make-struct-instance

(make-struct-instance klass . args) -> object

  klass := type-descriptor
  args  := rest of arguments

Creates a new instance of klass. If there is a constructor method, it will be invoked with args on a freshly allocated object. Otherwise, the object is initialized with args, which must have the same length as the struct has fields.

struct-instance-init!

(struct-instance-init! obj . args)

  obj  := any object
  args := rest of arguments

Initializes obj by setting its fields to args from left to right. If there are more fields than arguments, then they are left uninitialized. It is an error if there are more arguments than fields in the object.

struct-field-offset

(struct-field-offset klass field) -> fixnum

  klass := type-descriptor
  field := fixnum

Returns the absolute field offset for klass's field field.

struct-field-ref

(struct-field-ref klass obj off) -> any

  klass := type-descriptor
  obj   := instance of klass
  off   := fixnum; absolute field offset

:::

Accesses obj's field with absolute offset off; obj is checked to be an instance of klass.

struct-field-set!

(struct-field-set! klass obj off val) -> void

  klass := type-descriptor
  obj := instance of klass
  off := fixnum; absolute field offset
  val := any

Mutates obj's field with absolute offset off to val; obj is checked to be an instance of klass.

unchecked-field-ref

(unchecked-field-ref obj off) -> any

  obj := instance of klass
  off := fixnum; absolute field offset

Accesses obj's field with absolute offset off; there is no type check.

unchecked-field-set!

(unchecked-field-set! obj off val) -> void

Mutates obj's field with absolute offset off to val; there is no type check.

struct->list

(struct->list obj) -> list

  obj := any object

Converts obj to a list, which conses its type and to its fields.

make-class-type

(make-class-type id super slots name plist ctor) -> type-descriptor

  id     := symbol; the type id
  super  := list of type-descriptors or #f; super types
  slots  := list of symbols; class slot names
  plist  := alist; type properties
  ctor   := symbol or #f; id of constructor method

plist elements:
 (transparent: . boolean) ; controls whether the object is transparent
                            in equality and printing
 (final: . boolean)       ; controls whether the class if final
 (print: slot ...)        ; printable slots
 (equal: slot ...)        ; equality comparable slots

Creates a new class type descriptor.

make-class-predicate

(make-class-predicate klass) -> procedure

  klass := type-descriptor

Creates a class instance predicate for instances of klass.

make-class-slot-accessor

(make-class-slot-accessor klass slot) -> procedure

  klass := type-descriptor
  slot  := symbol

Creates a slot accessor for slot.

make-class-slot-mutator

(make-class-slot-mutator klass slot) -> procedure

  klass := type-descriptor
  slot  := symbol

Creates a slot mutator for slot.

make-class-slot-unchecked-accessor

(make-class-slot-unchecked-accessor klass slot) -> procedure

  klass := type-descriptor
  slot  := symbol

Like make-class-slot-accessor, but creates an unchecked accessor.

make-class-slot-unchecked-mutator

(make-class-slot-unchecked-mutator klass slot) -> procedure

  klass := type-descriptor
  slot  := symbol

Like make-class-slot-mutator, but creates an unchecked mutator.

make-class-instance

(make-class-instance klass . args) -> object

  klass := type-descriptor
  args  := rest of arguments

class-instance-init!

(class-instance-init! obj . args)

  obj  := any object
  args := rest of arguments

Initializes obj, using args as a plist of slot keywords/symbols and values. For every slot and value in the plist, the corresponding object slot is set to the value.

class-slot-offset

(class-slot-offset klass slot) -> fixnum

  klass := type-descriptor
  slot  := symbol or keyword

Returns the absolute field offset for slot in instances of klass.

class-slot-ref

(class-slot-ref klass obj slot) -> any

  klass := type-descriptor
  obj   := instance of klass
  slot  := symbol or keyword

Checks that obj is a class instance of klass and returns the value in slot slot.

class-slot-set!

(class-slot-set! klass obj slot val) -> void

  klass := type-descriptor
  obj   := instance of klass
  slot  := symbol or keyword
  val   := any

Checks that obj is a class instance of klass and sets the value in the slot slot to val.

slot-ref

(slot-ref obj slot [E = slot-error]) -> any

  obj  := object
  slot := symbol or keyword
  E    := procedure

Returns the value associated with slot slot in obj. If the object has no such slot, then E is invoked in tail position as (E obj slot). By default, this raises an error.

slot-set!

(slot-set! obj slot val [E = slot-error]) -> void

  obj  := object
  slot := symbol or keyword
  val  := any
  E    := procedure;

Sets the value associated with slot slot in obj to val. If the object has no such slot, then E is invoked in tail position as (E obj slot). By default, this raises an error.

unchecked-slot-ref

(unchecked-slot-ref obj slot) -> any

  obj  := object
  slot := symbol or keyword

Returns the value associated with slot slot in obj, without any checks.

unchecked-slot-set!

(unchecked-slot-set! obj slot val) -> void

  obj  := object
  slot := symbol or keyword
  val  := any

Sets the value associated with slot slot in obj to val, without any checks.

class->list

(class->list obj)

  obj := any object

Converts obj to a list, which conses its type and to a plist of slot keywords and values.

bind-method!

(bind-method! klass id proc [rebind? = #t]) -> void

  klass   := type-descriptor or builtin record descriptor
  id      := symbol; method id
  proc    := procedure; method implementation
  rebind? := boolean; allow method rebinding?

Binds proc as the method with id in class klass.

call-method

(call-method obj id . args) -> any

  obj  := any object
  id   := symbol; method id
  args := rest of arguments

Applies the method with id in obj to args, with the object itself as the first argument. Raises an error if the object has no such method bound.

find-method

(find-method klass id) -> procedure | #f

  klass := type-descriptor or builtin record descriptor
  id    := symbol; method id

Looks up the method with id in klass class. Returns the procedure implementing the method or #f if the method is not bound in the class hierarchy.

call-next-method

(call-next-method klass obj id . args) -> any

  klass := type-descriptor or builtin record descriptor
  obj   := object
  id    := symbol; method id

Invokes the next method in obj's hierarchy, following klass.

next-method

(next-method klass obj id) -> procedure | #f

  klass := type-descriptor or builtin record descriptor
  obj   := object
  id    := symbol; method id

Returns the next method in obj's hierarchy, following klass.

method-ref

(method-ref obj id) -> procedure | #f
  obj := object
  id  := symbol; method id

Looks up the method with id in obj's hierarchy.

bound-method-ref

(bound-method-ref obj id) -> procedure | #f

  obj := object
  id  := symbol; method id

Looks up the method with id in obj's hierarchy and returns a procedure which applies the method currying the object.

checked-method-ref

(checked-method-ref obj id) -> procedure | #f
  obj := object
  id  := symbol; method id

Like method-ref, but raises an error if the method is not found.

checked-bound-method-ref

(checked-bound-method-ref obj id) -> procedure | #f

  obj := object
  id  := symbol; method id

Like bound-method-ref, but raises an error if the method is not found.

direct-method-ref

(direct-method-ref klass id) -> procedure | #f

  klass := type-descriptor
  id    := symbol; method id

Returns the binding of method with id in class klass.

seal-class!

(seal-class! klass) -> unspecified

  klass := type-descriptor

Seals a class, which must be final. Sealing a class specializes and coalesces all methods in the hierarchy to the class' method table.

bind-specializer!

(bind-specializer! method specializer) -> unspecified

  method      := procedure implementing a method
  specializer := procedure of one argument that returns the specialized method

Binds a specializer procedure associated with a method. When a class is sealed, the specializer is invoked with the concrete class to generate a version of the method that is specialized for the concrete class.

Special Objects

absent-obj

(def absent-obj)

Special object used by Gambit primitives to signal absent optional values.

absent-value

(def absent-value)

Special object used to denote missing hash values.

true

(true . args) -> #t

Returns #t, ignoring its arguments.

true?

(true? obj) -> boolean

  obj := any object

:::

Returns true if the object is #t.

false

(false . args) -> #f

Returns #f, ignoring its arguments.

void

(void . args) -> #!void

Returns #!void, ignoring its arguments

void?

(void? obj) -> boolean

Returns true if the object obj is #!void.

eof-object

(eof-object . args)

Returns the eof object, ignoring its arguments.

identity

(identity x) -> x

  x := any value

The identity function, eg. returns anything passed to it.

dssl-object?

(dssl-object? obj) -> boolean

  obj := any object

Returns true if the object is a DSSL syntactic token.

dssl-key-object?

(dssl-key-object? obj) -> boolean

  obj := any object

Returns true if the object is #!key.

dssl-rest-object?

(dssl-rest-object? obj) -> boolean

  obj := any object

Returns true if the object is #!rest.

dssl-optional-object?

(dssl-optional-object? obj) -> boolean

  obj := any object

Returns true if the object is #!optional.

immediate?

(immediate? obj) -> boolean

  obj := any object

Returns true if the object obj is an immediate value.

Hash Tables

make-hash-table

(make-hash-table . options) -> hash table

options:
    size: size
    init: init
    weak-keys: weak-keys?
    weak-values: weak-values?
    test: test
    hash: hash
    min-load: min-load
    max-load: max-load

Creates a hash table.

make-hash-table-eq

(make-hash-table-eq . options) -> hash table

Creates a hash table using eq? as the test function so this is equivalent to (make-hash-table test: eq? options ...).

make-hash-table-eqv

(make-hash-table-eqv . options) -> hash table

Creates a hash table using eqv? as the test function so this is equivalent to (make-hash-table test: eqv? options ...).

hash?

(hash? obj) -> boolean

  obj := any object

Returns true if the object is a hash table.

hash-table?

(hash-table? obj) -> boolean

  obj := any object

Same as hash?.

hash-length

(hash-length hash) -> fixnum

  hash := hash table

Returns the number of entries in the hash.

hash-ref

(hash-ref hash key [default]) -> any

  hash := hash table
  key  := any

Returns the value bound to key, defaulting to default if no value was bound. If the default is absent, then if an init parameter was specified in the table constructor it is returned instead. If no init parameter was specified, then an error is raised.

hash-get

(hash-get hash key) -> any

  hash := hash table
  key  := any

Returns the value bound to key or #f if no value was bound. This is equivalent to (hash-ref hash key #f).

hash-put!

(hash-put! hash key val) -> void

  hash := hash table
  key  := any
  val  := val

Binds key to val in hash.

hash-update!

(hash-update! hash key update [default = #!void]) -> void

  hash := hash table
  key  := any
  update: = procedure of one argument

Updates hash's binding for key to the result of (update (hash-ref hash key default))

hash-remove!

(hash-remove! hash key) -> void

  hash := hash table
  key  := any

Removes hash's binding for key.

hash-clear!

(hash-clear! hash [size = 0]) -> void

  hash := hash table
  size := fixnum; the new initial size for the hash table or 0 for default

Clears the hash table.

hash-key?

(hash-key? hash key) -> boolean

  hash := hash table
  key  := any

Returns true if hash has a binding for key.

hash-for-each

(hash-for-each proc hash) -> void

  proc := procedure of two arguments
  hash := hash table

Applies proc to all key/value bindings in hash.

hash-map

(hash-map proc hash) -> list

  proc := procedure of two arguments
  hash := hash table

Maps the bindings of hash to a list, applying proc.

hash-fold

(hash-fold proc iv hash) -> any

  proc := procedure of three arguments
  iv   := any; initial value
  hash := hash table

Fold the bindings of hash, applying proc with initial iv.

hash-find

(hash-find proc hash) -> any

  proc := procedure of two arguments
  hash := hash table

Returns the first true value returned when applying proc to the bindings of hash or #f.

hash-keys

(hash-keys hash) -> list

  hash := hash table

Returns the list of keys for all bindings in hash.

hash-values

(hash-values hash) -> list

  hash := hash table

Returns the list of values for all bindings in hash.

hash-copy

(hash-copy hash) -> hash table

  hash := hash table

Copies hash into a new hash table

hash-merge

(hash-merge hash . more) -> hash table

  hash := hash table
  more := list of hash tables

Creates a new hash table, merging more hash tables into hash. Entries in hash tables on the left take precedence over entries on the right.

> (define t1 (list->hash-table '((a . 1) (b . 2) (c . 3))))
> (define t2 (list->hash-table '((a . 4) (b . 5) (z . 6))))
> (hash->list (hash-merge t1 t2))
((a . 1) (z . 6) (b . 2) (c . 3))

hash-merge!

(hash-merge! hash . more) -> hash table

  hash := hash table
  more := list of hash tables

:::

Merges more hash tables into hash. Entries in hash tables on the left take precedence over entries on the right.

> (define t1 (list->hash-table '((a . 1) (b . 2) (c . 3))))
> (define t2 (list->hash-table '((a . 4) (b . 5) (z . 6))))
> (begin (hash-merge! t1 t2) (hash->list t1))
((a . 1) (z . 6) (b . 2) (c . 3))

hash->list

(hash->list hash) -> list

  hash := hash table

Returns the bindings of hash as an alist.

list->hash-table

(list->hash-table lst . options) -> hash table

  lst := alist; table bindings

Creates a hash table from an alist lst.

list->hash-table-eq

(list->hash-table-eq lst . options) -> hash table

  lst := alist; table bindings

Same as list->hash-table, but using eq? as the test function for the table.

list->hash-table-eqv

(list->hash-table-eqv lst . options) -> hash table

  lst := alist; table bindings

Same as list->hash-table, but using eqv? as the test function for the table.

hash->plist

(hash->plist hash) -> list

  hash := hash table

Returns the bindings of hash as a plist.

plist->hash-table

(plist->hash-table lst) -> hash table

  lst := plist; table bindings

Creates a hash table from a plist lst.

plist->hash-table-eq

(plist->hash-table-eq lst) -> hash table

  lst := plist; table bindings

Same as plist->hash-table, but using eq? as the test function for the table.

plist->hash-table-eqv

(plist->hash-table-eqv lst) -> hash table

  lst := plist; table bindings

Same as plist->hash-table, but using eqv? as the test function for the table.

Lists

make-list

(make-list len [val = #f]) -> list

  len := fixnum
  val := any value

Creates a new list of length len, with initial value of val.

cons*

(cons* x y ... tail) -> list

  x    := any
  y    := any
  tail := list

Conses x, y, ... to tail. This is equivalent to (cons x (cons y ... (cons ... tail))).

foldl

(foldl f iv . lsts) -> any

  f    := procedure
  iv   := any
  lsts := lists

Left fold.

foldr

(foldr f iv . lsts) -> any

  f    := procedure
  iv   := any
  lsts := lists

Right fold.

andmap

(andmap f . lsts) -> boolean

  f    := procedure
  lsts := lists

Boolean and fold.

ormap

(ormap f . lsts) -> any

  f    := procedure
  lsts := lists

Boolean or fold.

filter

(filter f lst) -> list

  f   := procedure
  lst := list

Returns a new list including only elements x for which (f x) is true.

filter-map

(filter-map f . lsts) -> list

  f     := procedure
  lsts := lists

Filter and map; returns a new list including the true results of (f x y ...), where x, y, ... are the elements of each list in lsts.

iota

(iota count [start = 0] [step = 1]) -> list

  count := fixnum; elements in the list
  start,step := number

Returns a list of count elements, iterating from start and adding step on each iteration.

last-pair

(last-pair obj) -> pair

  obj := pair or

Returns the last pair in the tail of obj; ie the tail pair of a (possibly improper) list.

last

(last obj) -> any

  obj := pair

Returns the car of the last pair of obj. This is equivalent to (car (last-pair obj)).

assgetq

(assgetq key alist [default = #f]) -> any

  key   := any
  alist := associative list

Returns the value associated with key in alist, using eq? for the key comparison. If the key is not found, then if default is a procedure it is applied on the key. Otherwise returns default.

assgetv

(assgetv key alist [default = #f]) -> any

  key   := any
  alist := associative list

Like assgetq, but uses eqv? for the key comparison.

assget

(assget key alist [default = #f]) -> any

  key   := any
  alist := associative list

Like assgetq, but uses equal? for the key comparison.

pgetq

(pgetq key plist [default = #f]) -> any

  key   := any
  plist := property list

Like assgetq, but for plists.

pgetv

(pgetv key plist [default = #f]) -> any

  key   := any
  plist := property list

Like assgetv, but for plists.

pget

(pget key plist [default = #f]) -> any

  key   := any
  plist := property list

Like assget, but for plists.

find

(find pred lst) -> any

  pred := procedure
  lst  := list

Returns the first element in lst that satisfies pred.

memf

(memf pred lst) -> pair | #f

  pred := procedure
  lst  := list

Generalization of member; returns the first pair in lst whose car satisfies pred.

remove1

(remove1 el lst) -> list

  el  := any
  lst := list

Returns lst removing the first element x that satisfies (equal? el x).

remv

(remv el lst) -> list

  el  := any
  lst := list

Apply remove1 using eqv? as the comparator.

remq

(remq el lst) -> list

  el  := any
  lst := list

Apply remove1 using eq? as the comparator.

remf

(remf pred lst) -> list

  pred := procedure
  lst  := list

Like remove1, but removes the first element x that satisfies (pred x)

Numerics

1+

(1+ num) -> number

  num := number

Increment num by 1.

1-

(1- num) -> number

  num := number

Decrement num by 1.

fx1+

(fx1+ num) -> fixnum

  num := fixnum

Increment a fixnum num by 1.

fx1-

(fx1- num) -> fixnum

  num := fixnum

Decrement a fixnum num by 1.

fxshift

(fxshift num shift) -> fixnum

  num   := fixnum
  shift := number

Shift a fixnum num arithmetically by shift; same as fxarithmetic-shift.

fx/

(fx/ x y) -> fixnum

  x, y := fixnum

Perform fixnum division on x and y; same as fxquotient.

nonnegative-fixnum?

(nonnegative-fixnum? obj) -> boolean

  obj := any object

Returns true if the object obj is a non-negative fixnum.

Symbols

make-symbol

(make-symbol . templates) -> symbol

template:
 string
 symbol
 keyword
 number

Creates a symbol concatenating the arguments.

interned-symbol?

(interned-symbol? obj) -> boolean

  obj := any object

Returns true if the object obj is an interned symbol.

interned-keyword?

(interned-keyword? obj) -> boolean

  obj := any object

Returns true if the object obj is an interned keyword.

symbol->keyword

(symbol->keyword sym) -> keyword

  sym := symbol

Converts a symbol sym to a keyword.

keyword->symbol

(keyword->symbol kw) -> symbol

  kw := keyword

Converts a keyword kw to a symbol

Strings

bytes->string

(bytes->string bstr [encoding = 'UTF-8]) -> string

  bstr := u8vector

Decodes a byte vector bstr to a string.

Note: if you are decoding UTF-8, then you should consider using string->utf8 from :std/text/utf8 which is considerably faster.

string->bytes

(string->bytes str [encoding = 'UTF-8]) -> u8vector

  str := string

Encodes a string str to a bytevector.

Note: if you are encoding UTF-8, then you should consider using utf8->string from :std/text/utf8 which is considerably faster.

substring->bytes

(substring->bytes str start end [encoding = 'UTF-8]) -> u8vector

  str := string
  start, end := fixnum

Encodes a substring str to a vector.

Note: if you are encoding UTF-8, then you should consider using utf8-encode from :std/text/utf8 which is considerably faster.

string-empty?

(string-empty? str) -> boolean

  str := string

Returns true if str is the empty string.

string-prefix?

(string-prefix? prefix str) -> boolean

  prefix, str := string

Returns true if prefix is a prefix of string.

string-index

(string-index str char [start = 0]) -> fixnum | #f

  str   := string
  char  := character
  start := fixnum

Returns the index of the first occurrence of char in str.

string-rindex

(string-rindex str char [start = #f]) -> fixnum | #f

  str   := string
  char  := character
  start := fixnum or #f

Returns the index of the first occurrence from the right of char in str.

string-split

(string-split str char) -> list

  str  := string
  char := character; separator

Splits str into substrings using char as the separator.

string-join

(string-join strs char) -> string

  str  := list of strings
  char := character; separator

Joins strs into a string, using char as the separator.

Control Flow

make-promise

(make-promise thunk) -> promise

  thunk := procedure taking no args

Creates a promise.

promise?

(promise? obj) -> boolean

  obj := any object

Returns true if the object obj is a promise.

call-with-parameters

(call-with-parameters thunk . parameterization) -> any

  thunk := procedure taking no args

parameterization:
 parameter value ...

Calls thunk with parameterization.

with-catch

(with-catch handler thunk) -> any

  handler, thunk := procedure

Calls thunk with handler as the exception catcher.

with-unwind-protect

(with-unwind-protect thunk fini) -> any

  thunk, fini := procedure

Calls thunk, invoking fini when execution exits the dynamic extent of thunk.

Exception Objects

exception::t

(def exception::t)

Base class for all Gerbil-derived exception types. It's an empty struct type that extends the Gambit builtin exception record type.

error::t

(def error::t)

Base class for all Gerbil-derived errors. It's a struct type that extends exception::t and has 3 fields: message, irritants, and trace.

exception?

(exception? obj) -> boolean

  obj := any object

Returns true if the object obj is an exception object. This includes the builtin Gambit exceptions.

error?

(error? obj) -> boolean

  obj := any object

Returns true if the object obj is an instance of error::t.

error-object?

(error-object? obj) -> boolean

  obj := any object

Returns true if the object obj is an exception object raised by the builtin error procedure. Note that this is separate from instances of error::t; nomenclature.

error-message

(error-message obj) -> string

  obj := any object

Returns the message associated with an error instance. If the object obj is not an error instance, it returns the result of (display-exception obj).

error-irritants

(error-irritants obj) -> list | #f

  obj := any object

Returns the irritants associated with an error instance. If the object obj is not an error instance, it returns #f.

error-trace

(error-trace obj) -> any

  obj := any object

Returns the trace associated with an error instance. If the object obj is not an error instance, it returns #f.

Miscellaneous Procedures

values-count

(values-count obj) -> fixnum

  obj := any object

Counts the values in the object obj. If the object is not multiple values, it is considered a single value.

values-ref

(values-ref obj n) -> any

  n := fixnum

Returns the nth value in the object obj. If the object is not multiple values, it returns the object itself.

values->list

(values->list obj) -> list

  obj := any object

Converts multiple values to a list. If the object obj is not multiple values, it returns a list containing the object.

subvector->list

(subvector->list obj [start = 0]) -> list

  obj   := any object
  start := number

Coverts a vector-like object obj to a list, starting from field start.

vector-map

(vector-map f . vectors) -> any

  f       := procedure
  vectors := list of vectors

Map for vectors. Traverses vector(s) vectors and applies procedure f to elements of each vector, stopping after shortest vector runs out of elements.

displayln

(displayln . args) -> void

  args := rest of arguments

Displays the arguments, followed by a newline.

display*

(display* . args) -> void

  args = rest of arguments

Displays the arguments args.

file-newer?

(file-newer? a b) -> boolean

  a, b := string

Returns true if file a is newer than b by modification-time. Both files must exist.

create-directory*

(create-directory* path [perms = #o755]) -> void

  path  := string
  perms := fixnum

Creates a directory pointed by path and its parents if they don't exist, like mkdir -p. Sets directory permissions to perms.

keyword-dispatch

(keyword-dispatch kwt proc . args) -> any

  kwt  := keyword
  proc := procedure
  args := rest of arguments

Dispatches a keyword lambda. You shouldn't invoke this directly.

load-module

(load-module modpath [reload = #f]) -> string

  modpath := string
  reload  := boolean

Loads a module modpath from the file system. If the module is already loaded, then it's only reloaded if reload is specified. Returns the path of the loaded module.

Syntax Objects

AST::t

(def AST::t)

Base class for syntax objects. It is a struct type with two fields, content and location.

make-AST

(make-AST e src) -> syntax-object

  e   := any
  src := location or #f

Creates a new syntax object.

AST?

(AST? obj) -> boolean

  obj := any object

Returns true if the object obj is a syntax object.

AST-e

(AST-e ast) -> any

  ast := syntax object

Returns the content of a syntax object ast.

AST-source

(AST-source ast) -> location | #f

  ast := syntax object

Returns the source location of a syntax object ast.

read-syntax

(read-syntax [port = (current-input-port)]) -> syntax object | eof

  port := input port

Reads the next syntax object from port.

read-syntax-from-file

(read-syntax-from-file path) -> list of syntax objects

  path := string

Reads the contents of a file pointed by path as syntax objects.

source-location?

(source-location? obj) -> boolean

  obj := any object

Returns true if the object obj is a source location.

source-location-path?

(source-location-path? obj) -> boolean

  obj := any object

Returns true if the object obj is a source location with a file path.

source-location-path

(source-location-path loc) -> string

  loc := source location with a path

Returns the source location path.

System Information

gerbil-system-version-string

(gerbil-system-version-string) -> string

The full Gerbil system version.

gerbil-system

(gerbil-system) -> symbol

Symbolic name of the gerbil system; this is defined as a cond-expand feature by the expander.

gerbil-runtime-smp?

(gerbil-runtime-smp?) -> boolean

Returns true if the SMP scheduler is detected at runtime.

gerbil-greeting

(def gerbil-greeting)

The greeting displayed by the interpreter at interactive load; a string.

Thread Primitives

The following primitives are defined in the :gerbil/gambit/threads prelude module.

To use the bindings from this module:

(import :gerbil/gambit/threads)

spawn

(spawn f . args) -> actor thread

  f := procedure

Spawns an actor thread, invoking (f . args).

Differences of actor threads and plain Gambit threads:

actor threads have an abortive exception handler that unwinds the stack on exceptional exits thus ensuring that unwind finalizers are run.
actor threads have an extra field for efficient access to thread locals.

spawn/name

(spawn/name name f . args) -> actor thread

  name := any
  f     := procedure

Like spawn, but the thread is named.

spawn/group

(spawn/group name f . args) -> actor thread

  name := any
  f     := procedure

Like spawn, but the thread is in a new thread group with name name.

spawn-actor

(spawn-actor f args name tgroup) -> actor thread

  f      := procedure
  args   := list; procedure arguments
  name   := any
  tgroup := thread-group

Spawns an actor thread.

spawn-thread

(spawn-thread thunk [name] [tgroup]) -> thread

  thunk := procedure
  name   := any
  tgroup := thread-group

Spawns a plain thread

actor-thread?

(actor-thread? obj) -> boolean

  obj := any object

Returns true if the object obj is an actor thread.

thread-local-ref

(thread-local-ref key [default]) -> any

  key, default := any

Retrieves the thread local value associated with key.

thread-local-get

(thread-local-get key) -> any

  key := any

Retrieves the thread local value associated with key, defaulting to #f.

thread-local-set!

(thread-local-set! key val) -> void

  key, val := any

Sets the thread local value associated with key to val.

thread-local-clear!

(thread-local-clear! key) -> void

  key := any

Clears the thread local value associated with key.

thread-local-table

(thread-local-table) -> hash table

Return the table of thread local values, creating it if it doesn't exist.

current-thread-group

(current-thread-group) -> thread-group

Returns the thread-group of the current thread.

with-lock

(with-lock mx thunk) -> any

  mx    := mutex
  thunk := procedure

Evaluates thunk in a dynamic extent where mx is locked.

unhandled-actor-exception-hook-set!

(unhandled-actor-exception-hook-set! proc) -> void

  proc := procedure

Hooks the actor exception handler to invoke (proc continuation exception) on uncaught exceptions occurring in actor threads.

dump-stack-trace!

(dump-stack-trace! cont exn [port = (current-error-port)]) -> void

  cont := continuation
  exn  := exception
  port := error port

Dumps a stack trace from an exception handler hook.

with-exception-stack-trace

(with-exception-stack-trace thunk [port = (current-error-port)]) -> any

  thunk := procedure

Evaluate thunk, with a handler that dumps a stack trace on uncaught exceptions.

← The Core Prelude Expander Runtime→

# Runtime Builtins

# MOP

# make-object

# object?

# object-type

# type-descriptor?

# struct-type?

# class-type?

# struct-subtype?

# class-subtype?

# direct-instance?

# struct-instance?

# direct-struct-instance?

# class-instance?

# direct-class-instance?

# make-struct-type

# make-struct-predicate

# make-struct-field-accessor

# make-struct-field-mutator

# make-struct-field-unchecked-accessor

# make-struct-field-unchecked-mutator

# make-struct-instance

# struct-instance-init!

# struct-field-offset

# struct-field-ref

# struct-field-set!

# unchecked-field-ref

# unchecked-field-set!

# struct->list

# make-class-type

# make-class-predicate

# make-class-slot-accessor

# make-class-slot-mutator

# make-class-slot-unchecked-accessor

# make-class-slot-unchecked-mutator

# make-class-instance

# class-instance-init!

# class-slot-offset

# class-slot-ref

# class-slot-set!

# slot-ref

# slot-set!

# unchecked-slot-ref

# unchecked-slot-set!

# class->list

# bind-method!

# call-method

# find-method

# call-next-method

# next-method

# method-ref

# bound-method-ref

# checked-method-ref

# checked-bound-method-ref

# direct-method-ref

# seal-class!

# bind-specializer!

# Special Objects

# absent-obj

# absent-value

# true

# true?

# false

# void

# void?

# eof-object

# identity

# dssl-object?

# dssl-key-object?

# dssl-rest-object?

# dssl-optional-object?

# immediate?

# Hash Tables

# make-hash-table

# make-hash-table-eq

# make-hash-table-eqv

# hash?

# hash-table?

# hash-length

# hash-ref