[ < ] | [ > ] | [ << ] | [ 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.
9.1 API Functions 9.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 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.
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 setence 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).
relation-and-arguments
satisfies
the relation relation
.
null
, then no switch is performed and the current
module is returned.
Signals a Proposition-Error
if PowerLoom could not conceive sentence.
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.
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.
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.
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.
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.
s-evaluate
.
module.
In a non-case-sensitive module, the returned
name will be all upper case (This latter feature may change!)
(relation <result> value)
holds.
(relation <result> value)
holds.
v
such that (relation arg v
)
has been asserted or can be inferred.
null
.
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.
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.
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.
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.
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.
object-to-integer
and object-to-float
will both work on it.
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.
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.
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.
true
if more
elements are available, false
otherwise.
object-to-string
, but puts
escaped double quotes around strings.
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
.
arguments
satisfies
the relation relation
.
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.
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.
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).
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.
no-such-context-exception
is thrown.
no-such-context-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.
Signals a Proposition-Error
if PowerLoom could not conceive sentence.
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.
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.
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.
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.
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.
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.
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.
no-such-context-exception
is thrown.
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.
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.
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.
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.
v
such that (relation-name arg-name v
)
has been asserted or can be inferred.
A module name of null
or the empty string refers to the current module.
If no module can be found with the name module-name, then a Stella
no-such-context-exception
is thrown.
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.
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.
no-such-context-exception
is thrown.
no-such-context-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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
9.2.1 Lisp API 9.2.2 C++ API 9.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 9. PowerLoom API. They are exported from the PLI
package.
Other Stella symbols and names are in the STELLA
package, but
currently none of the Stella symbols are exported!.
PowerLoom can be used from Allegro Common Lisp, CMU Common Lisp, LispWorks Common Lisp and Macintosh Common Lisp. It may be possible to use the system from other Common Lisp systems, but they have not been tested.
9.2.1.1 Common Lisp Initialization 9.2.1.2 Type Declarations 9.2.1.3 NULL values 9.2.1.4 Wrapped Literal Values 9.2.1.5 Special Variables 9.2.1.6 CLOS Objects versus Structs
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
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 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 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.newIntegerWrapper(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 9. PowerLoom API. The names of functions in that section will need to be converted
to their Java equivalents using the conventions described in
9.2.3.2 PowerLoom Java Conventions. We also provide javadoc
documentation for the edu.isi.powerloom.PLI
class. We recommend
using this method for accessing PowerLoom functionality. We expect to
expand the range of PowerLoom interface functions that have an analog in
the PLI
class over time.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 9.2.3.6 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 9.2.3.10 Utility Classes for Java. It will present a more familiar Java interface. Since the iteration models are a bit different, it would be unwise to mix accesses between the iteration models.
Stella iterators do not compute any values until the next? method (in
Java: nextP
) is called. This method will try to compute the next
value of the iterator and it will return a boolean value which is true
if more values are present. Each time it is called, the iteration
advances. Values can be read out of the value field of the iterator,
which will have type Stella_Object
. Some iterators will also
have a key field which can be read.
The way one would normally use a Stella iterator is as follows, with possible casting of the value field:
Iterator iter = ...; while (iter.nextP()) { processValue(iter.value); } |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |