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

6. Library Functions

6.1 Basic Constants and Predicates  
6.2 Numbers  
6.3 Characters  
6.4 Strings  
6.5 CONS Lists and Trees  
6.6 Lists  
6.7 Property and Key-Value Lists  
6.8 Vectors  
6.9 Hash Tables  
6.10 Key Value Maps  
6.11 Hash Sets  
6.12 Iterators  
6.13 Symbols  
6.14 Context and Modules  
6.15 Input and Output  
6.16 Files  
6.17 Dates and Times  
6.18 XML Support  
6.19 Miscellaneous  


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

6.1 Basic Constants and Predicates

???: true
Not yet implemented.

???: false
Not yet implemented.

Method: OBJECT null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: SECOND-CLASS-OBJECT null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: NATIVE-VECTOR null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: STRING null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: MUTABLE-STRING null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: CHARACTER null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: CODE null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: INTEGER null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: FLOAT null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: OBJECT defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: SECOND-CLASS-OBJECT defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: NATIVE-VECTOR defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: STRING defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: MUTABLE-STRING defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: CHARACTER defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: CODE defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: INTEGER defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: 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: OBJECT object-equal? (x (y OBJECT)) : BOOLEAN
Return true if x and y are eq?.

Method: 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] [ ? ]

6.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: INTEGER abs (x) : INTEGER
Return the absolute value of x.

Method: 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].

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.

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.

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] [ ? ]

6.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] [ ? ]

6.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: STRING empty? (x) : BOOLEAN
Return true if x is the empty string ""

Method: 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: STRING first (self) : CHARACTER
Return the first character of self.

Method: MUTABLE-STRING first (self) : CHARACTER
Return the first character of self (settable via setf).

Method: STRING second (self) : CHARACTER
Return the second character of self.

Method: MUTABLE-STRING second (self) : CHARACTER
Return the second character of self (settable via setf).

Method: STRING third (self) : CHARACTER
Return the third character of self.

Method: MUTABLE-STRING third (self) : CHARACTER
Return the third character of self (settable via setf).

Method: STRING fourth (self) : CHARACTER
Return the fourth character of self.

Method: MUTABLE-STRING fourth (self) : CHARACTER
Return the fourth character of self (settable via setf).

Method: STRING fifth (self) : CHARACTER
Return the fifth character of self.

Method: MUTABLE-STRING fifth (self) : CHARACTER
Return the fifth character of self (settable via setf).

Method: STRING nth (self (position INTEGER)) : CHARACTER
Return the character in self at position.

Method: MUTABLE-STRING nth (self (position INTEGER)) : CHARACTER
Return the character in self at position.

Method: STRING rest (self) : STRING
Not documented.

Method: STRING length (self) : INTEGER
Return the length of the string self.

Method: MUTABLE-STRING length (self) : INTEGER
Return the length of the string self.

Method: STRING member? (self (char CHARACTER)) : BOOLEAN
Not documented.

Method: 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: 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.

Method: 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: 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: 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: STRING remove (string (char CHARACTER)) : STRING
Remove all occurences of char from string.

Method: STRING substitute (self (new-char CHARACTER) (old-char CHARACTER)) : STRING
Substitute all occurences of old-char with new-char in the string self.

Method: 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.

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.

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] [ ? ]

6.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: CONS empty? (self) : BOOLEAN
Return true iff self equals nil.

Method: 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: 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: 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: 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: 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: 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: 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: 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: 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: CONS nth-rest (self (position INTEGER)) : (LIKE SELF)
Apply rest position times to self.

Method: CONS last (self) : (LIKE (ANY-VALUE SELF))
Return the last element of self.

Method: 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: CONS length (self) : INTEGER
Return the length of the CONS list self.

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

Method: CONS memb? (self (object OBJECT)) : BOOLEAN
Return true iff object is a member of the cons list self (uses an eq? test).

Method: 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: 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: CONS reverse (self) : (LIKE SELF)
Destructively reverse the members of the cons list self.

Method: 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: 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: 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: CONS substitute (self (inValue OBJECT) (outValue OBJECT)) : CONS
Destructively replace each appearance of outValue by inValue in the cons list self.

Method: 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: 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: CONS consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return self.

Method: CONS allocate-iterator (self) : (CONS-ITERATOR OF (LIKE (ANY-VALUE SELF)))
Not documented.

Method: CONS-ITERATOR next? (self) : BOOLEAN
Not documented.

Method: 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: 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.

6.5.1 CONS Lists as Sets  


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

6.5.1 CONS Lists as Sets

Method: 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: 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: 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: 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: 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: 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] [ ? ]

6.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: LIST empty? (self) : BOOLEAN
Return TRUE if the list self has no members.

Method: LIST non-empty? (self) : BOOLEAN
Return TRUE if the list self has at least one member.

Method: 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: 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: LIST first (self) : (LIKE (ANY-VALUE SELF))
Return the first item in the list self, or NULL if empty.

Method: LIST second (self) : (LIKE (ANY-VALUE SELF))
Return the second item in the list self, or NULL if empty.

Method: LIST third (self) : (LIKE (ANY-VALUE SELF))
Return the third item in the list self, or NULL if empty.

Method: LIST fourth (self) : (LIKE (ANY-VALUE SELF))
Return the fourth item in the list self, or NULL if empty.

Method: LIST fifth (self) : (LIKE (ANY-VALUE SELF))
Return the fifth item in the list self, or NULL if empty.

Method: LIST nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))
Return the nth item in the list self, or NULL if empty.

Method: LIST rest (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return a cons list of all but the first item in the list self.

Method: LIST last (self) : (LIKE (ANY-VALUE SELF))
Return the last element of self.

Method: LIST but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))
Generate all but the last element of the list self.

Method: LIST length (self) : INTEGER
Not documented.

Method: LIST member? (self (object OBJECT)) : BOOLEAN
Return TRUE iff object is a member of the list self (uses an eql? test).

Method: 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: 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: 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: LIST insert (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the front of the list self.

Method: LIST push (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the front of the list self.

Method: LIST insert-new (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the front of the list self unless its already a member.

Method: LIST insert-last (self (value (LIKE (ANY-VALUE SELF)))) :
Insert value as the last entry in the list self.

Method: LIST reverse (self) : (LIKE SELF)
Reverse the members of self (in place).

Method: LIST remove (self (value (LIKE (ANY-VALUE SELF)))) : (LIKE SELF)
Destructively remove all entries in self that match value.

Method: LIST remove-duplicates (self) : (LIKE SELF)
Destructively remove duplicates from self and return the result. Preserves the original order of the remaining members.

Method: LIST remove-deleted-members (self) : (LIKE SELF)
Not documented.

Method: 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: 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: LIST substitute (self (inValue OBJECT) (outValue OBJECT)) : (LIKE SELF)
Destructively replace each appearance of outValue by inValue in the list self.

Method: 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: 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: 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: LIST clear (self) :
Make self an empty list.

Method: LIST consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return a list of elements in self.

Method: LIST allocate-iterator (self) : (LIST-ITERATOR OF (LIKE (ANY-VALUE SELF)))
Not documented.

Method: LIST-ITERATOR next? (self) : BOOLEAN
Not documented.

Method: 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.

6.6.1 Lists as Sets  


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

6.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: 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: 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: 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: 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: 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: 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: SET insert (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the set self unless it is already a member.

Method: SET push (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the front of set self unless it is already a member.

Method: SET insert-last (self (value (LIKE (ANY-VALUE SELF)))) :
Add value to the end of set self unless it is already a member.

Method: 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: 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: 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: 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] [ ? ]

6.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: PROPERTY-LIST empty? (self) : BOOLEAN
Not documented.

Method: PROPERTY-LIST non-empty? (self) : BOOLEAN
Not documented.

Method: PROPERTY-LIST object-equal? (x (y OBJECT)) : BOOLEAN
Return TRUE if x and y represent the same set of key/value pairs..

Method: 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: PROPERTY-LIST length (self) : INTEGER
Not documented.

Method: PROPERTY-LIST lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: 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: 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: PROPERTY-LIST copy (self) : (LIKE SELF)
Return a copy of the list self. The conses in the copy are freshly allocated.

Method: PROPERTY-LIST clear (self) :
Make self an empty property list.

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

Method: 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: KEY-VALUE-LIST empty? (self) : BOOLEAN
Not documented.

Method: KEY-VALUE-LIST non-empty? (self) : BOOLEAN
Not documented.

Method: KEY-VALUE-LIST object-equal? (x (y OBJECT)) : BOOLEAN
Return TRUE if x and y represent the same set of key/value pairs.

Method: 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: KEY-VALUE-LIST length (self) : INTEGER
Not documented.

Method: KEY-VALUE-LIST lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: KEY-VALUE-LIST reverse (self) : (LIKE SELF)
Destructively reverse the members of the list self.

Method: 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: 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: 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: 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: 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: 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: 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: 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: KEY-VALUE-LIST clear (self) :
Make self an empty dictionary.

Method: KEY-VALUE-LIST consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return a list of key-value pairs in self.

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

Method: KV-LIST-ITERATOR next? (self) : BOOLEAN
Not documented.


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

6.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: VECTOR empty? (self) : BOOLEAN
Return true if self has length 0.

Method: VECTOR non-empty? (self) : BOOLEAN
Return true if self has length > 0.

Method: 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: 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: VECTOR first (self) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR second (self) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR third (self) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR fourth (self) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR fifth (self) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: VECTOR last (self) : (LIKE (ANY-VALUE SELF))
Return the last item in the vector self.

Method: VECTOR but-last (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))
Generate all but the last element of the vector self.

Method: VECTOR length (self) : INTEGER
Not documented.

Method: VECTOR member? (self (object OBJECT)) : BOOLEAN
Not documented.

Method: 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: 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: VECTOR insert-at (self (offset INTEGER) (value (LIKE (ANY-VALUE SELF)))) :
Not documented.

Method: VECTOR copy (self) : (VECTOR OF (LIKE (ANY-VALUE SELF)))
Return a copy of the vector self.

Method: 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: VECTOR consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return a list of elements in self.

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

Method: VECTOR-SEQUENCE insert (self (value (LIKE (ANY-VALUE SELF)))) :
Append value to the END of the sequence self. Resize the array if necessary.

Method: 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: VECTOR-SEQUENCE length (self) : INTEGER
Not documented.


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

6.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: HASH-TABLE lookup (self (key (LIKE (ANY-KEY SELF)))) : (LIKE (ANY-VALUE SELF))
Not documented.

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

Method: HASH-TABLE remove-at (self (key (LIKE (ANY-KEY SELF)))) :
Not documented.

Method: STRING-HASH-TABLE lookup (self (key STRING)) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: STRING-HASH-TABLE insert-at (self (key STRING) (value OBJECT)) :
Not documented.

Method: STRING-HASH-TABLE remove-at (self (key STRING)) :
Not documented.

Method: STRING-TO-INTEGER-HASH-TABLE lookup (self (key STRING)) : INTEGER
Not documented.

Method: STRING-TO-INTEGER-HASH-TABLE insert-at (self (key STRING) (value INTEGER)) :
Not documented.

Method: INTEGER-HASH-TABLE lookup (self (key INTEGER)) : (LIKE (ANY-VALUE SELF))
Not documented.

Method: INTEGER-HASH-TABLE insert-at (self (key INTEGER) (value OBJECT)) :
Not documented.

Method: 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: 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: 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: 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: STELLA-HASH-TABLE length (self) : INTEGER
Return the number of entries in self.

Method: STELLA-HASH-TABLE empty? (self) : BOOLEAN
Return TRUE if self has zero entries.

Method: STELLA-HASH-TABLE non-empty? (self) : BOOLEAN
Return TRUE if self has at least 1 entry.

Method: 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: 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: 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: STELLA-HASH-TABLE object-equal? (x (y OBJECT)) : BOOLEAN
Return TRUE if x and y represent the same set of key/value pairs.

Method: 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: 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: 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: STANDARD-OBJECT hash-code (self) : INTEGER
Not documented.

Method: STRING-WRAPPER hash-code (self) : INTEGER
Not documented.

Method: INTEGER-WRAPPER hash-code (self) : INTEGER
Not documented.

Method: FLOAT-WRAPPER hash-code (self) : INTEGER
Not documented.

Method: CHARACTER-WRAPPER hash-code (self) : INTEGER
Not documented.

Method: BOOLEAN-WRAPPER hash-code (self) : INTEGER
Not documented.

Method: STRING hash-code (self) : INTEGER
Not documented.

Method: INTEGER hash-code (self) : INTEGER
Not documented.

Method: FLOAT hash-code (self) : INTEGER
Not documented.

Method: CHARACTER hash-code (self) : INTEGER
Not documented.

Method: 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] [ ? ]

6.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: 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: 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: 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: KEY-VALUE-MAP length (self) : INTEGER
Return the number of entries in self.

Method: KEY-VALUE-MAP empty? (self) : BOOLEAN
Return TRUE if self has zero entries.

Method: KEY-VALUE-MAP non-empty? (self) : BOOLEAN
Return TRUE if self has at least 1 entry.

Method: 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: KEY-VALUE-MAP clear (self) :
Reset self to have zero entries.

Method: 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: KEY-VALUE-MAP consify (self) : CONS
Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

Method: KEY-VALUE-MAP object-equal? (x (y OBJECT)) : BOOLEAN
Return TRUE if x and y represent the same set of key/value pairs.

Method: 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] [ ? ]

6.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: 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: 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: 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: 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: 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: 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: 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: HASH-SET consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Collect all entries of self into a cons list and return the result.

Method: 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: 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: 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: 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: 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: 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: 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: 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] [ ? ]

6.12 Iterators

Method: ITERATOR empty? (self) : BOOLEAN
Return TRUE if the sequence represented by self has no elements. Side-effect free.

Method: ITERATOR member? (self (value OBJECT)) : BOOLEAN
Iterate over values of self, returning TRUE if one of them is eql to 'value.

Method: 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: 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: ITERATOR advance (self (n INTEGER)) : (LIKE SELF)
Return self after skipping over the first n elements in the (remainder of the) iteration.

Method: 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: ITERATOR consify (self) : (CONS OF (LIKE (ANY-VALUE SELF)))
Return a list of elements generated by self.

Method: ALL-PURPOSE-ITERATOR next? (self) : BOOLEAN
Apply the stored next? function to self.


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

6.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] [ ? ]

6.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: CONTEXT destroy-context (self) :
Make the translator happy.

Method: STRING destroy-context (self) :
Destroy the context self, and recursively destroy all contexts that inherit self.

Method: CONTEXT change-context (context) : CONTEXT
Change the current context to be the context context.

Method: 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: 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: MODULE change-module (module) : MODULE
Change the current module to be the module module.

Method: 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.

Function: push-world () : WORLD
Spawn a new world that is a child of the current context, and change the current context to the new world.

Function: 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: 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] [ ? ]

6.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] [ ? ]

6.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 :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.

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. Note that this will currently overrun for files that are longer than what can be represented by a STELLA integer.

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: 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] [ ? ]

6.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: 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: 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] [ ? ]

6.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: 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: 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: 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: 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] [ ? ]

6.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: DIMENSIONAL-ARRAY-MIXIN 1d-aref (self (i INTEGER)) : (LIKE (ANY-VALUE SELF))
Return the element of self at position [i].

Method: 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: 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: 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: 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: 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: 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: 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-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :
Insert the function named hookFunction into hookList.

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.

Method: 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: MEMOIZABLE-ITERATOR allocate-iterator (self) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))
Alias for clone-memoized-iterator.

Method: STORAGE-SLOT allocation (self) : KEYWORD
Return the most specific :allocation facet, or :instance if all inherited values are NULL.

Function: apply ((code FUNCTION-CODE) (arguments (CONS OF OBJECT))) : OBJECT
Apply code to arguments, returning a value of type OBJECT.

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: 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: 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: 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: 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: 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: 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: 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 :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: VECTOR-SEQUENCE clear (self) :
Clear self by setting its active length to zero.

Method: HEAP 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-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-to-float ((number NUMBER-WRAPPER)) : FLOAT
Coerce number to a float value.

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-symbol ((name NAME)) : GENERALIZED-SYMBOL
Return the (generalized) symbol represented by name. Return null if name is undefined or does not represent a string.

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: 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.

Method: 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: 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: 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: VECTOR-SEQUENCE copy (self) : (VECTOR-SEQUENCE OF (LIKE (ANY-VALUE SELF)))
Return a copy of the vector sequence self.

Method: CUSTOM-VECTOR-SEQUENCE copy (self) : (CUSTOM-VECTOR-SEQUENCE OF (LIKE (ANY-VALUE SELF)))
Return a copy of the vector sequence self.

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.

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: deactivate-demon ((demon DEMON)) :
Detach demon from the location(s) specified by its internal structure.

Method: 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.

Method: 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-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-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: LONG-INTEGER defined? (x) : BOOLEAN
Return true if x is defined (handled specially by all translators).

Method: 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: :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: 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: 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: 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: 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: INTEGER div (x (y INTEGER)) : INTEGER
Return the integer quotient from dividing x by y.

Method: 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.

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.

Macro: either ((value1 OBJECT) (value2 OBJECT)) : OBJECT
If value1 is defined, return that, else return value2.

Method: STRING-WRAPPER empty? (x) : BOOLEAN
Return true if x is the wrapped empty string ""

Method: VECTOR-SEQUENCE empty? (self) : BOOLEAN
Return true if self has length 0.

Method: HEAP empty? (self) : BOOLEAN
Return TRUE if self is empty.

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: 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.

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: 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: INTEGER even? (x) : BOOLEAN
Return true if x is an even number.

Method: LONG-INTEGER even? (x) : BOOLEAN
Return true if x is an even number.

Function: exception-message ((e NATIVE-EXCEPTION)) : STRING
Accesses the error message of the exception e.

Method: 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: HEAP fast-heap-root (self) : (LIKE (ANY-VALUE SELF))
Return the root of self which is assumed to be non-empty.

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

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.

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.

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-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: ACTIVE-OBJECT free (self) :
Remove all pointers between self and other objects, and then deallocate the storage for self.

Method: OBJECT free (self) :
Default method. Deallocate storage for self.

Method: ABSTRACT-HASH-TABLE free-hash-table-values (self) :
Call free on each value in the hash table 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: 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: 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-global-value ((self SURROGATE)) : OBJECT
Return the (possibly-wrapped) value of the global variable for the surrogate self.

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-quoted-tree ((tree-name STRING) (modulename STRING)) : CONS
Return the quoted tree with name tree-name.

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: 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: 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: 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.

Method: 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: 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: HEAP heap-root (self) : (LIKE (ANY-VALUE SELF))
Return the root of self (NULL if self is empty).

Method: 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.

Method: CLASS help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :
Helper method for print-outline

Method: MODULE help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :
Helper method for print-outline

Method: OBJECT help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :
Helper method for print-outline

Method: SLOT help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :
Helper method for print-outline

Method: CONTEXT help-print-outline (top (stream OUTPUT-STREAM) (current-depth INTEGER) (depth INTEGER) (named? BOOLEAN)) :
Helper method for print-outline

Method: 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: CLASS initial-value (self) : OBJECT
Return an initial value for the class self.

Method: 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: DIMENSIONAL-ARRAY-MIXIN initialize-array (self (initialValue (LIKE (ANY-VALUE SELF)))) :
Initialize the elements of self with initialValue.

Method: 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: STORAGE-SLOT initially (self) : OBJECT
Defines the value of a slot before it has been assigned a value.

Method: 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: 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: 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., the minimum of self if 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: 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-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))) :
Interpret any STELLA-relevant command line arguments.

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: VECTOR-SEQUENCE last (self) : (LIKE (ANY-VALUE SELF))
Return the last item in the vector self.

Method: CONS-ITERATOR length (self) : INTEGER
Iterate over self, and count how many items there are.

Method: HEAP length (self) : INTEGER
Return the length of the currently filled portion of self.

Method: DIMENSIONAL-ARRAY-MIXIN length (self) : INTEGER
Return the total number of elements in self.

Method: 2-DIMENSIONAL-ARRAY-MIXIN length (self) : INTEGER
Return the total number of elements in self.

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-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: CONS listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return a list of elements in self.

Method: LIST listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return self.

Method: KEY-VALUE-LIST listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return a list of key-value pairs in self.

Method: VECTOR listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return a list of elements in self.

Method: ITERATOR listify (self) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return a list of elements generated by self.

Function: 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.

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.

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: 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: 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: 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-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-configuration-property ((property STRING) (defaultValue WRAPPER) (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.

Method: SURROGATE lookup-global-variable (self) : GLOBAL-VARIABLE
Return a global variable with name self.

Method: GENERALIZED-SYMBOL lookup-global-variable (self) : GLOBAL-VARIABLE
Return a global variable with name self.

Method: STRING lookup-global-variable (self) : GLOBAL-VARIABLE
Return a global variable with name self.

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).

Method: 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: 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-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.

Method: INTEGER max (x (y INTEGER)) : INTEGER
Return the maximum of x and y. If either is NULL, return the other.

Method: LONG-INTEGER max (x (y LONG-INTEGER)) : LONG-INTEGER
Return the maximum of x and y. If either is NULL, return the other.

Method: FLOAT max (x (y FLOAT)) : FLOAT
Return the maximum of x and y. If either is NULL, return the other.

Method: NUMBER-WRAPPER max (x (y NUMBER-WRAPPER)) : NUMBER-WRAPPER
Return the maximum of x and y. If y is NULL, return x.

Method: CONS-ITERATOR member? (self (value OBJECT)) : BOOLEAN
Iterate over values of self and return TRUE if one of them is eql? to 'value.

Method: COLLECTION member? (self (object OBJECT)) : BOOLEAN
Return true iff object is a member of the collection self.

Method: 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: 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: 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: INTEGER min (x (y INTEGER)) : INTEGER
Return the minimum of x and y. If either is NULL, return the other.

Method: LONG-INTEGER min (x (y LONG-INTEGER)) : LONG-INTEGER
Return the minimum of x and y. If either is NULL, return the other.

Method: FLOAT min (x (y FLOAT)) : FLOAT
Return the minimum of x and y. If either is NULL, return the other.

Method: NUMBER-WRAPPER min (x (y NUMBER-WRAPPER)) : NUMBER-WRAPPER
Return the minimum of x and y. If y is NULL, return x.

Method: 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: 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: CLASS multiple-parents? (class) : BOOLEAN
Return true if class has more than one direct superclass.

Method: MODULE multiple-parents? (module) : BOOLEAN
Return TRUE if module has more than one parent.

Method: 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-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

Method: 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: COLLECTION no-duplicates? (self) : BOOLEAN
Return true if the collection self forbids duplicate values.

Method: STRING-WRAPPER non-empty? (x) : BOOLEAN
Return true if x is not the wrapped empty string ""

Method: VECTOR-SEQUENCE 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: NATIVE-VECTOR nth (self (position INTEGER)) : (LIKE (ANY-VALUE SELF))
Return the element in self at position.

Method: LONG-INTEGER null? (x) : BOOLEAN
Return true if x is undefined (handled specially by all translators).

Method: 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: 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: INTEGER odd? (x) : BOOLEAN
Return true if x is an odd number.

Method: 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: 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: 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-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: INTEGER plus? (x) : BOOLEAN
Return true if x is greater than 0.

Method: LONG-INTEGER plus? (x) : BOOLEAN
Return true if x is greater than 0.

Method: OBJECT primary-type (self) : TYPE
Returns the primary type of self. Gets defined automatically for every non-abstract subclass of OBJECT.

Method: 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-exception-context ((e NATIVE-EXCEPTION) (stream OUTPUT-STREAM)) :
Prints a system dependent information about the context of the specified exception. 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.

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: RELATION private? (self) : BOOLEAN
Return true if self is not public.

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: CLASS public-slots (self) : (ITERATOR OF SLOT)
Return an iterator over public slots of self.

Method: OBJECT public-slots (self) : (ITERATOR OF SLOT)
Return an iterator over public slots of self.

Method: SLOT public? (self) : BOOLEAN
True if self or one it its ancestors is marked public.

Macro: pushf ((place CONS) (value OBJECT)) : OBJECT
Push value onto the cons list place.

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-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.

Method: STORAGE-SLOT reader (self) : SYMBOL
Name of a method called to read the value of the slot self.

Function: regular-integer-valued? ((x LONG-INTEGER)) : BOOLEAN
Return true if x can be represented by a regular integer.

Method: 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: 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: COLLECTION remove-duplicates (self) : (LIKE SELF)
Return self with duplicates removed. Preserves the original order of the remaining members.

Method: 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: CLASS required-slots (self) : (LIST OF SYMBOL)
Returns a list of names of required slots for self.

Method: STORAGE-SLOT required? (self) : BOOLEAN
True if a value must be assigned to this slot at creation time.

Command: reset-stella-features () :
Reset STELLA features to their default settings.

Function: reverse-interval ((lowerbound INTEGER) (upperbound INTEGER)) : REVERSE-INTEGER-INTERVAL-ITERATOR
Create a reverse interval object.

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-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 with the current time.

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: DECODED-DATE-TIME set-current-date (values-structure) :
Sets the current date into values-structure

Method: DECODED-DATE-TIME set-current-date-time (values-structure) :
Sets the current date and time into values-structure

Method: DECODED-DATE-TIME set-current-time (values-structure) :
Sets the current time into values-structure

Function: set-global-value ((self SURROGATE) (value OBJECT)) : OBJECT
Set the value of the global variable for the surrogate self to value.

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 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-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: 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: 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: 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: 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.

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-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: OUTPUT-FILE-STREAM stream-position (self) : LONG-INTEGER
Return the current position of the file input cursor in self.

Method: INPUT-FILE-STREAM stream-position (self) : LONG-INTEGER
Return the current position of the file input cursor in self.

Method: 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: 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: INPUT-STREAM stream-to-string (from) : STRING
Read all of the input from stream and return it as a string.

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-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: subclass-of? ((subClass CLASS) (superClass CLASS)) : BOOLEAN
Return true if subClass is a subclass of superClass.

Method: 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: 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: 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: CLASS super-classes (self) : (ITERATOR OF CLASS)
Returns an iterator that generates all super classes of self. Non-reflexive.

Function: surrogate-name? ((name STRING)) : BOOLEAN
Return TRUE if name is prefixed by SURROGATE-PREFIX-CHARACTER.

Method: SURROGATE surrogatify (self) : SURROGATE
Converts self into a surrogate.

Method: SYMBOL surrogatify (self) : SURROGATE
Converts self into a surrogate (same semantics as symbol-to-surrogate which see).

Method: STRING surrogatify (self) : SURROGATE
Converts self into a surrogate.

Method: 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: STORAGE-SLOT system-default-value (self) : OBJECT
Return a default value expression, or if self has dynamic storage, an initial value expression.

Method: 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.

Function: terminate-program () :
Terminate and exit the program with normal exit code.

Method: TIME-DURATION time-duration-to-string (date) : STRING
Returns a string representation of date

Function: time-zone-format60 ((timezone FLOAT)) : STRING
Format zone as an hh:mm string

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.

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?.

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: SLOT type (self) : TYPE
The type of a storage slot is its base type.

Method: 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: 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: unset-stella-feature (&rest (features KEYWORD)) :
Disable all listed STELLA features.

Method: 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: 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: 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-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.

Method: STORAGE-SLOT writer (self) : SYMBOL
Name of a method called to write the value of the slot self.

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-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" "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: INTEGER zero? (x) : BOOLEAN
Return true if x is 0.

Method: LONG-INTEGER zero? (x) : BOOLEAN
Return true if x is 0.


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

This document was generated by Hans Chalupsky on September, 16 2008 using texi2html