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

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

9.1 API Functions  
9.2 Language Specific Interface  


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

9.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 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 OBJECT)) : TRUTH-VALUE
Returns a truth value for the query in module and environment. The truth value represents the degree of belief in the answer. See also the helping functions is-true, is-false , is-unknown.

Function: assert-binary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (value OBJECT) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : PROPOSITION
Assert that the proposition represented by the list arguments satisfies the relation relation.

Function: assert-proposition ((proposition PROPOSITION) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : PROPOSITION
Assert that the proposition (relation arg) is TRUE in module. Return the asserted proposition.

Function: change-module ((module MODULE)) : OBJECT
Set the current module to module. The return value is module unless the context switch cannot be performed, in which case the current module is returned.

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

Function: create-enumerated-list ((members CONS)) : LOGIC-OBJECT
Create a logical term that denotes a list containing members. Useful for passing lists as arguments to parameterized queries.

Function: create-enumerated-set ((members CONS)) : LOGIC-OBJECT
Create a logical term that denotes the enumerated set containing members.

Function: create-function ((name STRING) (arity INTEGER) (module MODULE) (environment OBJECT)) : 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.

Function: create-object ((name STRING) (concept LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : 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.

Return the object.

Function: create-relation ((name STRING) (arity INTEGER) (module MODULE) (environment OBJECT)) : 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.

Function: destroy-object ((object LOGIC-OBJECT)) :
Delete the object object, retracting all facts attached to it.

Method: empty? ((self PL-ITERATOR)) : BOOLEAN
Return TRUE if the iterator self has no more elements.

Function: evaluate ((command OBJECT) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : STRING
Generates a name based on prefix with a number appended that is not currently in use in the knowledge base.

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

Function: get-concept ((name STRING) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : 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 OBJECT)) : 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 OBJECT)) : 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-direct-concept-instances ((concept LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : (PL-ITERATOR OF LOGIC-OBJECT)
Return relations that directly specialize relation. Non-reflexive.

Function: get-direct-superrelations ((relation LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : (PL-ITERATOR OF LOGIC-OBJECT)
Return relations that directly generalize relation. Non-reflexive.

Function: get-direct-types ((object LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : (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)) : 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 OBJECT)) : PL-ITERATOR
Return all values v such that (relation arg v) has been asserted or can be inferred.

Function: get-module ((name STRING) (environment OBJECT)) : MODULE
Return a module named name.

Function: get-modules () : (PL-ITERATOR OF MODULE)
Return all modules currently loaded into PowerLoom.

Function: get-name ((obj OBJECT)) : STRING
Return the 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.

Function: get-nth-float ((sequence OBJECT) (n INTEGER)) : 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 NULL-FLOAT will be returned.

Function: get-nth-integer ((sequence OBJECT) (n INTEGER)) : INTEGER
Return an integer representation of the 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 an integer value, then NULL-INTEGER will be returned.

Function: get-nth-logic-object ((sequence OBJECT) (n INTEGER)) : LOGIC-OBJECT
Return a logic object representation of the 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. A zero column number returns the proposition's relational predicate.

Function: get-nth-string ((sequence OBJECT) (n INTEGER)) : STRING
Return a string representation of the 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. This will always succeed, even if the nth value is not a string object. In that case, a string reprensentation will be returned.

Function: get-nth-value ((sequence OBJECT) (n INTEGER)) : OBJECT
Return the 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 number of columns is for the current value of the iterator.

Function: get-object ((name STRING) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : (PL-ITERATOR OF LOGIC-OBJECT)
Return relations that specialize relation. Non-reflexive.

Function: get-proper-superrelations ((relation LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : (PL-ITERATOR OF LOGIC-OBJECT)
Return relations that generalize relation. Non-reflexive.

Function: get-proposition ((relation-and-arguments OBJECT) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : (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 OBJECT)) : (PL-ITERATOR OF PROPOSITION)
Return propositions that have been conceived in the module module.

Function: get-propositions-of ((object LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : (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 OBJECT)) : 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 OBJECT)) : (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 OBJECT)) : (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 OBJECT)) : (PL-ITERATOR OF LOGIC-OBJECT)
Return all named concepts that object belongs to.

Function: initialize () :
Initialize the PowerLoom logic system. This needs to be called by all applications before using PowerLoom.

Function: is-a ((object OBJECT) (concept LOGIC-OBJECT) (module MODULE) (environment OBJECT)) : 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-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 OBJECT)) : 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 OBJECT)) : 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 OBJECT)) : BOOLEAN
Return TRUE if proposition is TRUE in the module module.

Function: is-true-unary-proposition ((relation LOGIC-OBJECT) (arg OBJECT) (module MODULE) (environment OBJECT)) : 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: length ((self PL-ITERATOR)) : INTEGER
Number of items in self.

Function: list-to-pl-iterator ((self LIST)) : PL-ITERATOR
Convert a Stella list into an API iterator.

Function: load ((filename STRING)) :
Read logic commands from the file named filename 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.

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

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.

Command: print-rules ((relation OBJECT)) :
Print the list of rules associated with relation.

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 OBJECT)) : 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 OBJECT)) : PROPOSITION
Retract the proposition that arguments satisfies the relation relation.

Function: retract-proposition ((proposition PROPOSITION) (module MODULE) (environment OBJECT)) : 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 OBJECT)) : PROPOSITION
Retract that the proposition (relation arg) is TRUE in module. Return the asserted proposition.

Function: retrieve ((query CONS) (module MODULE) (environment OBJECT)) : PL-ITERATOR
Returns an iterator for variables that satisfy query in module-name and environment. This uses the normal PowerLoom query syntax:

[n-values] output-variables query-form [options]

The output-variables should either be a single variable name -- preceded by the ? character -- or a list of one or more such names. If a single variable name is provided, then each element in the returned iterator will be a value binding. If a list (even of one variable name) is provided, then each element in the returned iterator can be accessed using the get-nth-... functions.

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 OBJECT)) : TRUTH-VALUE
Returns a truth value for the query in module-name and environment. The truth value represents the degree of belief in the answer. See also the helping functions is-true, is-false , is-unknown.

Function: s-assert-proposition ((sentence STRING) (module-name STRING) (environment OBJECT)) : (PL-ITERATOR OF PROPOSITION)
Assert that the logical sentence sentence is true in the module named module-name. Return an iterator of the propositions resulting from sentence.

Function: s-change-module ((name STRING) (environment OBJECT)) : OBJECT
Set the current module to the module named name. The return value is the module named name unless the context switch cannot be performed, in which case the current module is returned.

Function: s-clear-module ((name STRING) (environment OBJECT)) : MODULE
Destroy the contents of the module named name, as well as the contents of all of its children, recursively.

Function: s-conceive ((sentence STRING) (module-name STRING) (environment OBJECT)) : (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.

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

Function: s-create-concept ((name STRING) (parent-name STRING) (module-name STRING) (environment OBJECT)) : 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.

Function: s-create-function ((name STRING) (arity INTEGER) (module-name STRING) (environment OBJECT)) : 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.

Function: s-create-object ((name STRING) (concept-name STRING) (module-name STRING) (environment OBJECT)) : 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.

Return the object.

Function: s-create-relation ((name STRING) (arity INTEGER) (module-name STRING) (environment OBJECT)) : 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.

Function: s-destroy-object ((object-name STRING) (module-name STRING) (environment OBJECT)) :
Delete the object named object-name, retracting all facts attached to it.

Function: s-evaluate ((command STRING) (module-name STRING) (environment OBJECT)) : 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.

Function: s-get-arity ((relation-name STRING) (module-name STRING) (environment OBJECT)) : INTEGER
Return the arity of the relation named relation-name.

Function: s-get-child-modules ((name STRING) (environment OBJECT)) : (PL-ITERATOR OF MODULE)
Return the modules that are immediate children of module name.

Function: s-get-concept ((name STRING) (module-name STRING) (environment OBJECT)) : LOGIC-OBJECT
Return a class/concept named name that is local to or visible from the module module-name.

Function: s-get-concept-instances ((concept-name STRING) (module-name STRING) (environment OBJECT)) : 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.

Function: s-get-direct-concept-instances ((concept-name STRING) (module-name STRING) (environment OBJECT)) : 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.

Function: s-get-domain ((relation-name STRING) (module-name STRING) (environment OBJECT)) : LOGIC-OBJECT
Return the type (concept) for the first argument to the binary relation relation-name.

Function: s-get-inferred-binary-proposition-values ((relation-name STRING) (arg-name STRING) (module-name STRING) (environment OBJECT)) : PL-ITERATOR
Return all values v such that (relation-name arg-name v) has been asserted or can be inferred.

Function: s-get-nth-domain ((relation-name STRING) (n INTEGER) (module-name STRING) (environment OBJECT)) : LOGIC-OBJECT
Return the type (a concept) for the nth argument of the relation named relation-name. Counting starts at zero.

Function: s-get-object ((name STRING) (module-name STRING) (environment OBJECT)) : OBJECT
Look for an object named name that is local to or visible from the module module-name.

Function: s-get-parent-modules ((name STRING) (environment OBJECT)) : (PL-ITERATOR OF MODULE)
Return the modules that are immediate parents of module name.

Function: s-get-parent-modules ((name STRING) (environment OBJECT)) : (PL-ITERATOR OF MODULE)
Return the modules that are immediate parents of module name.

Function: s-get-proposition ((relation-and-arguments STRING) (module-name STRING) (environment OBJECT)) : 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.

Function: s-get-propositions ((relation-and-arguments STRING) (module-name STRING) (environment OBJECT)) : (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.

Function: s-get-propositions-of ((object-name STRING) (module-name STRING) (environment OBJECT)) : (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.

Function: s-get-range ((relation-name STRING) (module-name STRING) (environment OBJECT)) : LOGIC-OBJECT
Return the type (a concept) for fillers of the binary relation relation-name.

Function: s-get-relation ((name STRING) (module-name STRING) (environment OBJECT)) : LOGIC-OBJECT
Return a concept or relation named name that is local to or visible from the module module-name.

Function: s-get-relation-extension ((relation-name STRING) (module MODULE) (environment OBJECT)) : (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 OBJECT)) : (PL-ITERATOR OF PROPOSITION)
Return rules attached to the concept/relation named relation-name found in the module named module-name.

Function: s-is-true-proposition ((relation-and-arguments STRING) (module-name STRING) (environment OBJECT)) : BOOLEAN
Return TRUE if a proposition that prints as the string relation-and-arguments is true in the module named module-name.

Function: s-print-rules ((name STRING) (stream OUTPUT-STREAM) (module-name STRING) (environment OBJECT)) :
Print rules attached to the concept/relation named name.

Function: s-retract-proposition ((sentence STRING) (module-name STRING) (environment OBJECT)) : (PL-ITERATOR OF PROPOSITION)
Retract the truth of the logical sentence sentence in the module named module-name. Return an iterator of the retracted propositions resulting from sentence.

Function: s-retrieve ((query STRING) (module-name STRING) (environment OBJECT)) : PL-ITERATOR
Returns an iterator for variables that satisfy query in module-name and environment. This uses the normal PowerLoom query syntax:

"[n-values] output-variables query-form [options]"

The output-variables should either be a single variable name -- preceded by the ? character -- or a list of one or more such names. If a single variable name is provided, then each element in the returned iterator will be a value binding. If a list (even of one variable name) is provided, then each element in the returned iterator can be accessed using the get-nth-... functions.

Function: s-save-module ((module-name STRING) (filename STRING) (ifexists STRING) (environment OBJECT)) :
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.

Function: save-module ((module MODULE) (filename STRING) (ifexists STRING) (environment OBJECT)) :
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 OBJECT)) : 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] [ ? ]

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

9.2.1 Lisp API  
9.2.2 C++ API  
9.2.3 Java API  


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

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

9.2.1.1 Common Lisp Initialization  
9.2.1.2 Type Declarations  
9.2.1.3 NULL values  
9.2.1.4 Wrapped Literal Values  
9.2.1.5 Special Variables  
9.2.1.6 CLOS Objects versus Structs  


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

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

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

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

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

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

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

9.2.2 C++ API

<to be written>


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

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

9.2.3.1 Initializing PowerLoom  
9.2.3.2 PowerLoom Java Conventions  
9.2.3.3 Using the PLI Class  
9.2.3.4 Using Stella Objects  
9.2.3.5 PowerLoom and Threads  
9.2.3.6 Setting and Restoring Global Variable Values  
9.2.3.7 Java Character Mapping  
9.2.3.8 Stella Exceptions in Java  
9.2.3.9 Iteration in Java  
9.2.3.10 Utility Classes for Java  


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

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

9.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 See section 9.2.3.7 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 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.newIntegerWrapper(42);
    ...
    int answer = iWrap.wrapperValue;
    ...


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

9.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 See section 9. PowerLoom API. The names of functions in that section will need to be converted to their Java equivalents using the conventions described in See section 9.2.3.2 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] [ ? ]

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

9.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 See section 9.2.3.6 Setting and Restoring Global Variable Values.


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

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

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

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


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

9.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 See section 9.2.3.10 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:

 
    Iterator iter = ...;

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


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

9.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 September, 30 2003 using texi2html