[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Library Functions


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Basic Constants and Predicates

Method on OBJECT: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on SECOND-CLASS-OBJECT: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on NATIVE-VECTOR: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on STRING: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on MUTABLE-STRING: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on CHARACTER: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on CODE: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on INTEGER: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on FLOAT: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on OBJECT: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on SECOND-CLASS-OBJECT: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on NATIVE-VECTOR: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on STRING: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on MUTABLE-STRING: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on CHARACTER: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on CODE: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on INTEGER: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on FLOAT: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Function: eq? ((x UNKNOWN) (y UNKNOWN)) : BOOLEAN

Return true if x and y are literally the same object (or simple number). Analogue to the Common Lisp EQL and C++ and Java’s ==.

Function: eql? ((x OBJECT) (y OBJECT)) : BOOLEAN

Return true if x and y are eq? or equivalent literals such as strings that also might be wrapped in non-identical wrappers. For the case where x or y are plain literals such as strings or integers, the STELLA translator substitutes the equality test appropriate for the particular target language and does not actually call this function. For cases where x or y are known to be of type STANDARD-OBJECT, the STELLA translator substitutes the faster eq? test inline.

Function: equal? ((x OBJECT) (y OBJECT)) : BOOLEAN

Return true if x and y are eql? or considered equal by a user-defined object-equal? method. This implements a fully extensible equality test similar to Java’s equals method. Note that writers of custom object-equal? methods must also implement a corresponding equal-hash-code method.

Method on OBJECT: object-equal? (x (y OBJECT)) : BOOLEAN

Return true if x and y are eq?.

Method on WRAPPER: object-equal? (x (y OBJECT)) : BOOLEAN

Return true if x and y are literal wrappers whose literals are considered eql?.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 Numbers

Constant: pi : FLOAT

A float approximation of the mathematical constant pi.

Function: + (&rest (arguments NUMBER)) : NUMBER

Return the sum of all arguments.

Function: - ((x NUMBER) &rest (arguments NUMBER)) : NUMBER

If only x was supplied return the result of 0 - x. Otherwise, return the result of (...((x - arg1) - arg2) - ... - argN).

Function: * (&rest (arguments NUMBER)) : NUMBER

Return the product of all arguments.

Function: / ((x NUMBER) &rest (arguments NUMBER)) : NUMBER

If only x was supplied return the result of 1 / x. Otherwise, return the result of (...((x / arg1) / arg2 ) / ... / argN).

Macro: 1+ ((expression OBJECT)) : OBJECT

Add 1 to expression and return the result.

Macro: 1- ((expression OBJECT)) : OBJECT

Subtract 1 from expression and return the result.

Macro: ++ ((place OBJECT) &body (increment CONS)) : OBJECT

Increment the value of place and return the result. place can be either a variable name or a slot reference. Increment by the optional increment (which can be a float) or 1 otherwise.

Macro: -- ((place OBJECT) &body (decrement CONS)) : OBJECT

Decrement the value of place and return the result. place can be either a variable name or a slot reference. Decrement by the optional decrement (which can be a float) or 1 otherwise.

Function: = ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x and y are numbers of exactly the same magnitude.

Function: < ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is less than y.

Function: <= ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is less than or equal to y.

Function: >= ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is greater than or equal to y.

Function: > ((x NUMBER) (y NUMBER)) : BOOLEAN

Return true if x is greater than y.

???: zero?

Not yet implemented.

???: plus?

Not yet implemented.

???: even?

Not yet implemented.

???: odd?

Not yet implemented.

???: div

Not yet implemented.

???: rem

Not yet implemented.

???: mod

Not yet implemented.

Function: gcd ((x LONG-INTEGER) (y LONG-INTEGER)) : LONG-INTEGER

Return the greatest common divisor of x and y.

Function: ceiling ((n NUMBER)) : INTEGER

Return the smallest integer >= n.

Function: floor ((n NUMBER)) : INTEGER

Return the biggest integer <= n.

Function: round ((n NUMBER)) : INTEGER

Round n to the closest integer and return the result.

Method on INTEGER: abs (x) : INTEGER

Return the absolute value of x.

Method on FLOAT: abs (x) : FLOAT

Return the absolute value of x.

???: min

Not yet implemented.

???: max

Not yet implemented.

Function: sqrt ((n FLOAT)) : FLOAT

Return the square root of n.

Function: exp ((n FLOAT)) : FLOAT

Return the e to the power n.

Function: expt ((x FLOAT) (y FLOAT)) : FLOAT

Return x ^ y.

Function: log ((n FLOAT)) : FLOAT

Return the natural logarithm (base e) of n.

Function: log10 ((n FLOAT)) : FLOAT

Return the logarithm (base 10) of n.

Function: sin ((n FLOAT)) : FLOAT

Return the sine of n radians.

Function: cos ((n FLOAT)) : FLOAT

Return the cosine of n radians.

Function: tan ((n FLOAT)) : FLOAT

Return the tangent of n radians.

Function: asin ((n FLOAT)) : FLOAT

Return the arcsine of n in radians.

Function: acos ((n FLOAT)) : FLOAT

Return the arccosine of n in radians.

Function: atan ((n FLOAT)) : FLOAT

Return the arc tangent of n in radians.

Function: atan2 ((x FLOAT) (y FLOAT)) : FLOAT

Return the arc tangent of x / y in radians.

Function: random ((n INTEGER)) : INTEGER

Generate a random integer in the interval [0..n-1]. The random number generator is seeded based on the current time every time STELLA starts up; however, your mileage may vary depending on the native language implementation.

Function: integer-to-string ((i LONG-INTEGER)) : STRING

Convert i to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : LONG-INTEGER

Convert a string representation of an integer into an integer. Use parse-long-integer if the syntax of string needs to be checked for errors.

Function: float-to-string ((f FLOAT)) : STRING

Convert f to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-float ((string STRING)) : FLOAT

Convert a string representation of a float into a float. Use parse-float if the syntax of string needs to be checked for errors.

Function: format-float ((f FLOAT) (nDecimals INTEGER)) : STRING

Print f in fixed-point format with nDecimals behind the decimal point and return the result as a string.

Function: wrap-integer ((value INTEGER)) : INTEGER-WRAPPER

Return a literal object whose value is the INTEGER value.

Function: unwrap-integer ((wrapper INTEGER-WRAPPER)) : INTEGER

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: wrap-float ((value FLOAT)) : FLOAT-WRAPPER

Return a literal object whose value is the FLOAT value.

Function: unwrap-float ((wrapper FLOAT-WRAPPER)) : FLOAT

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 Characters

Function: character-code ((ch CHARACTER)) : INTEGER

Return the 8-bit ASCII code of ch as an integer.

Function: code-character ((code INTEGER)) : CHARACTER

Return the character encoded by code (0 <= code <= 255).

Function: digit-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a digit.

Function: letter-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a letter.

Function: upper-case-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents an upper-case character.

Function: lower-case-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch represents a lower-case character.

Function: white-space-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch is a white space character.

Function: character-downcase ((ch CHARACTER)) : CHARACTER

If ch is lowercase, return its uppercase version, otherwise, return ch unmodified.

Function: character-upcase ((ch CHARACTER)) : CHARACTER

If ch is uppercase, return its lowercase version, otherwise, return ch unmodified. If only the first character of a sequence of characters is to be capitalized, character-capitalize should be used instead.

Function: character-capitalize ((ch CHARACTER)) : CHARACTER

Return the capitalized character for ch. This is generally the same as the uppercase character, except for obscure non-English characters in Java. It should be used if only the first character of a sequence of characters is to be capitalized.

Function: character-to-string ((c CHARACTER)) : STRING

Convert c into a one-element string and return the result.

Function: wrap-character ((value CHARACTER)) : CHARACTER-WRAPPER

Return a literal object whose value is the CHARACTER value.

Function: unwrap-character ((wrapper CHARACTER-WRAPPER)) : CHARACTER

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.4 Strings

Function: string-eql? ((x STRING) (y STRING)) : BOOLEAN

Return true if x and y are equal strings or are both undefined. This test is substituted automatically by the STELLA translator if eql? is applied to strings.

Function: string-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x and y are equal strings ignoring character case or are both undefined.

Method on STRING: empty? (x) : BOOLEAN

Return true if x is the empty string ""

Method on STRING: non-empty? (x) : BOOLEAN

Return true if x is not the empty string ""

Function: string-compare ((x STRING) (y STRING) (case-sensitive? BOOLEAN)) : INTEGER

Compare x and y lexicographically, and return -1, 0, or 1, depending on whether x is less than, equal, or greater than y. If case-sensitive? is true, then case does matter for the comparison

Function: string< ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically < y, considering case.

Function: string<= ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically <= y, considering case.

Function: string>= ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically >= y, considering case.

Function: string> ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically > y, considering case.

Function: string-less? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically < y, ignoring case.

Function: string-less-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically <= y, ignoring case.

Function: string-greater-equal? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically >= y, ignoring case.

Function: string-greater? ((x STRING) (y STRING)) : BOOLEAN

Return true if x is lexicographically > y, ignoring case.

Function: all-upper-case-string? ((s STRING)) : BOOLEAN

Return TRUE if all letters in s are upper case.

Function: all-lower-case-string? ((s STRING)) : BOOLEAN

Return TRUE if all letters in s are lower case.

Function: make-string ((size INTEGER) (initchar CHARACTER)) : STRING

Return a new string filled with size initchars.

Function: make-mutable-string ((size INTEGER) (initchar CHARACTER)) : MUTABLE-STRING

Return a new mutable string filled with size initchars.

Function: make-raw-mutable-string ((size INTEGER)) : MUTABLE-STRING

Return a new uninitialized mutable string of size.

Method on STRING: first (self) : CHARACTER

Return the first character of self.

Method on MUTABLE-STRING: first (self) : CHARACTER

Return the first character of self (settable via setf).

Method on STRING: second (self) : CHARACTER

Return the second character of self.

Method on MUTABLE-STRING: second (self) : CHARACTER

Return the second character of self (settable via setf).

Method on STRING: third (self) : CHARACTER

Return the third character of self.

Method on MUTABLE-STRING: third (self) : CHARACTER

Return the third character of self (settable via setf).

Method on STRING: fourth (self) : CHARACTER

Return the fourth character of self.

Method on MUTABLE-STRING: fourth (self) : CHARACTER

Return the fourth character of self (settable via setf).

Method on STRING: fifth (self) : CHARACTER

Return the fifth character of self.

Method on MUTABLE-STRING: fifth (self) : CHARACTER

Return the fifth character of self (settable via setf).

Method on STRING: nth (self (position INTEGER)) : CHARACTER

Return the character in self at position.

Method on MUTABLE-STRING: nth (self (position INTEGER)) : CHARACTER

Return the character in self at position.

Method on STRING: rest (self) : STRING

Not documented.

Method on STRING: length (self) : INTEGER

Return the length of the string self.

Method on MUTABLE-STRING: length (self) : INTEGER

Return the length of the string self.

Method on STRING: member? (self (char CHARACTER)) : BOOLEAN

Not documented.

Method on STRING: position (string (character CHARACTER) (start INTEGER)) : INTEGER

Return the position of character within string (counting from zero); or return NULL if character does not occur within string. If start was supplied as non-NULL, only consider the substring starting at start, however, the returned position will always be relative to the entire string.

Method on STRING: last-position (string (character CHARACTER) (end INTEGER)) : INTEGER

Return the last position of character within string (counting from zero); or return NULL if character does not occur within string. If end was supplied as non-NULL, only consider the substring ending at end, however, the returned position will always be relative to the entire string.

Function: string-search ((string STRING) (substring STRING) (start INTEGER)) : INTEGER

Return start position of the left-most occurrence of substring in string, beginning from start. Return NULL if it is not a substring. The comparison is exact.

Method on STRING: copy (string) : STRING

Return a copy of string.

Function: string-upcase ((string STRING)) : STRING

Return an upper-case copy of string.

Function: string-downcase ((string STRING)) : STRING

Return a lower-case copy of string.

Function: string-capitalize ((string STRING)) : STRING

Return a capitalized version of string.

Method on STRING: concatenate (string1 (string2 STRING) &rest (otherStrings STRING)) : STRING

Return a new string representing the concatenation of string1, string2, and otherStrings. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method on STRING: subsequence (string (start INTEGER) (end INTEGER)) : STRING

Return a substring of string beginning at position start and ending up to but not including position end, counting from zero. An end value of NULL stands for the rest of the string.

Method on STRING: remove (string (char CHARACTER)) : STRING

Remove all occurences of char from string.

Method on STRING: substitute (self (new-char CHARACTER) (old-char CHARACTER)) : STRING

Substitute all occurences of old-char with new-char in the string self.

Method on MUTABLE-STRING: substitute (self (new-char CHARACTER) (old-char CHARACTER)) : MUTABLE-STRING

Substitute all occurences of old-char with new-char in the string self.

Function: replace-substrings ((string STRING) (new STRING) (old STRING)) : STRING

Replace all occurrences of old in string with new.

Function: instantiate-string-template ((template STRING) &rest (vars&values STRING)) : STRING

For each occurrence of a <var> string from vars&values in template replace it with its corresponding <value> string. Replacement is done in sequence which means (part of) a value might be replaced further with a later <var> and <value>.

Function: insert-string ((source STRING) (start INTEGER) (end INTEGER) (target MUTABLE-STRING) (target-index INTEGER) (case-conversion KEYWORD)) : INTEGER

Inserts characters from source begining at start and ending at end into target starting at target-index. If end is null, then the entire length of the string is used. The copy of characters is affected by the case-conversion keyword which should be one of :UPCASE :DOWNCASE :CAPITALIZE :PRESERVE.

The final value of target-index is returned.

Function: wrap-string ((value STRING)) : STRING-WRAPPER

Return a literal object whose value is the STRING value.

Function: wrap-mutable-string ((value MUTABLE-STRING)) : MUTABLE-STRING-WRAPPER

Return a literal object whose value is the MUTABLE-STRING value.

Function: unwrap-string ((wrapper STRING-WRAPPER)) : STRING

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: unwrap-mutable-string ((wrapper MUTABLE-STRING-WRAPPER)) : MUTABLE-STRING

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: string-to-mutable-string ((s STRING)) : MUTABLE-STRING

Copy s into a mutable string with the same content. In Lisp and C++ this simply copies s.

Function: mutable-string-to-string ((s MUTABLE-STRING)) : STRING

Convert s into a regular string with the same content. In Lisp and C++ this is a no-op.

Function: integer-to-string ((i LONG-INTEGER)) : STRING

Convert i to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : LONG-INTEGER

Convert a string representation of an integer into an integer. Use parse-long-integer if the syntax of string needs to be checked for errors.

Function: float-to-string ((f FLOAT)) : STRING

Convert f to its string representation and return the result. This is more efficient than using a string stream.

Function: string-to-float ((string STRING)) : FLOAT

Convert a string representation of a float into a float. Use parse-float if the syntax of string needs to be checked for errors.

Function: format-float ((f FLOAT) (nDecimals INTEGER)) : STRING

Print f in fixed-point format with nDecimals behind the decimal point and return the result as a string.

Function: character-to-string ((c CHARACTER)) : STRING

Convert c into a one-element string and return the result.

Function: stringify ((expression OBJECT)) : STRING

Print expression onto a string and return the result. Printing is done with *printReadably?* set to true and with *printPretty?* set to false.

Function: stringify-in-module ((tree OBJECT) (module MODULE)) : STRING

Stringify a parse tree relative to module, or *module* if no module is specified.

Function: unstringify ((string STRING)) : OBJECT

Read a STELLA expression from string and return the result. This is identical to read-s-expression-from-string.

Function: unstringify-in-module ((string STRING) (module MODULE)) : OBJECT

Unstringify relative to module, or *MODULE* if no module is specified.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.5 CONS Lists and Trees

Class: CONS : STANDARD-OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: value : (LIKE (ANY-VALUE SELF))

Not documented.

Slot: rest : (CONS OF (LIKE (ANY-VALUE SELF)))

Not documented.

Variable: nil : CONS

Not documented.

Method on CONS: empty? (self) : BOOLEAN

Return true iff self equals nil.

Method on CONS: non-empty? (self) : BOOLEAN

Return true iff self is not equal to nil.

Function: nil? ((x OBJECT)) : BOOLEAN

Return true iff x equals nil.

Function: equal-cons-trees? ((tree1 OBJECT) (tree2 OBJECT)) : BOOLEAN

Return true iff the cons trees tree1 and tree2 are structurally equivalent. Uses an eql? test.

Method on CONS: object-equal? (tree1 (tree2 OBJECT)) : BOOLEAN

Return true iff the cons trees tree1 and tree2 are structurally equivalent. Uses equal? to test equality of subtrees.

Method on CONS: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: cons ((value OBJECT) (rest CONS)) : CONS

Return a cons record that points to value and rest.

Method on CONS: first (self) : (LIKE (ANY-VALUE SELF))

Return the first element of self. The first element of self can be set with setf. Note that (first NIL) = null.

Method on CONS: second (self) : (LIKE (ANY-VALUE SELF))

Return the second element of self. The second element of self can be set with setf. Note that (second NIL) = null.

Method on CONS: third (self) : (LIKE (ANY-VALUE SELF))

Return the third element of self. The third element of self can be set with setf. Note that (third NIL) = null.

Method on CONS: fourth (self) : (LIKE (ANY-VALUE SELF))

Return the fourth element of self. The fourth element of self can be set with setf. Note that (fourth NIL) = null.

Method on CONS: fifth (self) : (LIKE (ANY-VALUE SELF))

Return the fifth element of self. The fifth element of self can be set with setf. Note, that (fifth NIL) = null.

Method on CONS: nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position. The nth element of self can be set with setf. Note, that (nth NIL <pos>) = null.

Method on CONS: nth-rest (self (position INTEGER)) : (LIKE SELF)

Apply rest position times to self.

Method on CONS: last (self) : (LIKE (ANY-VALUE SELF))

Return the last element of self.

Method on CONS: but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the cons list self.

Function: last-cons ((self CONS)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return the last cons of self.

Method on CONS: length (self) : INTEGER

Return the length of the CONS list self.

Method on CONS: member? (self (object OBJECT)) : BOOLEAN

Return true iff object is a member of the cons list self (uses an eql? test).

Method on CONS: memb? (self (object OBJECT)) : BOOLEAN

Return true iff object is a member of the cons list self (uses an eq? test).

Method on CONS: position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the cons-list self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-‘null’, only consider the sublist starting at start, however, the returned position will always be relative to the entire list.

Method on CONS: last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the cons-list self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-‘null’, only consider the sublist ending at end, however, the returned position will always be relative to the entire list.

Method on CONS: reverse (self) : (LIKE SELF)

Destructively reverse the members of the cons list self.

Method on CONS: remove (self (value OBJECT)) : (LIKE SELF)

Destructively remove all entries in the cons list self that match value. Unless the remaining list is nil, insure that the cons that heads the list is unchanged.

Method on CONS: remove-duplicates (self) : (LIKE SELF)

Destructively remove duplicates from self and return the result. Removes all but the first occurrence of items in the list. Preserves the original order of the remaining members. Runs in linear time.

Method on CONS: remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively removes all members of the cons list self for which test? evaluates to true. test takes a single argument of type OBJECT and returns true or false. Returns a cons list. In case the first element is removed, the return result should be assigned to a variable.

Method on CONS: substitute (self (inValue OBJECT) (outValue OBJECT)) : CONS

Destructively replace each appearance of outValue by inValue in the cons list self.

Method on CONS: concatenate (list1 (list2 CONS) &rest (otherLists CONS)) : CONS

Return a cons list consisting of the concatenation of list1, list2, and otherLists. The operation is destructive wrt all but the last list argument which is left intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Function: append ((consList1 CONS) (consList2 CONS)) : CONS

Return a cons list representing the concatenation of consList1 and consList2. The concatenation is NOT destructive.

Method on CONS: prepend (self (list1 CONS)) : CONS

Return a cons list consisting of the concatenation of list1 and self. A copy of list1 is prepended to self. This operation results in structure sharing of self; to avoid this, self should not be pointed to by anything other than the tail of the prepended copy.

Macro: pushq ((variable SYMBOL) (value OBJECT)) : OBJECT

Push value onto the cons list variable.

Macro: pushq-new ((variable SYMBOL) (value OBJECT)) : OBJECT

Push value onto the cons list variable, unless value is already a member of the list.

Macro: popq ((variable SYMBOL)) : OBJECT

Pops a value from the cons list variable.

Function: cons-list (&rest (values OBJECT)) : CONS

Return a cons list containing values, in order.

Function: list* (&rest (values OBJECT)) : CONS

Return a list of conses that make up the list values, terminated by the last value rather than by nil. Assumes that at least one value is passed in.

Function: copy-cons-list ((self CONS)) : (LIKE SELF)

Return a copy of the cons list self.

Function: copy-cons-tree ((self OBJECT)) : (LIKE SELF)

Return a copy of the cons tree self.

Function: substitute-cons-tree ((tree OBJECT) (newValue OBJECT) (oldValue OBJECT)) : OBJECT

Destructively replace each appearance of oldValue by newValue in the cons tree tree. Return the tree. Uses an eql? test.

Function: search-cons-tree? ((tree OBJECT) (value OBJECT)) : BOOLEAN

Return true iff the value value is embedded within the cons tree tree. Uses an eql? test.

Function: tree-size ((self OBJECT)) : INTEGER

Not documented.

Function: safe-tree-size ((tree CONS)) : INTEGER STRING

Not documented.

Function: cons-tree-nth ((tree CONS) &rest (index INTEGER)) : OBJECT

Access an arbitrary element of tree identified by a path specified as a list of index values. The first index specifies the index-th element of tree, the second index the index-th subelement of that element, etc. Example:

 
  (cons-tree-nth (quote (a (b (c d e) f) g)) 1 1 2) => e
Function: cons-tree-nth-rest ((tree CONS) &rest (index INTEGER)) : CONS

Access an arbitrary sublist of tree identified by a path specified as a list of index values. The first index specifies the index-th element of tree, the second index the index-th subelement of that element, ..., the last index specifies the nth-rest of the previous element (different from cons-tree-nth). Example:

 
  (cons-tree-nth-rest (quote (a (b (c d e) f) g)) 1 1 1) => (d e)
Function: match-cons-tree ((tree OBJECT) (pattern OBJECT) (bindings KEY-VALUE-LIST)) : KEY-VALUE-LIST

Match pattern against tree and return a list of variable bindings if they match, or NULL otherwise. bindings can be NULL or an initial list of bindings to consider. Pattern variables use KIF syntax, i.e., they need to start with a ? character. A single question mark is interpreted as the anonymous variable. Example:

 
  (match-cons-tree (quote (a (b (a d) e) (a d) f g))
                   (quote (a (?x ?y ?) ?y ? g))
                   NULL)
  => |kv|(<?Y,(A D)> <?X,B>)

Variables can’t be quoted but quoting can effectively be achieved by inserting to-be-quoted variables bound to themselves into bindings.

Function: cons-tree-match? ((tree OBJECT) (pattern OBJECT)) : BOOLEAN

Predicate version of match-cons-tree (which see).

Method on CONS: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return self.

Method on CONS: allocate-iterator (self) : (CONS-ITERATOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Method on CONS-ITERATOR: next? (self) : BOOLEAN

Not documented.

Method on CONS: sort (self (predicate FUNCTION-CODE)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Perform a stable, destructive sort of self according to predicate, and return the result. If predicate has a < semantics, the result will be in ascending order. It is not guaranteed that self will point to the beginning of the sorted result. If predicate is null, a suitable < predicate is chosen depending on the first element of self, and it is assumed that all elements of self have the same type (supported element types are GENERALIZED-SYMBOL, STRING, INTEGER, and FLOAT).

Method on CONS: sort-tuples (self (n INTEGER) (predicate FUNCTION-CODE)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Just like sort but assumes each element of self is a tuple (a cons) whose n-th element (0-based) will be used for comparison.

Function: map-null-to-nil ((self CONS)) : (LIKE SELF)

Return nil iff self is null or self otherwise.

Special Variable: *printpretty?* : BOOLEAN

If true conses will be pretty printed.

Special Variable: *printreadably?* : BOOLEAN

If true conses will be printed as readable Stella code.

Special Variable: *printprettycode?* : BOOLEAN

When true pretty-print Stella and translated code. Since (Lisp) pretty-printing is somewhat slow, turning this off speeds up file translation, but it also makes translated output very unreadable.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.5.1 CONS Lists as Sets

Method on CONS: subset? (self (otherList CONS)) : BOOLEAN

Return true if every element of self also occurs in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method on CONS: equivalent-sets? (self (otherList CONS)) : BOOLEAN

Return true if every element of self occurs in otherList and vice versa. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method on CONS: union (self (otherList CONS)) : CONS

Return the set union of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on CONS: intersection (self (otherList CONS)) : CONS

Return the set intersection of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on CONS: difference (self (otherList CONS)) : CONS

Return the set difference of self and otherList (i.e., all elements that are in self but not in otherSet). Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on CONS: subtract (self (otherList CONS)) : CONS

Return the set difference of self and otherList by destructively removing elements from self that also occur in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if self is a set.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.6 Lists

Class: LIST : SEQUENCE

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-cons-list : (CONS OF (LIKE (ANY-VALUE SELF)))

Not documented.

Variable: nil-list : LIST

Not documented.

Function: defined-list? ((self LIST)) : BOOLEAN

Return TRUE unless self is NULL or the NIL-LIST.

Function: null-list? ((self LIST)) : BOOLEAN

Return TRUE iff self is NULL or the NIL-LIST.

Method on LIST: empty? (self) : BOOLEAN

Return TRUE if the list self has no members.

Method on LIST: non-empty? (self) : BOOLEAN

Return TRUE if the list self has at least one member.

Method on LIST: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff the lists x and y are structurally equivalent. Uses equal? to test equality of elements.

Method on LIST: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: list (&rest (values OBJECT)) : LIST

Return a list containing values, in order.

Method on LIST: first (self) : (LIKE (ANY-VALUE SELF))

Return the first item in the list self, or NULL if empty.

Method on LIST: second (self) : (LIKE (ANY-VALUE SELF))

Return the second item in the list self, or NULL if empty.

Method on LIST: third (self) : (LIKE (ANY-VALUE SELF))

Return the third item in the list self, or NULL if empty.

Method on LIST: fourth (self) : (LIKE (ANY-VALUE SELF))

Return the fourth item in the list self, or NULL if empty.

Method on LIST: fifth (self) : (LIKE (ANY-VALUE SELF))

Return the fifth item in the list self, or NULL if empty.

Method on LIST: nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the nth item in the list self, or NULL if empty.

Method on LIST: rest (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a cons list of all but the first item in the list self.

Method on LIST: last (self) : (LIKE (ANY-VALUE SELF))

Return the last element of self.

Method on LIST: but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the list self.

Method on LIST: length (self) : INTEGER

Not documented.

Method on LIST: member? (self (object OBJECT)) : BOOLEAN

Return TRUE iff object is a member of the list self (uses an eql? test).

Method on LIST: memb? (self (object (LIKE (ANY-VALUE SELF)))) : BOOLEAN

Return TRUE iff object is a member of the cons list self (uses an eq? test).

Method on LIST: position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the list self (counting from zero); or return NULL if object does not occur within self (uses an eql? test). If start was supplied as non-NULL, only consider the sublist starting at start, however, the returned position will always be relative to the entire list.

Method on LIST: last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the list self (counting from zero); or return NULL if object does not occur within self (uses an eql? test). If end was supplied as non-NULL, only consider the sublist ending at end, however, the returned position will always be relative to the entire list.

Method on LIST: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self.

Method on LIST: push (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self.

Method on LIST: insert-new (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of the list self unless its already a member.

Method on LIST: insert-last (self (value (LIKE (ANY-VALUE SELF)))) :

Insert value as the last entry in the list self.

Method on LIST: reverse (self) : (LIKE SELF)

Reverse the members of self (in place).

Method on LIST: remove (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE SELF)

Destructively remove all entries in self that match value.

Method on LIST: remove-duplicates (self) : (LIKE SELF)

Destructively remove duplicates from self and return the result. Preserves the original order of the remaining members.

Method on LIST: remove-deleted-members (self) : (LIKE SELF)

Not documented.

Method on LIST: remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively remove all members of the list self for which test? evaluates to TRUE. test takes a single argument of type OBJECT and returns TRUE or FALSE. Returns self.

Method on LIST: pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return the first element in the list self. Return NULL if the list is empty.

Method on LIST: substitute (self (inValue OBJECT) (outValue OBJECT)) : (LIKE SELF)

Destructively replace each appearance of outValue by inValue in the list self.

Method on LIST: concatenate (list1 (list2 LIST) &rest (otherLists LIST)) : LIST

Copy list2 and all otherLists onto the end of list1. The operation is destructive wrt list1, but leaves all other lists intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method on LIST: prepend (self (list2 LIST)) : (LIKE SELF)

Copy list2 onto the front of the list self. The operation is destructive wrt self, but leaves list2 intact.

Method on LIST: copy (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a copy of the list self. The conses in the copy are freshly allocated.

Method on LIST: clear (self) :

Make self an empty list.

Method on LIST: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method on LIST: allocate-iterator (self) : (LIST-ITERATOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Method on LIST-ITERATOR: next? (self) : BOOLEAN

Not documented.

Method on LIST: sort (self (predicate FUNCTION-CODE)) : (LIST OF (LIKE (ANY-VALUE SELF)))

Perform a stable, destructive sort of self according to predicate, and return the result. If predicate has a < semantics, the result will be in ascending order. If predicate is NULL, a suitable < predicate is chosen depending on the first element of self, and it is assumed that all elements of self have the same type (supported element types are GENERALIZED-SYMBOL, STRING, INTEGER, and FLOAT).

Function: map-null-to-nil-list ((self LIST)) : LIST

Return NIL-LIST iff self is NULL or self otherwise.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.6.1 Lists as Sets

Similar to CONS lists LIST’s can also be treated as sets and support the set manipulations below. Note that LIST constructors do not check for proper set-hood and may have surprising results if a list contains duplicate elements.

Method on LIST: subset? (self (otherList LIST)) : BOOLEAN

Return true if every element of self also occurs in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method on LIST: equivalent-sets? (self (otherList LIST)) : BOOLEAN

Return true if every element of self occurs in otherList and vice versa. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method on LIST: union (self (otherList LIST)) : LIST

Return the set union of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on LIST: intersection (self (otherList LIST)) : LIST

Return the set intersection of self and otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on LIST: difference (self (otherList LIST)) : LIST

Return the set difference of self and otherList (i.e., all elements that are in self but not in otherSet). Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if both self and otherList are sets.

Method on LIST: subtract (self (otherList LIST)) : LIST

Return the set difference of self and otherList by destructively removing elements from self that also occur in otherList. Uses an eql? test and a simple quadratic-time algorithm. Note that the result is only guaranteed to be a set if self is a set.

SET is a subclass of LIST that overrides certain LIST operations to prevent duplicate elements. The following additional or modified operations are supported:

Class: SET : LIST, SET-MIXIN

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Method on SET: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the set self unless it is already a member.

Method on SET: push (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the front of set self unless it is already a member.

Method on SET: insert-last (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the end of set self unless it is already a member.

Method on SET: substitute (self (new OBJECT) (old OBJECT)) : (LIKE SELF)

Destructively replace old with new in the set self unless new is already a member.

Method on SET: concatenate (set1 (set2 LIST) &rest (otherSets LIST)) : SET

Union set2 and all otherSets onto the end of set1. The operation is destructive wrt set1, but leaves all other sets intact. The two mandatory parameters allow us to optimize the common binary case by not relying on the somewhat less efficient variable arguments mechanism.

Method on SET: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff x and y are SET’s with equivalent members. Uses equal? to test equality of elements. This is more general than equivalent-sets?, since that only uses an eql? test.

Method on SET: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.

Function: set (&rest (values OBJECT)) : SET

Return a set containing values, in order.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.7 Property and Key-Value Lists

Class: PROPERTY-LIST : DICTIONARY

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-plist : CONS

Not documented.

Method on PROPERTY-LIST: empty? (self) : BOOLEAN

Not documented.

Method on PROPERTY-LIST: non-empty? (self) : BOOLEAN

Not documented.

Method on PROPERTY-LIST: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs..

Method on PROPERTY-LIST: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method on PROPERTY-LIST: length (self) : INTEGER

Not documented.

Method on PROPERTY-LIST: lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on PROPERTY-LIST: insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert the entry <‘key’, value> into the property list self. If a previous entry existed with key key, that entry is replaced.

Method on PROPERTY-LIST: remove-at (self (key (LIKE (ANY-KEY SELF)))) : OBJECT

Remove the entry that matches the key key. Return the value of the matching entry, or NULL if there is no matching entry. Assumes that at most one entry matches key.

Method on PROPERTY-LIST: copy (self) : (LIKE SELF)

Return a copy of the list self. The conses in the copy are freshly allocated.

Method on PROPERTY-LIST: clear (self) :

Make self an empty property list.

Method on PROPERTY-LIST: allocate-iterator (self) : (PROPERTY-LIST-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Not documented.

Method on PROPERTY-LIST-ITERATOR: next? (self) : BOOLEAN

Not documented.

Class: KV-CONS : STANDARD-OBJECT

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: key : OBJECT

Not documented.

Slot: value : OBJECT

Not documented.

Slot: rest : KV-CONS

Not documented.

Function: kv-cons ((key OBJECT) (value OBJECT) (rest KV-CONS)) : KV-CONS

Create, fill-in, and return a new KV-CONS.

Function: copy-kv-cons-list ((kvconslist KV-CONS)) : KV-CONS

Return a copy of the cons list consList.

Class: KEY-VALUE-LIST : DICTIONARY

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-kv-list : KV-CONS

Not documented.

Method on KEY-VALUE-LIST: empty? (self) : BOOLEAN

Not documented.

Method on KEY-VALUE-LIST: non-empty? (self) : BOOLEAN

Not documented.

Method on KEY-VALUE-LIST: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method on KEY-VALUE-LIST: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method on KEY-VALUE-LIST: length (self) : INTEGER

Not documented.

Method on KEY-VALUE-LIST: lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on KEY-VALUE-LIST: reverse (self) : (LIKE SELF)

Destructively reverse the members of the list self.

Method on KEY-VALUE-LIST: insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert the entry <‘key’, value> into the association self. If a previous entry existed with key key, that entry is replaced.

Method on KEY-VALUE-LIST: remove-at (self (key (LIKE (ANY-KEY SELF)))) : OBJECT

Remove the entry that matches the key key. Return the value of the matching entry, or NULL if there is no matching entry. Assumes that at most one entry matches key.

Method on KEY-VALUE-LIST: insert-entry (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Insert an entry <‘key’,value> to self unless an identical entry already exists. This can generate duplicate entries for key.

Method on KEY-VALUE-LIST: remove-entry (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Remove the entry that matches <‘key’,value>. Assumes that more than one entry can match key.

Method on KEY-VALUE-LIST: push (self (value KV-CONS)) :

Make value be the new first element of self. Note that the rest slot of value should be null, since it will be overwritten. This might duplicate an existing entry. If a previous entry existed with the same key as value, that entry is retained, but shadowed by this new entry.

Method on KEY-VALUE-LIST: kv-push (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Add a new entry <‘key’, value> to the front of the association self. This might duplicate an existing entry. If a previous entry existed with key key, that entry is retained, but shadowed by this new entry.

Method on KEY-VALUE-LIST: pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return the value of the first element of the kv-list self. It does NOT return the KV-CONS object. Return null if the list is empty.

Method on KEY-VALUE-LIST: copy (self) : (LIKE SELF)

Return a copy of the kv-list self. The kv-conses in the copy are freshly allocated.

Method on KEY-VALUE-LIST: clear (self) :

Make self an empty dictionary.

Method on KEY-VALUE-LIST: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of key-value pairs in self.

Method on KEY-VALUE-LIST: allocate-iterator (self) : (KV-LIST-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Not documented.

Method on KV-LIST-ITERATOR: next? (self) : BOOLEAN

Not documented.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.8 Vectors

Class: VECTOR : SEQUENCE

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: array-size : INTEGER

Not documented.

Slot: the-array : (NATIVE-VECTOR OF (LIKE (ANY-VALUE SELF)))

Not documented.

Class: EXTENSIBLE-VECTOR : VECTOR

Not documented.

Method on VECTOR: empty? (self) : BOOLEAN

Return true if self has length 0.

Method on VECTOR: non-empty? (self) : BOOLEAN

Return true if self has length > 0.

Method on VECTOR: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff the vectors x and y are structurally equivalent. Uses equal? to test equality of elements.

Method on VECTOR: equal-hash-code (self) : INTEGER

Return an equal? hash code for self.

Function: vector (&rest (values OBJECT)) : VECTOR

Return a vector containing values, in order.

Method on VECTOR: first (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: second (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: third (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: fourth (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: fifth (self) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on VECTOR: last (self) : (LIKE (ANY-VALUE SELF))

Return the last item in the vector self.

Method on VECTOR: but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Generate all but the last element of the vector self.

Method on VECTOR: length (self) : INTEGER

Not documented.

Method on VECTOR: member? (self (object OBJECT)) : BOOLEAN

Not documented.

Method on VECTOR: position (self (object OBJECT) (start INTEGER)) : INTEGER

Return the position of object within the vector self (counting from zero); or return null if object does not occur within self (uses an eql? test). If start was supplied as non-‘null’, only consider the portion starting at start, however, the returned position will always be relative to the entire vector.

Method on VECTOR: last-position (self (object OBJECT) (end INTEGER)) : INTEGER

Return the position of object within the vector self (counting from zero); or return null if object does not occur within self (uses an eql? test). If end was supplied as non-‘null’, only consider the portion ending at index end, however, the returned position will always be relative to the entire vector.

Method on VECTOR: insert-at (self (offset INTEGER) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method on VECTOR: copy (self) : (VECTOR OF (LIKE (ANY-VALUE SELF)))

Return a copy of the vector self.

Method on VECTOR: clear (self) :

Not documented.

Function: resize-vector ((self VECTOR) (size INTEGER)) :

Change the size of self to size. If size is smaller than the current size of self the vector will be truncated. Otherwise, the internal array of self will be grown to size and unused elements will be initialized to NULL.

Method on VECTOR: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method on EXTENSIBLE-VECTOR: insert-at (self (offset INTEGER) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method on VECTOR-SEQUENCE: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Append value to the END of the sequence self. Resize the array if necessary.

Method on VECTOR-SEQUENCE: remove (self (value (LIKE (ANY-VALUE SELF)))) : VECTOR-SEQUENCE

Remove value from the sequence self, and left shift the values after it to close the gap.

Method on VECTOR-SEQUENCE: length (self) : INTEGER

Not documented.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.9 Hash Tables

Class: HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: STRING-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : STRING

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: STRING-TO-INTEGER-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : STRING

Not documented.

Class Parameter: any-value : INTEGER

Not documented.

Class: INTEGER-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : INTEGER

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Class: FLOAT-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : FLOAT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Method on HASH-TABLE: lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on HASH-TABLE: insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Not documented.

Method on HASH-TABLE: remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Not documented.

Method on STRING-HASH-TABLE: lookup (self (key STRING)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on STRING-HASH-TABLE: insert-at (self (key STRING) (value OBJECT)) :

Not documented.

Method on STRING-HASH-TABLE: remove-at (self (key STRING)) :

Not documented.

Method on STRING-TO-INTEGER-HASH-TABLE: lookup (self (key STRING)) : INTEGER

Not documented.

Method on STRING-TO-INTEGER-HASH-TABLE: insert-at (self (key STRING) (value INTEGER)) :

Not documented.

Method on INTEGER-HASH-TABLE: lookup (self (key INTEGER)) : (LIKE (ANY-VALUE SELF))

Not documented.

Method on INTEGER-HASH-TABLE: insert-at (self (key INTEGER) (value OBJECT)) :

Not documented.

Method on FLOAT-HASH-TABLE: insert-at (self (key FLOAT) (value OBJECT)) :

Not documented.

STELLA provides its own implementation of hash tables for cases where language-native implementations are not available, or where additional features are needed.

Class: STELLA-HASH-TABLE : ABSTRACT-HASH-TABLE

Not documented.

Class Parameter: any-key : OBJECT

Not documented.

Class Parameter: any-value : OBJECT

Not documented.

Slot: the-table : (ARRAY SIZE () OF KV-CONS)

Not documented.

Slot: size : INTEGER

Not documented.

Slot: initial-size : INTEGER

If supplied, the initial hash table will be sized to hold at least that many elements.

Slot: free-elements : INTEGER

Not documented.

Slot: equal-test? : BOOLEAN

If true use equal? as the equality test and equal-hash-code as the hash function, otherwise, use eql? and hash-code (the default).

Method on STELLA-HASH-TABLE: lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup the entry identified by key in self and return its value, or NULL if no such entry exists. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on STELLA-HASH-TABLE: insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Set the value of the entry identified by key in self to value or add a new entry if no entry with key exists yet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on STELLA-HASH-TABLE: remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Remove the entry identified by key from self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on STELLA-HASH-TABLE: length (self) : INTEGER

Return the number of entries in self.

Method on STELLA-HASH-TABLE: empty? (self) : BOOLEAN

Return TRUE if self has zero entries.

Method on STELLA-HASH-TABLE: non-empty? (self) : BOOLEAN

Return TRUE if self has at least 1 entry.

Method on STELLA-HASH-TABLE: copy (self) : (LIKE SELF)

Return a copy of the hash table self. The bucket table and buckets are freshly allocated, however, the keys and values of entries are not copied themselves (similar to what we do for lists, etc.).

Method on STELLA-HASH-TABLE: clear (self) :

Remove all entries from self. This will result in a re-initialization of the table upon the first insertion into self.

Method on STELLA-HASH-TABLE: consify (self) : (CONS OF CONS)

Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

Method on STELLA-HASH-TABLE: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method on STELLA-HASH-TABLE: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method on STELLA-HASH-TABLE: allocate-iterator (self) : (STELLA-HASH-TABLE-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Allocate an iterator for self.

Hashing objects into STELLA hash tables is accomplished via hash-code and equal-hash-code methods. These methods are implemented for all built-in STELLA types but are user extensible for cases where special functionality on user-defined objects is needed. Defining new hash-code methods should only be necessary if new wrapper types are defined, since for all types descending from STANDARD-OBJECT the built-in method should be adequate.

Function: object-hash-code ((self OBJECT)) : INTEGER

Return a hash code for self (can be negative). Two objects that are eq? are guaranteed to generate the same hash code. Two objects that are not eq? do not necessarily generate different hash codes. Similar to hash-code but always hashes on the address of self even if it is a wrapper.

Method on OBJECT: hash-code (self) : INTEGER

Return a hash code for self (can be negative). Two objects that are eql? are guaranteed to generate the same hash code. Two objects that are not eql? do not necessarily generate different hash codes.

Method on STANDARD-OBJECT: hash-code (self) : INTEGER

Not documented.

Method on STRING-WRAPPER: hash-code (self) : INTEGER

Not documented.

Method on INTEGER-WRAPPER: hash-code (self) : INTEGER

Not documented.

Method on FLOAT-WRAPPER: hash-code (self) : INTEGER

Not documented.

Method on CHARACTER-WRAPPER: hash-code (self) : INTEGER

Not documented.

Method on BOOLEAN-WRAPPER: hash-code (self) : INTEGER

Not documented.

Method on STRING: hash-code (self) : INTEGER

Not documented.

Method on INTEGER: hash-code (self) : INTEGER

Not documented.

Method on FLOAT: hash-code (self) : INTEGER

Not documented.

Method on CHARACTER: hash-code (self) : INTEGER

Not documented.

Method on OBJECT: equal-hash-code (self) : INTEGER

Return a hash code for self (can be negative). Two objects that are equal? are guaranteed to generate the same hash code (provided, that writers of object-equal? methods also implemented the appropriate equal-hash-code method). Two objects that are not equal?do not necessarily generate different hash codes.

The following low-level utilities are available to implement specialized hashing schemes or for defining new versions of equal-hash-code.

Function: hashmod ((code INTEGER) (size INTEGER)) : INTEGER

Map the hash code code onto a bucket index for a hash table of size (i.e., onto the interval [0..size-1]. This is just like rem for positive hash codes but also works for negative hash codes by mapping those onto a positive number first. Note, that the sign conversion mapping is not equivalent to calling the abs function (it simply masks the sign bit for speed) and therefore really only makes sense for hash codes.

Function: rotate-hash-code ((arg INTEGER)) : INTEGER

Rotate arg to the right by 1 position. This means shift arg to the right by one and feed in args bit zero from the left. In Lisp the result will stay in positive FIXNUM range. In C++ and Java this might return a negative value which might be equal to NULL-INTEGER. Important: to make this inlinable, it must be called with an atom (i.e., constant or variable) as its argument. This function is primarily useful for hashing sequences of items where the hash code should take the sequential order of elements into account (e.g., lists).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.10 Key Value Maps

KEY-VALUE-MAP is a full-featured dictionary class that supports eql? or extensible equal? equality tests, O(1) access operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small tables and iteration even if the dictionary is represented by a hash table (note that in STELLA we cannot iterate over regular HASH-TABLE’s, since native Lisp hash tables do not allow us to implement a hash table iterator). Since large KEY-VALUE-MAP’s are implemented via STELLA-HASH-TABLE’s, we can support iteration.

Class: KEY-VALUE-MAP : DICTIONARY

Full-featured dictionary class that supports eql? or equal? equality tests, O(1) access operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small tables and iteration even if the dictionary is represented by a hash table.

Slot: the-map : OBJECT

Not documented.

Slot: equal-test? : BOOLEAN

If true use equal? as the equality test (and equal-hash-code as the hash function), otherwise, use eql? (and hash-code) (the default).

Slot: initial-size : INTEGER

If supplied, the initial table will be sized to hold at least that many elements.

Slot: crossover-point : INTEGER

Not documented.

Method on KEY-VALUE-MAP: lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup the entry identified by key in self and return its value, or NULL if no such entry exists. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on KEY-VALUE-MAP: insert-at (self (key (LIKE (ANY-KEY SELF))) (value (LIKE (ANY-VALUE SELF)))) :

Set the value of the entry identified by key in self to value or add a new entry if no entry with key exists yet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on KEY-VALUE-MAP: remove-at (self (key (LIKE (ANY-KEY SELF)))) :

Remove the entry identified by key from self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on KEY-VALUE-MAP: length (self) : INTEGER

Return the number of entries in self.

Method on KEY-VALUE-MAP: empty? (self) : BOOLEAN

Return TRUE if self has zero entries.

Method on KEY-VALUE-MAP: non-empty? (self) : BOOLEAN

Return TRUE if self has at least 1 entry.

Method on KEY-VALUE-MAP: copy (self) : (LIKE SELF)

Return a copy of the map self. All entries are freshly allocated, however, the keys and values of entries are not copied themselves (similar to what we do for lists, etc.).

Method on KEY-VALUE-MAP: clear (self) :

Reset self to have zero entries.

Method on KEY-VALUE-MAP: allocate-iterator (self) : (DICTIONARY-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Allocate an iterator for self. The only modifying operations allowed during iteration are removal of the current element or changing its value. All other removal or insertion operations might lead to corruption or undefined results.

Method on KEY-VALUE-MAP: consify (self) : CONS

Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

Method on KEY-VALUE-MAP: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE if x and y represent the same set of key/value pairs.

Method on KEY-VALUE-MAP: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.11 Hash Sets

HASH-SET is a full-featured set class that supports eql? or extensible equal? equality tests, O(1) insert and member? operations, O(N) intersection etc. operations even for large numbers of entries by using a STELLA hash table, light-weight KV-CONS representation for small sets and iteration even if the set is represented by a hash table. The only minor drawback right now is that we waste one value slot per entry, since we piggy-back off KEY-VALUE-MAP’s, however, that wastes at most 25% space.

Class: HASH-SET : KEY-VALUE-MAP, SET-MIXIN

Full-featured set class that supports eql? or equal? equality tests, O(1) insert and member? operations & O(N) intersection etc. operations even for large numbers of entries by using a hash table, light-weight KV-CONS representation for small sets and iteration even if the set is represented by a hash table. The only minor drawback right now is that this wastes a value slot per entry, since we piggy-back off KEY-VALUE-MAP’s, however, that wastes at most 25% space.

Function: hash-set (&rest (values OBJECT)) : HASH-SET

Return an eql? HASH-SET containing values.

Method on HASH-SET: member? (self (object OBJECT)) : BOOLEAN

Return TRUE iff object is a member of the set self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Add value to the set self unless it is already a member. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: remove (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE SELF)

Destructively remove value from the set self if it is a member and return self. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: remove-if (self (test? FUNCTION-CODE)) : (LIKE SELF)

Destructively remove all elements of the set self for which test? evaluates to TRUE. test? takes a single argument of type OBJECT and returns TRUE or FALSE. Returns self.

Method on HASH-SET: pop (self) : (LIKE (ANY-VALUE SELF))

Remove and return an arbitrary element of the set self. Return NULL if the set is empty. Performance note: for large sets implemented via hash tables it takes O(N) to empty out the set with repeated calls to pop, since the emptier the table gets, the longer it takes to find an element. Therefore, it is usually better to use iteration with embedded removals for such cases.

Method on HASH-SET: substitute (self (new OBJECT) (old OBJECT)) : (LIKE SELF)

Destructively replace old with new in the set self unless new is already a member. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: copy (self) : (LIKE SELF)

Return a copy of the set self. All entries are freshly allocated, however, the values are not copied themselves (similar to what we do for lists, etc.).

Method on HASH-SET: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Collect all entries of self into a cons list and return the result.

Method on HASH-SET: subset? (self (otherSet HASH-SET)) : BOOLEAN

Return true if every element of self also occurs in otherSet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: equivalent-sets? (self (otherSet HASH-SET)) : BOOLEAN

Return true if every element of self occurs in otherSet and vice versa. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: intersection (self (otherSet HASH-SET)) : HASH-SET

Return the set intersection of self and otherSet as a new set. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: union (self (otherSet HASH-SET)) : HASH-SET

Return the set union of self and otherSet as a new set. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: difference (self (otherSet HASH-SET)) : HASH-SET

Return the set difference of self and otherSet as a new set (i.e., all elements that are in self but not in otherSet). Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: subtract (self (otherSet HASH-SET)) : HASH-SET

Return the set difference of self and otherSet by destructively removing elements from self that also occur in otherSet. Uses an eql? test by default or equal? if equal-test? of self is TRUE.

Method on HASH-SET: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff sets x and y are HASH-SET’s with equivalent members. Uses an eql? test by default or equal? if equal-test? of self is TRUE. This is equivalent to calling equivalent-sets?.

Method on HASH-SET: equal-hash-code (self) : INTEGER

Return an equal? hash code for self. Note that this is O(N) in the number of elements of self.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.12 Iterators

Method on ITERATOR: empty? (self) : BOOLEAN

Return TRUE if the sequence represented by self has no elements. Side-effect free.

Method on ITERATOR: member? (self (value OBJECT)) : BOOLEAN

Iterate over values of self, returning TRUE if one of them is eql to ’value.

Method on ABSTRACT-ITERATOR: length (self) : INTEGER

Iterate over self, and count how many items there are. Bad idea if self iterates over an infinite collection, since in that case it will run forever.’

Method on ITERATOR: pop (self) : (LIKE (ANY-VALUE SELF))

Return the first item of the sequence represented by self, or NULL if it is empty. Destructively uses up the first iteration element.

Method on ITERATOR: advance (self (n INTEGER)) : (LIKE SELF)

Return self after skipping over the first n elements in the (remainder of the) iteration.

Method on ITERATOR: concatenate (iterator1 (iterator2 ITERATOR) &rest (otherIterators ITERATOR)) : ALL-PURPOSE-ITERATOR

Return an iterator that first generates all values of iterator1, then those of iterator2, and then those of all otherIterators. The generated values can be filtered by supplying a filter function to the resulting iterator.

Method on ITERATOR: consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))

Return a list of elements generated by self.

Method on ALL-PURPOSE-ITERATOR: next? (self) : BOOLEAN

Apply the stored next? function to self.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.13 Symbols

Function: lookup-symbol ((name STRING)) : SYMBOL

Return the first symbol with name visible from the current module.

Function: intern-symbol ((name STRING)) : SYMBOL

Return a newly-created or existing symbol with name name.

Function: unintern-symbol ((self SYMBOL)) :

Remove self from its home module and the symbol table.

Function: lookup-symbol-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SYMBOL

Return the first symbol with name visible from module. If local? only consider symbols directly interned in module. If module is null, use *MODULE* instead.

Function: intern-symbol-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SYMBOL

Look for a symbol named name in module (if local? do not consider inherited modules). If none exists, intern it locally in module. Return the existing or newly-created symbol.

Function: intern-derived-symbol ((baseSymbol GENERALIZED-SYMBOL) (newName STRING)) : SYMBOL

Return a newly-created or existing symbol with name newName which is interned in the same module as baseSymbol.

Function: visible-symbol? ((self SYMBOL)) : BOOLEAN

Return true if self is visible from the current module.

Function: lookup-visible-symbols-in-module ((name STRING) (module MODULE) (enforceShadowing? BOOLEAN)) : (CONS OF SYMBOL)

Return the list of symbols with name visible from module. More specific symbols (relative to the module precedence order defined by visible-modules) come earlier in the list. If module is null, start from *MODULE* instead. If enforceShadowing? is true, do not return any symbols that are shadowed due to some :SHADOW declaration.

Function: import-symbol ((symbol SYMBOL) (module MODULE)) : SYMBOL

Import symbol into module and return the imported symbol. Signal an error if a different symbol with the same name already exists locally in module. Any symbol with the same name visible in module by inheritance will be shadowed by the newly imported symbol.

Function: safe-import-symbol ((symbol SYMBOL) (module MODULE)) : SYMBOL

Safe version of import-symbol (which see). Only imports symbol if no symbol with that name is currently interned or visible in module. Returns symbol if it was imported or the conflicting symbol in module otherwise.

Function: lookup-surrogate ((name STRING)) : SURROGATE

Return the first surrogate with name visible from the current module.

Function: intern-surrogate ((name STRING)) : SURROGATE

Return a newly-created or existing surrogate with name name.

Function: unintern-surrogate ((self SURROGATE)) :

Remove self from its home module and the surrogate table.

Function: lookup-surrogate-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SURROGATE

Return the first surrogate with name visible from module. If local? only consider surrogates directly interned in module. If module is null, use *MODULE* instead.

Function: intern-surrogate-in-module ((name STRING) (module MODULE) (local? BOOLEAN)) : SURROGATE

Look for a symbol named name in module (if local? do not consider inherited modules). If none exists, intern it locally in module. Return the existing or newly-created symbol.

Function: intern-derived-surrogate ((baseSymbol GENERALIZED-SYMBOL) (newName STRING)) : SURROGATE

Return a newly-created or existing surrogate with name newName which is interned in the same module as baseSymbol.

Function: visible-surrogate? ((self SURROGATE)) : BOOLEAN

Return true if self is visible from the current module.

Function: lookup-visible-surrogates-in-module ((name STRING) (module MODULE) (enforceShadowing? BOOLEAN)) : (CONS OF SURROGATE)

Return the list of surrogates with name visible from module. More specific surrogates (relative to the module precedence order defined by visible-modules) come earlier in the list. If module is null, start from *MODULE* instead. If enforceShadowing? is true, do not return any surrogates that are shadowed due to some :SHADOW declaration.

Function: import-surrogate ((surrogate SURROGATE) (module MODULE)) : SURROGATE

Import surrogate into module and return the imported surrogate. Signal an error if a different surrogate with the same name already exists locally in module. Any surrogate with the same name visible in module by inheritance will be shadowed by the newly imported surrogate.

Function: safe-import-surrogate ((surrogate SURROGATE) (module MODULE)) : SURROGATE

Safe version of import-surrogate (which see). Only imports surrogate if no surrogate with that name is currently interned or visible in module. Returns surrogate if it was imported or the conflicting surrogate in module otherwise.

Function: lookup-keyword ((name STRING)) : KEYWORD

Return the keyword with name if it exists.

Function: intern-keyword ((name STRING)) : KEYWORD

Return a newly-created or existing keyword with name name. Storage note: a COPY of name is stored in the keyword

Function: gensym ((prefix STRING)) : SYMBOL

Return a transient symbol with a name beginning with prefix and ending with a globally gensym’d integer.

Function: local-gensym ((prefix STRING)) : SYMBOL

Not documented.

Function: symbol-plist ((symbol SYMBOL)) : CONS

Return the property list of symbol. The symbol-plist of a symbol can be set with setf. IMPORTANT: Property list are modified destructively, hence, if you supply it as a whole make sure to always supply a modfiable copy, e.g., by using bquote.

Function: symbol-property ((symbol SYMBOL) (key STANDARD-OBJECT)) : OBJECT

Return the property of symbol whose key is eq? to key. Symbol properties can be set with setf.

Function: symbol-value ((symbol SYMBOL)) : OBJECT

Return the value of symbol. Note, that this value is not visible to code that references a variable with the same name as symbol. The symbol-value is simply a special property that can always be accessed in constant time. The symbol-value of a symbol can be changed with setf.

Function: symbolize ((surrogate SURROGATE)) : SYMBOL

Convert surrogate into a symbol with the same name and module.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.14 Context and Modules

Function: get-stella-context ((pathName STRING) (error? BOOLEAN)) : CONTEXT

Return the context located at pathName, or null if no such context exists. If error? is true, throw an exception if no context is found, otherwise silently return null.

Function: clear-context ((self CONTEXT)) :

Destroy all objects belonging to self or any of its subcontexts.

Macro: within-context ((contextForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the context resulting from contextForm.

Method on CONTEXT: destroy-context (self) :

Make the translator happy.

Method on STRING: destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Method on CONTEXT: change-context (context) : CONTEXT

Change the current context to be the context context.

Method on STRING: change-context (contextName) : CONTEXT

Change the current context to be the context named contextName.

N-Command: cc (&rest (name NAME)) : CONTEXT

Change the current context to the one named name. Return the value of the new current context. If no name is supplied, return the pre-existing value of the current context. cc is a no-op if the context reference cannot be successfully evaluated.

N-Command: defmodule ((name NAME) &rest (options OBJECT)) :

Define (or redefine) a module named name. The accepted syntax is:

 
  (defmodule <module-name>
     [:documentation <docstring>]
     [:includes {<module-name> | (<module-name>*)}]
     [:uses {<module-name> | (<module-name>*)}]
     [:lisp-package <package-name-string>]
     [:java-package <package-specification-string>]
     [:cpp-namespace <namespace-name-string>]
     [:java-catchall-class
     [:api? {TRUE | FALSE}]
     [:case-sensitive? {TRUE | FALSE}]
     [:shadow (<symbol>*)]
     [:java-catchall-class <class-name-string>]
     [<other-options>*])

name can be a string or a symbol.

Modules include objects from other modules via two separate mechanisms: (1) they inherit from their parents specified via the :includes option and/or a fully qualified module name, and (2) they inherit from used modules specified via the :uses option. The main difference between the two mechanisms is that inheritance from parents is transitive, while uses-links are only followed one level deep. I.e., a module A that uses B will see all objects of B (and any of B’s parents) but not see anything from modules used by B. Another difference is that only objects declared as public can be inherited via uses-links (this is not yet enforced). Note that - contrary to Lisp - there are separate name spaces for classes, functions, and variables. For example, a module could inherit the class CONS from the STELLA module, but shadow the function of the same name.

The above discussion of :includes and :uses semantics keyed on the inheritance/visibility of symbols. The PowerLoom system makes another very important distinction: If a module A is inherited directly or indirectly via :includes specification(s) by a submodule B, then all definitions and facts asserted in A are visible in B. This is not the cases for :uses; the :uses options does not impact inheritance of propositions at all.

The list of modules specified in the :includes option plus (if supplied) the parent in the path used for name become the new module’s parents. If no :uses option was supplied, the new module will use the STELLA module by default, otherwise, it will use the set of specified modules.

If :case-sensitive? is supplied as TRUE, symbols in the module will be interned case-sensitively, otherwise (the default), they will be converted to uppercase before they get interned. That means that any reference from inside a case-sensitive module to a non-case-sensitive module will have to use uppercase names for symbols in the non-case-sensitive module. The standard system modules are all NOT case sensitive.

Modules can shadow definitions of functions and classes inherited from parents or used modules. Shadowing is done automatically, but generates a warning unless the shadowed type or function name is listed in the :shadow option of the module definition .

Examples:

 
  (defmodule "PL-KERNEL/PL-USER"
    :uses ("LOGIC" "STELLA")
    :package "PL-USER")

  (defmodule PL-USER/GENEALOGY)

The remaining options are relevant only for modules that contain STELLA code. Modules used only to contain knowledge base definitions and assertions have no use for them:

The keywords :lisp-package, :java-package, and :cpp-package specify the name of a native package or name space in which symbols of the module should be allocated when they get translated into one of Lisp, Java, or C++. By default, Lisp symbols are allocated in the STELLA package, and C++ names are translated without any prefixes. The rules that the STELLA translator uses to attach translated Java objects to classes and packages are somewhat complex. Use :java-package option to specify a list of package names (separated by periods) that prefix the Java object in this module. Use :java-catchall-class to specify the name of the Java class to contain all global & special variables, parameter-less functions and functions defined on arguments that are not classes in the current module. The default value will be the name of the module.

When set to TRUE, the :api? option tells the PowerLoom User Manual generator that all functions defined in this module should be included in the API section. Additionally, the Java translator makes all API functions synchronized.

Function: get-stella-module ((pathName STRING) (error? BOOLEAN)) : MODULE

Return the module located at pathName, or null if no such module exists. The search looks at ancestors and top-most (cardinal) modules. If error? is true, throw an exception if no module is found.

Function: find-or-create-module ((pathname STRING)) : MODULE

Return a module located at pathname if one exists, otherwise create one

N-Command: clear-module (&rest (name NAME)) :

Destroy all objects belonging to module name or any of its children. If no name is supplied, the current module will be cleared after confirming with the user. Important modules such as STELLA are protected against accidental clearing.

Function: destroy-module ((self MODULE)) :

Destroy the module self, and recursively destroy all contexts that inherit self.

Method on MODULE: destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Function: visible-modules ((from MODULE)) : (CONS OF MODULE)

Return a list of all modules visible from module from (or *module* if from is NULL. The generated modules are generated from most to least-specific and will start with the module from.

Macro: within-module ((moduleForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the module resulting from moduleForm. *module* is an acceptable moduleForm. It will locally rebind *module* and *context* and shield the outer bindings from changes.

N-Command: in-module ((name NAME)) : MODULE

Change the current module to the module named name.

Method on MODULE: change-module (module) : MODULE

Change the current module to be the module module.

Method on STRING: change-module (moduleName) : MODULE

Change the current module to be the module named moduleName.

Function: create-world ((parentContext CONTEXT) (name STRING)) : WORLD

Create a new world below the world or module parentContext. Optionally, specify a name.

Command: push-world () : WORLD

Spawn a new world that is a child of the current context, and change the current context to the new world.

Command: pop-world () : CONTEXT

Destroy the current world and change the current context to be its parent. Return the current context. Nothing happens if there is no current world.

Method on WORLD: destroy-context (self) :

Destroy the context self, and recursively destroy all contexts that inherit self.

Macro: within-world ((worldForm OBJECT) &body (body CONS)) : OBJECT

Execute body within the world resulting from worldForm.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.15 Input and Output

Function: read-s-expression ((stream INPUT-STREAM)) : OBJECT BOOLEAN

Read one STELLA s-expression from stream and return the result. Return true as the second value on EOF.

Function: read-s-expression-from-string ((string STRING)) : OBJECT

Read one STELLA s-expression from string and return the result.

Function: read-line ((stream INPUT-STREAM)) : STRING

Read one line from stream and return the result. This differs from native-read-line in that it is not platform-dependent. It recognizes any of the three common line ending formats: CR, LF, CR-LF in any combination. It is not as fast as native-read-line, however.

Function: read-character ((inputStream INPUT-STREAM)) : CHARACTER BOOLEAN

Read one character from inputStream and return the result. Return true as the second value on EOF.

Function: unread-character ((ch CHARACTER) (inputStream INPUT-STREAM)) :

Unread ch from inputStream. Signal an error if ch was not the last character read.

Function: y-or-n? ((message STRING)) : BOOLEAN

Read a line of input from STANDARD-INPUT and return true if the input was y or false if the input was n. Loop until either y or n was entered. If message is non-‘null’ prompt with it before the input is read. See also special variable *USER-QUERY-ACTION*.

Function: yes-or-no? ((message STRING)) : BOOLEAN

Read a line of input from STANDARD-INPUT and return true if the input was yes or false if the input was no. Loop until either yes or no was entered. If message is non-‘null’ prompt with it before the input is read. See also special variable *USER-QUERY-ACTION*.

Function: flush-output ((self OUTPUT-STREAM)) :

Flush all buffered output of self.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.16 Files

Function: open-input-file ((fileName STRING) &rest (options KEYWORD)) : FILE-INPUT-STREAM

Open file fileName for input and return the resulting input stream. By default signal an error if the file does not exist. The only legal option so far is :IF-NOT-EXISTS (or :IF-NOT-EXISTS-ACTION) which specifies what to do in case the file does not exist. If its value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

Function: open-output-file ((fileName STRING) &rest (options KEYWORD)) : FILE-OUTPUT-STREAM

Open file fileName for output and return the resulting output stream. By default the file will be created or overwritten if it already exists. If :IF-EXISTS (or :IF-EXISTS-ACTION) is one of the options its value specifies what to do in case the file already exists. If the value is :SUPERSEDE the pre-existing file will be overwritten. If the value is :APPEND the preexisting file will be appended to (if the file did not yet exist the file will simply be created). If the value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

If :IF-NOT-EXISTS (or :IF-NOT-EXISTS-ACTION) is one of the options its value specifies what to do in case the file does not already exist. If the value is :CREATE, the file will simply be created. If the value is :CREATE-PATH the file will be created plus any non-existing directories in the directory path of fileName will also be created. If the value is :ERROR then an error will be signaled. If it is :ABORT or :PROBE the opening operation will be aborted and NULL will be returned.

Function: close-stream ((self STREAM)) :

Close the stream self.

Function: close-all-files () :

Close all currently open file streams. Use for emergencies or for cleanup.

Macro: with-input-file ((binding CONS) &body (body CONS)) : OBJECT

Sets up an unwind-protected form which opens a file for input and closes it afterwards. The stream for reading is bound to the variable provided in the macro form. Syntax is (WITH-INPUT-FILE (var filename options*) body+) where options can be any that are legal for open-input-file (which see).

Macro: with-output-file ((binding CONS) &body (body CONS)) : OBJECT

Sets up an unwind-protected form which opens a file for output and closes it afterwards. The stream for writing is bound to the variable provided in the macro form. Syntax is (WITH-OUTPUT-FILE (var filename options*) body+) where options can be any that are legal for open-output-file (which see).

Function: probe-file? ((fileName FILE-NAME)) : BOOLEAN

Return true if file fileName exists. Note that this does not necessarily mean that the file can also be read. IMPORTANT Java idiosyncrasy: if file foo/bar exists and is not a directory, Java will also say foo/bar/ exists, which is different behavior than in Lisp and C++. For this reason, make sure to always use probe-directory? to test whether a directory exists.

Function: file-write-date ((fileName FILE-NAME)) : CALENDAR-DATE

Return the time at which file fileName was last modified or NULL if that cannot be determined.

Function: file-length ((fileName FILE-NAME)) : LONG-INTEGER

Return the length of file fileName in bytes or NULL if that cannot be determined.

Function: copy-file ((fromFile FILE-NAME) (toFile FILE-NAME)) :

Copy file fromFile to file toFile, clobbering any data already in toFile.

Function: delete-file ((fileName FILE-NAME)) :

Delete the file fileName.

Function: rename-file ((fromFile FILE-NAME) (toFile FILE-NAME)) :

Rename the file fromFile to toFile.

Function: make-temporary-file-name ((prefix STRING) (suffix STRING)) : STRING

Return a file name of the form <prefix>NNNNNN<suffix> which is guaranteed to not refer to any existing file. A null prefix defaults to tmpfile, a null suffix defaults to the empty string. The number portion NNNNNN will correpond to a random number between 0 and 999999. If no qualifying filename can be found after 100 attempts, NULL will be returned. Note that it is possible due to multi-threading or processing that the generated filename becomes used by another thread or OS process. If necessary, this case can be handled by the caller.

Function: directory-file-name ((directory FILE-NAME)) : FILE-NAME

Return directory as a file name, i.e., without a terminating directory separator.

Function: directory-parent-directory ((directory FILE-NAME) (level INTEGER)) : FILE-NAME

Return the level-th parent directory component of directory including the final directory separator, or the empty string if directory does not have that many parents.

Function: file-name-as-directory ((file FILE-NAME)) : FILE-NAME

Return file interpreted as a directory, i.e., with a terminating directory separator. If file is the empty string simply return the empty string, i.e., interpret it as the current directory instead of the root directory.

Function: file-name-directory ((file FILE-NAME)) : FILE-NAME

Return the directory component of file including the final directory separator or the empty string if file does not include a directory. Note that for purposes of this function, a logical host is considered part of the directory portion of file

Function: file-name-without-directory ((file FILE-NAME)) : FILE-NAME

Return the file name portion of file by removing any directory and logical host components.

Function: file-name-without-extension ((file FILE-NAME)) : FILE-NAME

Remove files extension (or type) if there is any and return the result.

Function: file-extension ((file FILE-NAME)) : STRING

Return files extension (or type) if it has any including the separator character.

Function: file-base-name ((file FILE-NAME)) : FILE-NAME

Remove files directory (including logical host) and extension components and return the result.

Function: absolute-pathname? ((pathname STRING)) : BOOLEAN

Not documented.

Function: logical-host? ((host STRING)) : BOOLEAN

Not documented.

Function: logical-pathname? ((pathname STRING)) : BOOLEAN

Not documented.

Function: translate-logical-pathname ((pathname STRING)) : STRING

Not documented.

Function: directory-separator () : CHARACTER

Not documented.

Function: directory-separator-string () : STRING

Not documented.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.17 Dates and Times

Function: get-current-date-time () : INTEGER INTEGER INTEGER KEYWORD INTEGER INTEGER INTEGER INTEGER

Returns the current time in UTC as multiple values of year month day day-of-week hour minute second millisecond. Currently millisecond will always be zero (even in Java where it is technically available).

Function: get-local-time-zone () : FLOAT

Returns the current time zone offset from UTC as a float, considering the effects of daylight savings time.

Function: make-current-date-time () : CALENDAR-DATE

Create a calendar date with current time and date.

Function: make-date-time ((year INTEGER) (month INTEGER) (day INTEGER) (hour INTEGER) (minute INTEGER) (second INTEGER) (millis INTEGER) (timezone FLOAT)) : CALENDAR-DATE

Create a calendar date with the specified components. year must be the complete year (i.e., a year of 98 is 98 A.D in the 1st century). timezone is a real number in the range -12.0 to +14.0 where UTC is zone 0.0; The number is the number of hours to add to UTC to arrive at local time.

Function: parse-date-time ((date-time-string STRING) (start INTEGER) (end INTEGER) (error-on-mismatch? BOOLEAN)) : DECODED-DATE-TIME

Tries very hard to make sense out of the argument date-time-string and returns a time structure if successful. If not, it returns null. If error-on-mismatch? is true, parse-date-time will signal an error instead of returning null. Default values are 00:00:00 local time on the current date

Method on CALENDAR-DATE: decode-calendar-date (date (timezone FLOAT)) : DECODED-DATE-TIME

Returns a decoded time object for date interpreted in timezone timezone is the number of hours added to UTC to get local time. It is in the range -12.0 to +14.0 where UTC is zone 0.0

Method on DECODED-DATE-TIME: encode-calendar-date (time-structure) : CALENDAR-DATE

Returns a calendar date object for time-structure.

???: calendar-date-to-string

Not yet implemented.

Function: string-to-calendar-date ((input STRING)) : CALENDAR-DATE

Returns a calendar date object representing the date and time parsed from the input string. If no valid parse is found, null is returned.

???: relative-date-to-string

Not yet implemented.

Function: compute-calendar-date ((julian-day INTEGER)) : INTEGER INTEGER INTEGER KEYWORD

Returns the YEAR, MONTH, DAY, DAY-OF-WEEK on which the given julian-day begins at noon.

Function: compute-day-of-week ((yyyy INTEGER) (mm INTEGER) (dd INTEGER)) : KEYWORD

Returns the day of the week for yyyy-mm-dd.

Function: compute-day-of-week-julian ((julian-day INTEGER)) : KEYWORD

Returns the day of the week for julian-day

Function: compute-julian-day ((yyyy INTEGER) (mm INTEGER) (dd INTEGER)) : INTEGER

Returns the Julian day that starts at noon on yyyy-mm-dd. yyyy is the year. mm is the month. dd is the day of month. Negative years are B.C. Remember there is no year zero.

Function: compute-next-moon-phase ((n INTEGER) (phase KEYWORD)) : INTEGER FLOAT

Returns the Julian Day and fraction of day of the Nth occurence since January 1, 1900 of moon PHASE. PHASE is one of :NEW-MOON, :FIRST-QUARTER, :FULL-MOON, :LAST-QUARTER

Function: decode-time-in-millis ((time INTEGER)) : INTEGER INTEGER INTEGER INTEGER

Returns multiple values of hours, minutes, seconds, milliseconds for time specified in milliseconds.

Function: julian-day-to-modified-julian-day ((julian-day INTEGER)) : INTEGER

Returns the modified Julian day during which julian-daystarts at noon.

Function: modified-julian-day-to-julian-day ((modified-julian-day INTEGER)) : INTEGER

Returns the modified Julian day during which julian-daystarts at noon.

Function: time-add ((t1 DATE-TIME-OBJECT) (t2 DATE-TIME-OBJECT)) : DATE-TIME-OBJECT

Add t1 to t2. If one of t1 or t2 is a calendar date, then the result is a calendar date. If both t1 and t2 are relative dates, then the result is a relative date. t1 and t2 cannot both be calendar dates.

Function: time-divide ((t1 TIME-DURATION) (t2 OBJECT)) : OBJECT

Divides the relative date t1 by t2. t2 must be either a relative date or a wrapped number. If t2 is a relative date, then the return value will be a wrapped float. If t2 is a wrapped number, then the reutrn value will be a relative date.

Function: time-multiply ((t1 OBJECT) (t2 OBJECT)) : TIME-DURATION

Multiplies a relative date by a wrapped number. One of t1 or t2 must be a relative date and the other a wrapped number.

Function: time-subtract ((t1 DATE-TIME-OBJECT) (t2 DATE-TIME-OBJECT)) : DATE-TIME-OBJECT

Subtract t2 from t1. If t1 is a calendar date, then t2 can be either a calendar date (in which case the return value is a relative date) or it can be a relative date (in which case the return value is a calendar date). If t1 is a relative date, then t2 must also be a relative date and a relative date is returned.

Function: get-ticktock () : TICKTOCK

Return the current CPU time. If the current OS/Language combination does not support measuring of CPU time, return real time instead. Use ticktock-difference to measure the time difference between values returned by this function. This is an attempt to provide some platform independent support to measure (at least approximately) consumed CPU time.

Function: ticktock-difference ((t1 TICKTOCK) (t2 TICKTOCK)) : FLOAT

The difference in two TICKTOCK time values in seconds where t1 is the earlier time. The resolution is implementation dependent but will normally be some fractional value of a second.

Function: ticktock-resolution () : FLOAT

The minimum theoretically detectable resolution of the difference in two TICKTOCK time values in seconds. This resolution is implementation dependent. It may also not be realizable in practice, since the timing grain size may be larger than this resolution.

Function: sleep ((seconds FLOAT)) :

The program will sleep for the indicated number of seconds. Fractional values are allowed, but the results are implementation dependent: Common Lisp uses the fractions natively, Java with a resolution of 0.001, and C++ can only use integral values.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.18 XML Support

Function: make-xml-element ((name STRING) (namespace-name STRING) (namespace STRING)) : XML-ELEMENT

Creates and interns an XML element object name using namespace-name to refer to namespace. If namespace is null, then the element will be interned in the null namespace. namespace must otherwise be a URI.

Function: make-xml-global-attribute ((name STRING) (namespace-name STRING) (namespace STRING)) : XML-GLOBAL-ATTRIBUTE

Creates and interns an XML global attribute object with name using namespace-name to refer to namespace. namespacemust be a URI.

Function: make-xml-local-attribute ((name STRING) (element XML-ELEMENT)) : XML-LOCAL-ATTRIBUTE

Make an XML-LOCAL-ATTRIBUTE named name associated with element

Function: get-xml-tag ((expression CONS)) : XML-ELEMENT

Return the XML tag object of an XML expression.

Function: get-xml-attributes ((expression CONS)) : CONS

Return the list of attributes of an XML expression (may be empty).

Function: get-xml-content ((expression CONS)) : CONS

Return the list of content elements of an XML expression (may be empty).

Function: get-xml-cdata-content ((form CONS)) : STRING

Return the CDATA content of a CDATA form. Does NOT make sure that form actually is a CDATA form, so bad things can happen if it is given wrong input.

Function: xml-declaration? ((item OBJECT)) : BOOLEAN

Return true if item is an XML declaration object

Function: xml-element? ((item OBJECT)) : BOOLEAN

Return true if item is an XML element object

Function: xml-attribute? ((item OBJECT)) : BOOLEAN

Return true if item is an XML attribute object

Function: xml-cdata? ((item OBJECT)) : BOOLEAN

Return true if item is an XML CDATA tag object

Function: xml-cdata-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by a CDATA tag

Method on XML-ELEMENT: xml-element-match? (tag (name STRING) (namespace STRING)) : BOOLEAN

Returns true if tag is an XML element with the name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case tag must not have a namespace associated with it.

Method on XML-ATTRIBUTE: xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is an XML attribute with name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case attribute must not have a namespace associated with it.

Method on XML-GLOBAL-ATTRIBUTE: xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is a global XML attribute with name name in namespace namespace. Note that namespace is the full URI, not an abbreviation. Also, namespace may be null, in which case attribute must not have a namespace associated with it.

Method on XML-LOCAL-ATTRIBUTE: xml-attribute-match? (attribute (name STRING) (namespace STRING)) : BOOLEAN

Return true if attribute is a local XML attribute with name name. Note that namespace must be null and that the attributes parent element element is not considered by the match. To take the parent element into account use xml-local-attribute-match?.

Function: xml-local-attribute-match? ((attribute XML-LOCAL-ATTRIBUTE) (name STRING) (element-name STRING) (element-namespace STRING)) : BOOLEAN

Return true if attribute is a local attribute with name and whose parent element matches element-name and element-namespace.

Function: xml-lookup-attribute ((attributes CONS) (name STRING) (namespace STRING)) : STRING

Find the XML attribute in attributes with name and namespace and return its value. Note that it is assumed that all attributes come from the same known tag, hence, the parent elements of any local attributes are not considered by the lookup.

Macro: xml-tag-case ((item OBJECT) &body (clauses CONS)) : OBJECT

A case form for matching item against XML element tags. Each element of clauses should be a clause with the form ("tagname" ...) or (("tagname" "namespace-uri") ...) The clause heads can optionally be symbols instead of strings. The key forms the parameters to the method xml-element-match?, with a missing namespace argument passed as NULL.

The namespace argument will be evaluated, so one can use bound variables in place of a fixed string. As a special case, if the namespace argument is :ANY, then the test will be done for a match on the tag name alone.

Function: read-xml-expression ((stream INPUT-STREAM) (start-tag OBJECT)) : OBJECT BOOLEAN

Read one balanced XML expression from stream and return its s-expression representation (see xml-token-list-to-s-expression). If startTagName is non-‘null’, skip all tags until a start tag matching start-tag is encountered. XML namespaces are ignored for outside of the start tag. Use s-expression representation to specify start-tag, e.g., (KIF (:version "1.0")). The tag can be an XML element object, a symbol, a string or a cons. If the tag is a cons the first element can also be (name namespace) pair.

Return true as the second value on EOF.

CHANGE WARNING: It is anticipated that this function will change to a) Properly take XML namespaces into account and b) require XML element objects instead of strings as the second argument. This change will not be backwards-compatible.

Function: xml-expressions ((stream INPUT-STREAM) (regionTag OBJECT)) : XML-EXPRESSION-ITERATOR

Return an XML-expression-iterator (which see) reading from stream. regionTag can be used to define delimited regions from which expressions should be considered. Use s-expression representation to specify regionTag, e.g., (KIF (:version "1.0")). The tag can be an XML element object, a symbol, a string or a cons. If the tag is a cons the first element can also be (name namespace) pair.

Function: print-xml-expression ((stream OUTPUT-STREAM) (xml-expression CONS) (indent INTEGER)) :

Prints xml-expression on stream. Indentation begins with the value of indent. If this is the null integer, no indentation is performed. Otherwise it should normally be specified as 0 (zero) for top-level calls.

It is assumed that the xml-expression is a well-formed CONS-list representation of an XML form. It expects a form like that form returned by read-XML-expression.

Also handles a list of xml forms such as that returned by XML-expressions. In that case, each of the forms is indented by indent spaces.

Function: reset-xml-hash-tables () :

Resets Hashtables used for interning XML elements and global attribute objects. This will allow garbage collection of no-longer used objects, but will also mean that newly parsed xml elements and global attributes will not be eq? to already existing ones with the same name.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.19 Miscellaneous

This is a catch-all section for functions and methods that haven’t been categorized yet into any of the previous sections. They are in random order and many of them will never be part of the official STELLA interface. So beware!

Function: operating-system () : KEYWORD

Not documented.

Method on DIMENSIONAL-ARRAY-MIXIN: 1d-aref (self (i INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position [i].

Method on DIMENSIONAL-ARRAY-MIXIN: 1d-aref-address (self (i INTEGER)) : INTEGER

Return the 1D address of the element at position [i]. This is useful for fast element-wise iteration that doesn’t need arithmetic.

Method on DIMENSIONAL-ARRAY-MIXIN: 1d-aref-setter (self (value (LIKE (ANY-VALUE SELF))) (i INTEGER)) : (LIKE (ANY-VALUE SELF))

Set the element of self at position [i] to value and return the result.

Method on 2-DIMENSIONAL-ARRAY-MIXIN: 2d-aref (self (i INTEGER) (j INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element of self at position [i, j].

Method on 2-DIMENSIONAL-ARRAY-MIXIN: 2d-aref-address (self (i INTEGER) (j INTEGER)) : INTEGER

Return the 1D address of the element at position [i, j]. This is useful for fast element-wise iteration that doesn’t need arithmetic.

Method on 2-DIMENSIONAL-ARRAY-MIXIN: 2d-aref-setter (self (value (LIKE (ANY-VALUE SELF))) (i INTEGER) (j INTEGER)) : (LIKE (ANY-VALUE SELF))

Set the element of self at position [i, j] to value and return the result.

Method on LONG-INTEGER: abs (x) : LONG-INTEGER

Return the absolute value of x.

Function: activate-demon ((demon DEMON)) :

Install demon in the location(s) specified by its internal structure.

Method on POLYMORPHIC-RELATION: active? (self) : BOOLEAN

True if self or a superslot of self is marked active.

Function: add-configuration-property ((property STRING) (value OBJECT) (configuration CONFIGURATION-TABLE)) : OBJECT

Add value to property in configuration and return it. If a previous value exists add value to the end (listify the old value if it is not yet a list). Otherwise, create a new list containing value. Use the global system configuration table if configuration is NULL.

Function: add-current-date-substitution ((substitution-list (KEY-VALUE-LIST OF STRING-WRAPPER STRING-WRAPPER))) :

Fill in substitution-list with date information for the current date and time. See add-date-substitution for details.

Function: add-date-substitution ((date CALENDAR-DATE) (substitution-list (KEY-VALUE-LIST OF STRING-WRAPPER STRING-WRAPPER))) :

Fill in substitution-list with template variable substitions for the names YEAR, MONTH, MON, DAY, HOUR, MINUTE, SECOND, TIMEZONE, DAY-OF-WEEK, DOW with their values for date. Also, pre-formatted DATE, TIME and ISO8601 variables are set.

TIMEZONE is in the format "{+|-}hhmm". MONTH is the full English month name and MON is the numeric month. DAY-OF-WEEK is an English string and DOW is the first three letters. Minutes and seconds are zero-padded.

These substitutions can be used with substitute-template-variables-in-string

Function: add-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :

Insert the function named hookFunction into hookList.

Command: add-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Append the directories listed in the |-separated path to the end of the STELLA load path. Return the resulting load path.

Command: add-property-value ((property NAME) (value OBJECT)) :

Add value to the end of propertys (a string or symbol) value list in the configuration table. Coerces the current value to a list or initializes the list if it is as yet undefined. Allows incremental addition of values to list-valued propertys. Note that property is evaluated and will need to be quoted if supplied as a symbol. Symbols will also be upcased if this command is run in a non-case-sensitive module.

N-Command: add-trace (&rest (keywords GENERALIZED-SYMBOL)) : LIST

Enable trace messages identified by any of the listed keywords. After calling (add-trace <keyword>) code guarded by (trace-if <keyword> ...) will be executed when it is encountered.

Function: advance-past-whitespace ((source STRING) (start INTEGER)) : INTEGER

Returns the first index into source, starting from start, of the first character that is not white space.

Function: all-classes ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF CLASS)

Iterate over all classes visible from module. If local?, return only classes interned in module. If module is null, return all classes interned everywhere.

Function: all-contexts () : (ITERATOR OF CONTEXT)

Return an iterator that generates all contexts.

Macro: all-defined? (&body (forms CONS)) : OBJECT

Evaluate each of the forms in forms, and return TRUE if none of them are NULL.

Function: all-functions ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF FUNCTION)

Iterate over all functions visible from module. If local?, return only functions bound to symbols interned in module. If module is null, return all functions defined everywhere.

Function: all-included-modules ((self MODULE)) : (ITERATOR OF MODULE)

Generate a sequence of all modules included by self, inclusive, starting from the highest ancestor and working down to self (which is last).

Function: all-methods ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF METHOD-SLOT)

Iterate over all methods visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-modules () : (ITERATOR OF MODULE)

Return an iterator that generates all modules.

Function: all-public-functions ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF FUNCTION)

Iterate over all functions visible from module. If local?, return only functions bound to symbols interned in module. If module is null, return all functions defined everywhere.

Function: all-public-methods ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF METHOD-SLOT)

Iterate over all public methods visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-required-systems ((system-name STRING)) : (CONS OF STRING-WRAPPER)

Returns a CONS of all of the systems required by system-name

Function: all-slots ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SLOT)

Iterate over all slots visible from module. If local?, return only methods interned in module. If module is null, return all methods interned everywhere.

Function: all-subcontexts ((context CONTEXT) (traversal KEYWORD)) : (ALL-PURPOSE-ITERATOR OF CONTEXT)

Return an iterator that generates all subcontexts of self (not including self) in the order specified by traversal (one of :preorder, :inorder, :postorder or :topdown).

Function: all-surrogates ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SURROGATE)

Iterate over all surrogates visible from module. If local?, return only surrogates interned in module. If module is null, return all surrogates interned everywhere.

Function: all-symbols ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SYMBOL)

Iterate over all symbols visible from module. If local?, return only symbols interned in module. If module is null, return all symbols interned everywhere.

Function: all-variables ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF GLOBAL-VARIABLE)

Iterate over all variables visible from module. If local?, return only variables bound to symbols interned in module. If module is null, return all variables defined everywhere.

Function: allocate-cross-product-iterator ((domains (CONS OF CONS))) : CROSS-PRODUCT-ITERATOR

Allocate a cross product iterator for a list of domains.

Method on ABSTRACT-ITERATOR: allocate-iterator (self) : (LIKE SELF)

Iterator objects return themselves when asked for an iterator (they occupy the same position as a collection within a foreach statement).

Method on MEMOIZABLE-ITERATOR: allocate-iterator (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Alias for clone-memoized-iterator.

Method on STORAGE-SLOT: allocation (self) : KEYWORD

Return the most specific :allocation facet, or :instance if all inherited values are NULL.

Method on BUFFERED-STRING: append-character (self (char CHARACTER)) :

Append char to the END of the string self. Resize the buffer if necessary.

Method on BUFFERED-STRING: append-string (self (value STRING)) :

Append value to the END of the string self. Resize the buffer if necessary.

Function: apply ((code FUNCTION-CODE) (arguments (CONS OF OBJECT))) : OBJECT

Apply code to arguments, returning a value of type OBJECT. Currently limited to at most 10 arguments.

Function: apply-boolean-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : BOOLEAN

Apply code to arguments, returning a value of type BOOLEAN.

Function: apply-float-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : FLOAT

Apply code to arguments, returning a value of type FLOAT.

Function: apply-integer-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : INTEGER

Apply code to arguments, returning a value of type INTEGER.

Function: apply-long-integer-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : LONG-INTEGER

Apply code to arguments, returning a value of type LONG-INTEGER.

Function: apply-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : OBJECT

Apply code to arguments, returning a value of type OBJECT.

Function: apply-string-method ((code METHOD-CODE) (arguments (CONS OF OBJECT))) : STRING

Apply code to arguments, returning a value of type STRING.

Function: autoload ((qualifiedName STRING) (systemName STRING) (cache SURROGATE) (error? BOOLEAN)) : FUNCTION-CODE

Autoload function qualifiedName from system systemName. If it is already present in the system, simply return its code. If cache is defined, return its value if defined, otherwise, set its value to the function found. If the function failed to be defined by loading systemName and error? is true, raise an error. Otherwise, simply return NULL.

Function: base60-to-float ((l (CONS OF NUMBER-WRAPPER))) : FLOAT

Converts (x y z) into a float. The return value is x + y/60 + z/3600. This can be used to convert from Degree-Minute-Second to decimal degrees or from Hour-Minute-Second format to decimal hours.

Function: blank-string? ((string STRING)) : BOOLEAN

Return true if string is either NULL, empty, or only contains white space characters.

Command: break-program ((message STRING)) :

Interrupt the program and print message. Continue after confirmation with the user.

Command: bump-log-indent () :

Increase the indentation level for subsequent log messages.

Function: byte-array-read-sequence ((buffer TOKENIZER-BYTE-ARRAY) (stream INPUT-STREAM) (start INTEGER) (end INTEGER)) : INTEGER

Read from stream filling buffer between start and end (depending on how many characters are available). Return the actual end pointer to the input read into buffer. EOF is indicated by the return value being equal to start.

Function: byte-array-write-sequence ((buffer TOKENIZER-BYTE-ARRAY) (stream NATIVE-OUTPUT-STREAM) (start INTEGER) (end INTEGER)) :

Write from buffer to stream, using data in the buffer starting at position start stopping just before end.

Method on CALENDAR-DATE: calendar-date-to-date-string (date (timezone FLOAT) (numeric-month? BOOLEAN)) : STRING

Returns the date part of the string representation of date adjusted for timezone. Format is YYYY-MMM-DD, where MMM is a three letter English abbreviation of the month if numeric-month? is false and a two digit numeric value if numeric-month? is true. The value false is recommended.

Method on CALENDAR-DATE: calendar-date-to-iso8601-string (date (timezone FLOAT) (include-timezone? BOOLEAN)) : STRING

Returns an ISO-8601 string representation of date adjusted for timezone. The Format is YYYY-MM-DDThh:mm:ss z:zz. The timezone as an offset hh:mm is included if include-timezone? is true.

Recommended values for the flag is true.

Method on CALENDAR-DATE: calendar-date-to-string (date (timezone FLOAT) (numeric-month? BOOLEAN) (include-timezone? BOOLEAN)) : STRING

Returns a string representation of date adjusted for timezone. The Format is YYYY-MMM-DD hh:mm:ss z.z, where MMM is a three letter English abbreviation of the month if numeric-month? is false and a two digit numeric value if numeric-month? is true. The timezone as a float offset z.z is included if include-timezone? is true.

Recommended values for the flags are false and true respectively.

Method on CALENDAR-DATE: calendar-date-to-time-string (date (timezone FLOAT) (include-timezone? BOOLEAN) (include-millis? BOOLEAN) (pad-hours? BOOLEAN)) : STRING

Returns the time part of the string representation of date adjusted for timezone. The timezone is included in the string if include-timezone? is true. The value true is recommended. Milliseconds will be included if include-millis? is true. Hours will be zero-padded to length 2 if pad-hours? is true.

Command: call-clear-module (&rest (name NAME)) :

Destroy all objects belonging to module name or any of its children. If no name is supplied, the current module will be cleared after confirming with the user. Important modules such as STELLA are protected against accidental clearing.

Function: canonical-slot ((slot STORAGE-SLOT)) : STORAGE-SLOT

Computes the slot at the base of a renaming chain for slot.

Function: canonical-slot-name ((slot STORAGE-SLOT)) : SYMBOL

Name of the slot at the base of a renaming chain for slot.

Function: cast ((value OBJECT) (type TYPE)) : OBJECT

Perform a run-time type check, and then return value.

N-Command: ccc (&rest (name NAME)) : CONTEXT

Change the current context to the one named name. Return the value of the new current context. If no name is supplied, return the pre-existing value of the current context. cc is a no-op if the context reference cannot be successfully evaluated. In CommonLisp, if the new context is case sensitive, then change the readtable case to the value of CL-USER::*STELLA-CASE-SENSITIVE-READ-MODE* [default = :INVERT], otherwise to :UPCASE.

Function: cl-slot-value ((object OBJECT) (slotName STRING) (dontConvert? BOOLEAN)) : LISP-CODE

Lookup slot slotName on object and return the lispified slot value (see lispify). If dontConvert? is TRUE, the returned slot value will not be lispified. Generate a warning if no such slot exists on object. In a call directly from Lisp slotName can also be supplied as a Lisp symbol.

Function: cl-slot-value-setter ((object OBJECT) (slotName STRING) (value LISP-CODE) (dontConvert? BOOLEAN)) : LISP-CODE

Lookup slot slotName on object and set its value to the stellafied value (see stellafy). If dontConvert? is TRUE, value will not be stellafied before it gets assigned. Generate a warning if no such slot exists on object, or if value has the wrong type. In a call directly from Lisp slotName can also be supplied as a Lisp symbol.

Function: cl-translate-file ((file FILE-NAME) (relative? BOOLEAN)) :

Translate a Stella file to Common-Lisp. If relative?, concatenate root directory to file.

Function: cl-translate-system ((system-name STRING)) :

Translate a Stella system named system-name to Common Lisp.

Function: cleanup-unfinalized-classes () :

Remove all finalized classes from *UNFINALIZED-CLASSES*, and set *NEWLY-UNFINALIZED-CLASSES?* to false.

Method on VECTOR-SEQUENCE: clear (self) :

Clear self by setting its active length to zero.

Method on HEAP: clear (self) :

Clear self by setting its active length to zero.

Method on BUFFERED-STRING: clear (self) :

Clear self by setting its active length to zero.

Function: clear-configuration-property ((property STRING) (configuration CONFIGURATION-TABLE)) : OBJECT

Remove property in configuration and return the previous value. Use the global system configuration table if configuration is NULL.

Function: clear-input ((self INPUT-STREAM)) :

Clear all buffered raw and tokenized input of self.

Function: clear-recycle-list ((list RECYCLE-LIST)) :

Reset list to its empty state.

Function: clear-recycle-lists () :

Reset all currently active recycle lists to their empty state.

Function: clear-system ((name STRING)) :

Clears out the system definition named name. If name is null, then clear out all system definitions. This function is useful when changes have been made to the system definition, and one wants to have it reloaded from the standard location in the file system.

Command: clear-trace () :

Disable all tracing previously enabled with add-trace.

Function: clone-memoized-iterator ((self MEMOIZABLE-ITERATOR)) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))

Clone the memoized iterator self so it can be used to iterate over the collection represented by self, while allowing to iterate over it multiple times via multiple clones.

Macro: clv ((code OBJECT)) : OBJECT

Convenience macro to splice Lisp expressions into STELLA expressions without upsetting the translator during interactive sessions. If code is a currently bound Lisp variable, this tries to infer the type of the resulting expression from the object code is bound to and generates an appropriate cast. clv stands for Common-Lisp Value or Verbatim.

Macro: coerce-&rest-to-cons ((restVariable SYMBOL)) : OBJECT

Coerce the argument list variable restVariable into a CONS list containing all its elements (uses argument list iteration to do so). If restVariable already is a CONS due to argument listification, this is a no-op.

Function: coerce-option-value ((value OBJECT) (type TYPE)) : OBJECT

Coerce value to type. Return NULL if not possible.

Function: coerce-to-boolean ((object OBJECT)) : BOOLEAN-WRAPPER

Return the boolean object represented by object. Return NULL if coercion is not possible.

Function: coerce-to-float ((object OBJECT)) : FLOAT

Coerce number to a float value or NULL if not possible.

Function: coerce-to-hash-set ((self OBJECT) (equalTest? BOOLEAN)) : HASH-SET

Coerce the collection self into a HASH-SET. Use an equal test if equalTest? is TRUE (equalTest? will be ignored if self already is a HASH-SET).

Function: coerce-to-string ((object OBJECT)) : STRING

Coerce object into a string. If no standard coercion is possible, simply stringify object.

Function: coerce-to-symbol ((name NAME)) : GENERALIZED-SYMBOL

Return the (generalized) symbol represented by name. Return null if name is undefined or does not represent a string.

Function: coerce-value-to-boolean ((value OBJECT) (error? BOOLEAN)) : BOOLEAN-WRAPPER

Return the boolean object represented by value. Return NULL if coercion is not possible or raise an error if error? is TRUE.

Function: coerce-value-to-float ((value OBJECT) (error? BOOLEAN)) : FLOAT

Coerce value to a float value if possible, return NULL otherwise or raise an error if error? is true.

Function: coerce-value-to-string ((value OBJECT) (error? BOOLEAN)) : STRING

Coerce value into a string if possible, return NULL otherwise or raise an error if error? is true.

Function: coerce-value-to-type ((value OBJECT) (type TYPE) (error? BOOLEAN)) : OBJECT

Coerce value to type. Return NULL if not possible or raise an error if error? is TRUE.

Macro: collect (&body (body CONS)) : OBJECT

Use a VRLET to collect values. Input can have one of the following forms:

 
  (collect <var> in <expression> [where <test> <var>])
  (collect <collect-expression>
           foreach <var> in <expression>
           {as ...}*
           [where <test> <var>]
           [do ...])

The second form really accepts an arbitrary foreach expression following the foreach keyword.

Method on SLOT: collection-valued? (self) : BOOLEAN

True if slot values are collections.

Function: command? ((method METHOD-SLOT)) : BOOLEAN

Return true if method is an evaluable command.

Function: compare-strings ((x STRING) (y STRING) (collation KEYWORD)) : INTEGER

Compare x and y and return -1, 0, or 1, depending on whether x is less than, equal, or greater than y relative to collation. Currently supported values for collation are :ascii-case-sensitive, :ascii-case-insensitive :ascii-case-normalized. The first two correspond to string-compare called with the appropriate third argument. :ascii-case-normalized calls the function string-compare-case-normalized (which see).

Method on STORAGE-SLOT: component? (self) : BOOLEAN

True if fillers of this slot are components of the owner slot, and therefore should be deleted if the owner is deleted.

Function: compose-namestring ((name-components (CONS OF STRING-WRAPPER)) &rest (options OBJECT)) : STRING

name-components is a cons to be processed into a namestring. :prefix and :suffix are strings that will NOT be case-converted. :case is one of :UPCASE :TitleCase :titleCaseX :downcase :Capitalize default is :TitleCase :separator is a string that should separate word elements. It does not separate the prefix or suffix. Default is "" :translation-table should be a STRING-HASH-TABLE hash table that strings into their desired printed representation as a string. In general the argument will be strings, but that is not strictly necessary.

Function: compose-namestring-full ((strings (CONS OF STRING-WRAPPER)) (prefix STRING) (suffix STRING) (outputcase KEYWORD) (outputseparator STRING) (translationtable STRING-HASH-TABLE) (useacronymheuristics? BOOLEAN)) : STRING

Non-keyword version of compose-namestring, which will probably be easier to use when called from non-Lisp languages.

Function: compute-module-and-bare-name ((name STRING)) : MODULE STRING

Compute the module indicated by the STELLA name name and return it. Return the bare symbol name as the second value. name does not necessarily have to be qualified in which case the current module is returned. name is assumed to be the printed representation of a STELLA symbol, surrogate or keyword.

Function: compute-system-root-directories ((system SYSTEM-DEFINITION)) :

Compute any root directories for sources, native and Lisp binary directories in case they were not explicitly specified in systems definition. Raises an error in case any of those root directories is missing and can’t be computed.

Function: concatenate-file-names ((file FILE-NAME) &rest (otherFiles FILE-NAME)) : FILE-NAME

Intelligently join file and otherFiles into a concatenated path where each component is separated by a single separator (similar to Python’s os.path.join). Keeps the result a logical pathname as long as possible, but converts to physical as soon as any of otherFiles contain a physical directory separator.

Function: config-file-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Load the configuration file value. This will modify currently set system properties defined in value with new values but leave all other currently set properties as they are.

Command: configure-stella ((file FILE-NAME)) :

Perform STELLA run-time configuration. If supplied, load the configuration file file first which should be supplied with a physical pathname.

Method on OBJECT: consify (self) : CONS

If object is a CONS, return it. Otherwise, return a singleton cons list containing it.

Function: consify-command-line-arguments ((count INTEGER) (arguments (ARRAY () OF STRING))) : (CONS OF STRING-WRAPPER)

Convert count command line arguments into a CONS list.

Macro: continuable-error (&body (body CONS)) : OBJECT

Signal error message, placing non-string arguments in quotes.

Method on VECTOR-SEQUENCE: copy (self) : (VECTOR-SEQUENCE OF (LIKE (ANY-VALUE SELF)))

Return a copy of the vector sequence self.

Method on CUSTOM-VECTOR-SEQUENCE: copy (self) : (CUSTOM-VECTOR-SEQUENCE OF (LIKE (ANY-VALUE SELF)))

Return a copy of the vector sequence self.

Method on HEAP: copy (self) : (HEAP OF (LIKE (ANY-VALUE SELF)))

Return a copy of the heap self.

Method on MUTABLE-STRING: copy (string) : MUTABLE-STRING

Return a copy of string.

Function: copy-stream-to-stream ((in INPUT-STREAM) (out OUTPUT-STREAM)) :

Copy in verbatimely to out. Does the right thing for binary data.

Function: cpp-find-native-slot-value-offset ((self STANDARD-OBJECT) (slot STORAGE-SLOT)) : INTEGER

Dynamically determine the byte offset where the native value for slot starts in self. This basically performs the function of the C++ macro offsetof but does it dynamically. Of course, it relies on a working read/write-slot-value mechanism and we currently primarily use this for the Python API. This basically writes value changes of slot to determine a byte position where a change occurred and then restores the original value (which can be NULL). This handles all native OBJECT and LITERAL slots but does not handle special slots such as dynamic-slots or hardwired slots or other non-standard types.

Function: cpp-translate-system ((systemName STRING)) :

Translate the system systemName to C++.

N-Command: cpptrans ((statement OBJECT)) :

Translate statement to C++ and print the result.

Function: create-derived-list ((self LIST)) : LIST

Create a new list object with the same type as self.

Command: create-directories ((directory STRING)) :

If directory does not yet exist, create it and any of its parents that do not yet exist. If directory already does exist, this simply is a no-op.

Function: create-object ((type TYPE) &rest (initial-value-pairs OBJECT)) : OBJECT

Funcallable version of the new operator. Return an instance of the class named by type. If initial-value-pairs is supplied, it has to be a key/value list similar to what’s accepted by new and the named slots will be initialized with the supplied values. Similar to new, all required arguments for type must be included. Since all the slot initialization, etc. is handled dynamically at run time, create-object is much slower than new; therefore, it should only be used if type cannot be known at translation time.

Function: date-to-version-string ((date CALENDAR-DATE) (granularity KEYWORD)) : STRING

Transform date into a version string according to granularity which is at least :days and defaults to :seconds.

Function: deactivate-demon ((demon DEMON)) :

Detach demon from the location(s) specified by its internal structure.

Method on DECODED-DATE-TIME: decoded-date-time-to-iso8601-string (date) : STRING

Returns an ISO-8601 string representation of date The Format is YYYY-MM-DDThh:mm:ss+zz:zz, with the string stopping at when a null value is first encountered. The time zone will only be included (if present) if a time value is given.

Function: decompose-namestring ((namestring STRING) &rest (options OBJECT)) : (CONS OF STRING-WRAPPER)

Keyword options: :break-on-cap one of :YES :NO :CLEVER default is :CLEVER :break-on-number one of :YES :NO :CLEVER default is :CLEVER :break-on-separators string default is "-_ "

DECOMPOSE-NAMESTRING returns a cons of STRING-WRAPPERS that are the decomposition of the input STRING. The arguments are used as follows: namestring is the input string. :break-on-cap is a keyword controlling whether changes in capitalization is used to indicate word boundaries. If :YES, then all capitalization changes delineate words. If :CLEVER, then unbroken runs of capitalized letters are treated as acronyms and remain grouped. If :NO or NULL, there is no breaking of words based on capitalization. :break-on-number is a flag controlling whether encountering a number indicates a word boundary. If :YES, then each run of numbers is treated as a word separate from surrounding words. If :CLEVER, then an attempt is made to recognize ordinal numbers (ie, 101st) and treat them as separate words. If :NO or NULL, there is no breaking of words when numbers are encountered. :break-on-separators A string of characters which constitute word delimiters in the input word. This is used to determine how to break the name into individual words. Defaults are space, - and _.

Function: decompose-namestring-full ((namestring STRING) (break-on-cap KEYWORD) (break-on-number KEYWORD) (break-on-separators STRING)) : (CONS OF STRING-WRAPPER)

Non-keyword version of decompose-namestring, which will probably be easier to use when called from non-Lisp languages.

Function: default-cmd-line-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Default handler that tries to set a system property based on option and value.

Method on STORAGE-SLOT: default-form (self) : OBJECT

Returns the current value of default expression when the slot has not been assigned a value.

Macro: defdemon ((name STRING-WRAPPER) (parameterstree CONS) &body (optionsandbody CONS)) : OBJECT

Define a demon name and attach it to a class or slot.

Function: define-demon ((name STRING) &rest (options OBJECT)) : DEMON

Define a class or slot demon. Options are :create, :destroy, :class, :slot, :guard?, :code, :method, :inherit?, and :documentation.

Function: define-global-variable-object ((definition STRING) (nativeObject NATIVE-OBJECT-POINTER)) :

Define a STELLA global variable object based on definition, and initialize its variable-native-object slot to nativeObject (which is primarily needed for C++).

Command: define-logical-host-property ((host STRING) (property KEYWORD) (value OBJECT)) :

Define property with value for the logical host host. As a side-effect, this also defines host as a logical host (both property and value can be supplied as NULL). If :ROOT-DIRECTORY is specified, all pathnames with host are assumed to be relative to that directory (even if they are absolute) and will be rerooted upon translation. :ROOT-DIRECTORY can be a logical or physical pathname. If :LISP-TRANSLATIONS is specified, those will be used verbatimely as the value of (CL:logical-pathname-translations host) if we are running in Lisp, which allows us to depend on the native CL:translate-logical-pathname for more complex translation operations.

Function: define-module ((name STRING) (options CONS)) : MODULE

Define or redefine a module named name having the options options. Return the new module.

Function: define-stella-class ((name TYPE) (supers (LIST OF TYPE)) (slots (LIST OF SLOT)) (options KEYWORD-KEY-VALUE-LIST)) : CLASS

Return a Stella class with name name. Caution: If the class already exists, the Stella class object gets redefined, but the native C++ class is not redefined.

Function: define-stella-global-variable-from-stringified-source ((stringifiedSource STRING)) :

Define a stella global variable using a parse tree derived from stringifiedSource.

Function: define-stella-method-slot ((inputname SYMBOL) (returntypes CONS) (function? BOOLEAN) (inputParameters CONS) (options KEYWORD-KEY-VALUE-LIST)) : METHOD-SLOT

Define a new Stella method object (a slot), and attach it to the class identified by the first parameter in inputParameters.

Method on LONG-INTEGER: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Method on ARRAY: defined? (x) : BOOLEAN

Return true if x is defined (handled specially by all translators).

Macro: defmain ((varList CONS) &body (body CONS)) : OBJECT

Defines a function called MAIN which will have the appropriate signature for the target translation language. The signature will be: C++: public static int main (int v1, char** v2) {<body>} Java: public static void main (String [] v2) {<body>} Lisp: (defun main (&rest args) <body>) The argument varList must have two symbols, which will be the names for the INTEGER argument count and an array of STRINGs with the argument values. It can also be empty to indicate that no command line arguments will be handled. The startup function for the containing system will automatically be called before body is executed unless the option :STARTUP-SYSTEM? was supplied as FALSE. There can only be one DEFMAIN per module.

N-Command: defsystem ((name SYMBOL) &rest (options OBJECT)) : SYSTEM-DEFINITION

Define a system of files that collectively define a Stella application. Required options are: :directory – the relative path from the respective source/native/binary root directory to the directory containing the system files. Can be a string or a list of strings (do not include directory separators). :files – a list of files in the system, containing strings and lists of strings; the latter defines exploded paths to files in subdirectories. Optional options are: :data-files – a list of files like the :files keyword, which contain data or other content that should not be processed, but instead copied verbatim to the native directory :required-systems – a list of systems (strings) that should be loaded prior to loading this system. :cardinal-module – the name (a string) of the principal module for this system. :copyright-header – string with a header for inclusion into all translated files produced by Stella. :lisp-only-files – Like the :files keyword, but these are only included :cpp-only-files in the translation for the specific language, namely :java-only-files Common Lisp, C++ or Java

Method on OBJECT: deleted? (self) : BOOLEAN

Default deleted? method which always returns FALSE. Objects that inherit DYNAMIC-SLOTS-MIXIN also inherit the dynamically-allocated slot deleted-object? which is read/writable with specializations of this method.

N-Command: describe ((name OBJECT) &rest (mode OBJECT)) :

Print a description of an object in :verbose, :terse, or :source modes.

Method on OBJECT: describe-object (self (stream OUTPUT-STREAM) (mode KEYWORD)) :

Prints a description of self to stream stream. mode can be :terse, :verbose, or :source. The :terse mode is often equivalent to the standard print function.

Method on CLASS: destroy-class (self) :

Destroy the Stella class self. Unfinalize its subclasses (if it has any).

Function: destroy-class-and-subclasses ((self CLASS)) :

Destroy the Stella class self and all its subclasses.

Function: destructure-defmethod-tree ((method-tree CONS) (options-table KEY-VALUE-LIST)) : OBJECT CONS CONS

Return three parse trees representing the name, parameters, and code body of the parse tree method-tree. Fill options-table with a dictionary of method options. Storage note: Options are treated specially because the other return values are subtrees of method-tree, while options-table is a newly-created cons tree. Note also, the parameter and body trees are destructively removed from method-tree.

Function: dictionary ((collectionType TYPE) &rest (alternatingkeysandvalues OBJECT)) : (ABSTRACT-DICTIONARY OF OBJECT OBJECT)

Return a dictionary of collectionType containing values, in order. Currently supported collectionTypes are @HASH-TABLE, @STELLA-HASH-TABLE, @KEY-VALUE-LIST, @KEY-VALUE-MAP and @PROPERTY-LIST.

Method on CLASS: direct-super-classes (self) : (ITERATOR OF CLASS)

Returns an iterator that generates all direct super classes of self.

Command: disable-memoization () :

Enable memoization and use of memoized expression results.

Function: disabled-stella-feature? ((feature KEYWORD)) : BOOLEAN

Return true if the STELLA feature is currently disabled.

Method on CONS: disjoint-sets? (self (otherList CONS)) : BOOLEAN

Return true if the intersection of self and otherList is empty. This is always true if at least one of the two sets is the empty set. Uses an eql? test and a simple quadratic-time algorithm. Note that this does not check whether self and otherList actually are sets.

Method on INTEGER: div (x (y INTEGER)) : INTEGER

Return the integer quotient from dividing x by y.

Method on LONG-INTEGER: div (x (y LONG-INTEGER)) : LONG-INTEGER

Return the integer quotient from dividing x by y.

Function: drop-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :

Remove the function named hookFunction from hookList.

Command: drop-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Remove the directories listed in the |-separated path from the PowerLoom load path.

Function: drop-slot-value ((self STANDARD-OBJECT) (slot STORAGE-SLOT) (value OBJECT)) :

Clear or remove value for the slot slot on self. CAUTION: Assumes that collection-valued slots are non-null.

N-Command: drop-trace (&rest (keywords GENERALIZED-SYMBOL)) : LIST

Disable trace messages identified by any of the listed keywords. After calling (drop-trace <keyword>) code guarded by (trace-if <keyword> ...) will not be executed when it is encountered.

Function: eight-bit-character? ((ch CHARACTER)) : BOOLEAN

Return TRUE if ch is in the upper half of the byte set such as UTF-8 codes, etc.

Macro: either ((value1 OBJECT) (value2 OBJECT)) : OBJECT

If value1 is defined, return that, else return value2.

Method on STRING-WRAPPER: empty? (x) : BOOLEAN

Return true if x is the wrapped empty string ""

Method on VECTOR-SEQUENCE: empty? (self) : BOOLEAN

Return true if self has length 0.

Method on HEAP: empty? (self) : BOOLEAN

Return TRUE if self is empty.

Method on BUFFERED-STRING: empty? (self) : BOOLEAN

Return true if self has length 0.

Command: enable-memoization () :

Enable memoization and use of memoized expression results.

Function: enabled-stella-feature? ((feature KEYWORD)) : BOOLEAN

Return true if the STELLA feature is currently enabled.

Function: ends-with? ((string STRING) (suffix STRING) (end INTEGER)) : BOOLEAN

Return TRUE if the substring of string ending at end ends with suffix. If end is NULL it defaults to the length of string.

Command: ensure-directories-exist ((fileName FILE-NAME)) :

Ensure all physical directories in the directory portion of fileName exist.

Function: ensure-file-does-not-exist ((filename STRING) (context STRING)) :

Ensures that filename does not exist. If it does, an exception of type FILE-ALREADY-EXISTS-EXCEPTION is thrown with context supplying context for the error message.

Function: ensure-file-exists ((filename STRING) (context STRING)) :

Ensures that filename exists. If not, an exception of type NO-SUCH-FILE-EXCEPTION is thrown with context supplying context for the error message.

Method on BUFFERED-STRING: ensure-free-space (self (size INTEGER)) : MUTABLE-STRING

Ensure self is big enough to accommodate an additional item of size.

Function: eql-except-in-whitespace? ((s1 STRING) (s2 STRING)) : BOOLEAN

Return true if the strings s1 and s2 are the same except for the amounts of whitespace separating words. Leading or trailing whitespace is also not considered.

Macro: error (&body (body CONS)) : OBJECT

Signal error message, placing non-string arguments in quotes.

Function: eval-in-module-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Interpret an –eval-in-module option. value is expected to be of the form (<module-name> <s-expression>).

Function: eval-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Interpret an –eval option by evaluating value.

Command: evaluate ((expression OBJECT)) : OBJECT

Evaluate the expression expression and return the result. Currently, only the evaluation of (possibly nested) commands and global variables is supported. The second return value indicates the actual type of the result (which might have been wrapped), and the third return value indicates whether an error occurred during the evaluation. Expressions are simple to program in Common Lisp, since they are built into the language, and relatively awkward in Java and C++. Users of either of those languages are more likely to want to call evaluate-string.

Function: evaluate-string ((expression STRING)) : OBJECT

Evaluate the expression represented by expression and return the result. This is equivalent to (evaluate (unstringify expression)).

Method on INTEGER: even? (x) : BOOLEAN

Return true if x is an even number.

Method on LONG-INTEGER: even? (x) : BOOLEAN

Return true if x is an even number.

Function: exception-context ((e NATIVE-EXCEPTION)) : STRING

Print the exception context of e to a string and return the result.

Function: exception-message ((e NATIVE-EXCEPTION)) : STRING

Accesses the error message of the exception e.

Method on CLASS: extension (self) : CLASS-EXTENSION

Return the nearest class extension that records instances of the class self.

Function: external-id-head? ((attribute OBJECT)) : BOOLEAN

Checks to see if this attribute is the literal marking either a PUBLIC or SYSTEM literal for an XML Elternal ID. (See 4.2.2)

Method on HEAP: fast-heap-root (self) : (LIKE (ANY-VALUE SELF))

Return the root of self which is assumed to be non-empty.

Function: file-name-without-device ((file FILE-NAME)) : FILE-NAME

Return the file name portion of file by removing any physical device components. This is just like logical-pathname-without-host but only looks for one-character device strings as used in Windows.

Function: file-to-string ((file STRING)) : STRING

Read the content of file and return it as a string.

Function: fill-in-date-substitution ((substitution-list (KEY-VALUE-LIST OF STRING-WRAPPER STRING-WRAPPER))) :

Fill in substitution-list with template variable substitions for the names YEAR and DATE which correspond to the current year and date. These substitutions can then be used with substitute-template-variables-in-string DEPRECATED. Use add-date-subsitution or add-current-date-substitution instead.

Function: finalize-classes () :

Finalize all currently unfinalized classes.

Function: finalize-classes-and-slots () :

Finalize all currently unfinalized classes and slots.

Function: finalize-slots () :

Finalize all currently unfinalized slots.

Command: find-file-in-load-path ((file STRING) (extensions (CONS OF STRING-WRAPPER))) : STRING

Try to find file in the current load path and, if found, return its full name. If file can’t be found literally, try to find it with any of the listed extensions added. If extensions is NULL it defaults to *stella-file-extensions*, therefore, to not default to any extensions the value has to be supplied as NIL.

Function: find-matching-prefix-length ((string1 STRING) (start1 INTEGER) (end1 INTEGER) (string2 STRING) (start2 INTEGER) (end2 INTEGER)) : INTEGER

Finds the length of the matching prefix strings of string1 and string2, starting at position start1 and start2 respectively. The search will end when end1 or end2 is reached. If either end1 or end2 is null, then they will be set to the length of their respective strings.

Function: find-mismatch ((string1 STRING) (start1 INTEGER) (end1 INTEGER) (string2 STRING) (start2 INTEGER) (end2 INTEGER)) : INTEGER INTEGER

Finds the first position in each of string1 and string2 where they mismatch, starting at position start1 and start2 respectively. The search will end when end1 or end2 is reached. If either end1 or end2 is null, then they will be set to the length of their respective strings. If there is no mismatch, then null values are returned.

Function: find-source-from-native-file-name ((nativeFileName STRING)) : STRING

Try to find a STELLA source file based on the name and system components of nativeFileName. This will generally search the current STELLA systems path, since the tree where a native file resides is not necessarily the one where the corresponding source file is also. This will only work for Lisp and C++ files where the basename of translated files corresponds to the source file from which they were derived. The main purpose for this is to support the Emacs Lisp/STELLA interface to find function definitions.

Function: find-system-definition-file ((name STRING)) : FILE-NAME

Try to find an existing system definition file for a system named name in the current STELLA_SYSTEMS_PATH or built-in implicit systems path. Return NULL if no such definition file can be found. See build-stella-systems-path on where it looks.

Function: find-system-root-directory ((system SYSTEM-DEFINITION)) : FILE-NAME

Given a system definition system try to determine the root directory of the STELLA installation containing this system based on its definition file.

Function: find-system-root-directory-from-file ((sysDefFile FILE-NAME)) : FILE-NAME

Given a system definition file sysDefFile try to determine the root directory of the STELLA installation containing this system by looking for top-level native directories.

Macro: first-defined (&body (forms CONS)) : OBJECT

Return the result of the first form in forms whose value is defined or NULL otherwise.

Function: float-to-base60 ((x FLOAT) (all-integers? BOOLEAN)) : (CONS OF NUMBER-WRAPPER)

Returns a cons of x in a base-60 form. That means the first value will be the integer part of x, the next value the iteger value of the fraction part of x times 60 and the third value the fraction part of x time 3600. If all-integers? is true, then the last value will be rounded to an integer. This can be used to convert from decimal degree values to Degree-Minute-Second or from decimal hours to Hour-Minute-Second format.

Function: fmod ((x FLOAT) (modulus FLOAT)) : FLOAT

True modulus for floats. Return the result of x mod modulo. Note: In C++ and Java, mod has more overhead than the similar function rem. The answers returned by mod and rem are only different when the signs of x and modulo are different.

Function: format-date ((date OBJECT) (timezone OBJECT) (control STRING)) : STRING

Format date just like format-date-to-stream (which see), but return the result as a string.

Function: format-date-to-stream ((date OBJECT) (timezone OBJECT) (control STRING) (stream OUTPUT-STREAM)) :

Perform formatted printing of date relative to timezone onto stream. date has to be either a calendar-date or a decoded-date-time object. timezone can be null to indicate the local timezone, or a float or supported timezone name. control is a format control string whose characters are printed literally, unless they are a %-code such as one of these (inspired by the codes supported by the Unix date command): %% a literal % %a abbreviated weekday name (e.g., Sun) %A full weekday name (e.g., Sunday) %b abbreviated month name (e.g., Jan) %B full month name (e.g., January) %d day of month (e.g., 01) %D date; same as %m/%d/%y %F full date; same as %Y-%m-%d %H hour (00..23) %I hour (01..12) %m month (01..12) %M minute (00..59) %p either AM or PM %r 12-hour clock time (e.g., 11:11:04 PM) %R 24-hour hour and minute; same as %H:%M %S second (00..60) %T time; same as %H:%M:%S %y last two digits of year (00..99) %Y year %z +hhmm numeric time zone (e.g., -0400) %:z +hhmm numeric time zone (e.g., -04:00) %Z alphabetic time zone abbreviation (e.g., EDT) By default, numeric fields are padded with zeroes. The following optional flags may follow %: - (hyphen) do not pad the field _ (underscore) pad with spaces 0 (zero) pad with zeros ^ use upper case if possible , use lower case if possible

Function: format-with-padding ((input STRING) (length INTEGER) (padchar CHARACTER) (align KEYWORD) (truncate? BOOLEAN)) : STRING

Formats input to be (at least) length long, using padchar to fill if necessary. align must be one of :LEFT, :RIGHT, :CENTER and will control how input will be justified in the resulting string. If truncate? is true, then then an overlength string will be truncated, using the opposite of align to pick the truncation direction.

Method on OBJECT: free (self) :

Default method. Deallocate storage for self.

Method on ACTIVE-OBJECT: free (self) :

Remove all pointers between self and other objects, and then deallocate the storage for self.

Method on ABSTRACT-HASH-TABLE: free-hash-table-values (self) :

Call free on each value in the hash table self.

Method on BUFFERED-STRING: free-space (self) : INTEGER

Return the amount of free space in self.

Function: frem ((x FLOAT) (y FLOAT)) : FLOAT

Return the floating point remainder from dividing x by y. The sign of the result is always the same as the sign of x. This has slightly different behavior than the mod function, and has less overhead in C++ and Java, which don’t have direct support for a true modulus function.

Function: gc-protect-object ((object NATIVE-OBJECT-POINTER)) : NATIVE-OBJECT-POINTER

Protect object from garbage collection. Returns a handle that can later be passed to gc-release-object to release object from garbage collection protection.

Function: gc-release-object ((handle NATIVE-OBJECT-POINTER)) : NATIVE-OBJECT-POINTER

Release the object pointed to by handle from garbage collection protection and return the protected object. This frees handle but does not necessarily mean that the object will be garbage collected, it just can be again, once all references to it disappear.

Function: generate-random-uuid () : STRING

Generates a random UUID (Type 4), according to the guidelines of IETF RFC 4122 (see http://www.ietf.org/rfc/rfc4122.txt )

Take 16 random bytes (octets), put them all behind each other, for the description the numbering starts with byte 1 (most significant, first) to byte 16 (least significant, last). Then put in the version and variant. To put in the version, take the 7th byte and perform an and operation using 0x0f, followed by an or operation with 0x40. To put in the variant, take the 9th byte and perform an and operation using 0x3f, followed by an or operation with 0x80. To make the string representation, take the hexadecimal presentation of bytes 1-4 (without 0x in front of it) let them follow by a -, then take bytes 5 and 6, - bytes 7 and 8, - bytes 9 and 10, - then followed by bytes 11-16.

Function: generate-uuid ((uuid-type KEYWORD)) : STRING

Generates a UUID of the specified type. Legal types are a subset of the IETF RFC 4122 (see http://www.ietf.org/rfc/rfc4122.txt ) UUID types. Currently supported are: :TYPE-4 :RANDOM A type-4 (random) UUID. These are synonyms.

Method on CALENDAR-DATE: get-calendar-date (date (timezone FLOAT)) : INTEGER INTEGER INTEGER KEYWORD

Returns multiple values of year, month, day and day of week for date in timezone. timezone is the number of hours added to UTC to get local time. It is in the range -12.0 to +14.0 where UTC is zone 0.0

Function: get-generic-slot-accessor ((slot STORAGE-SLOT) (class CLASS) (warn? BOOLEAN)) : FUNCTION-CODE

Return the accessor code to read slot on an object of type class, or NULL if no such accessor exists. In that case, print a warning if warn? is TRUE. NOTE: the accessor expects canonical-slot-names (which see).

Function: get-global-variable-native-object ((variable GLOBAL-VARIABLE)) : NATIVE-OBJECT-POINTER

Return the native object of variable which can be used to access its runtime value. In Lisp this is the Lisp symbol which holds the variable value, in C++ this is the address of the variable, and in Java this is the declared Field object. For C++ native object addresses are initialized at startup time, for Lisp and Java native objects will be accessed upon first call and then cached in the slot.

Function: get-language-subdirectory-from-file-type ((type KEYWORD)) : STRING

Compute a language-specific native subdirectory that should be used for files of type. If type does not naturally suggest which native language it is associated with, key in on the current translation output language. Returns the empty string for unhandled types.

Command: get-load-path () : (CONS OF STRING-WRAPPER)

Return the current STELLA load path.

Function: get-local-standard-time-zone () : FLOAT

Returns the standard time zone offset from UTC as a float, without considering the effects of daylight savings time.

Function: get-local-time-zone-for-date ((year INTEGER) (month INTEGER) (day INTEGER) (hour INTEGER) (minute INTEGER) (second INTEGER)) : FLOAT

Returns the time zone offset from UTC (as a float) that is applicable to the given date. Assumes that the date is one that is valid for the underlying programming language. If not, then returns 0.0

Function: get-log-stream ((module STRING)) : OUTPUT-STREAM

Return a valid log stream for module.

Command: get-logical-host-property ((host OBJECT) (property OBJECT)) : OBJECT

Lookup the value of property for the logical host host.

Function: get-native-source-subdirectory-from-file-type ((type KEYWORD)) : STRING

Compute a native source subdirectory that should be used for files of type. If type does not naturally suggest which native language it is associated with, key in on the current translation output language. Returns the empty string for unhandled types.

Command: get-property ((property NAME) &rest (defaultValue OBJECT)) : OBJECT

Lookup property (a string or symbol) in the configuration table and return its value. If it is undefined, return the optional defaultValue. Note that property is evaluated and will need to be quoted if supplied as a symbol. Symbols will also be upcased if this command is run in a non-case- sensitive module.

Function: get-quoted-tree ((tree-name STRING) (modulename STRING)) : CONS

Return the quoted tree with name tree-name.

Function: get-root-directory-from-file-extension ((file FILE-NAME)) : FILE-NAME

Given a file, determine which STELLA installation root directory tree it naturally belongs to based on its extension (i.e., source, native or binary).

Function: get-root-directory-from-file-type ((type KEYWORD)) : STRING

Given a normalized file type, determine which STELLA installation root directory tree it naturally belongs to (i.e., source, native or binary).

Function: get-slot ((self STANDARD-OBJECT) (slot-name SYMBOL)) : SLOT

Return the slot named slot-name on the class representing the type of self.

Method on SURROGATE: get-stella-class (class-name (error? BOOLEAN)) : CLASS

Return a class with name class-name. If none exists, break if error?, else return null.

Method on SYMBOL: get-stella-class (class-name (error? BOOLEAN)) : CLASS

Return a class with name class-name. If non exists, break if error?, else return null.

Method on STRING: get-stella-class (class-name (error? BOOLEAN)) : CLASS

Return a class with name class-name. If none exists, break if error?, else return null.

Function: get-system-definition ((name STRING) (error? BOOLEAN)) : SYSTEM-DEFINITION

Return a system named name. If no such system is currently defined, look for a system definition file for name in standard locations and try to load it. If no matching system could be found or loaded and error? is true, raise an error, otherwise, simply return NULL.

Function: get-system-last-modified-date ((system SYSTEM-DEFINITION)) : CALENDAR-DATE

Compute a last-modified date for system based on its most recently modified source file.

Function: get-system-subdirectory-from-file-type ((type KEYWORD)) : STRING

Compute a native system subdirectory that should be used for files of type. If type does not naturally suggest which native language it is associated with, key in on the current translation output language. Returns the empty string for unhandled types.

Function: get-system-version-string ((system SYSTEM-DEFINITION)) : STRING

Compute a version string for system which is either based on an explicit :version annotation on systems definition, the readable value of an existing *<system>-version[-string]*, variable or on its most recent modification date of any of its source files.

Function: get-temp-directory () : STRING

Return a suitable directory for temporary files. Uses the value of stella.tempDirectory if defined; otherwise, it will use a suitable OS-specific default. The returned directory will end in a separator for immediate concatenation with a physical filename.

Method on CALENDAR-DATE: get-time (date (timezone FLOAT)) : INTEGER INTEGER INTEGER INTEGER

Returns multiple values of hours, minutes, seconds, milliseconds for the calendar date date in timezone. timezone is the number of hours added to UTC to get local time. It is in the range -12.0 to +14.0 where UTC is zone 0.0

Macro: get-token-float () : OBJECT

User-level macro to access the most recently parsed token as a float. This assumes correct signed float syntax and only checks for overflows. The main benefit for this is that it doesn’t generate strings and wrappers. Float parsing and conversion is generally hairy and we are probably not covering all special cases here; but we are fast :-)

Macro: get-token-integer () : OBJECT

User-level macro to access the most recently parsed token as an integer. This assumes correct signed integer syntax and only checks for overflows.

Macro: get-token-long-integer () : OBJECT

User-level macro to access the most recently parsed token as a long integer. This assumes correct signed long-integer syntax and only checks for overflows.

Function: get-xml-base-attribute-value ((expression CONS)) : STRING

Return the last base url attribute in the attribute list of this element if it exists. Otherwise NULL.

Command: getenv ((varname STRING) &rest (deflt STRING)) : STRING

Return the value of the OS environment variable varname. If it is not defined or if its value is the empty string and a deflt is provided, return the default value instead.

Function: global-variable-type-spec ((global GLOBAL-VARIABLE)) : TYPE-SPEC

Return the type spec for the global variable global.

Function: hash-string ((string STRING) (seedCode INTEGER)) : INTEGER

Generate a hash-code for string and return it. Two strings that are equal but not eq will generate the same code. The hash-code is based on seedCode which usually will be 0. However, seedCode can also be used to supply the result of a previous hash operation to achieve hashing on sequences of strings without actually having to concatenate them.

Method on HEAP: heap-root (self) : (LIKE (ANY-VALUE SELF))

Return the root of self (NULL if self is empty). The root contains the minimum element of a min-heap with < predicate.

Method on HEAP: heapify (self) :

Restore the heap property of self according to its predicate. Normally, this is not needed, since insert operations preserve the heap property. However, this can be useful after bulk insertion of values or if predicate has been changed.

Function: help-advance-past-whitespace ((source STRING) (start INTEGER) (end INTEGER)) : INTEGER

Helper for advance-past-whitespace that requires end to be properly set.

Function: help-find-matching-prefix-length ((string1 STRING) (start1 INTEGER) (end1 INTEGER) (string2 STRING) (start2 INTEGER) (end2 INTEGER)) : INTEGER

Helping function for find-matching-prefix that requires end1 and end2 to be properly set up.

Function: help-get-stella-module ((pathName STRING) (error? BOOLEAN)) : MODULE

Return the module located at pathName, or null if no such module exists. The search looks at ancestors and top-most (cardinal) modules. If error? is true, throw an exception if no module is found.

Function: help-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Print documentation about all currently registered option handlers.

Method on CLASS: help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :

Helper method for print-outline

Method on OBJECT: help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :

Helper method for print-outline

Method on SLOT: help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :

Helper method for print-outline

Method on MODULE: help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :

Helper method for print-outline

Method on CONTEXT: help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :

Helper method for print-outline

Function: hex-character-value ((c CHARACTER)) : INTEGER

Convert the base-16 hex character c into a base-10 number.

Method on OBJECT: home-module (self) : MODULE

Return the home module of self.

Macro: if-output-language ((language KEYWORD) (thenForm OBJECT) (elseForm OBJECT)) : OBJECT

Expand to thenForm if the current translator output language equals language. Otherwise, expand to elseForm. This can be used to conditionally translate Stella code.

Macro: if-stella-feature ((feature KEYWORD) (thenForm OBJECT) (elseForm OBJECT)) : OBJECT

Expand to thenForm if feature is a currently enabled STELLA environment feature. Otherwise, expand to elseForm. This can be used to conditionally translate Stella code.

Macro: ignore (&body (variables CONS)) : OBJECT

Ignore unused variables with NoOp setq statements.

Function: incrementally-translate ((tree OBJECT)) : OBJECT

Translate a single Stella expression tree and return the result. For C++ and Java print the translation to standard output and return NIL instead.

Function: indent-outline ((current-depth INTEGER) (stream OUTPUT-STREAM)) :

Helper function that indents outline printings for level current-depth on stream using the value of the global variable *OUTLINE-INDENT-STRING*

Macro: inform (&body (body CONS)) : OBJECT

Print informative message, placing non-string arguments in quotes, and terminating with a newline.

Method on CLASS: initial-value (self) : OBJECT

Return an initial value for the class self.

Method on STORAGE-SLOT: initial-value (self) : OBJECT

Return an initial value for self, or null. The initial value can be defined by the slot itself, inherited from an equivalent slot, or inherit from the :initial-value option for the class representing the type of self.

Method on DIMENSIONAL-ARRAY-MIXIN: initialize-array (self (initialValue (LIKE (ANY-VALUE SELF)))) :

Initialize the elements of self with initialValue.

Method on STELLA-HASH-TABLE: initialize-hash-table (self) :

Initialize the STELLA hash table self. This is a no-op and primarily exists to shadow the standard initializer inherited from ABSTRACT-HASH-TABLE. STELLA hash tables are initialized at the first insertion operation.

Method on STORAGE-SLOT: initially (self) : OBJECT

Defines the value of a slot before it has been assigned a value.

Method on CUSTOM-VECTOR-SEQUENCE: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Append value to the END of the sequence self. Resize the array if necessary.

Method on HEAP: insert (self (value (LIKE (ANY-VALUE SELF)))) :

Insert value into self and restore the heap property. Signal an error if there is no more room in self. Maintains self as a Min-heap if selfs predicate has < semantics; otherwise as a Max-heap.

Method on HEAP: insert-if-better (self (value (LIKE (ANY-VALUE SELF)))) :

Insert value into self and restore the heap property. If self has available room, simply insert value. If the heap is full, only insert value if it is better than the current root (i.e., if value is greater than the minimum of self for the case of a min-heap where selfs predicate has < semantics). In that case, replace the root of self and restore the heap property. This is useful to build and maintain a heap with some top-N elements (relative to predicate) where the root (or minimum) of self is the currently weakest element at the end of the list.

Function: int-to-string ((i INTEGER)) : STRING

Convert i to its string representation and return the result. This is a convenience function that expects regular integers as opposed to longs which is useful in contexts where we do automatic unwrapping based on the target.

Function: integer-length ((x LONG-INTEGER)) : INTEGER

Return the 1-based position of the left-most bit in x. If x is negative, we only count the value bits, not the sign.

Function: integer-length10 ((x LONG-INTEGER)) : INTEGER

Return the 1-based position of the left-most non-zero digit in the base-10 representation of x. If x is negative, we only consider its absolute value, not the sign. This effectively computes the minimum number of base-10 digits to represent x, with the exception of x=0.

Function: integer-to-hex-string ((i LONG-INTEGER)) : STRING

Convert i to a string representation in hexadecimal notation and return the result.

Function: integer-to-string-in-base ((i LONG-INTEGER) (base INTEGER)) : STRING

Convert i to a string representation in base and return the result. base must be positive and not more than 36.

Note that in the C++ version, only 8, 10 and 16 will work as base arguments, since that is all the underlying implementation supports. Other argument values will be treated as 10.

Function: integer-valued? ((x FLOAT)) : BOOLEAN

Returns true if x is the floating point representation of an integer.

Function: intern-stella-name ((name STRING)) : GENERALIZED-SYMBOL

Parse name which is assumed to be the printed representation of a STELLA symbol, surrogate or keyword, intern it into the current or specified module and return the result. This is identical to calling unstringify on name but 10-15 times faster.

Function: interpret-command-line-arguments ((count INTEGER) (arguments (ARRAY () OF STRING))) :

Old name for process-command-line-arguments (which see).

Function: isa? ((object OBJECT) (type TYPE)) : BOOLEAN

Return true iff object is an instance of the class named type.

Function: java-translate-system ((systemName STRING)) :

Translate the system systemName to Java.

N-Command: jptrans ((statement OBJECT)) :

Translate statement to C++ and print the result.

Function: keyword-name? ((name STRING)) : BOOLEAN

Return TRUE if name is prefixed by :.

Function: kvlist-to-plist ((self KEY-VALUE-LIST)) : (PROPERTY-LIST OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Convert self into a property list with identical and identically ordered keys and values.

Method on VECTOR-SEQUENCE: last (self) : (LIKE (ANY-VALUE SELF))

Return the last item in the vector self.

Method on HEAP: last (self) : (LIKE (ANY-VALUE SELF))

Return the last item in the heap self which will be the largest or best item if self is a sorted min-heap with a < predicate.

Method on BUFFERED-STRING: last (self) : CHARACTER

Return the last character in self.

Method on CONS-ITERATOR: length (self) : INTEGER

Iterate over self, and count how many items there are.

Method on HEAP: length (self) : INTEGER

Return the length of the currently filled portion of self.

Method on DIMENSIONAL-ARRAY-MIXIN: length (self) : INTEGER

Return the total number of elements in self.

Method on 2-DIMENSIONAL-ARRAY-MIXIN: length (self) : INTEGER

Return the total number of elements in self.

Method on BUFFERED-STRING: length-setter (self (newLength INTEGER)) : INTEGER

Reset the length of self to newLength. Fill in NULL characters if newLength is greater than the current length. This is the safe way to reset the fill pointer.

Function: lispify ((thing UNKNOWN)) : LISP-CODE

Convert a Stella thing as much as possible into a Common-Lisp analogue. The currently supported thing types are CONS, LIST, KEY-VALUE-LIST, ITERATOR, SYMBOL, KEYWORD, and all wrapped and unwrapped literal types. BOOLEANs are translated into Lisp’s CL:T and CL:NIL logic. Unsupported types are left unchanged.

Function: lispify-boolean ((thing UNKNOWN)) : LISP-CODE

Lispify thing which is assumed to be a (possibly wrapped) Stella boolean.

Command: list-directory-files ((directory STRING)) : (CONS OF STRING-WRAPPER)

Return all the files and sub-directories in directory sorted by name. Each returned file is a bare file name without a directory component. If a file is a directory, it will look just like a plain file. This means consumers might have to explicitly test whether a file is a directory depending on what they do. Excludes . and .. directories. Handles logical pathnames but resulting files will always use physical pathname syntax. This is mostly consistent across native languages, but some differences still exist - e.g., Lisp will convert . or .. into absolute pathnames.

Command: list-directory-files-recursively ((directory STRING)) : (CONS OF STRING-WRAPPER)

Just like list-directory-files (which see) but also recurses into subdirectories. Files at the top level of directory will be bare file names without a directory component. Files in subdirectories will be prefixed with the relative subdirectory path starting right below directory. The sort order is lexicographic within directories which results in a depth-first presentation order of files.

Command: list-modules ((kb-only? BOOLEAN)) : (CONS OF MODULE)

Returns a cons of all modules defined in PowerLoom. If kb-only? is true, then any modules which are code only or just namespaces are not returned.

Method on CONS: listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method on LIST: listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return self.

Method on KEY-VALUE-LIST: listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a list of key-value pairs in self.

Method on VECTOR: listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a list of elements in self.

Method on ITERATOR: listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))

Return a list of elements generated by self.

Command: load-configuration-file ((file FILE-NAME)) : CONFIGURATION-TABLE

Read a configuration file and return its content as a configuration table. Also enter each property read into the global system configuration table. Assumes Java-style property file syntax. Each property name is represented as a wrapped string and each value as a wrapped string/integer/float or boolean.

Command: load-file ((file STRING)) :

Read STELLA commands from file and evaluate them. The file should begin with an in-module declaration that specifies the module within which all remaining commands are to be evaluated The remaining commands are evaluated one-by-one, applying the function evaluate to each of them.

Function: load-file-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Load the file value using the STELLA load-file command.

Function: load-path-option-handler ((option CMD-LINE-OPTION) (value OBJECT)) :

Modify the current file load path according to option and value.

Command: load-system ((systemName STRING) &rest (language&options OBJECT)) : BOOLEAN

Natively language-compile out-of-date translated files of system systemName (only supported for Lisp at the moment) and then load them into the running system. Return true if at least one file was compiled. The following keyword/value options are recognized:

:language: can be used as an alternative to the optional language argument. If not specified, the language of the running implementation is assumed.

:force-recompilation? (default false): if true, files will be compiled whether or not their compilations are up-to-date.

:startup? (default true): if true, the system startup function will be called once all files have been loaded.

:recursive? (default false): if true, perform load-system with the provided options on systemName as well as all its required systems and so on. Required systems will be processed first. Note that even without this option, any required systems that have not yet been loaded or started up will also be processed, since that is assumed when loading systemName and supporting modules from a definition file.

:root-source-directory, :root-native-directory, :root-binary-directory: if specified these directories will be used to override the respective paths provided in system definitions or computed as defaults from a system’s home location.

Function: log-level<= ((level OBJECT) (module STRING)) : BOOLEAN

Return TRUE if level is lower than or equal to the current log level of module. Return FALSE if any of them are undefined.

Function: log-message ((module STRING) (logLevel OBJECT) (message CONS)) :

Log all elements of message to modules log stream if logLevel is the same or lower than the modules log level. Interprets EOL or :EOL to print a line terminator.

Function: log2 ((n FLOAT)) : FLOAT

Return the logarithm (base 2) of n.

Function: logmsg ((module STRING) (logLevel OBJECT) &rest (message OBJECT)) :

Log all elements of message to modules log stream if logLevel is the same or lower than the modules log level. Interprets EOL or :EOL to print a line terminator.

Method on SYMBOL: lookup-class (name) : CLASS

Return a class with name name. Scan all visible surrogates looking for one that has a class defined for it.

Method on STRING: lookup-class (name) : CLASS

Return a class with name name. Scan all visible surrogates looking for one that has a class defined for it.

Function: lookup-class-by-qualified-name ((qualifiedName STRING)) : CLASS

Variant of string.lookup-class that can specify a starting module through a qualifiedName.

Function: lookup-class-cpp-type-by-name ((qualifiedName STRING)) : STRING

Return a namespace-qualified C++ translation of the class type named by qualifiedName or NULL if no such STELLA class exists.

Function: lookup-command ((name SYMBOL)) : METHOD-SLOT

If name names an evaluable command return its associated command object; otherwise, return null. Currently, commands are not polymorphic, i.e., they can only be implemented by functions.

Function: lookup-command-like-function ((name SYMBOL)) : METHOD-SLOT

Look up a function with name that can be evaluated via apply just like a command, regardless of whether it was marked as such.

Function: lookup-configuration-property ((property STRING) (defaultValue OBJECT) (configuration CONFIGURATION-TABLE)) : OBJECT

Lookup property in configuration and return its value. Use the global system configuration table if configuration is NULL. Return defaultValue if property is not defined.

Function: lookup-configuration-property-values ((property STRING) (defaultValue OBJECT) (configuration CONFIGURATION-TABLE)) : CONS

Lookup property in configuration, assume it is a multi-valued property and return its value(s) as a list. Use the global system configuration table if configuration is NULL. Return defaultValue if property is not defined or NIL is no default value is specified.

Function: lookup-demon ((name STRING)) : DEMON

Return the demon named name.

Function: lookup-function ((functionSymbol SYMBOL)) : FUNCTION

Return the function defined for functionSymbol, if it exists.

Function: lookup-function-by-name ((name STRING)) : FUNCTION

Return a function with name name visible from the current module. Scan all visible symbols looking for one that has a function defined for it.

Function: lookup-function-by-qualified-name ((qualifiedName STRING)) : METHOD-SLOT

Variant of lookup-function-by-name that can specify a starting module through a qualifiedName.

Method on SURROGATE: lookup-global-variable (self) : GLOBAL-VARIABLE

Return a global variable with name self.

Method on GENERALIZED-SYMBOL: lookup-global-variable (self) : GLOBAL-VARIABLE

Return a global variable with name self.

Method on STRING: lookup-global-variable (self) : GLOBAL-VARIABLE

Return a global variable with name self.

Function: lookup-global-variable-by-name ((name STRING)) : GLOBAL-VARIABLE

Return a global variable with name visible from the current module. Scan all visible symbols looking for one that has a global variable defined for it. NOTE: this is more robust than STRING.lookup-global-variable which will fail if there is a local symbol with name which shadows one higher up that is the name of a global.

Function: lookup-global-variable-by-qualified-name ((qualifiedName STRING)) : GLOBAL-VARIABLE

Variant of lookup-global-variable-by-name that can specify a starting module through a qualifiedName.

Function: lookup-local-slot ((class CLASS) (slot-name SYMBOL)) : SLOT

Lookup a local slot with slot-name on class.

Function: lookup-logging-parameter ((module STRING) (parameter KEYWORD) (default OBJECT)) : OBJECT

Lookup logging parameter for module. Use default if no value is defined.

Function: lookup-macro ((name SYMBOL)) : METHOD-SLOT

If name has a macro definition, return the method object holding its expander function.

Function: lookup-slot ((class CLASS) (slot-name SYMBOL)) : SLOT

Return a slot owned by the class class with name slot-name. Multiply inherited slots are disambiguated by a left-to-right class precedence order for classes with multiple parents (similar to CLOS).

Function: lookup-slot-and-class-by-qualified-name ((qualifiedname STRING)) : SLOT CLASS

Lookup a slot via dotted notation with a possibly qualified class name. Examples: "cons.first" or "stella/cons.first". This is a variant of string-to-slot in describe.ste that actually obeys the class module if it is given. This also returns the specified class as a second value which might differ from the slot’s owner class.

Function: lookup-slot-by-qualified-name ((qualifiedname STRING)) : SLOT

Lookup a slot via dotted notation with a possibly qualified class name. Examples: "cons.first" or "stella/cons.first". This is a variant of string-to-slot in describe.ste that actually obeys the class module if it is given.

Function: lookup-stella-name ((name STRING)) : GENERALIZED-SYMBOL

Parse name which is assumed to be the printed representation of a STELLA symbol, surrogate or keyword, and try to look it up according to its type. This is a lookup version of intern-stella-name (which see) for cases where we don’t necessarily want to create a symbol in case it doesn’t exist already.

Method on PROPERTY-LIST: lookup-with-default (self (key (LIKE (ANY-KEY SELF))) (default (LIKE (ANY-VALUE SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup key in self and return the result. Return default if no value was found.

Method on KEY-VALUE-LIST: lookup-with-default (self (key (LIKE (ANY-KEY SELF))) (default (LIKE (ANY-VALUE SELF)))) : (LIKE (ANY-VALUE SELF))

Lookup key in self and return the result. Return default if no value was found.

N-Command: lptrans ((statement OBJECT)) :

Translate statement to Common-Lisp and print the result.

Function: make-file-name ((filePath STRING) (type KEYWORD) (relative? BOOLEAN)) : FILE-NAME

Make an absolute file-name string from filePath with directory location and file extension determined by type and relative?. type is the main determiner for whether we are creating a source, native or binary pathname in the respective root directories, and it also controls the new extension of the resulting pathname replacing any one on filePath. If relative? is TRUE, then the respective root directory prefix is appended, plus any additional relevant language, system and source subdirectories. If relative? is FALSE, then the current directory prefix of filePath as indicated by its extension is switched to the new root directory indicated by type. In this case, only the root and language directories are inserted, but all the remaining source directory components are left the same (thus, this will generally not do the right thing for Java file names). This function takes the dynamic state of currently active systems and modules into account.

Function: make-matching-name ((original STRING) &rest (options OBJECT)) : STRING

Keyword options: :break-on-cap one of :YES :NO :CLEVER default is :CLEVER :break-on-number one of :YES :NO :CLEVER default is :CLEVER :break-on-separators string default is "-_ " :remove-prefix string :remove-suffix string

:case one of :UPCASE :TitleCase :titleCaseX :downcase :Capitalize :preserve default is :TitleCase :separator string default is "" :add-prefix string :add-suffix string

MAKE-MATCHING-NAME returns a matching name (a string) for the input name (a string). A matching name is constructed by breaking the input into words and then applying appropriate transforms. The arguments are used as follows: original is the input name. It is a string. :break-on-cap is a keyword controlling whether changes in capitalization is used to indicate word boundaries. If :YES, then all capitalization changes delineate words. If :CLEVER, then unbroken runs of capitalized letters are treated as acronyms and remain grouped. If :NO or NULL, there is no breaking of words based on capitalization. :break-on-number is a flag controlling whether encountering a number indicates a word boundary. If :YES, then each run of numbers is treated as a word separate from surrounding words. If :CLEVER, then an attempt is made to recognize ordinal numbers (ie, 101st) and treat them as separate words. If :NO or NULL, there is no breaking of words when numbers are encountered. :break-on-separators A string of characters which constitute word delimiters in the input word. This is used to determine how to break the name into individual words. Defaults are space, - and _. :remove-prefix Specifies a prefix or suffix that is stripped from the input :remove-suffix name before any other processing. This allows the removal of any naming convention dictated prefixes or suffixes. :add-prefix Specifies a prefix or suffix that is added to the output name :add-suffix after all other processing. This allows the addition of any naming convention dictated prefixes or suffixes. :case The case of the resulting name. This is applied to the name before adding prefixes or suffixes. The two title case options differ only in how the first word of the name is treated. :TitleCase capitalizes the first letter of the first word and also the first letter of all other words. :TitleCaseX does not capitalizes the first letter of the first word but capitalizes the first letter of all subsequent words. :preserve results in no change in case. :separator This is a string specifying the word separator to use in the returned name. An empty string (the default) means that the resulting words are concatenated without any separation. This normally only makes sense when using one of the title case values for the case keyword.

Function: make-matching-name-full ((originalname STRING) (breakoncap KEYWORD) (breakonnumber KEYWORD) (breakonseparators STRING) (removeprefix STRING) (removesuffix STRING) (addprefix STRING) (addsuffix STRING) (outputcase KEYWORD) (outputseparator STRING)) : STRING

Non-keyword version of make-matching-name, which will probably be easier to use when called from non-Lisp languages.

Command: make-system ((systemName STRING) &rest (language&options OBJECT)) : BOOLEAN

Translate all out-of-date files of system systemName into language (the first optional argument of language&options) and then compile and load them (the latter is only possible for Lisp right now). The following keyword/value options are recognized:

:language: can be used as an alternative to the optional language argument. If not specified, the language of the running implementation is assumed.

:two-pass?: if true, all files will be scanned twice, once to load the signatures of objects defined in them, and once to actually translate the definitions. Otherwise, the translator will make one pass in the case that the system is already loaded (and is being remade), and two passes otherwise.

:development-settings? (default false): if true translation will favor safe, readable and debuggable code over efficiency (according to the value of :development-settings on the system definition). If false, efficiency will be favored instead (according to the value of :production-settings on the system definition).

:production-settings? (default true): inverse to :development-settings?.

:force-translation? (default false): if true, files will be translated whether or not their translations are up-to-date.

:force-recompilation? (default false): if true, translated files will be recompiled whether or not their compilations are up-to-date (only supported in Lisp right now).

:load-system? (default true): if true, compiled files will be loaded into the current STELLA image (only supported in Lisp and Java right now).

:startup? (default true): if true, the system startup function will be called once all files have been loaded.

:recursive? (default false): if true, perform make-system with the provided options on systemName as well as all its required systems and so on. Required systems will be processed first. Note that even without this option, any required systems that have not yet been loaded or started up will also be processed, since that is assumed when loading systemName and supporting modules from a definition file.

:root-source-directory, :root-native-directory, :root-binary-directory: if specified these directories will be used to override the respective paths provided in system definitions or computed as defaults from a system’s home location.

Function: make-system-definition-file-name ((name STRING)) : FILE-NAME

Make a canonical system definition file name for a system named name.

Function: make-temporary-file ((prefix STRING) (suffix STRING)) : STRING

Variant of make-temporary-file-name that actually allocates the file to prevent other processes from using that name. This is still not fully thread safe - for that we would need a file lock - but maybe a bit better in avoiding collisions.

Method on INTEGER: max (x (y INTEGER)) : INTEGER

Return the maximum of x and y. If either is NULL, return the other.

Method on LONG-INTEGER: max (x (y LONG-INTEGER)) : LONG-INTEGER

Return the maximum of x and y. If either is NULL, return the other.

Method on FLOAT: max (x (y FLOAT)) : FLOAT

Return the maximum of x and y. If either is NULL, return the other.

Method on NUMBER-WRAPPER: max (x (y NUMBER-WRAPPER)) : NUMBER-WRAPPER

Return the maximum of x and y. If y is NULL, return x.

Method on CONS-ITERATOR: member? (self (value OBJECT)) : BOOLEAN

Iterate over values of self and return TRUE if one of them is eql? to ’value.

Method on COLLECTION: member? (self (object OBJECT)) : BOOLEAN

Return true iff object is a member of the collection self.

Method on SEQUENCE: member? (self (value OBJECT)) : BOOLEAN

Return TRUE if value is a member of the sequence self.

Macro: memoize ((inputArgs CONS) &body (body CONS)) : OBJECT

Compute the value of an expression and memoize it relative to the values of inputArgs. inputArgs should characterize the complete set of values upon which the computation of the result depended. Calls to memoize should be of the form

(memoize (<arg>+) {:<option> <value>}* <expression>)

and have the status of an expression. The following options are supported:

:timestamps A single or list of keywords specifying the names of timestamps which when bumped should invalidate all entries currently memoized in this table. :name Names the memoization table so it can be shared by other memoization sites. By default, a gensymed name is used. CAUTION: IT IS ASSUMED THAT ALL ENTRIES IN A MEMOZATION TABLE DEPEND ON THE SAME NUMBER OF ARGUMENTS!! :max-values The maximum number of values to be memoized. Only the :max-values most recently used values will be kept in the memoization table, older values will be discarded and recomputed if needed. Without a :max-values specification, the memoization table will grow indefinitely.

PERFORMANCE NOTES: For most efficient lookup, input arguments that vary the most should be listed first. Also, arguments of type STANDARD-OBJECT (and all its subtypes) can be memoized more efficiently than arguments of type OBJECT or wrapped literals (with the exception of BOOLEANs).

Function: merge-file-names ((baseFile FILE-NAME) (defaults FILE-NAME)) : FILE-NAME

Parse baseFile, supply any missing components from defaults if supplied and return the result.

Method on DECODED-DATE-TIME: merge-null-fields (self (default DECODED-DATE-TIME)) :

Replace any null valued fields in self with values from default. The day of the week will be set consistently, if possible.

Method on DECODED-DATE-TIME: merge-superior-null-fields (self (default DECODED-DATE-TIME)) :

Replace only null valued fields in self that represent larger time units than the smallest non-null in self with values from default. The day of the week will be set consistently, if possible. Example: if self just has the month being non-null, then only the year will be filled in from default. If the day and minute were non-null, then hour, month and year will be filled.

This can be useful when one doesn’t want to extend the precision of the answer.

Method on INTEGER: min (x (y INTEGER)) : INTEGER

Return the minimum of x and y. If either is NULL, return the other.

Method on LONG-INTEGER: min (x (y LONG-INTEGER)) : LONG-INTEGER

Return the minimum of x and y. If either is NULL, return the other.

Method on FLOAT: min (x (y FLOAT)) : FLOAT

Return the minimum of x and y. If either is NULL, return the other.

Method on NUMBER-WRAPPER: min (x (y NUMBER-WRAPPER)) : NUMBER-WRAPPER

Return the minimum of x and y. If y is NULL, return x.

Method on INTEGER: mod (x (modulus INTEGER)) : INTEGER

True modulus. Return the result of x mod modulo. Note: In C++ and Java, mod has more overhead than the similar function rem. The answers returned by mod and rem are only different when the signs of x and modulo are different.

Method on LONG-INTEGER: mod (x (modulus LONG-INTEGER)) : LONG-INTEGER

True modulus. Return the result of x mod modulo. Note: In C++ and Java, mod has more overhead than the similar function rem. The answers returned by mod and rem are only different when the signs of x and modulo are different.

Method on CLASS: multiple-parents? (class) : BOOLEAN

Return true if class has more than one direct superclass.

Method on MODULE: multiple-parents? (module) : BOOLEAN

Return TRUE if module has more than one parent.

Method on WORLD: multiple-parents? (world) : BOOLEAN

Return FALSE always, since worlds never have more than one parent.

Function: name-to-string ((name OBJECT)) : STRING

Return the string represented by name. Return null if name is undefined or does not represent a string.

Function: native-delete-file ((fileName FILE-NAME)) :

Delete the file fileName. This does not handle any necessary pathname translations or error conditions.

Function: native-file-length ((fileName FILE-NAME)) : LONG-INTEGER

Return the length of file fileName in bytes or NULL if that cannot be determined. This does not handle any necessary pathname translations or error conditions.

Function: native-file-write-date ((fileName FILE-NAME)) : CALENDAR-DATE

Return the time at which file fileName was last modified or NULL if that cannot be determined. This does not handle any necessary pathname translations or error conditions.

Function: native-probe-directory? ((fileName FILE-NAME)) : BOOLEAN

Return true if file fileName exists and is a directory. Note that this does not necessarily mean that the directory can also be read. This does not handle any necessary pathname translations or error conditions.

Function: native-probe-file? ((fileName FILE-NAME)) : BOOLEAN

Return true if file fileName exists. Note that this does not necessarily mean that the file can also be read. This does not handle any necessary pathname translations or error conditions.

Function: native-read-line ((inputStream INPUT-STREAM)) : STRING

Read one line from inputStream using the native language readline algorithm and return the result. On EOF return null

Function: native-rename-file ((fromFile FILE-NAME) (toFile FILE-NAME)) :

Rename the file fromFile to toFile. This does not handle any necessary pathname translations or error conditions.

Method on MEMOIZABLE-ITERATOR: next? (self) : BOOLEAN

Generate the next value of the memoized iterator self (or one of its clones) by either using one of the values generated so far or by generating and saving the next value of the base-iterator.

Method on COLLECTION: no-duplicates? (self) : BOOLEAN

Return true if the collection self forbids duplicate values.

Method on STRING-WRAPPER: non-empty? (x) : BOOLEAN

Return true if x is not the wrapped empty string ""

Method on VECTOR-SEQUENCE: non-empty? (self) : BOOLEAN

Return true if self has length > 0.

Method on BUFFERED-STRING: non-empty? (self) : BOOLEAN

Return true if self has length > 0.

Function: non-matching-position ((source STRING) (start INTEGER) (match STRING)) : INTEGER

Returns the index into source, starting from start, of the first character that is not included in match.

Function: non-matching-position-helper ((source STRING) (start INTEGER) (end INTEGER) (match STRING)) : INTEGER

Helper for non-matching-position that requires end to not be null.

Method on BUFFERED-STRING: nth (self (position INTEGER)) : CHARACTER

Return the character in self at position.

Method on NATIVE-VECTOR: nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))

Return the element in self at position.

Method on BUFFERED-STRING: nth-setter (self (ch CHARACTER) (position INTEGER)) : CHARACTER

Set the character in self at position to ch.

Method on LONG-INTEGER: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Method on ARRAY: null? (x) : BOOLEAN

Return true if x is undefined (handled specially by all translators).

Function: number-less-than? ((x NUMBER-WRAPPER) (y NUMBER-WRAPPER)) : BOOLEAN

Generic number comparison that works with integers, longs and floats.

Method on VECTOR-SEQUENCE: object-equal? (x (y OBJECT)) : BOOLEAN

Return TRUE iff the sequences x and y are structurally equivalent. Uses equal? to test equality of elements.

Method on INTEGER: odd? (x) : BOOLEAN

Return true if x is an odd number.

Method on LONG-INTEGER: odd? (x) : BOOLEAN

Return true if x is an odd number.

Macro: only-if ((test OBJECT) (expression OBJECT)) : OBJECT

If test is TRUE, return the result of evaluating expression.

Function: open-network-stream ((host STRING) (port INTEGER)) : INPUT-STREAM OUTPUT-STREAM

Open a TCP/IP network stream to host at port and return the result as an input/output stream pair.

Method on COLLECTION: ordered? (self) : BOOLEAN

Return true if the collection self is ordered.

Function: outline-depth-exceeded? ((current-depth INTEGER) (depth-limit INTEGER)) : BOOLEAN

Helper function that returns true if current-depth exceeds depth-limit. This functions uses the convention that a null or negative value of depth-limit means the depth is unlimited. In those cases it always returns false.

Method on CLASS: parameters (self) : (LIST OF SYMBOL)

Returns the list of parameters names of self.

Function: parse-date-time-in-time-zone ((date-time-string STRING) (time-zone FLOAT) (start INTEGER) (end INTEGER) (error-on-mismatch? BOOLEAN)) : DECODED-DATE-TIME

Tries very hard to make sense out of the argument date-time-string and returns a time structure if successful. If not, it returns null. If error-on-mismatch? is true, parse-date-time will signal an error instead of returning null. Default values are 00:00:00 in the given timezone on the current date. If the given time-zone value is null, then the local time zone for the given date and time will be used as determined by the operating system.

Function: parse-date-time-relative-to-base ((date-time-string STRING) (base-date-time DECODED-DATE-TIME) (start INTEGER) (end INTEGER) (error-on-mismatch? BOOLEAN) (merge-null-fields? BOOLEAN)) : DECODED-DATE-TIME

Tries very hard to make sense out of the argument date-time-string and returns a time structure if successful. If not, it returns null. If error-on-mismatch? is true, parse-date-time will signal an error instead of returning null. Default values are passed in via base-date-time. If the timezone field that is passed in is NULL, then the local time zone for the parsed date/time will be used. If merge-null-fields? is true, then default values from base-time-date will be merged into missing components. If false, then they won’t be merged in for null components but can still be used as a basis for interpreatation of relative time strings like "now" or "yesterday"

Function: parse-float ((value STRING)) : FLOAT

Convert a float value string into a float. Leading and trailing whitespace is allowed. Raise an error if we have illegal number syntax which makes it preferable over the naive C++ stringToFloat conversion function which just returns 0.

Function: parse-integer ((value STRING)) : INTEGER

Convert an integer value string into an integer. Leading and trailing whitespace is allowed. Raise an error if we have illegal number syntax which makes it preferable over the naive C++ stringToInteger conversion function which just returns 0.

Function: parse-long-integer ((value STRING)) : LONG-INTEGER

Convert a long integer value string into a long integer. Leading and trailing whitespace is allowed. Raise an error if we have illegal number syntax which makes it preferable over the naive C++ stringToInteger conversion function which just returns 0.

Function: parse-options ((options OBJECT) (legalOptions&Types CONS) (coercionError? BOOLEAN) (allowOtherKeys? BOOLEAN)) : PROPERTY-LIST

Parse options, check their validity according to legalOptions&Types and return the result as a PROPERTY-LIST. legalOptions&Types has to either be NULL or a flat list of legal <keyword> <coercionType> pairs. A type specifcation of @IDENTITY means don’t perform any coercion. If coercionError? is TRUE, raise an error if a coercion failed. If allowOtherKeys? is TRUE options other than those specified in legalOptions&Types are allowed but won’t be coerced since we don’t know their type. A special implicit :options keyword that does not need to be declared can be used to pass in an already parsed options list from a caller, which will then be analyzed and used instead.

Function: parse-stella-name ((name STRING) (enableCaseConversion? BOOLEAN)) : STRING STRING KEYWORD

Parse the printed representation name of a STELLA symbol, surrogate or keyword and return its symbol name, module name and type (which is either :SYMBOL, :SURROGATE or :KEYWORD). name can be qualified and must use the exact same syntax and escape characters that would be used if it were to be read by read-s-expression-from-string (or unstringify). If enableCaseConversion? is TRUE, the returned symbol name will be upcased if the current module is case-insensitive; otherwise, it will be returned as is. Raises a read exception if name does not represent a symbol. This function is available primarily for efficiency, since it is about 10-15 times faster than unstringify.

Function: pick-hash-table-size-prime ((minSize INTEGER)) : INTEGER

Return a hash table prime of at least minSize.

Function: plist-to-kvlist ((self PROPERTY-LIST)) : (KEY-VALUE-LIST OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))

Convert self into a key-value list with identical and identically ordered keys and values.

Method on INTEGER: plus? (x) : BOOLEAN

Return true if x is greater than 0.

Method on LONG-INTEGER: plus? (x) : BOOLEAN

Return true if x is greater than 0.

Command: pop-load-path () : STRING

Remove the first element from the STELLA load path and return the removed element.

Method on OBJECT: primary-type (self) : TYPE

Returns the primary type of self. Gets defined automatically for every non-abstract subclass of OBJECT.

Method on RELATION: primitive? (self) : BOOLEAN

Return true if self is not a defined relation.

Macro: print (&body (body CONS)) : OBJECT

Print arguments to the standard output stream.

Function: print-configuration-properties ((configuration CONFIGURATION-TABLE) (stream OUTPUT-STREAM)) :

Print all properties defined in configuration to stream.

Function: print-exception-context ((e NATIVE-EXCEPTION) (stream OUTPUT-STREAM)) :

Prints system dependent information about the context of the specified exception e. For example, in Java it prints a stack trace. In Lisp, it is vendor dependent.

Command: print-outline ((thing OBJECT) (stream OUTPUT-STREAM) (depth INTEGER) (named? BOOLEAN)) :

Print an outline of thing and its subparts on stream. If depth is non-negative, only depth levels will be printed. If named? is TRUE, then only named entities will be printed.

This function is intended to be used on things like modules, contexts, concepts, etc. that have hierarchical structure. If thing doesn’t have a hierarchical structure, it will just be printed.

Command: print-properties () :

Print all current configuration property information to standard output.

Function: print-recycle-lists () :

Print the current state of all recycle lists.

Macro: print-spaces (&body (body CONS)) : OBJECT

(print-spaces [stream] N) prints N spaces onto stream. If no stream form is provided, then STANDARD-OUTPUT will be used.

Command: print-stella-features () :

Print the list of enabled and disabled STELLA features.

N-Command: print-unbound-surrogates (&rest (args OBJECT)) :

Print all unbound surrogates visible from the module named by the first argument (a symbol or string). Look at all modules if no module name or null was supplied. If the second argument is true, only consider surrogates interned in the specified module.

Function: print-undefined-methods ((module MODULE) (local? BOOLEAN)) :

Print all declared but not yet defined functions and methods in module. If local? is true, do not consider any parent modules of module. If module is NULL, look at all modules in the system. This is handy to pinpoint forward declarations that haven’t been followed up by actual definitions.

N-Command: print-undefined-super-classes ((class NAME)) :

Print all undefined or bad (indirect) super classes of class.

Function: private-class-methods ((class CLASS)) : (ITERATOR OF METHOD-SLOT)

Iterate over all private methods attached to class.

Function: private-class-storage-slots ((class CLASS)) : (ITERATOR OF STORAGE-SLOT)

Iterate over all private storage-slots attached to class.

Method on RELATION: private? (self) : BOOLEAN

Return true if self is not public.

Function: probe-directory? ((fileName FILE-NAME)) : BOOLEAN

Return true if file fileName exists and is a directory. Note that this does not necessarily mean that the directory can also be read.

Function: process-command-line-arguments ((count INTEGER) (arguments (ARRAY () OF STRING)) (unhandledOptionAction KEYWORD)) :

Interpret any command line arguments for which handlers have been registered. Leave any remaining unprocessed arguments in *unprocessed-command-line-arguments*. If any unprocessed arguments use option syntax (that is they start with a -), proceed according to unhandledOptionAction which can be one of :ignore, :warn or :error. This ensures that at any point in the option processing, *unprocessed-command-line-arguments* accurately reflects the arguments which have been either skipped or not handled yet.

Function: process-doctype ((doctype-declaration CONS)) : XML-DOCTYPE

Takes an S-Expression representing a doctype and processes into a DOCTYPE object.

N-Command: ptrans ((statement OBJECT)) :

Translate statement to Common-Lisp and print the result.

Function: public-class-methods ((class CLASS)) : (ITERATOR OF METHOD-SLOT)

Iterate over all private methods attached to class.

Function: public-class-storage-slots ((class CLASS)) : (ITERATOR OF STORAGE-SLOT)

Iterate over all public storage-slots attached to class.

Method on CLASS: public-slots (self) : (ITERATOR OF SLOT)

Return an iterator over public slots of self.

Method on OBJECT: public-slots (self) : (ITERATOR OF SLOT)

Return an iterator over public slots of self.

Method on SLOT: public? (self) : BOOLEAN

True if self or one it its ancestors is marked public.

Command: push-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Add the directories listed in the |-separated path to the front of the STELLA load path. Return the resulting load path.

Macro: pushf ((place CONS) (value OBJECT)) : OBJECT

Push value onto the cons list place.

Function: put-slot-value ((self STANDARD-OBJECT) (slot STORAGE-SLOT) (value OBJECT)) : OBJECT

Set or insert value for the slot slot on self. CAUTION: Assumes that collection-valued slots are non-null.

Function: qualified-stella-name? ((name STRING)) : BOOLEAN

Return TRUE if name is a symbol or surrogate qualified with a module pathname or a module pathname ending with a /. Assumes that name is the printed representation of a STELLA symbol (potentially containing escape characters).

Function: read-global-variable-value ((variable GLOBAL-VARIABLE)) : OBJECT

Interpreted global variable reader which reads and returns its native value which will be wrapped if necessary. This will access the value at the top of the special stack.

Function: read-line2 ((stream INPUT-STREAM)) : STRING KEYWORD

Read one line from stream and return the result and a keyword that indicates the terminator for that line ending: :CR :LF :CRLF or :EOF. This is not platform-dependent and differs from read-line by returning a second value. It may hang when used on interactive streams such as terminal or network streams with only CR line endings. It should only be used on file or string input streams.

Function: read-native-variable-value ((var NATIVE-OBJECT-POINTER) (type TYPE)) : OBJECT

Interpreted variable reader which reads a native code variable represented by var of type type and returns its value which will be wrapped if necessary. If var is a special variable, this will access the current dynamic value at the top of the special stack. This relies upon type being completely accurate and bad things will happen if it is not.

Function: read-slot-value ((self STANDARD-OBJECT) (slot STORAGE-SLOT)) : OBJECT

Read and return a (possibly wrapped) value for the slot slot on self.

Function: read-xml-expressions ((filename STRING)) : CONS

Read all of the top-level XML expressions from filename and return them in a list.

Method on STORAGE-SLOT: reader (self) : SYMBOL

Name of a method called to read the value of the slot self.

Function: register-cmd-line-option (&rest (options OBJECT)) :

Register a command line option. :key identifies the name of the option which will usually start with a dash such as -e or --eval. :key2 and :key3 can be used to supply additional options (e.g., long option formats). To supply even more keys, a list can be supplied with the :keys option. If a :property is supplied, this option simply sets or adds to the values of the specified system configuration property. If a :handler name is specified, its function will be used to interpret the values of the option. :documentation can be used to supply a documentation string which will be printed by the help-option-handler (usually bound to -?). :value-type describes what type an option value should be coerced to before assigning it to the specified configuration :property. :n-arguments describes how many arguments this option takes. This will be 0 for simple switches and can be 1 or greater than one for option handlers that need one or more arguments. :default-value defines the value to use for zero-argument :property options. If :multi-valued? is true, values of multiple occurrences of the option will be added to the specified configuration :property. :error-action can be one of :ignore, :warn or :error to specify what to do in case an error is encountered during option processing.

Function: register-property-demon ((property STRING) (demonName SYMBOL)) :

Register the function named demonName as the demon for property. Demons will be run as after demons on every configuration table update. Set the property stella.test.propertyDemon to see a test demon in action.

Function: regular-integer-valued? ((x LONG-INTEGER)) : BOOLEAN

Return true if x can be represented by a regular integer.

Function: relative-unlogicalize-pathname ((pathName STRING)) : STRING

If pathName is a logical pathname translate it, however, remove the :root-directory prefix of the logical host. Otherwise, return pathName as is.

Method on INTEGER: rem (x (y INTEGER)) : INTEGER

Return the remainder from dividing x by y. The sign of the result is always the same as the sign of x. This has slightly different behavior than the mod function, and has less overhead in C++ and Java, which don’t have direct support for a true modulus function.

Method on LONG-INTEGER: rem (x (y LONG-INTEGER)) : LONG-INTEGER

Return the remainder from dividing x by y. The sign of the result is always the same as the sign of x. This has slightly different behavior than the mod function, and has less overhead in C++ and Java, which don’t have direct support for a true modulus function.

Function: remove-configuration-property ((property STRING) (value OBJECT) (configuration CONFIGURATION-TABLE)) : OBJECT

Remove value from property in configuration and return it. Use the global system configuration table if configuration is NULL.

Method on COLLECTION: remove-duplicates (self) : (LIKE SELF)

Return self with duplicates removed. Preserves the original order of the remaining members.

Method on CONS: remove-duplicates-equal (self) : (LIKE SELF)

remove-duplicates (which see) using an equal? test. IMPORTANT: since this uses hashing to speed things up, an equal-hash-code method needs to be defined for this to work.

Method on LIST: remove-duplicates-equal (self) : (LIKE SELF)

remove-duplicates (which see) using an equal? test.

Method on HEAP: replace-heap-root (self (value (LIKE (ANY-VALUE SELF)))) :

Replace the current root of self with value and restore the heap property. Signal an error if self is empty. Maintains self as a Min-heap if selfs predicate has < semantics; otherwise as a Max-heap.

Method on CLASS: required-slots (self) : (LIST OF SYMBOL)

Returns a list of names of required slots for self.

Method on STORAGE-SLOT: required? (self) : BOOLEAN

True if a value must be assigned to this slot at creation time.

Method on CROSS-PRODUCT-ITERATOR: reset (self) :

Reset self to its initially allocated state. Note, that this is somewhat expensive, costing almost as much as allocating the iterator.

Command: reset-stella-features () :

Reset STELLA features to their default settings.

Method on BUFFERED-STRING: resize-buffer (self (size INTEGER)) : MUTABLE-STRING

Change the size of self to size. If size is smaller than the current size of self, it’s buffer will be truncated.

Method on VECTOR-SEQUENCE: reverse (self) : (LIKE SELF)

Reverse the order of elements in the active portion of self.

Function: reverse-interval ((lowerbound INTEGER) (upperbound INTEGER)) : REVERSE-INTEGER-INTERVAL-ITERATOR

Create a reverse interval object.

Function: root-binary-directory () : FILE-NAME

Accessor to determine the currently active binary directory root. If it is defined as an option in the currently active system action, use that. If we have an active system, use its value, otherwise use the STELLA default value.

Function: root-native-directory () : FILE-NAME

Accessor to determine the currently active native directory root. If it is defined as an option in the currently active system action, use that. If we have an active system, use its value, otherwise use the STELLA default value.

Function: root-source-directory () : FILE-NAME

Accessor to determine the currently active sources directory root. If it is defined as an option in the currently active system action, use that. If we have an active system, use its value, otherwise use the STELLA default value.

Function: run-hooks ((hooklist HOOK-LIST) (argument OBJECT)) :

Run all hook functions in hooklist, applying each one to argument.

Function: running-as-lisp? () : BOOLEAN

Return true if the executable code is a Common Lisp application.

Function: running-in-language () : KEYWORD

Returns the keyword for the language the current implementation is running in.

Function: running-system-information () : STRING

Returns an information string about the current running system environment.

Function: safe-compare-strings ((x STRING) (y STRING) (collation KEYWORD)) : INTEGER

Variant of compare-strings that also tolerates NULL values. NULL sorts after everything else in any collation.

Function: safe-equal-hash-code ((self OBJECT)) : INTEGER

Return a hash code for self. Just like equal-hash-code - which see, but also works for NULL. equal-hash-code methods that expect to handle NULL components should use this function for recursive calls.

Function: safe-hash-code ((self OBJECT)) : INTEGER

Return a hash code for self. Just like hash-code - which see, but also works for NULL.

Function: safe-lookup-slot ((class CLASS) (slot-name SYMBOL)) : SLOT

Alias for lookup-slot. Kept for backwards compatibility.

Macro: safety ((level INTEGER-WRAPPER) (test OBJECT) &body (body CONS)) : OBJECT

Signal warning message, placing non-string arguments in quotes.

Function: save-configuration-file ((table CONFIGURATION-TABLE) (file FILE-NAME) (title STRING)) :

Save table as a configuration file. Uses a Java-style property file syntax.

Function: save-configuration-value ((stream OUTPUT-STREAM) (value OBJECT)) :

Save value to stream as a properly formatted configuration value.

Function: search-cons-tree-with-filter? ((tree OBJECT) (value OBJECT) (filter CONS)) : BOOLEAN

Return true iff the value value is embedded within the cons tree tree. Uses an eql? test. Does not descend into any cons whose first element matches an element of filter.

Function: search-for-object ((self OBJECT) (typeref OBJECT)) : OBJECT

If self is a string or a symbol, search for an object named self of type type. Otherwise, if self is an object, return it.

Function: seed-random-number-generator () :

Seeds the random number generator based on the current time.

Function: seed-random-number-generator2 () :

Seeds the random number generator based on the current time and /dev/random if it is available.

Function: sequence ((collectiontype TYPE) &rest (values OBJECT)) : (SEQUENCE OF OBJECT)

Return a sequence containing values, in order.

Command: set-call-log-break-point ((count INTEGER)) :

Set a call log break point to count. Execution will be interrupted right at the entry of the countth logged function call.

Function: set-configuration-property ((property STRING) (value OBJECT) (configuration CONFIGURATION-TABLE)) : OBJECT

Set property in configuration to value and return it. Use the global system configuration table if configuration is NULL.

Method on DECODED-DATE-TIME: set-current-date (values-structure) :

Sets the current date into values-structure

Method on DECODED-DATE-TIME: set-current-date-time (values-structure) :

Sets the current date and time into values-structure

Method on DECODED-DATE-TIME: set-current-time (values-structure) :

Sets the current time into values-structure

Command: set-load-path ((path STRING)) : (CONS OF STRING-WRAPPER)

Set the STELLA load path to the |-separated directories listed in path. Return the resulting load path.

Command: set-log-level ((module STRING) (level OBJECT)) :

Set the log-level for module to level. This is a convenience function for this common operation.

Command: set-logging-parameters ((module STRING) &rest (params&values OBJECT)) :

Set logging parameters for module. The supported parameters are: :LOG-LEVELS - a cons list of legal levels in ascending log level order; for example, (:NONE :LOW :MEDIUM :HIGH) or (0 1 2 3). :LEVEL - the current log level for module :STREAM - the stream or file to log to (defaults to STANDARD-OUTPUT) :PREFIX - the prefix to use to identify the module (defaults to module) :MAX-WIDTH - logging output lines will be kept to approximately this width (defaults to 10000, minimum width of about 30 is used to print line header information).

Function: set-optimization-levels ((safety INTEGER) (debug INTEGER) (speed INTEGER) (space INTEGER)) :

Set optimization levels for the qualities safety, debug, speed, and space.

Command: set-property ((property NAME) (value OBJECT)) :

Set property (a string or symbol) in the configuration table to value. Note that property is evaluated and will need to be quoted if supplied as a symbol. Symbols will also be upcased if this command is run in a non-case-sensitive module.

Command: set-stella-feature (&rest (features KEYWORD)) :

Enable all listed STELLA features.

Command: set-translator-output-language ((new-language KEYWORD)) : KEYWORD

Set output language to new-language. Return previous language.

Macro: setq? ((variable SYMBOL) (expression CONS)) : OBJECT

Assign variable the result of evaluating expression, and return TRUE if expression is not NULL else return FALSE.

Function: shadowed-symbol? ((symbol GENERALIZED-SYMBOL)) : BOOLEAN

Return true if symbol is shadowed in its home module.

Method on INTEGER: shift-right (arg (count INTEGER)) : INTEGER

Shift arg to the right by count positions and 0-extend from the left if arg is positive or 1-extend if it is negative. This is an arithmetic shift that preserve the sign of arg and is equivalent to dividing arg by 2** count.

Method on LONG-INTEGER: shift-right (arg (count INTEGER)) : LONG-INTEGER

Shift arg to the right by count positions and 0-extend from the left if arg is positive or 1-extend if it is negative. This is an arithmetic shift that preserve the sign of arg and is equivalent to dividing arg by 2** count.

Macro: signal ((type SYMBOL) &body (body CONS)) : OBJECT

Signal error message, placing non-string arguments in quotes.

Macro: signal-read-error (&body (body CONS)) : OBJECT

Specialized version of signal that throws a READ-EXCEPTION.

Method on VECTOR: sort (self (predicate FUNCTION-CODE)) : (VECTOR OF (LIKE (ANY-VALUE SELF)))

Perform a destructive sort of self according to predicate, and return the result. If predicate has a < semantics, the result will be in ascending order. If predicate is null, a suitable < predicate is chosen depending on the first element of self, and it is assumed that all elements of self have the same type (supported element types are GENERALIZED-SYMBOL, STRING, INTEGER, and FLOAT).

Method on HEAP: sort (self (predicate FUNCTION-CODE)) : (HEAP OF (LIKE (ANY-VALUE SELF)))

Sort the heap self according to predicate (in ascending order if predicate has < semantics). If predicate is NULL simply use selfs internal predicate (the normal case). If it is different from selfs internal predicate, heapify self first according to the new predicate, store the new predicate in self and then sort the heap. Note that a sorted array automatically satisfies the heap property. This is slightly different than a regular heap sort due to the way HEAP’s are maintained; however, the complexity is the same.

Method on CONS: sort-objects (self (slot STORAGE-SLOT) (predicate FUNCTION-CODE)) : (CONS OF (LIKE (ANY-VALUE SELF)))

Just like sort but assumes each element of self has a slot whose value will be used for comparison. Elements must be descendants of STANDARD OBJECT. Note that while this will work with literal-valued slots, it will cause value wrapping everytime slot is read.

Method on VECTOR: sort-objects (self (slot STORAGE-SLOT) (predicate FUNCTION-CODE)) : (VECTOR OF (LIKE (ANY-VALUE SELF)))

Just like sort but assumes each element of self has a slot whose value will be used for comparison. Elements must be descendants of STANDARD OBJECT. Note that while this will work with literal-valued slots, it will cause value wrapping everytime slot is read.

Method on VECTOR: sort-tuples (self (n INTEGER) (predicate FUNCTION-CODE)) : (VECTOR OF (LIKE (ANY-VALUE SELF)))

Just like sort but assumes each element of self is a tuple (a cons) whose n-th element (0-based) will be used for comparison.

Function: split-string ((input STRING) (separator CHARACTER)) : (CONS OF STRING-WRAPPER)

Split input into separate strings based on the separator character.

Command: start-function-call-logging ((fileName STRING)) :

Start function call logging to fileName.

Function: starts-with? ((string STRING) (prefix STRING) (start INTEGER)) : BOOLEAN

Return TRUE if string starts with prefix starting from start (which defaults to 0 if it is supplied as NULL).

Function: stella-collection? ((self OBJECT)) : BOOLEAN

Return true if self is a native collection.

Command: stella-information () : STRING

Returns information about the current Stella implementation. Useful when reporting problems.

Function: stella-integer-to-string-in-base ((integer LONG-INTEGER) (base INTEGER)) : STRING

STELLA version of integer-to-string-in-base which is faster than the C++ version we have but slower than the native Java version.

Function: stella-object? ((self OBJECT)) : BOOLEAN

Return true if self is a member of the STELLA class OBJECT.

Function: stella-version-string () : STRING

Return a string identifying the current version of STELLA.

Function: stellafy ((thing LISP-CODE) (targetType TYPE)) : OBJECT

Partial inverse to lispify. Convert the Lisp object thing into a Stella analogue of type targetType. Note: See also stellify. it is similar, but guesses targetType on its own, and makes somewhat different translations.

Function: stellify ((self OBJECT)) : OBJECT

Convert a Lisp object into a STELLA object.

Command: stop-function-call-logging () :

Stop function call logging and close the current log file.

Method on OUTPUT-FILE-STREAM: stream-position (self) : LONG-INTEGER

Return the current position of the file input cursor in self.

Method on INPUT-FILE-STREAM: stream-position (self) : LONG-INTEGER

Return the current position of the file input cursor in self.

Method on OUTPUT-FILE-STREAM: stream-position-setter (self (newpos LONG-INTEGER)) : LONG-INTEGER

Set the current position of the file input cursor in self to newpos.

Method on INPUT-FILE-STREAM: stream-position-setter (self (newpos LONG-INTEGER)) : LONG-INTEGER

Set the current position of the file input cursor in self to newpos. If self has any tokenizer state associated with it, this will also reset to the start state of the tokenizer table; otherwise, behavior would be unpredictable unless the character class of the new position is exactly the same as the one following the most recent token.

Method on INPUT-STREAM: stream-to-string (from) : STRING

Read all of the input from stream and return it as a string.

Function: string-compare-case-normalized ((x STRING) (y STRING)) : INTEGER

Compare x and y and return -1, 0, or 1, depending on whether x is less than, equal, or greater than y relative to the :ascii-case-normalized collation. In this collation a < A < b which gives strings that only differ in case a definite order while otherwise behaving identically to :ascii-case-insensitive. This is similar to using a Java Collator for Locale.US with strength set to TERTIARY (which see).

Function: string-search-ignore-case ((string STRING) (substring STRING) (start INTEGER)) : INTEGER

Return start position of the left-most occurrence of substring in string, beginning from start. Return NULL if it is not a substring. The comparison ignores differences in letter case.

Function: string-to-calendar-date-with-default ((input-date STRING) (default-date DECODED-DATE-TIME)) : CALENDAR-DATE

Returns a calendar date object representing the date and time parsed from the input-date string. Default values for missing fields and the interpretation of relative references come from default-date. If the default-date is null, the current date will be used. If a null set of defaults is desired, use *NULL-DECODED-DATE-TIME*. If no valid parse is found, null is returned.

Function: string-to-decoded-date-time ((input STRING)) : DECODED-DATE-TIME

Returns a decoded date-time object representing the date and time parsed from the input string. If no valid parse is found, null is returned.

Function: string-to-int ((string STRING)) : INTEGER

Convert a string representation of an integer into an integer. This is a convenience function that ensures a regular integer return value. If string represents a long integer, the behavior is undefined. Use parse-integer if the syntax of string needs to be checked for errors.

Function: string-to-surrogate ((self STRING)) : SURROGATE

Return a surrogate with the name self visible in the current module. Very tricky: The logic is designed to avoid returning an inherited surrogate that has no value. In that case, a new local surrogate is created that shadows the inherited surrogate.

Function: string-to-time-duration ((duration STRING)) : TIME-DURATION

Parses and returns an time-duration object corresponding to duration. The syntax for time duration strings is "{plus|minus} N days[; M ms]" where N and M are integer values for days and milliseconds. If no valid parse is found, null is returned.

Function: string-trim ((string STRING)) : STRING

Remove any leading and trailing white space from string and return a copy of the trimmed substring (which might be empty if we had all white space). If no white space was removed, string is returned unmodified and uncopied.

Function: subclass-of? ((subClass CLASS) (superClass CLASS)) : BOOLEAN

Return true if subClass is a subclass of superClass.

Method on BUFFERED-STRING: subsequence (self (start INTEGER) (end INTEGER)) : STRING

Return a substring of string beginning at position start and ending up to but not including position end, counting from zero. An end value of NULL stands for the rest of the string.

Method on MUTABLE-STRING: subsequence (string (start INTEGER) (end INTEGER)) : STRING

Return a substring of string beginning at position start and ending up to but not including position end, counting from zero. An end value of NULL stands for the rest of the string.

Method on STRING: substitute-characters (self (new-chars STRING) (old-chars STRING)) : STRING

Substitute all occurences of of a member of old-chars with the corresponding member of new-chars in the string self. Returns a new string.

Method on MUTABLE-STRING: substitute-characters (self (new-chars STRING) (old-chars STRING)) : MUTABLE-STRING

Substitute all occurences of of a member of old-chars with the corresponding member of new-chars in the string self. IMPORTANT: The return value should be used instead of relying on destructive substitution, since the substitution will not be destructive in all translated languages.

Function: subtype-of? ((sub-type TYPE) (super-type TYPE)) : BOOLEAN

Return true iff the class named sub-type is a subclass of the class named super-type.

Method on CLASS: super-classes (self) : (ITERATOR OF CLASS)

Returns an iterator that generates all proper super classes of self.

Function: surrogate-name? ((name STRING)) : BOOLEAN

Return TRUE if name is prefixed by SURROGATE-PREFIX-CHARACTER.

Method on SURROGATE: surrogatify (self) : SURROGATE

Converts self into a surrogate.

Method on SYMBOL: surrogatify (self) : SURROGATE

Converts self into a surrogate (same semantics as symbol-to-surrogate which see).

Method on STRING: surrogatify (self) : SURROGATE

Converts self into a surrogate.

Method on OBJECT: sweep (self) :

Default method. Sweep up all self-type objects.

Function: symbol-to-surrogate ((self SYMBOL)) : SURROGATE

Return a surrogate with the same name as self. Very tricky: The logic is designed to avoid returning an inherited surrogate that has no value. In that case, a new local surrogate is created that shadows the inherited surrogate. Unlike string-to-surrogate, the search starts first from the home context of self, and if that fails, then it restarts in *module*.

Function: symbol-to-type ((self SYMBOL)) : SURROGATE

Convert self into a surrogate with the same name and module.

Method on STORAGE-SLOT: system-default-value (self) : OBJECT

Return a default value expression, or if self has dynamic storage, an initial value expression.

Method on SLOT: system-default-value (self) : OBJECT

Return a default value expression, or if self has dynamic storage, an initial value expression.

Function: system-loaded-or-started-up? ((name STRING)) : BOOLEAN

Return true if system name has either been loaded or initialized with its startup function.

Function: system-loaded? ((name STRING)) : BOOLEAN

Return true if system name has been loaded.

Command: terminate-program () :

Terminate and exit the program with normal exit code.

Function: test-property-demon ((action KEYWORD) (property STRING) (value OBJECT) (table CONFIGURATION-TABLE)) :

A test demon for the property demon machinery which simply prints arguments.

Method on BUFFERED-STRING: the-string (self) : STRING

Return a substring of string beginning at position start and ending up to but not including position end, counting from zero. An end value of NULL stands for the rest of the string.

Method on TIME-DURATION: time-duration-to-string (date) : STRING

Returns a string representation of date

Function: time-zone-format60 ((timezone FLOAT) (include-colon? BOOLEAN)) : STRING

Format zone as an hh:mm or hhmm string depending on include-colon?

Function: toggle-output-language () : KEYWORD

Switch between Common Lisp and C++ as output languages.

Function: tokenize-string ((string STRING) (punctuationchars STRING) (quotechars STRING) (escapechars STRING)) : (CONS OF CONS)

Simple tokenizer that is somewhere between Java’s StringTokenizer and StreamTokenizer in functionality. It doens’t specially support number tokens nor comment strings/sequences even though this could be added at the expense of some extra complexity. Returns a list of (<token-string> <token-type>) pairs, where the token type is one of :TEXT, :PUNCTUATION or :QUOTE, i.e., all white space is ignored and escape characters are handled and removed. For example:

 
  (tokenize-string "for(i='fo^'o'; i>0; i++)" "()=<>+-;" "'" "^")
  =>
  (("for" :TEXT) ("(" :PUNCTUATION) ("i" :TEXT)
   ("=" :PUNCTUATION) ("'" :QUOTE) ("fo'o" :TEXT)
   ("'" :QUOTE) (";" :PUNCTUATION) ("i" :TEXT)
   (">" :PUNCTUATION) ("0" :TEXT) (";" :PUNCTUATION)
   ("i" :TEXT) ("++)" :PUNCTUATION))

NOTE: this aggregates multiple punctuation characters that immediately follow each other into a single token which is (generally) useful to pickup multi-character operators such as ++, >=, etc. It’s still easy to pick them apart in a post-processing step if necessary (e.g., for the ++) case above), so we leave this for now as a feature.

Function: top-level-stella-system-directory? ((directory FILE-NAME)) : BOOLEAN

Return TRUE if directory is a top-level STELLA installation directory containing one or more STELLA systems. We currently determine this solely by looking for the existence of at least one relevant top-level native directory. This is needed to find system root directories and other relevant STELLA installation directories.

Macro: trace-if ((keyword OBJECT) &body (body CONS)) : OBJECT

If keyword is a trace keyword that has been enabled with add-trace print all the elements in body to standard output. Otherwise, do nothing. keyword can also be a list of keywords in which case printing is done if one or more of them are trace enabled.

Command: translate-system ((systemName STRING) &rest (language&options OBJECT)) : BOOLEAN

Translate all of the STELLA source files in system systemName into language (the optional first argument). The following keyword/value options are recognized:

:language: can be used as an alternative to the optional language argument. If not specified, the language of the running implementation is assumed.

:two-pass? (default false): if true, all files will be scanned twice, once to load the signatures of objects defined in them, and once to actually translate the definitions.

:force-translation? (default false): if true, files will be translated whether or not their translations are up-to-date.

:development-settings? (default false): if true translation will favor safe, readable and debuggable code over efficiency (according to the value of :development-settings on the system definition). If false, efficiency will be favored instead (according to the value of :production-settings on the system definition).

:production-settings? (default true): inverse to :development-settings?.

:recursive? (default false): if true, perform translate-system with the provided options on systemName as well as all its required systems and so on. Required systems will be processed first. Note that even without this option, any required systems that have not yet been loaded or started up will also be processed, since that is assumed when loading systemName and supporting modules from a definition file.

:root-source-directory, :root-native-directory, :root-binary-directory: if specified these directories will be used to override the respective paths provided in system definitions or computed as defaults from a system’s home location.

Function: translate-to-common-lisp? () : BOOLEAN

Return true if current output language is Common-Lisp.

Function: translate-to-cpp? () : BOOLEAN

Return true if current output language is C++

Function: translate-to-java? () : BOOLEAN

Return true if current output language is Java

Function: truncate ((n NUMBER)) : INTEGER

Truncate n toward zero and return the result.

Function: try-to-evaluate ((tree OBJECT)) : OBJECT

Variant of evaluate that only evaluates tree if it represents an evaluable expression. If it does not, tree is returned unmodified. This can be used to implement commands with mixed argument evaluation strategies.

Function: two-argument-least-common-superclass ((class1 CLASS) (class2 CLASS)) : CLASS

Return the most specific class that is a superclass of both class1 and class2. If there is more than one, arbitrarily pick one. If there is none, return null.

Function: two-argument-least-common-supertype ((type1 TYPE-SPEC) (type2 TYPE-SPEC)) : TYPE-SPEC

Return the most specific type that is a supertype of both type1 and type2. If there is more than one, arbitrarily pick one. If there is none, return @VOID. If one or both types are parametric, also try to generalize parameter types if necessary.

Method on SLOT: type (self) : TYPE

The type of a storage slot is its base type.

Method on SLOT: type-specifier (self) : TYPE-SPEC

If self has a complex type return its type specifier, otherwise, return type of self.

Function: type-to-symbol ((type TYPE)) : SYMBOL

Convert type into a symbol with the same name and module.

Method on SURROGATE: type-to-wrapped-type (self) : TYPE

Return the wrapped type for the type self, or self if it is not a bare literal type.

Function: unbound-surrogates ((module MODULE) (local? BOOLEAN)) : (ITERATOR OF SURROGATE)

Iterate over all unbound surrogates visible from module. Look at all modules if module is null. If local?, only consider surrogates interned in module.

Command: unbump-log-indent () :

Decrease the indentation level for subsequent log messages.

Function: unescape-html-string ((input STRING)) : STRING

Replaces HTML escape sequences such as &amp; with their associated characters.

Function: unescape-url-string ((input STRING)) : STRING

Takes a string and replaces %-format URL escape sequences with their real character equivalent according to RFC 2396.

Command: unprocessed-command-line-arguments () : (CONS OF STRING-WRAPPER)

Return all command line arguments which have not yet been processed by (or been ignored by) process-command-line-arguments. If arguments have not yet been processed, this will return NULL.

Function: unregister-all-cmd-line-options () :

Unregister all currently registered command line options.

Function: unregister-cmd-line-option ((key STRING)) :

Unregister the command line option identified by key under all its keys.

Function: unregister-property-demon ((property STRING)) :

Unregister any demon for property.

Command: unset-stella-feature (&rest (features KEYWORD)) :

Disable all listed STELLA features.

Method on INTEGER: unsigned-shift-right-by-1 (arg) : INTEGER

Shift arg to the right by 1 position and 0-extend from the left. This does not preserve the sign of arg and shifts the sign-bit just like a regular bit. In Common-Lisp we can’t do that directly and need to do some extra masking.

Method on LONG-INTEGER: unsigned-shift-right-by-1 (arg) : LONG-INTEGER

Shift arg to the right by 1 position and 0-extend from the left. This does not preserve the sign of arg and shifts the sign-bit just like a regular bit. In Common-Lisp we can’t do that directly and need to do some extra masking.

Function: unstringify-stella-source ((source STRING) (module MODULE)) : OBJECT

Unstringify a STELLA source string relative to module, or *MODULE* if no module is specified. This function allocates transient objects as opposed to unstringify-in-module or the regular unstringify.

Function: unwrap-boolean ((wrapper BOOLEAN-WRAPPER)) : BOOLEAN

Unwrap wrapper and return its values as a regular BOOLEAN. Map NULL onto FALSE.

Function: unwrap-function-code ((wrapper FUNCTION-CODE-WRAPPER)) : FUNCTION-CODE

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: unwrap-long-integer ((wrapper LONG-INTEGER-WRAPPER)) : LONG-INTEGER

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Function: unwrap-method-code ((wrapper METHOD-CODE-WRAPPER)) : METHOD-CODE

Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Method on ABSTRACT-DICTIONARY-ITERATOR: value-setter (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE (ANY-VALUE SELF))

Abstract method needed to allow application of this method on abstract iterator classes that do not implement it. By having this here all next? methods of dictionary iterators MUST use the slot-value paradigm to set the iterator value.

Macro: warn (&body (body CONS)) : OBJECT

Signal warning message, placing non-string arguments in quotes.

Macro: with-network-stream ((binding CONS) &body (body CONS)) : OBJECT

Sets up an unwind-protected form which opens a network socket stream to a host and port for input and output and closes it afterwards. Separate variables as provided in the call are bound to the input and output streams. Syntax is (WITH-NETWORK-STREAM (varIn varOut hostname port) body+)

Macro: with-permanent-objects (&body (body CONS)) : OBJECT

Allocate permanent (as opposed to transient) objects within the scope of this declaration.

Macro: with-system-definition ((systemnameexpression OBJECT) &body (body CONS)) : OBJECT

Set *currentSystemDefinition* to the system definition named system. Set *currentSystemDefinitionSubdirectory* to match. Execute body within that scope.

Macro: with-transient-objects (&body (body CONS)) : OBJECT

Allocate transient (as opposed to permanent) objects within the scope of this declaration. CAUTION: The default assumption is the allocation of permanent objects. The scope of with-transient-objects should be as small as possible, and the user has to make sure that code that wasn’t explicitly written to account for transient objects will continue to work correctly.

Function: wrap-boolean ((value BOOLEAN)) : BOOLEAN-WRAPPER

Return a literal object whose value is the BOOLEAN value.

Function: wrap-function-code ((value FUNCTION-CODE)) : FUNCTION-CODE-WRAPPER

Return a literal object whose value is the FUNCTION-CODE value.

Function: wrap-integer-value ((value LONG-INTEGER)) : NUMBER-WRAPPER

Return a literal object whose value is value. Choose a regular integer wrapper unless value is too large and needs to be stored in a long wrapper.

Function: wrap-long-integer ((value LONG-INTEGER)) : LONG-INTEGER-WRAPPER

Return a literal object whose value is the LONG-INTEGER value.

Function: wrap-method-code ((value METHOD-CODE)) : METHOD-CODE-WRAPPER

Return a literal object whose value is the METHOD-CODE value.

Function: wrapped-type-to-type ((self TYPE)) : TYPE

Return the unwrapped type for the wrapped type self, or self if it is not a wrapped type.

Function: wrapper-value-type ((self WRAPPER)) : TYPE

Return the type of the value stored in the wrapper self.

Function: write-global-variable-value ((variable GLOBAL-VARIABLE) (value OBJECT)) :

Interpreted global variable writer which sets its native value to value unwrappig it if necessary. This will change the current value at the top of the special stack.

Function: write-html-escaping-url-special-characters ((stream NATIVE-OUTPUT-STREAM) (input STRING)) :

Writes a string and replaces unallowed URL characters according to RFC 2396 with %-format URL escape sequences.

Function: write-native-variable-value ((var NATIVE-OBJECT-POINTER) (type TYPE) (value OBJECT)) :

Interpreted variable writer which sets a native code variable represented by var of type type to value which will be unwrapped if necessary. If var is a special variable, this will change the current dynamic value at the top of the special stack. This relies upon type being completely accurate and bad things will happen if it is not.

Function: write-slot-value ((self STANDARD-OBJECT) (slot STORAGE-SLOT) (value OBJECT)) : OBJECT

Write a (possibly wrapped) value for the slot slot on self.

Method on STORAGE-SLOT: writer (self) : SYMBOL

Name of a method called to write the value of the slot self.

Function: xml-base-attribute? ((item OBJECT)) : BOOLEAN

Return true if item is an XML attribute object

Function: xml-declaration-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by an XML DECLARATION tag

Function: xml-doctype-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by a DOCTYPE tag

Function: xml-element-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by an XML ELEMENT tag

Function: xml-global-attribute? ((item OBJECT)) : BOOLEAN

Return true if item is an XML attribute object

Function: xml-local-attribute? ((item OBJECT)) : BOOLEAN

Return true if item is an XML attribute object

Function: xml-processing-instruction-form? ((form OBJECT)) : BOOLEAN

Return true if form is a CONS headed by an XML PROCESSING INSTRUCTION tag

Function: xml-processing-instruction? ((item OBJECT)) : BOOLEAN

Return true if item is an XML processing instruction object

Function: xml-token-list-to-s-expression ((tokenList TOKENIZER-TOKEN) (doctype XML-DOCTYPE) (doctype-definition? BOOLEAN)) : OBJECT

Convert the XML tokenList (using doctype for guidance) into a representative s-expression and return the result. The doctype argument is currently only used for expansion of entity references. It can be null. The flag doctype-definition? should be true only when processing the DTD definition of a DOCTYPE tag, since it enables substitution of parameter entity values.

Every XML tag is represented as a cons-list starting with the tag as its header, followed by a possibly empty list of keyword value pairs representing tag attributes, followed by a possibly empty list of content expressions which might themselves be XML expressions. For example, the expression

<a a1=v1 a2=’v2’> foo <b a3=v3/> bar </a>

becomes

(<a> (<a1> "v1" <a2> "v2") "foo" (<b> (<a3> "v3")) "bar")

when represented as an s-expression. The tag names are subtypes of XML-OBJECT such as XML-ELEMENT, XML-LOCAL-ATTRIBUTE, XML-GLOBAL-ATTRIBUTE, etc. ?, ! and [ prefixed tags are encoded as their own subtypes of XML-OBJECT, namely XML-PROCESSING-INSTRUCTION, XML-DECLARATION, XML-SPECIAL, XML-COMMENT, etc. CDATA is an XML-SPECIAL tag with a name of CDATA.

The name is available using class accessors.

Function: yield-define-stella-class ((class CLASS)) : CONS

Return a cons tree that (when evaluated) constructs a Stella class object.

Function: zero-pad-integer ((value INTEGER) (size INTEGER)) : STRING

Returns a string representing value of at least length size, padded if necessary with 0 characters.

Method on INTEGER: zero? (x) : BOOLEAN

Return true if x is 0.

Method on LONG-INTEGER: zero? (x) : BOOLEAN

Return true if x is 0.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Hans Chalupsky on January 5, 2023 using texi2html 1.82.