| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| 6.1 API Functions | ||
| 6.2 Language Specific Interface |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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).
Assert that the proposition (relation arg value) is TRUE in module. Return the asserted proposition.
Assert that the proposition represented by the list relation-and-arguments satisfies
the relation relation.
Assert that the proposition proposition is true in module. Return the asserted proposition.
Assert that the proposition (relation arg) is TRUE in module. Return the asserted proposition.
Set the current module to module and return it.
If module is null, then no switch is performed and the current
module is returned.
Clear all query and memoization caches.
Destroy the contents of the module module as well as the contents of all of its children, recursively.
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.
Convert a STELLA cons list into an API iterator.
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.
Create a logical term that denotes a list containing members in module using environment. Useful for passing lists as arguments to parameterized queries.
Create a logical term that denotes the enumerated set containing members in module using environment.
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.
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.
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.
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.
Delete the object object, retracting all facts attached to it.
Return TRUE if the iterator self has no more elements.
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.
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!)
Return the arity of the relation relation.
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.
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.
Return the modules that are immediate children of module.
Return the number of columns in obj, which must be of type proposition, skolem, cons, vector or PL-iterator. For a proposition, the number includes both the predicate and arguments. For the PL-iterator case,the number of columns is for the current value of the iterator. For the skolem case, if the skolem is a function term, the column count of its defining proposition will be returned, otherwise it is treated as a non-sequence object.
For a null item, the column count is zero. For non sequence objects, the column count is one.
Return a class/concept named name that is local to
or visible from the module module. name is not taken literally but
will be parsed first (see get-object).
Return a member of concept concept that
has an attribute matching value for the binary relation relation, i.e.,
(relation <result> value) holds.
Return instances of the concept concept. Include instances of subconcepts of concept. Depending on concept, the return values could be (wrapped) literals.
Return members of concept concept that
have an attribute matching value for the binary relation relation, i.e.,
(relation <result> value) holds.
Return the currently set module
Return instances of concept concept. Exclude instances of subconcepts of concept. Depending on concept, the return values could be (wrapped) literals.
Return relations that directly specialize relation. Non-reflexive.
Return relations that directly generalize relation. Non-reflexive.
Return most specific concepts that object belongs to.
Return the type (a concept) for the first argument to the binary relation relation.
Returns the members of an enumerated collection. This works on all types of collection, i.e., sets and lists
Return the module in which object was created.
Return all values v such that (relation arg v)
has been asserted or can be inferred via a general PowerLoom retrieve.
Both relation and arg have to be non-NULL.
Return a module named name or NULL if no such module exists.
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.
Return the fully qualified name of obj, if it has one. Otherwise return null.
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).
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.
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.
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.
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.
Return the value in the nth column of sequence.
Counting starts at zero. Unless n is zero, sequence must be of type
proposition, skolem, 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. For the skolem case,
if the skolem is a function term, the nth value of its defining proposition
will be returned, otherwise it is treated as a non-sequence object.
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.
Returns the logical operator object (a Stella SYMBOL) for name.
If no such operator exists then a no-such-object exception is thrown.
Look for an object named name that is local to or visible from the module module. name is not taken literally but will be parsed first with the PowerLoom symbol reader and, hence, can contain escape characters, module prefixes, etc.
Return the modules that are immediate parents of module.
Return the concept or relation predicate for the proposition prop.
Return relations that specialize relation. Non-reflexive.
Return relations that generalize relation. Non-reflexive.
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.
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.
Return propositions that have been locally conceived in the module module (but are not necessarily true).
Return all propositions that have object among their arguments, and that are TRUE in the scope of the module module.
Return the type (a concept) for fillers of the binary relation relation.
Return a concept or relation named name that is local to
or visible from the module module. name is not taken literally but will
be parsed first (see get-object).
Return propositions that satisfy relation. Include propositions that satisfy subrelations of relation.
Return rules attached to the concept/relation relation in either antecedent or consequent position.
Return all named concepts that object belongs to.
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.
Deprecated - use is-instance instead.
Tests whether tv is a default truth value.
Test whether obj is an enumerated collection. This subsumes both sets and lists.
Test whether obj is an enumerated list
Test whether obj is an enumerated set.
Tests whether tv is a false truth value. It can be false either absolutely or by default.
Test whether obj is of type FLOAT (double)
Tests whether tv is an inconsistent truth value.
Test whether obj is of type INTEGER
Test whether obj is of type LOGIC-OBJECT
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.
Tests whether tv is a strict (non-default) truth value.
Test whether obj is of type STRING
Return TRUE if sub is a subconcept/subrelation of super.
Tests whether tv is a true truth value. It can be true either absolutely or by default.
Return TRUE if the proposition (relation arg value) has been asserted (or inferred by forward chaining).
Return TRUE if proposition is TRUE in the module module.
Return TRUE if the proposition (relation arg) has been asserted (or inferred by forward chaining).
Tests whether tv is an unknown truth value.
Convert an arbitrary STELLA iterator into an API iterator. This will first exhaust self and then create an API iterator that will iterate over the previously generated values.
Number of items remaining in self. Non destructive.
Convert a STELLA list into an API iterator.
Read logic commands from the file named filename and evaluate them.
See load command help for more information.
Read logic commands from the STELLA stream stream and evaluate them.
See load command help for more information.
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.
See load command help for more information.
Advance the PL-Iterator self and return true if more
elements are available, false otherwise.
Coerce self to a float, or throw a Stella Exception if the coersion is not feasible.
Coerce self to an integer, or throw a Stella Exception if the coersion is not feasible. Floating point values will be coerced by rounding.
Return a string representing a printed
representation of the object self. Like object-to-string, but puts
escaped double quotes around strings.
Return a printed representation of the term self as a string.
Print the list of true rules associated with relation.
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.
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.
Retract that the proposition (relation arg value) is TRUE in module. Return the asserted proposition.
Retract the proposition that arguments satisfies
the relation relation.
Retract the truth of the proposition proposition in module. Return the retracted proposition.
Retract that the proposition (relation arg) is TRUE in module. Return the asserted proposition.
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.
Run forward inference rules in module module which defaults
to the current module. See run-forward-rules command for more information.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Return the modules that are immediate children of module name.
If no module named name exists, a Stella no-such-context-exception
is thrown.
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.
name is not taken literally but will be parsed first (see get-object).
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.
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.
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.
Return all values v such that (relation-name arg-name v)
has been asserted or can be inferred via a general PowerLoom retrieve.
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 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.
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.
name is not taken literally but will be parsed first (see get-object).
Return the modules that are immediate parents of module name.
If no module named name exists, a Stella no-such-context-exception
is thrown.
Return the modules that are immediate parents of module name.
If no module named name exists, a Stella no-such-context-exception
is thrown.
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 such as a number, or the null identifier which 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
with name module-name can be found, a STELLA no-such-context-exception is thrown.
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), or the null identifier which acts like a wild card.
A module name of null or the empty string refers to the current module. If no module
with name module-name can be found, a STELLA no-such-context-exception is thrown.
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.
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.
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.
name is not taken literally but will be parsed first (see get-object).
Return propositions that satisfy the relation named relation-name. Include propositions that satisfy subrelations of the relation.
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.
Not yet implemented.
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.
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.
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.
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.
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.
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] | [ ? ] |
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.
| 6.2.1 Lisp API | ||
| 6.2.2 C++ API | ||
| 6.2.3 Java API |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| 6.2.1.1 Common Lisp Initialization | ||
| 6.2.1.2 Type Declarations | ||
| 6.2.1.3 NULL values | ||
| 6.2.1.4 Wrapped Literal Values | ||
| 6.2.1.5 Special Variables | ||
| 6.2.1.6 CLOS Objects versus Structs |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
All Stella special variables are implemented as Common Lisp special variables. Binding of the values can be used normally.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
<to be written>
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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:
string-wrapper => StringWrapper |
Exceptions are made for class names that would otherwise conflict with normal Java Classes. In that case, the prefix "Stella_" is added to each class name. At the moment this applies only to the following exceptions:
object => Stella_Object
class => Stella_Class
|
wrapper-value => wrapperValue |
dynamic-slots => dynamicSlots |
*html-quoted-characters* => $HTML_QUOTED_CHARACTERS$ |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
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 January 6, 2023 using texi2html 1.82.