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

6. PowerLoom API

This chapter lists functions that collectively define the PowerLoom API. The first section describes the API functions themselves. The signature is the basic Stella signature. Information on how to translate the names of the functions and their arguments into the programming languages Common Lisp, C++ or Java is given in the Language Specific Interface section.


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

6.1 API Functions

Many of the functions take a ‘module’ argument that causes the function to be evaluated in the context of that module. Passing in a NULL value for the module argument means that evaluation takes place in the current module. The module argument is frequently followed by an ‘environment’ argument that specifies which inference environment should be assumed during evaluation. Values for ‘environment’ are ‘ASSERTION-ENV’, ‘TAXONOMIC-ENV’, and ‘INFERENCE-ENV’. ‘ASSERTION-ENV’ specifies that a knowledge base query or lookup should take into account only explicitly asserted propositions. ‘TAXONOMIC-ENV’ specifies that a knowledge base query should take into account explicitly-asserted propositions plus any rules that specify subsumption relationships. ‘INFERENCE-ENV’ specifies that a knowledge base query should take all relevant propositions into account, including those generated during forward inferencing. A NULL value for the ‘environment’ argument defaults to ‘TAXONOMIC-ENV’.

Many of the functions that take PowerLoom or Stella objects as inputs also have an analog version whose name starts with the prefix "s-" that take strings as inputs. This is provided as a convenience so that programmers will not necessarily need to manipulate PowerLoom objects directly.

Function: ask ((query CONS) (module MODULE) (environment ENVIRONMENT)) : TRUTH-VALUE

Returns a truth value for query in module and environment. query has the same syntax as the PowerLoom ask command (which see) but with the ask operator omitted. For example, here are some legal query arguments:

 
    ((happy Fred))
    ((happy Fred) :inference-level :assertion)
    ((happy Fred) :inference-level :assertion :timeout 1.0)

As a convenience, a query argument whose first element is a symbol is interpreted as a sentence that is queried without any options. For example:

 
    (happy Fred)

is a legal query argument. Note that for a sentence whose relation is a list itself, e.g., ((FruitFn BananaTree) MyBanana) this shortcut is not available, that is, in that case an extra level of list nesting is always necessary. The returned truth value represents the logical truth of the queried sentence as determined by PowerLoom. It can be be tested via the functions is-true, is-false and is-unknown (which see).

Function: assert-binary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (value OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Assert that the proposition (relation arg value) is TRUE in module. Return the asserted proposition.

Function: assert-nary-proposition ((relation-and-arguments OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Assert that the proposition represented by the list relation-and-arguments satisfies the relation relation.

Function: assert-proposition ((proposition PROPOSITION) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Assert that the proposition proposition is true in module. Return the asserted proposition.

Function: assert-unary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Assert that the proposition (relation arg) is TRUE in module. Return the asserted proposition.

Function: change-module ((module MODULE)) : MODULE

Set the current module to module and return it. If module is null, then no switch is performed and the current module is returned.

Function: clear-caches () :

Clear all query and memoization caches.

Function: clear-module ((module MODULE)) : MODULE

Destroy the contents of the module module as well as the contents of all of its children, recursively.

Function: conceive ((sentence OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Create one or more proposition objects from the sentence sentence in the module module. Return an iterator of the propositions. If any of the new propositions has the same structure as an already existing proposition, an automatic check for duplicates will return the pre-existing proposition. Multiple propositions may be returned for a single sentence because of normalization of equivalences, conjunctions, etc.

Signals a Proposition-Error if PowerLoom could not conceive sentence.

Function: cons-to-pl-iterator ((self CONS)) : PL-ITERATOR

Convert a Stella cons list into an API iterator.

Function: create-concept ((name STRING) (parent LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a concept named name in the designated module, with the designated parent superconcept (which can be left undefined). Additional superconcepts can be added via assertions of the subset-of relation. Note that a specified parent concept needs to be created separately.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: create-enumerated-list ((members CONS) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a logical term that denotes a list containing members in module using environment. Useful for passing lists as arguments to parameterized queries.

Function: create-enumerated-set ((members CONS) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a logical term that denotes the enumerated set containing members in module using environment.

Function: create-function ((name STRING) (arity INTEGER) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a function named name with arity arity in the designated module. Domain and range information can be added via assertions of nth-domain (or domain and range) relations.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: create-module ((name STRING) (parent MODULE) (case-sensitive? BOOLEAN)) : MODULE

Creates a new module name as a child of parent. The flag case-sensitive? controls whether names read in this module will be case sensitive or not.

Function: create-object ((name STRING) (concept LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create an object named name of type concept in the designated module. Both name and concept can be null. If name is null then an object will be created with a new, non-conflicting name based on the name of concept, or system-generated if no concept is specified. If concept is null, then the object will be of type THING. It is an error to create an object with the same name as an existing object.

Note that the string can be a qualified name, in which case the object will be created in the module specified, but with a name as determined by the qualified name. Vertical bars in the name string are interpreted as Stella escape characters.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Return the object.

Function: create-relation ((name STRING) (arity INTEGER) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a relation named name with arity arity in the designated module. Domain and range information can be added via assertions of nth-domain (or domain and range) relations.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: destroy-object ((object OBJECT)) :

Delete the object object, retracting all facts attached to it.

Method on PL-ITERATOR: empty? (self) : BOOLEAN

Return TRUE if the iterator self has no more elements.

Function: evaluate ((command OBJECT) (module MODULE) (environment ENVIRONMENT)) : OBJECT

Evaluate the command command within module and return the result. Currently, only the evaluation of (possibly nested) commands and global variables is supported. Commands 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 s-evaluate.

Function: generate-unique-name ((prefix STRING) (module MODULE) (environment ENVIRONMENT)) : STRING

Generates a name based on prefix with a number appended that is not currently in use in module. In a non-case-sensitive module, the returned name will be all upper case (This latter feature may change!)

Function: get-arity ((relation LOGIC-OBJECT)) : INTEGER

Return the arity of the relation relation.

Function: get-binary-proposition ((relation LOGIC-OBJECT) (arg1 OBJECT) (arg2 OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Return a proposition such that (relation arg1 arg2) is true. The relation argument must be bound to a relation. One or both of the arg1 and arg2 arguments may be set to NULL, which is interpreted as a wildcard. If more than one proposition matches the input criteria, the selection is arbitrary. This procedure is normally applied to single-valued relations or functions.

Function: get-binary-propositions ((relation LOGIC-OBJECT) (arg1 OBJECT) (arg2 OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions such that (relation arg1 arg2) is true. The relation argument must be bound to a relation. One or both of the arg1 and arg2 arguments may be set to NULL, which is interpreted as a wildcard.

Function: get-child-modules ((module MODULE)) : (PL-ITERATOR OF MODULE)

Return the modules that are immediate children of module.

Function: get-column-count ((obj OBJECT)) : INTEGER

Return the number of columns in obj, which must be of type proposition, cons, vector or PL-iterator. For a proposition, the number includes both the predidate and arguments. For the PL-iterator case,the number of columns is for the current value of the iterator.

For a null item, the column count is zero. For non sequence objects, the column count is one.

Function: get-concept ((name STRING) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return a class/concept named name that is local to or visible from the module module.

Function: get-concept-instance-matching-value ((concept LOGIC-OBJECT) (relation LOGIC-OBJECT) (value OBJECT) (module MODULE) (environment ENVIRONMENT)) : OBJECT

Return a member of concept concept that has an attribute matching value for the binary relation relation, i.e., (relation <result> value) holds.

Function: get-concept-instances ((concept LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : PL-ITERATOR

Return instances of the concept concept. Include instances of subconcepts of concept. Depending on concept, the return values could be (wrapped) literals.

Function: get-concept-instances-matching-value ((concept LOGIC-OBJECT) (relation LOGIC-OBJECT) (value OBJECT) (module MODULE) (environment ENVIRONMENT)) : PL-ITERATOR

Return members of concept concept that have an attribute matching value for the binary relation relation, i.e., (relation <result> value) holds.

Function: get-current-module ((environment ENVIRONMENT)) : MODULE

Return the currently set module

Function: get-direct-concept-instances ((concept LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : PL-ITERATOR

Return instances of concept concept. Exclude instances of subconcepts of concept. Depending on concept, the return values could be (wrapped) literals.

Function: get-direct-subrelations ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return relations that directly specialize relation. Non-reflexive.

Function: get-direct-superrelations ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return relations that directly generalize relation. Non-reflexive.

Function: get-direct-types ((object LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return most specific concepts that object belongs to.

Function: get-domain ((relation LOGIC-OBJECT)) : LOGIC-OBJECT

Return the type (a concept) for the first argument to the binary relation relation.

Function: get-enumerated-collection-members ((collection OBJECT) (module MODULE) (environment ENVIRONMENT)) : CONS

Returns the members of an enumerated collection. This works on all types of collection, i.e., sets and lists

Function: get-home-module ((object LOGIC-OBJECT)) : MODULE

Return the module in which object was created.

Function: get-inferred-binary-proposition-values ((relation LOGIC-OBJECT) (arg OBJECT) (module MODULE) (environment ENVIRONMENT)) : PL-ITERATOR

Return all values v such that (relation arg v) has been asserted or can be inferred.

Function: get-module ((name STRING) (environment ENVIRONMENT)) : MODULE

Return a module named name.

Function: get-modules ((kb-modules-only? BOOLEAN)) : (PL-ITERATOR OF MODULE)

Return all modules currently loaded into PowerLoom. If kb-modules-only? is true, then Stella modules that are used only for program code are not included in the list.

Function: get-name ((obj OBJECT)) : STRING

Return the fully qualified name of obj, if it has one. Otherwise return null.

Function: get-nth-domain ((relation LOGIC-OBJECT) (n INTEGER)) : LOGIC-OBJECT

Return the type (a concept) for the the nth argument of the relation relation. Counting starts at zero. NOTE: if there are multiple nth-domain propositions for relation, this arbitrarily returns one of them; it does not look for the most specific one (which might have to be created).

Function: get-nth-float ((sequence OBJECT) (n INTEGER) (module MODULE) (environment ENVIRONMENT)) : FLOAT

Return the floating point value in the nth column of sequence. Counting starts at zero. sequence must be of type proposition, cons, vector or PL-iterator. A zero column number returns a proposition’s relational predicate. For the PL-iterator case, the the current value pointed to by the iterator is used. If this is not a floating point value, then an exception will be thrown.

As a special case, a column number of zero will also return the floating point value of sequence itself if it is not one of the types enumerated above. This allows the use of get-nth-float on PL-iterators with only a single return variable. If sequence cannot be turned into a floating point value, an exception will be thrown.

Function: get-nth-integer ((sequence OBJECT) (n INTEGER) (module MODULE) (environment ENVIRONMENT)) : INTEGER

Return an integer representation of the value in the nth column of sequence. Counting starts at zero. Unless n is zero, sequence must be of type proposition, cons, vector or PL-iterator. A zero column number returns a proposition’s relational predicate. For the PL-iterator case, the the current value pointed to by the iterator is used. If this is not an integer value, then an exception will be thrown.

As a special case, a column number of zero will also return the integer value of sequence itself if it is not one of the types enumerated above. This allows the use of get-nth-integer on PL-iterators with only a single return variable. If sequence cannot be turned into an integer, an exception will be thrown.

Function: get-nth-logic-object ((sequence OBJECT) (n INTEGER) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return a logic object representation of the value in the nth column of sequence. Counting starts at zero. Unless n is zero, sequence must be of type proposition, cons, vector or PL-iterator. A zero column number returns a proposition’s relational predicate. For the PL-iterator case, the the current value pointed to by the iterator is used. A zero column number returns the proposition’s relational predicate. If the return value is not a LOGIC-OBJECT, an exception is thrown.

As a special case, a column number of zero will also return sequence itself if it is not one of the types enumerated above. This is done to allow the use of get-nth-value on PL-iterators with only a single return variable. If sequence is not a LOGIC-OBJECT, an exception is thrown.

Function: get-nth-string ((sequence OBJECT) (n INTEGER) (module MODULE) (environment ENVIRONMENT)) : STRING

Return a string representation of the value in the nth column of sequence. Counting starts at zero. Unless n is zero, sequence must be of type proposition, cons, vector or PL-iterator. A zero column number returns a proposition’s relational predicate. For the PL-iterator case, the the current value pointed to by the iterator is used. This will always succeed, even if the nth value is not a string object. In that case, a string reprensentation will be returned.

As a special case, a column number of zero will also return sequence itself as a string if it is not one of the types enumerated above. This is done to allow the use of get-nth-string on PL-iterators with only a single return variable.

Function: get-nth-value ((sequence OBJECT) (n INTEGER) (module MODULE) (environment ENVIRONMENT)) : OBJECT

Return the value in the nth column of sequence. Counting starts at zero. Unless n is zero, sequence must be of type proposition, cons, vector or PL-iterator. A zero column number returns a proposition’s relational predicate. For the PL-iterator case, the number of columns is for the current value of the iterator.

As a special case, a column number of zero will also return sequence itself if it is not one of the types enumerated above. This is done to allow the use of get-nth-value on PL-iterators with only a single return variable.

Function: get-operator ((name STRING)) : SYMBOL

Returns the logical operator object (a Stella SYMBOL) for name. If no such operator exists then a no-such-object exception is thrown.

Function: get-object ((name STRING) (module MODULE) (environment ENVIRONMENT)) : OBJECT

Look for an object named name that is local to or visible from the module module.

Function: get-parent-modules ((module MODULE)) : (PL-ITERATOR OF MODULE)

Return the modules that are immediate parents of module.

Function: get-predicate ((prop PROPOSITION)) : LOGIC-OBJECT

Return the concept or relation predicate for the proposition prop.

Function: get-proper-subrelations ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return relations that specialize relation. Non-reflexive.

Function: get-proper-superrelations ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return relations that generalize relation. Non-reflexive.

Function: get-proposition ((relation-and-arguments OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Return a proposition matching relation-and-arguments that has been asserted (or inferred by forward chaining). relation-and-arguments is a sequence containing objects and nulls. The first argument must be the name of a relation. A null value acts like a wild card. If more than one proposition matches the input criteria, the selection among satisficing propositions is arbitrary. This procedure is normally applied to single-valued relations or functions.

Function: get-propositions ((relation-and-arguments OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions matching relation-and-arguments that have been asserted (or inferred by forward chaining). relation-and-arguments is a sequence containing objects and nulls. The first argument must be the name of a relation. A null value acts like a wild card.

Function: get-propositions-in-module ((module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions that have been conceived in the module module.

Function: get-propositions-of ((object LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return all propositions that have object among their arguments, and that are TRUE in the scope of the module module.

Function: get-range ((relation LOGIC-OBJECT)) : LOGIC-OBJECT

Return the type (a concept) for fillers of the binary relation relation.

Function: get-relation ((name STRING) (module MODULE) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return a concept or relation named name that is local to or visible from the module module.

Function: get-relation-extension ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions that satisfy relation. Include propositions that satisfy subrelations of relation.

Function: get-rules ((relation LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return rules attached to the concept/relation relation in either antecedent or consequent position.

Function: get-types ((object LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF LOGIC-OBJECT)

Return all named concepts that object belongs to.

Function: initialize () :

Initialize the PowerLoom logic system. This function needs to be called by all applications before using PowerLoom. If it is called more than once, every call after the first one is a no-op.

Function: is-a ((object OBJECT) (concept LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if object is a member of the concept concept.

Function: is-default ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is a default truth value.

Function: is-enumerated-collection ((obj OBJECT)) : BOOLEAN

Test whether obj is an enumerated collection. This subsumes both sets and lists.

Function: is-enumerated-list ((obj OBJECT)) : BOOLEAN

Test whether obj is an enumerated list

Function: is-enumerated-set ((obj OBJECT)) : BOOLEAN

Test whether obj is an enumerated set.

Function: is-false ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is a false truth value. It can be false either absolutely or by default.

Function: is-float ((obj OBJECT)) : BOOLEAN

Test whether obj is of type FLOAT (double)

Function: is-inconsistent ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is an inconsistent truth value.

Function: is-integer ((obj OBJECT)) : BOOLEAN

Test whether obj is of type INTEGER

Function: is-logic-object ((obj OBJECT)) : BOOLEAN

Test whether obj is of type LOGIC-OBJECT

Function: is-number ((obj OBJECT)) : BOOLEAN

Test whether obj is of type NUMBER. This can be either an integer or a floating point number. One key characteristic is that object-to-integer and object-to-float will both work on it.

Function: is-strict ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is a strict (non-default) truth value.

Function: is-string ((obj OBJECT)) : BOOLEAN

Test whether obj is of type STRING

Function: is-subrelation ((sub LOGIC-OBJECT) (super LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if sub is a subconcept/subrelation of super.

Function: is-true ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is a true truth value. It can be true either absolutely or by default.

Function: is-true-binary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (value OBJECT) (module MODULE) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if the proposition (relation arg value) has been asserted (or inferred by forward chaining).

Function: is-true-proposition ((proposition PROPOSITION) (module MODULE) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if proposition is TRUE in the module module.

Function: is-true-unary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (module MODULE) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if the proposition (relation arg) has been asserted (or inferred by forward chaining).

Function: is-unknown ((tv TRUTH-VALUE)) : BOOLEAN

Tests whether tv is an unknown truth value.

Function: iterator-to-pl-iterator ((self ITERATOR)) : PL-ITERATOR

Convert an arbitrary Stella iterator into an API iterator.

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

Number of items remaining in self. Non destructive.

Function: list-to-pl-iterator ((self LIST)) : PL-ITERATOR

Convert a Stella list into an API iterator.

Function: load ((filename STRING) (environment ENVIRONMENT)) :

Read logic commands from the file named filename and evaluate them. The file should contain 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-stream ((stream INPUT-STREAM) (environment ENVIRONMENT)) :

Read logic commands from the STELLA stream stream and evaluate them. The stream should contain 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-native-stream ((stream NATIVE-INPUT-STREAM) (environment ENVIRONMENT)) :

Read logic commands from the native input stream stream and evaluate them. Assumes stream is a line-buffered stream which is a safe compromise but does not generate the best efficiency for block-buffered streams such as files. The stream 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.

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

Advance the PL-Iterator self and return true if more elements are available, false otherwise.

Function: object-to-float ((self OBJECT)) : FLOAT

Coerce self to a float, or throw a Stella Exception if the coersion is not feasible.

Function: object-to-integer ((self OBJECT)) : INTEGER

Coerce self to an integer, or throw a Stella Exception if the coersion is not feasible. Floating point values will be coerced by rounding.

Function: object-to-parsable-string ((self OBJECT)) : STRING

Return a string representing a printed representation of the object self. Like object-to-string, but puts escaped double quotes around strings.

Function: object-to-string ((self OBJECT)) : STRING

Return a printed representation of the term self as a string.

N-Command: print-rules ((relation OBJECT)) :

Print the list of true rules associated with relation.

Function: reset-powerloom () :

Reset PowerLoom to its initial state. CAUTION: This will destroy all loaded knowledge bases and might break other loaded STELLA systems if they do reference PowerLoom symbols in their code.

N-Command: retract ((proposition PARSE-TREE)) : OBJECT

Retract the truth of proposition. Return the retracted proposition object. KIF example: "(retract (happy Fred))" retracts that Fred is happy. Note that for this assertion to succeed, the relation happy must already be defined. If the constant Fred has not yet been created, it is automatically created as a side-effect of calling retract.

Function: retract-binary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (value OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Retract that the proposition (relation arg value) is TRUE in module. Return the asserted proposition.

Function: retract-nary-proposition ((relation-and-arguments OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Retract the proposition that arguments satisfies the relation relation.

Function: retract-proposition ((proposition PROPOSITION) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Retract the truth of the proposition proposition in module. Return the retracted proposition.

Function: retract-unary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (module MODULE) (environment ENVIRONMENT)) : PROPOSITION

Retract that the proposition (relation arg) is TRUE in module. Return the asserted proposition.

Function: retrieve ((query CONS) (module MODULE) (environment ENVIRONMENT)) : PL-ITERATOR

Returns an iterator of variable bindings that when substituted for the open variables in query satisfy the query proposition. The query is run in module and relative to environment. query has the same syntax as the PowerLoom retrieve command (which see) but with the retrieve operator omitted. For example, here are some legal query arguments:

 
    ((happy ?x))
    (10 (happy ?x))
    (all (happy ?x))
    (all ?x (happy ?x))
    (10 (happy ?x) :inference-level :assertion)
    (10 (happy ?x) :inference-level :assertion :timeout 1.0)

If there is only a single output variable (as in all the examples above) each element generated by the returned iterator will be a binding for that variable - unless, the output variable was declared with a surrounding pair of parentheses. For example:

 
    (all (?x) (happy ?x))

In that case, the generated elements will be one-element lists. If there are multiple output variables, each element generated by the returned iterator will be a list of variable bindings that can be accessed using the various get-nth-... functions. The list of output variables does not need to be declared in which case they are taken to be the open variables in the query proposition in the order in which they were encountered. If order does matter or should be different from its default, it can be forced by declaring the set of output variables.

Function: run-forward-rules ((module OBJECT) (force? BOOLEAN)) :

Run forward inference rules in module module. If module is NULL, the current module will be used. If forward inferencing is already up-to-date in the designated module, no additional inferencing will occur, unless force is set to TRUE, in which case all forward rules are run or rerun.

Calling run-forward-rules temporarily puts the module into a mode where future assertional (monotonic) updates will trigger additional forward inference. Once a non-monotonic update is performed, i.e., a retraction or clipping of relation value, all cached forward inferences will be discarded and forward inferencing will be disabled until this function is called again.

Function: s-ask ((query STRING) (module-name STRING) (environment ENVIRONMENT)) : TRUTH-VALUE

Returns a truth value for query in module module-name and environment. query has the same syntax as the PowerLoom ask command (which see) but with the ask operator omitted. Different from the PLI ask function, s-ask does not expect a top-level pair of parentheses. For example, here are some legal query arguments:

 
    "(happy Fred)"
    "(happy Fred) :inference-level :assertion"
    "(happy Fred) :inference-level :assertion :timeout 1.0"

Names in query will be interpreted relative to module module-name. A null module-name or the empty string refers to the current module. If no module can be found with the name module-name, then a STELLA no-such-context-exception is thrown. The returned truth value represents the logical truth of the queried sentence as determined by PowerLoom. It can be be tested via the functions is-true, is-false and is-unknown (which see).

Function: s-assert-proposition ((sentence STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Assert that the logical sentence sentence is true in the module named module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Return an iterator of the propositions resulting from sentence.

Function: s-change-module ((name STRING) (environment ENVIRONMENT)) : MODULE

Set the current module to the module named name. The return value is the module named name unless name is null or the empty string. In that case, the current module is returned. If no module named name exists, a Stella no-such-context-exception is thrown.

Function: s-clear-module ((name STRING) (environment ENVIRONMENT)) : MODULE

Destroy the contents of the module named name, as well as the contents of all of its children, recursively. If no module named name exists, a Stella no-such-context-exception is thrown.

Function: s-conceive ((sentence STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Create one or more proposition objects from the sentence sentence in the module named module-name. Return an iterator of the propositions. If any of the new propositions has the same structure as an already existing proposition, an automatic check for duplicates will return the pre-existing proposition. Multiple propositions may be returned for a single sentence because of normalization of equivalences, conjunctions, etc.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella No-Such-Context-Exception is thrown.

Signals a Proposition-Error if PowerLoom could not conceive sentence.

Function: s-create-concept ((name STRING) (parent-name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a concept named name in the designated module, with with the concept named parent-name as superconcept (which can be left undefined). Additional superconcepts can be added via assertions of the subset-of relation. Note that a specified parent concept needs to be created separately.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: s-create-function ((name STRING) (arity INTEGER) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a function named name with arity arity in the designated module. Domain and range information can be added via assertions of domain, nth-domain and range relations.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: s-create-object ((name STRING) (concept-name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create an object named name of type concept-name in the designated module. Both name and concept-name can be null strings. If name is a null string then an object will be created with a new, non-conflicting name based on concept-name, or system-generated if no concept nameis specified. If concept-name is the null string, then the object will be of type THING.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Return the object.

Function: s-create-module ((name STRING) (parent-name STRING) (case-sensitive? BOOLEAN) (environment ENVIRONMENT)) : MODULE

Creates a new module name as a child of parent-name. The flag case-sensitive? controls whether names read in this module will be case sensitive or not.

Function: s-create-relation ((name STRING) (arity INTEGER) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Create a relation named name with arity arity in the designated module. Domain and range information can be added via assertions of nth-domain (or domain and range) relations.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Note that because names in modules that are not case-sensitive are canonicalized, the name of the returned object may not match name exactly.

Function: s-destroy-object ((object-name STRING) (module-name STRING) (environment ENVIRONMENT)) :

Delete the object named object-name, retracting all facts attached to it.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-evaluate ((command STRING) (module-name STRING) (environment ENVIRONMENT)) : OBJECT

Evaluate the command represented by the string command within module and return the result. Currently, only the evaluation of (possibly nested) commands and global variables is supported.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-arity ((relation-name STRING) (module-name STRING) (environment ENVIRONMENT)) : INTEGER

Return the arity of the relation named relation-name.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-child-modules ((name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF MODULE)

Return the modules that are immediate children of module name. If no module named name exists, a Stella no-such-context-exception is thrown.

Function: s-get-concept ((name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return a class/concept named name that is local to or visible from the module module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-concept-instances ((concept-name STRING) (module-name STRING) (environment ENVIRONMENT)) : PL-ITERATOR

Return instances of concept concept-name. Include instances of subconcepts of concept-name. Depending on concept-name, the return values could be (wrapped) literals.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-direct-concept-instances ((concept-name STRING) (module-name STRING) (environment ENVIRONMENT)) : PL-ITERATOR

Return instances of concept concept-name. Exclude instances of subconcepts of concept-name. Depending on concept-name, the return values could be (wrapped) literals.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-domain ((relation-name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return the type (concept) for the first argument to the binary relation relation-name.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-inferred-binary-proposition-values ((relation-name STRING) (arg-name STRING) (module-name STRING) (environment ENVIRONMENT)) : PL-ITERATOR

Return all values v such that (relation-name arg-name v) has been asserted or can be inferred.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-nth-domain ((relation-name STRING) (n INTEGER) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return the type (a concept) for the nth argument of the relation named relation-name. Counting starts at zero.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-object ((name STRING) (module-name STRING) (environment ENVIRONMENT)) : OBJECT

Look for an object named name that is local to or visible from the module module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-parent-modules ((name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF MODULE)

Return the modules that are immediate parents of module name. If no module named name exists, a Stella no-such-context-exception is thrown.

Function: s-get-parent-modules ((name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF MODULE)

Return the modules that are immediate parents of module name. If no module named name exists, a Stella no-such-context-exception is thrown.

Function: s-get-proposition ((relation-and-arguments STRING) (module-name STRING) (environment ENVIRONMENT)) : PROPOSITION

Return a proposition matching relation-and-arguments that has been asserted (or inferred by forward chaining). relation-and-arguments is a string that begins with a left parenthesis, followed by a relation name, one or more argument identifiers, and terminated by a right parenthesis. Each argument identifier can be the name of a logical constant, a literal reference (e.g., a number), the null identifier, or a variable (an identifier that begins with a question mark). Each occurrence of a null or a variable acts like a wild card. If more than one proposition matches the input criteria, the selection among satisficing propositions is arbitrary. This procedure is normally applied to single-valued relations or functions.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-propositions ((relation-and-arguments STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions matching relation-and-arguments that have been asserted (or inferred by forward chaining). relation-and-arguments is a string that begins with a left parenthesis, followed by a relation name, one or more argument identifiers, and terminated by a right parenthesis. Each argument identifier can be the name of a logical constant, a literal reference (e.g., a number), the null identifier, or a variable (an identifier that begins with a question mark). Each occurrence of a null or a variable acts like a wild card.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-propositions-of ((object-name STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return all propositions that have the object named object-name among their arguments, and that are TRUE in the scope of the module module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-range ((relation-name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return the type (a concept) for fillers of the binary relation relation-name.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-relation ((name STRING) (module-name STRING) (environment ENVIRONMENT)) : LOGIC-OBJECT

Return a concept or relation named name that is local to or visible from the module module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-get-relation-extension ((relation-name STRING) (module MODULE) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return propositions that satisfy the relation named relation-name. Include propositions that satisfy subrelations of the relation.

Function: s-get-rules ((relation-name STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Return rules attached to the concept/relation named relation-name found in the module named module-name.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella No-Such-Context-Exception is thrown.

Function: s-is-true-proposition ((relation-and-arguments STRING) (module-name STRING) (environment ENVIRONMENT)) : BOOLEAN

Return TRUE if a proposition that prints as the string relation-and-arguments is true in the module named module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-print-rules ((name STRING) (stream OUTPUT-STREAM) (module-name STRING) (environment ENVIRONMENT)) :

Print rules attached to the concept/relation named name.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: s-retract-proposition ((sentence STRING) (module-name STRING) (environment ENVIRONMENT)) : (PL-ITERATOR OF PROPOSITION)

Retract the truth of the logical sentence sentence in the module named module-name. A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Return an iterator of the retracted propositions resulting from sentence.

Function: s-retrieve ((query STRING) (module-name STRING) (environment ENVIRONMENT)) : PL-ITERATOR

Returns an iterator of variable bindings that when substituted for the open variables in query satisfy the query proposition. The query is run in module and relative to environment. query has the same syntax as the PowerLoom retrieve command (which see) but with the retrieve operator omitted. Different from the PLI retrieve function, s-retrieve does not expect a top-level pair of parentheses. For example, here are some legal query arguments:

 
    "(happy ?x)"
    "10 (happy ?x)"
    "all (happy ?x)"
    "all ?x (happy ?x)"
    "10 (happy ?x) :inference-level :assertion"
    "10 (happy ?x) :inference-level :assertion :timeout 1.0"

If there is only a single output variable (as in all the examples above) each element generated by the returned iterator will be a binding for that variable - unless, the output variable was declared with a surrounding pair of parentheses. For example:

 
    "all (?x) (happy ?x)"

In that case, the generated elements will be one-element lists. If there are multiple output variables, each element generated by the returned iterator will be a list of variable bindings that can be accessed using the various get-nth-... functions. The list of output variables does not need to be declared in which case they are taken to be the open variables in the query proposition in the order in which they were encountered. If order does matter or should be different from its default, it can be forced by declaring the set of output variables.

Names in query will be interpreted relative to module module-name. A null module-name or the empty string refers to the current module. If no module can be found with the name module-name, then a STELLA no-such-context-exception is thrown.

Function: s-save-module ((module-name STRING) (filename STRING) (ifexists STRING) (environment ENVIRONMENT)) :

Save the contents of the module module-name into a file named filename. If a file named filename already exists, then the action taken depends on the value of ifexists. Possible values are "ASK", "REPLACE", "WARN" and "ERROR":

REPLACE => Means overwrite without warning. WARN => Means overwrite with a warning. ERROR => Means don’t overwrite, signal an error instead. ASK => Ask the user whether to overwrite or not. If not overwritten, an exception is thrown.

A module name of null or the empty string refers to the current module. If no module can be found with the name module-name, then a Stella no-such-context-exception is thrown.

Function: save-module ((module MODULE) (filename STRING) (ifexists STRING) (environment ENVIRONMENT)) :

Save the contents of the module mod into a file named filename. If a file named filename already exists, then the action taken depends on the value of ifexists. Possible values are "ASK", "REPLACE", "WARN" and "ERROR":

REPLACE => Means overwrite without warning. WARN => Means overwrite with a warning. ERROR => Means don’t overwrite, signal an error instead. ASK => Ask the user whether to overwrite or not. If not overwritten, an exception is thrown.

Function: string-to-object ((string STRING) (type LOGIC-OBJECT) (module MODULE) (environment ENVIRONMENT)) : OBJECT

Evaluate string with respect to module and environment and return the corresponding logical term. type is a concept used to assist the correct interpretation of string.

Currently type only has an effect on the interpretation of literal types.


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

6.2 Language Specific Interface

This section contains the description of the programming language specific aspects of using the PowerLoom API. Each section describes the naming conventions and namespace issues related to calling the API functions from that programming language.


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

6.2.1 Lisp API

This section tells how to call the API functions in PowerLoom’s Common Lisp implementation from a Lisp program. The function names are identical to the Stella names in the PowerLoom API description See section PowerLoom API. They are exported from the PLI package. Other Stella symbols and names are in the STELLA package, but currently none of the Stella symbols are exported!.

PowerLoom can be used from Allegro Common Lisp, CMU Common Lisp, LispWorks Common Lisp and Macintosh Common Lisp. It may be possible to use the system from other Common Lisp systems, but they have not been tested.


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

6.2.1.1 Common Lisp Initialization

Loading the Common Lisp version of PowerLoom will normally initialize the system as part of the loading process. The Common Lisp version can be loaded by loading the file ‘load-powerloom.lisp’ from the top-level ‘powerloom’ directory. This will make the system available for use.


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

6.2.1.2 Type Declarations

Stella is a typed language, and the Common Lisp translation uses the type information for Common Lisp type declarations. That means that values specified as being of type INTEGER, STRING and FLOAT must have the correct type. In particular, integer values will not be coerced to floating point values by the code. The following native type assignments are made:

 
    Stella      Common Lisp
    =======     ===========
    INTEGER     FIXNUM
    FLOAT       DOUBLE-FLOAT
    STRING      SIMPLE-STRING

For convenience, loading PowerLoom will set the default format for reading floating point numbers in Common Lisp to be double-float.

Stella CONS objects are implmented as native Lisp conses. Boolean values can take on the values stella::true or stella::false.


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

6.2.1.3 NULL values

One additional consequence of the strong typing of the language is that there are specialized NULL values for numeric and string parameters.

 
  Stella Type   Null Value
  ===========   ===========
    INTEGER     stella::null-integer
    FLOAT       stella::null-float
    STRING      stella::null-string

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

6.2.1.4 Wrapped Literal Values

Literal values (integers, floats, strings, etc.) that are used in PowerLoom appear as wrapped values. The PowerLoom API functions object-to-... can be used to coerce the values into the appropriate return type.

<to be written: wrapping values>


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

6.2.1.5 Special Variables

All Stella special variables are implemented as Common Lisp special variables. Binding of the values can be used normally.


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

6.2.1.6 CLOS Objects versus Structs

PowerLoom can be translated in one of two ways for Common Lisp. One method uses CLOS objects as the basis for all Stella and PowerLoom objects. For faster execution, it is also possible to use a version in which Stella and PowerLoom objects are implemented using Common Lisp structs instead. This is controlled by the special variable cl-user::*load-cl-struct-stella?*. If this is set to cl:t, then the struct version will be loaded. This needs to be set before loading the ‘load-powerloom.lisp’ file.


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

6.2.2 C++ API

<to be written>


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

6.2.3 Java API

This section tells how to call the API functions in PowerLoom’s Java implementation from a Java program. The Java translation is written for Java version 1.2. All of the PowerLoom Interface functions appear as static methods of the class edu.isi.powerloom.PLI.


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

6.2.3.1 Initializing PowerLoom

PowerLoom needs to run initialization functions to set up its environment for proper operation when it starts up. The simplest method for initializing PowerLoom is to use the static method call:

 
        PLI.initialize()

This must be called before using any PowerLoom features and before loading any PowerLoom knowledge bases. It may be called more than once without ill effect.


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

6.2.3.2 PowerLoom Java Conventions

PowerLoom’s Java code is automatically generated by a translator from underlying Stella code. The character set for legal Stella names is larger than the character set for legal Java identifiers, so there is some mapping involved.

PowerLoom names are words separated by hyphen (-) characters. For Java, we have attempted to closely follow the Java conventions:

The most common non-alphanumeric characters are mapped as follows. A full set of mappings is in section Java Character Mapping.

 
   ?  =>  P      (for Predicate)
   !  =>  X      (eXclamation)
   $  =>  B      (Buck)
   %  =>  R      (peRcent)
   &  =>  A      (Ampersand)
   *  =>  $      Special variable marker.

The character mappings use uppercase characters if the basic identifier uses mixed or lower case. The mappings use lowercase characters if the basic identifier uses upper case.

Stella modules are mapped to Java packages. The basic system distribution includes the following package hierarchy:

 
  edu
     isi
        stella
            javalib
        powerloom
            logic
            pl_kernel_kb
                loom_api

Basic system functionality and data structures such as Cons and List objects are defined in stella. PowerLoom’s logic (concepts, relations, rules, etc.) are defined in the logic package. There is a set of interface functions in the PLI class in the powerloom package. They are described in their own section below.

We recommend the following import statements in Java files that use PowerLoom:

 
        import edu.isi.stella.*;
        import edu.isi.stella.javalib.*;
        import edu.isi.powerloom.PLI;
        import edu.isi.powerloom.logic.*;

Functions (in Java terms, static Methods) are translated as static methods on the class of their first argument (as long as that argument is not a primitive type and is in the same Stella module). Functions which take no arguments, those whose first argument is a primitive type, and those whose first argument is a class not defined in the same module are all placed into a class with the same name as the Stella module in which it appers. It will be in the package corresponding to that Stella module. Java constructors should not be called directly. Instead, there will be a static method new<ClassName> (with the class name in mixed case!) that should be used instead.

Most of the functions of interest will be in the edu.isi.stella.Stella, edu.isi.powerloom.PLI or edu.isi.powerloom.logic.Logic classes.

Methods typically refer to their first argument as "self".

Methods which return more than one return value will take a final argument which is an array of Stella_Object, which will be used to return the additional arguments.

Primitive types in Stella have the following mapping in Java:

 
        Stella          Java
        ======          ====
        INTEGER         int
        FLOAT           double
        NUMBER          double
        CHARACTER       char
        BOOLEAN         boolean
        STRING          String
        MUTABLE-STRING  StringBuffer

  NATIVE-OUTPUT-STREAM  java.io.PrintStream
  NATIVE-INPUT-STREAM   java.io.PushbackInputStream  (May change!!!)

Inside Stella/PowerLoom objects and collections, primitive types are wrapped using Stella wrappers instead of Java’s primitive classes. So integers will be wrapped as edu.isi.stella.IntegerWrapper rather than java.lang.Integer. Wrappers have a field called wrapperValue which accesses the internal value. Example of use:

 
    import edu.isi.stella.*;
    import edu.isi.stella.javalib.*;
    ...
    IntegerWrapper iWrap = IntegerWrapper.wrapInteger(42);
    ...
    int answer = iWrap.wrapperValue;
    ...

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

6.2.3.3 Using the PLI Class

To make interoperability between PowerLoom and Java a little simpler, we are providing a (PowerLoom Interface class named PLI which handles synchronization issues, setting and restoring the reasoning context, and the a more convenient use of some Java-native objects rather than Stella objects. Generally that means that strings are used for PowerLoom expressions and return values rather than Stella Cons objects.

Details about the methods can be found in the section PowerLoom API. The names of functions in that section will need to be converted to their Java equivalents using the conventions described in PowerLoom Java Conventions. We also provide javadoc documentation for the edu.isi.powerloom.PLI class. We recommend using this method for accessing PowerLoom functionality. We expect to expand the range of PowerLoom interface functions that have an analog in the PLI class over time.


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

6.2.3.4 Using Stella Objects

Stella objects can also be used directly. The most common ones used by PowerLoom users are Module and LogicObject. Other potentially useful Stella objects are Cons, Symbol, Keyword and List. Except for LogicObject, these are in the edu.isi.stella package. LogicObject is in the edu.isi.powerloom.logic package.

If one wishes to construct Cons objects (for example to create objects to pass to interface functions, one would begin by building items up using Stella_Object.cons static method, which takes a stella object and a cons. The empty cons is kept in the edu.isi.stella.Stella.NIL static variable. Another way to create stella objects is to use edu.isi.stella.Stella.unstringify static method. This method takes a string representation of a stella object and returns the object. If passed a list, an object of type Cons will be returned.

As an alternative, one can also convert one and two dimensional arrays of Stella_Object into Cons objects using the overloaded function edu.isi.stella.javalib.arrayToCons. These functions will return Cons objects constructed from the input arrays.

Keywords and symbols are objects that are stored in global static variables. The variable names are all in upper case and are constructed by concatenating the tag SYM with the module name and the name of the symbol or concatenating the tag KWD with the name of the keyword. For example, the symbol BACKWARD in the logic module would be stored in

 
        edu.isi.powerloom.logic.Logic.SYM_LOGIC_BACKWARD

whereas the keyword :ERROR in the stella module would be in

 
        edu.isi.stella.Stella.KWD_ERROR

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

6.2.3.5 PowerLoom and Threads

The most important consideration when using PowerLoom in a threaded environment is that the core of PowerLoom must not execute in concurrently running threads. The PLI class takes care of this for interface functions that run through that class. Other PowerLoom functions that are called need to synchronize on a lock object

 
        edu.isi.powerloom.logic.Logic.$POWERLOOM_LOCK$

for proper operation. This is not needed for setting Special Variables, since they are implemented on a per-thread basis. The most important special variable is the reasoning context. See section Setting and Restoring Global Variable Values.


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

6.2.3.6 Setting and Restoring Global Variable Values

As noted above, special variables in Stella are implemented as static fields in a catchall class named the same as the Stella module. It will be in the java package corresponding to that Stella module. The values of Special variables are stored in Java objects of the type StellaSpecialVariable, a subclass of Java’s InheritableThreadLocal. Any changes made to the values will not affect any other running threads. This means that the changes don’t need to be synchronized. Note that global (as opposed to special) variables don’t use these objects.

Numbers and boolean values are stored in special variables using the corresponding Java classes Integer, Double, Boolean, etc. The naming convention is to have all upper case letters with a dollar sign ($) at the beginning and end of the name.

To temporarily change the value of one of these variables, users will need to be responsible for saving and restoring the old values. Use of the "try ... finally ..." construct is very useful for this, since it guarantees that the restore of values will be done. An example follows of how to safely change modules. Contexts should be changed using the functions, although other global variables can be changed by using the set method. Note that we use variables of type Object to hold the values, since that avoids the need to cast when extracting the current value, since the only operation we do with the current value is save it to restore it later.

 
   import edu.isi.stella.*;

   // CONTEXT CHANGE.
   Object savedModule = Stella.$MODULE$.get();
   Module newModule
      = Stella.getStellaModule(contextName, true);
   if (newModule == null) { // Handle missing module
   }
   try {
     Module.changeCurrentModule(newModule)
     // Code that uses the newModule

   } finally {
     Module.changeCurrentModule(savedModule);
   }


   // INTEGER VALUE CHANGE:
   Object savedValue = Stella.$SAFETY$.get();
   try {
     Stella.$SAFETY$.set(new Integer(3));
     // Code that uses the newModule

   } finally {
     Stella.$SAFETY$.set(savedValue);
   }


   // BOOLEAN VALUE CHANGE:
   Object savedValue = Stella.$PRINTREADABLY$.get();
   try {
     Stella.$PRINTREADABLY$.set(Boolean.TRUE);
     // Code that uses the newModule

   } finally {
     Stella.$PRINTREADABLY$.set(savedValue);
   }

The need to change the module using this type of code can be largely avoided by using the functions in the PLI interface package. They take a module argument and can handle the binding and restoration of the module value themselves.


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

6.2.3.7 Java Character Mapping

The full Stella to Java character mapping is the following. The character mappings use uppercase characters if the basic identifier uses mixed or lower case. The mappings use lowercase characters if the basic identifier uses upper case.

 
   Stella  Java     Mnemonic
   ======  ====     ========
     !   =>  X      (eXclamation)
     "   =>  _
     #   =>  H      (Hash)
     $   =>  B      (Buck)
     %   =>  R      (peRcent)
     &   =>  A      (Ampersand)
     '   =>  Q      (Quote)
     (   =>  _
     )   =>  _
     *   =>  $
     +   =>  I      (Increase)
     ,   =>  _
     -   =>  _
     .   =>  D      (Dot)
     /   =>  S      (Slash)
     :   =>  C      (Colon)
     ;   =>  _
     <   =>  L      (Less than)
     =   =>  E      (Equal)
     >   =>  G      (Greater than)
     ?   =>  P      (Predicate)
     @   =>  M      (Monkey tail)
     [   =>  J      (Arbitrary (array index?))
     \   =>  _
     ]   =>  K      (Arbitrary (array index?)
     ^   =>  U      (Up arrow)
     `   =>  _
     {   =>  Y      (Arbitrary (adjacent free letter))
     |   =>  V      (Vertical bar)
     }   =>  Z      (Arbitrary (adjacent free letter))
     ~   =>  T      (Tilde)
<space>  => _

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

6.2.3.8 Stella Exceptions in Java

Stella exceptions are implemented as a subtype of java.lang.Exception (actually RunTimeException) and may be caught normally. All Stella Exceptions belong to the edu.isi.stella.StellaException class or one of its subclasses. The more specfic PowerLoom exceptions belong to the edu.isi.powerloom.logic.LogicException class or one of its subclasses.

Exceptions thrown during I/O operations will not use the standard Java exceptions. Instead, they will descend from edu.isi.stella.InputOutputException. The most useful descendents are edu.isi.stella.NoSuchFileException and edu.isi.stella.EndOfFileException.


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

6.2.3.9 Iteration in Java

Iteration in Stella (and by extension) PowerLoom is organized a little bit differently than in Java. You can either use the Stella iterators directly, or else use one of the wrapper classes described in the section Utility Classes for Java. It will present a more familiar Java interface. Since the iteration models are a bit different, it would be unwise to mix accesses between the iteration models.

Stella iterators do not compute any values until the next? method (in Java: nextP) is called. This method will try to compute the next value of the iterator and it will return a boolean value which is true if more values are present. Each time it is called, the iteration advances. Values can be read out of the value field of the iterator, which will have type Stella_Object. Some iterators will also have a key field which can be read.

The way one would normally use a Stella iterator is as follows, with possible casting of the value field:

 
    Stella.Iterator iter = ...;

    while (iter.nextP()) {
        processValue(iter.value);
    }

The PLI class also contains a number of functions for simplifying the interaction with PlIterator objects that are returned by various API functions. These are the getNth... functions. They work on sequences and sequence-like objects such as Proposition and and the value slot of PlIterator objects. Note that they do not return sequential elements of the iterator, but rather elements of the implicit sequence that is the value of iterators that have more than one return variable. For convenience, they also work (with index = 0) on the value of PlIterator objects that have only a single return variable. For example:

 
    // Get values of (object name age) in the iterator and then
    // print out a message with the name and age (position 1 & 2).
    // This skips the PowerLoom object bound to ?X in position 0.
    PlIterator iter = 
        PLI.sRetrieve("all (and (name ?x ?name) (age ?x ?age))",
                      null,
                      null);

    while (iter.nextP()) {
        System.out.println(PLI.getNthString(iter, 1, null, null) + " is " +
                           PLI.getNthInteger(iter, 2, null, null ) + " years old.");
    }

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

6.2.3.10 Utility Classes for Java

To make interoperation of Stella and Java easier, there are several convenience classes for wrapping Stella iterators and having them behave like Java enumerations or iterators. These convenience classes are in the edu.isi.stella.javalib package:

 
  ConsEnumeration.java      Enumeration class for Cons objects
  ConsIterator.java         Iterator class for Cons objects
  StellaEnumeration.java    Enumeration interface to Stella's Iterator
  StellaIterator.java       Iterator interface to Stella's Iterator

All of the iterators and enumerators return objects that are actually of type Stella_Object, but the signature specifies java.lang.Object as required for compatibility with the standard Java signature. The Cons... classes take a Cons in their constructor. The Stella... classes take a edu.isi.stella.Iterator object in their constructor.


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

This document was generated by Hans Chalupsky on October 16, 2010 using texi2html 1.82.