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
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.
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
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
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.
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
.
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
|
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>
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.
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.
9.2.2 C++ API
<to be written>
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
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:
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.
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:
-
Class names begin with a capital letter and each word is capitalized.
The hyphens from the PowerLoom names are removed. Example:
| 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
|
-
Method and Function names begin with a lower case letter but each
subsequent word is capitalized. The hyphens from PowerLoom names are
removed. Example:
| wrapper-value => wrapperValue
|
-
Storage slots are implemented as Java fields. The names begin with a
lower case letter but each subsequent word is capitalized. The hyphens
from PowerLoom names are removed. Example:
| dynamic-slots => dynamicSlots
|
-
Global and Special variable names are written in all uppercase. The
hyphens from PowerLoom are replaced by underscore (_) characters. By
convention, special variables are written in PowerLoom with surrounding
asterisk (*) characters. The asterisks are replaced by dollar signs ($).
Example:
| *html-quoted-characters* => $HTML_QUOTED_CHARACTERS$
|
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;
...
|
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.
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
|
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.
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.
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> => _
|
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.
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);
}
|
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.
This document was generated
by Hans Chalupsky on September, 30 2003
using texi2html