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

Constant: true : BOOLEAN
Represents the boolean true truth value.

Constant: false : BOOLEAN
Represents the boolean false truth value.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Method: object-equal? ((x WRAPPER) (y OBJECT)) : BOOLEAN
Return true if x and y are literal wrappers whose literals are considered eql?.

Function: object-hash-code ((self OBJECT)) : INTEGER
Return a hash code for self. 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: hash-code ((self OBJECT)) : INTEGER
Return a hash code for self. 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: hash-code ((self STANDARD-OBJECT)) : INTEGER
Not documented.

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

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

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

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

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

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

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

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

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

Method: equal-hash-code ((self OBJECT)) : INTEGER
Return a hash code for self. 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.


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

Function: zero? ((x INTEGER)) : BOOLEAN
Return true if x is 0.

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

Function: even? ((x INTEGER)) : BOOLEAN
Return true if x is an even number.

Function: odd? ((x INTEGER)) : BOOLEAN
Return true if x is an odd number.

Function: mod ((x INTEGER) (modulo INTEGER)) : INTEGER
Return the result of x mod modulo.

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

Method: abs ((x FLOAT)) : FLOAT
Return the absolute value of x.

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

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

Function: sqrt ((n FLOAT)) : FLOAT
Return the square root of n.

Function: exp ((n FLOAT)) : FLOAT
Return the e to the power n.

Function: log ((n FLOAT)) : FLOAT
Return the natural logarithm (base e) 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: random ((n INTEGER)) : INTEGER
Generate a random integer in the interval [0..n-1]. n must be <= 2^15.

Function: integer-to-string ((i INTEGER)) : STRING
Print i to a string and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : INTEGER
Convert a string representation of an integer into an integer.

Function: float-to-string ((f FLOAT)) : STRING
Print f to a string 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: empty? ((x STRING)) : BOOLEAN
Return true if x is the empty string ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Method: position ((string 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.

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

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

Method: substitute ((self MUTABLE-STRING) (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: 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 INTEGER)) : STRING
Print i to a string and return the result. This is more efficient than using a string stream.

Function: string-to-integer ((string STRING)) : INTEGER
Convert a string representation of an integer into an integer.

Function: float-to-string ((f FLOAT)) : STRING
Print f to a string 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

Variable: nil : CONS
Not documented.

Method: empty? ((self CONS)) : BOOLEAN
Return true iff self equals nil.

Method: non-empty? ((self CONS)) : 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: object-equal? ((tree1 CONS) (tree2 OBJECT)) : BOOLEAN
Return true iff the cons trees tree1 and tree2 are structurally equivalent. Uses equal? to test equality of subtrees.

Method: equal-hash-code ((self CONS)) : 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: first ((self CONS)) : (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: second ((self CONS)) : (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: third ((self CONS)) : (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: fourth ((self CONS)) : (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: fifth ((self CONS)) : (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: nth ((self CONS) (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: nth-rest ((self CONS) (position INTEGER)) : (LIKE SELF)
Apply rest position times to self.

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

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

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

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

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

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

Method: concatenate ((list1 CONS) (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: prepend ((self CONS) (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.

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

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

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

Method: sort ((self CONS) (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).

Function: map-null-to-nil ((self CONS)) : CONS
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: subset? ((self CONS) (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: equivalent-sets? ((self CONS) (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: union ((self CONS) (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: intersection ((self CONS) (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: difference ((self CONS) (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: subtract ((self CONS) (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

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

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

Method: object-equal? ((x LIST) (y OBJECT)) : BOOLEAN
Return TRUE iff the lists x and y are structurally equivalent. Uses equal? to test equality of elements.

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

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

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

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

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

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

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

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

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

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

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

Method: memb? ((self LIST) (object (LIKE (ANY-VALUE SELF)))) : BOOLEAN
Return TRUE iff object is a member of the cons list self (uses an eq? test).

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

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

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

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

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

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

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

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

Method: remove-if ((self LIST) (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: pop ((self LIST)) : (LIKE (ANY-VALUE SELF))
Remove and return the first element in the list self. Return NULL if the list is empty.

Method: substitute ((self LIST) (inValue OBJECT) (outValue OBJECT)) : (LIKE SELF)
Destructively replace each appearance of outValue by inValue in the list self.

Method: concatenate ((list1 LIST) (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: prepend ((self LIST) (list2 LIST)) : (LIKE SELF)
Copy list2 onto the front of the list self. The operation is destructive wrt self, but leaves list2 intact.

Method: copy ((self LIST)) : (LIST OF (LIKE (ANY-VALUE SELF)))
Return a copy of the list self. The conses in the copy are freshly allocated.

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

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

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

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

Method: sort ((self LIST) (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: subset? ((self LIST) (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: equivalent-sets? ((self LIST) (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: union ((self LIST) (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: intersection ((self LIST) (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: difference ((self LIST) (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: subtract ((self LIST) (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:

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

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

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

Method: substitute ((self SET) (new OBJECT) (old OBJECT)) : (LIKE SELF)
Destructively replace old with new in the set self unless new is already a member.

Method: concatenate ((set1 SET) (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: object-equal? ((x SET) (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: equal-hash-code ((self SET)) : 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

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

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

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

Method: equal-hash-code ((self PROPERTY-LIST)) : INTEGER
Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

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

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

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

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

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

Method: next? ((self PROPERTY-LIST-ITERATOR)) : BOOLEAN
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.

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

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

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

Method: equal-hash-code ((self KEY-VALUE-LIST)) : INTEGER
Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method: length ((self KEY-VALUE-LIST)) : INTEGER
Not documented.

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

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

Method: insert-at ((self KEY-VALUE-LIST) (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: remove-at ((self KEY-VALUE-LIST) (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: insert-entry ((self KEY-VALUE-LIST) (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: remove-entry ((self KEY-VALUE-LIST) (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: push ((self KEY-VALUE-LIST) (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: kv-push ((self KEY-VALUE-LIST) (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: pop ((self KEY-VALUE-LIST)) : (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: copy ((self KEY-VALUE-LIST)) : (LIKE SELF)
Return a copy of the kv-list self. The kv-conses in the copy are freshly allocated.

Method: clear ((self KEY-VALUE-LIST)) :
Make self an empty dictionary.

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

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

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


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

6.8 Vectors

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

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

Method: object-equal? ((x VECTOR) (y OBJECT)) : BOOLEAN
Return TRUE iff the vectors x and y are structurally equivalent. Uses equal? to test equality of elements.

Method: equal-hash-code ((self VECTOR)) : INTEGER
Return an equal? hash code for self.

Function: vector (&rest (values OBJECT)) : VECTOR
Return a vector containing values, in order.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

6.9 Hash Tables

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

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

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

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

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

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

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

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

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

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

Method: insert-at ((self FLOAT-HASH-TABLE) (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.

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

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

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

Method: copy ((self STELLA-HASH-TABLE)) : (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: clear ((self STELLA-HASH-TABLE)) :
Remove all entries from self. This will result in a re-initialization of the table upon the first insertion into self.

Method: consify ((self STELLA-HASH-TABLE)) : (CONS OF CONS)
Collect all entries of self into a cons list of (<key> <value>) pairs and return the result.

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

Method: equal-hash-code ((self STELLA-HASH-TABLE)) : INTEGER
Return an equal? hash code for self. Note that this is O(N) in the number of entries of self.

Method: allocate-iterator ((self STELLA-HASH-TABLE)) : (STELLA-HASH-TABLE-ITERATOR OF (LIKE (ANY-KEY SELF)) (LIKE (ANY-VALUE SELF)))
Allocate an iterator for self.


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

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

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

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

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

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

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

Method: equal-hash-code ((self KEY-VALUE-MAP)) : 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.

Function: hash-set (&rest (values OBJECT)) : HASH-SET
Return an eql? HASH-SET containing values.

Method: member? ((self HASH-SET) (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: insert ((self HASH-SET) (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: remove ((self HASH-SET) (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: remove-if ((self HASH-SET) (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: pop ((self HASH-SET)) : (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: substitute ((self HASH-SET) (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: copy ((self HASH-SET)) : (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: consify ((self HASH-SET)) : (CONS OF (LIKE (ANY-VALUE SELF)))
Collect all entries of self into a cons list and return the result.

Method: subset? ((self HASH-SET) (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: equivalent-sets? ((self HASH-SET) (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: intersection ((self HASH-SET) (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: union ((self HASH-SET) (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: difference ((self HASH-SET) (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: subtract ((self HASH-SET) (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: object-equal? ((x HASH-SET) (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: equal-hash-code ((self HASH-SET)) : 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: empty? ((self ITERATOR)) : BOOLEAN
Return TRUE if the sequence represented by self has no elements. Side-effect free.

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

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

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

Method: next? ((self ALL-PURPOSE-ITERATOR)) : 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: destroy-context ((self CONTEXT)) :
Make the translator happy.

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

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

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

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.

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

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: destroy-context ((self MODULE)) :
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.

Command: in-module ((name NAME)) : MODULE
Change the current module to the module named name.

Method: change-module ((module MODULE)) : MODULE
Change the current module to be the module module.

Method: change-module ((moduleName STRING)) : 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: destroy-context ((self WORLD)) :
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 ((inputStream INPUT-STREAM)) : STRING BOOLEAN
Read one line from inputStream and return the result. Return true as the second value on EOF.

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


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

6.16 Files

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)) : 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: decode-calendar-date ((date CALENDAR-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: encode-calendar-date ((time-structure DECODED-DATE-TIME)) : CALENDAR-DATE
Returns a calendar date object for time-structure.

Function: calendar-date-to-string ((date CALENDAR-DATE) (timezone FLOAT) (include-timezone? BOOLEAN)) : STRING
Returns a string representation of date adjusted for timezone

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 an CONS headed by a CDATA tag

Method: xml-element-match? ((tag XML-ELEMENT) (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-match? ((attribute XML-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-attribute-match? ((attribute XML-GLOBAL-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-attribute-match? ((attribute XML-LOCAL-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.

Function: acos ((n FLOAT)) : FLOAT
Return the arccosine of n in radians.

Function: activate-demon ((demon DEMON)) :
Install demon in the location(s) specified by its internal structure.

Method: active? ((self POLYMORPHIC-RELATION)) : BOOLEAN
True if self or a superslot of self is marked active.

Function: add-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :
Insert the function named hookFunction into hookList.

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: 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-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, or :postorder).

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: allocate-iterator ((self ABSTRACT-ITERATOR)) : (LIKE SELF)
Iterator objects return themselves when asked for an iterator (they occupy the same position as a collection within a foreach statement).

Method: allocate-iterator ((self MEMOIZABLE-ITERATOR)) : (ITERATOR OF (LIKE (ANY-VALUE SELF)))
Alias for clone-memoized-iterator.

Method: allocation ((self STORAGE-SLOT)) : 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-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: asin ((n FLOAT)) : FLOAT
Return the arcsine 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: break-program ((message STRING)) :
Interrupt the program and print message. Continue after confirmation with the user.

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.

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.

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.

Function: close-all-files () :
Close all currently open file streams. Use for emergencies or for cleanup.

Function: close-stream ((self STREAM)) :
Close the stream self.

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-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 ((collectvariable SYMBOL) &body (body CONS)) : OBJECT
Use a VRLET to collect values. Input has the form (collect <x> in <expression> where (<test> <x>)).

Method: collection-valued? ((self SLOT)) : BOOLEAN
True if slot values are collections.

Function: command? ((method METHOD-SLOT)) : BOOLEAN
Return true if method is an evaluable command.

Method: component? ((self STORAGE-SLOT)) : 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: 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: consify ((self OBJECT)) : CONS
If object is a CONS, return it. Otherwise, return a singleton cons list containing it.

Macro: continuable-error (&body (body CONS)) : OBJECT
Signal error message, placing non-string arguments in quotes.

Function: cpp-translate-system ((systemName STRING)) :
Translate the system systemName to C++.

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.

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: default-form ((self STORAGE-SLOT)) : 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.

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.

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 path from the Stella 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: deleted? ((self OBJECT)) : 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.

Command: describe ((name OBJECT) &rest (mode OBJECT)) :
Print a description of an object in :verbose, :terse, or :source modes.

Method: describe-object ((self OBJECT) (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: destroy-class ((self CLASS)) :
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: direct-super-classes ((self CLASS)) : (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.

Function: drop-hook ((hookList HOOK-LIST) (hookFunction SYMBOL)) :
Remove the function named hookFunction from hookList.

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

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.

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

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

Function: expt ((x FLOAT) (y FLOAT)) : FLOAT
Return x ^ y.

Method: extension ((self CLASS)) : CLASS-EXTENSION
Return the nearest class extension that records instances of the class self.

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.

Macro: first-defined (&body (forms CONS)) : OBJECT
Return the result of the first form in forms whose value is defined or NULL otherwise.

Function: flush-output ((self OUTPUT-STREAM)) :
Flush all buffered output of self.

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

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

Method: free-hash-table-values ((self ABSTRACT-HASH-TABLE)) :
Call free on each value in the hash table self.

Function: gcd ((x INTEGER) (y INTEGER)) : INTEGER
Return the greatest common divisor of x and y.

Method: get-calendar-date ((date CALENDAR-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: get-stella-class ((class-name TYPE) (error? BOOLEAN)) : CLASS
Return a class with name class-name. If none exists, break if error?, else return null.

Method: get-stella-class ((class-name SYMBOL) (error? BOOLEAN)) : CLASS
Return a class with name class-name. If non exists, break if error?, else return null.

Method: get-stella-class ((class-name STRING) (error? BOOLEAN)) : CLASS
Return a class with name class-name. If none exists, break if error?, else return null.

Method: get-time ((date CALENDAR-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

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.

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: home-module ((self OBJECT)) : 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.

Macro: inform (&body (body CONS)) : OBJECT
Print informative message, placing non-string arguments in quotes, and terminating with a newline.

Method: initial-value ((self CLASS)) : OBJECT
Return an initial value for the class self.

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

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.

Command: jptrans ((statement OBJECT)) :
Translate statement to C++ and print the result.

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

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.

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

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

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

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

Method: listify ((self ITERATOR)) : (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.

Function: load-system ((systemName STRING) (language KEYWORD) &rest (options OBJECT)) : BOOLEAN
Natively language-compile out-of-date translated files of system systemName and then load them into the running system (this is only supported/possible for Lisp at the moment). Return true if at least one file was compiled. The following keyword/value options are recognized:

: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: log10 ((n FLOAT)) : FLOAT
Return the logarithm (base 10) of n.

Method: lookup-class ((name SYMBOL)) : CLASS
Return a class with name name. Scan all visible surrogates looking for one that has a class defined for it.

Method: lookup-class ((name STRING)) : 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)) : WRAPPER
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-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: lookup-global-variable ((self SURROGATE)) : GLOBAL-VARIABLE
Return a global variable with name self.

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

Method: lookup-global-variable ((self STRING)) : 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-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).

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) (language KEYWORD) &rest (options OBJECT)) : BOOLEAN
Translate all out-of-date files of system systemName into language and then compile and load them (the latter is only possible for Lisp right now). The following keyword/value options are recognized:

: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 right now).

:startup? (default true): if true, the system startup function will be called once all files have been loaded.

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

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

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

Method: multiple-parents? ((module MODULE)) : BOOLEAN
Return TRUE if module has 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.

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

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

Method: nth ((self NATIVE-VECTOR) (position INTEGER)) : (LIKE (ANY-VALUE SELF))
Return the element in self at position.

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: ordered? ((self COLLECTION)) : BOOLEAN
Return true if the collection self is ordered.

Method: parameters ((self CLASS)) : (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: pick-hash-table-size-prime ((minSize INTEGER)) : INTEGER
Return a hash table prime of at least minSize.

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

Method: primitive? ((self RELATION)) : 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.

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.

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.

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

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

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

Method: public? ((self SLOT)) : 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.

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

Method: remove-duplicates ((self COLLECTION)) : (LIKE SELF)
Return self with duplicates removed. Preserves the original order of the remaining members.

Method: required-slots ((self CLASS)) : (LIST OF SYMBOL)
Returns a list of names of required slots for self.

Method: required? ((self STORAGE-SLOT)) : 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: 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-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: 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 WRAPPER) (configuration CONFIGURATION-TABLE)) : WRAPPER
Set property in configuration to value and return it. Use the global system configuration table if configuration is NULL.

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

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.

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.

Command: start-function-call-logging ((fileName STRING)) :
Start function call logging to fileName.

Function: stella-collection? ((self OBJECT)) : BOOLEAN
Return true if self is a native collection.

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.

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: subsequence ((string MUTABLE-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: substitute-characters ((self STRING) (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: substitute-characters ((self MUTABLE-STRING) (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: super-classes ((self CLASS)) : (ITERATOR OF CLASS)
Returns an iterator that generates all super classes of self. Non-reflexive.

Method: sweep ((self OBJECT)) :
Default method. Sweep up all self-type objects.

Method: system-default-value ((self STORAGE-SLOT)) : OBJECT
Return a default value expression, or if self has dynamic storage, an initial value expression.

Method: system-default-value ((self SLOT)) : OBJECT
Return a default value expression, or if self has dynamic storage, an initial value expression.

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.

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

Function: toggle-output-language () : KEYWORD
Switch between Common Lisp and C++ as output languages.

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.

Function: translate-system ((systemName STRING) (outputLanguage KEYWORD) &rest (options OBJECT)) : BOOLEAN
Translate all of the STELLA source files in system systemName into outputLanguage. The following keyword/value options are recognized:

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

Method: type-specifier ((self SLOT)) : 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: type-to-wrapped-type ((self TYPE)) : 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.

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.

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-method-code ((wrapper METHOD-CODE-WRAPPER)) : METHOD-CODE
Unwrap wrapper and return the result. Return NULL if wrapper is NULL.

Method: value-setter ((self ABSTRACT-DICTIONARY-ITERATOR) (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-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) body+)

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-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) 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-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: writer ((self STORAGE-SLOT)) : SYMBOL
Name of a method called to write the value of the slot self.

Function: xml-token-list-to-s-expression ((tokenList TOKENIZER-TOKEN)) : OBJECT
Convert the XML tokenList into a representative s-expression and return the result. 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.


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

This document was generated by Hans Chalupsky on August, 12 2003 using texi2html