NeoClassic Reference Manual
NeoClassic Overview
1/ What is Classic?
Classic is a full-featured knowledge representation system based on a small
description logic. Being a knowledge representation system, Classic stores
a collection of information and determines the consequences of this
information. Being based on a description logic, the information stored by
Classic consists of statements and other expressions from this description
logic and the consequences computed by Classic are those sanctioned by the
description logic. Being a full-featured knowledge representation system,
Classic allows for both the addition and the retraction of information.
Further, Classic can explain how it obtained the consequences it computed.
Classic provides a number of extra-logical features, including multiple
knowledge bases, forward-chaining rules, procedural extensions to the
description logic in the form of test functions and computed rules, and
hooks that allow programs to be informed of the actions that Classic
performs.
2/ What is NeoClassic?
NeoClassic is an implementation of Classic in C++. NeoClassic heavily uses
C++ object-oriented programming. NeoClassic currently provides two
low-level interfaces, a character-based interface (CI) and an application
program interface (API). There was a graphical user interface (GUI), but
it is no longer working. All interfaces can exercise the full knowledge
representation capabilities of NeoClassic.
In the CI commands are given to NeoClassic over a character stream, and
responses are given back on another character stream. The syntax for the
CI allows two ways of grouping a function with its arguments. Parentheses
may be placed around the arguments only or parentheses may be placed around
the function name as well as the arguments. Most examples are shown using
the second syntax. Many CI functions can take an arbitrary number of
arguments that are grouped into a set or list.
In the GUI concepts, roles, rules, and individuals can be created in
several ways: a file can be specified and read in; CI commands can be
entered; or a dialog box that guides the creation of a concept, role, rule,
or individual can be used. Concepts, roles, rules, and individuals can be
viewed and changes can be made to them and explanation can be performed on
them.
The API to NeoClassic exposes the object-oriented implementation of
NeoClassic, but in a way that does not (easily) allow subverting the
semantics of NeoClassic objects. There is some functionality that only
makes sense using the API, and thus does not show up in the CI.
3/ Running NeoClassic
The easiest way to run neoclassic is to execute a version of neoclassic
that reads from the standard input into the character interface and writes
to the standard output from the character interface. This version of
neoclassic is generally available via the command
neoclassic [...]
where is the name of a file containing character interface
commands. After reading these files, if any, this version of neoclassic
will prompt for more input from the standard input.
The easiest way to run NeoClassic under Windows 95 or Windows NT is to
double click on the executable file. Once the window for NeoClassic is up
files can be read by using the files menu.
Using NeoClassic as part of a larger C++ program is only slightly more
complicated. To compile a C++ program that uses NeoClassic, put the
NeoClassic directory in the include path, and include the file NeoClassic.H
in each file that uses NeoClassic classes. To link a C++ program that uses
NeoClassic, add the library libneoclassic.a to the libraries of the
program. The C++ program is responsible for starting NeoClassic by calling
the function NeoEnvironment::init and for cleaning up after all use of
NeoClassic is done by calling NeoEnvironment::cleanup. To process
NeoClassic character interface commands, use the function
NeoEnvironment::readFile.
4/ Knowledge Level Overview of NeoClassic
This overview ignores the exact syntax (and semantics) of NeoClassic, in
favor of providing a general idea of what NeoClassic can do. A passing
familiarity with description logics is required.
NeoClassic allows the creation of a collection of (named) knowledge bases.
Each knowledge base has a collection of (named) roles, (named) concepts,
(named) individuals, and (named) rules.
The allowable operations on knowledge bases are:
1. adding information to a knowledge base
- defining a role
- defining a concept (in terms of a description)
- creating a rule (in terms of a concept and a description)
- creating an individual (in terms of a description)
- adding information (in the form of a description) to an individual
- closing a role on an individual
2. retracting information from a knowledge base
- removing information (in the form of a description) from an individual
- unclosing a role on an individual
- removing a rule (not implemented yet)
3. querying information in the knowledge base
- determining whether one description subsumes another
- determining whether an individual satisfies a description
- retrieving the information told about an individual or concept
- retrieving the information derived about an individual or concept
- traversing the taxonomy of concepts and classic individuals
NeoClassic immediately computes the consequences of all information added
to a knowledge base. If an attempt is made to define an incoherent concept
(i.e., a concept that could never have any instances) then the attempt is
rejected. If an attempt is made to change a knowledge base in a way that
would make the knowledge base inconsistent then that attempt is rejected.
In both the above cases information is returned indicating why the attempt
was invalid.
NeoClassic is not quite a complete reasoner. There is one kind of
reasoning by cases that it does not perform.
5/ The Knowledge Language of NeoClassic
Individuals in a NeoClassic knowledge base are either host individuals or
classic individuals. Host individuals come from C++ and can be either
integers, floats, or strings. Classic individuals are created by NeoClassic
and represent anything desired.
Descriptions in NeoClassic are likewise either host descriptions or classic
descriptions. As expected, host individuals can only satisfy host
descriptions and classic individuals can only satisfy classic descriptions.
Most descriptions exist in a particular knowledge base, and cannot refer to
descriptions from other knowledge bases. Similarly, concepts, individuals,
and rules must use descriptions that are valid for their knowledge base.
The details of descriptions are contained elsewhere.
6/ The Collection of Knowledge Bases
NeoClassic maintains a collection of named knowledge bases. One of these
knowledge bases is the current knowledge base. This knowledge base is used
in the character interface and when looking up symbols.
The operations on the collection of knowledge bases are:
- initializing the collection of knowledge bases
- cleaning up the collection of knowlege bases by destroying them all
- retrieving the current knowledge base
- setting the current knowledge base
- creating a knowledge base
- finding a knowledge base by name
- removing a knowledge base from the collection of knowledge bases
7/ Incoherency and Inconsistency Reporting in NeoClassic
If an operation in NeoClassic would result in an inconsistent knowledge
base that operation is not performed. Instead the operation returns a
special value, which encodes the relevant portion of the knowledge base and
can be used to find and explain the source of the potential inconsistency.
This result can be used to explain why the operation would have resulted in
an inconsistent knowledge base.
Similarly, if an operation in NeoClassic would result in the creation of an
incoherent concept, that concept is not added to the knowledge base.
Instead the operation returns a special value, which can be used to find
and explain the source of the potential incoherency.
8/ Explanation Facilities in NeoClassic
NeoClassic can explain anything that is has inferred about any concept or
individual. It can explain why one description does/does not subsume
another, why an individual does/does not satisfy a description, why a
particular fact is/is not known about an individual or concept, and why a
rule did/did not fire. NeoClassic can even explain the inferences that
would have resulted in an inconsistent knowledge base.
Explanations report only the last (important) inference made in any chain
of inferences. To see an entire chain of inferences a series of
explanations must be requested, manually or automatically. There will
eventually be mechanisms for controlling what is and what is not important.
9/ Hooks in NeoClassic
NeoClassic provides a facility that allows functions from outside NeoClassic
to be run in response to particular activities performed by NeoClassic.
These activities include the creation of roles, concepts, rules, and
individuals; the addition of information to or the retraction of
information from an individual; the firing of rules; the transfer of
information from one individual to another; and the discovery of a new
individual that satisfies a concept. This facility can be used to build
user interfaces that maintain an up-to-date view of a NeoClassic knowledge
base.
10/ Features to be Added in the Future
Role Hierarchies
Meta Information
Subsumption between Test Functions
NeoClassic Conceptual Building Blocks
NeoClassic is a sophisticated knowledge representation system that allows
close program direct but safe access to its data structures. To
effectively access these data structures from a program requires a
knowledge of how they are organized.
1/ NeoPtrObject and named objects
Many NeoClassic objects belong to the NeoPtrObject class. This class is
actually a class of smart pointers that implement automatic storage
management, currently be means of reference counting. There are
type-checking operations provided for each subclass of NeoPtrObject to
allow discrimination between the various subclasses of NeoPtrObject. There
are also conditional downcasting operations provided for each subclass of
NeoPtrObject.
The classes Role, Concept, Rule, and ClassicIndividual share functionality
having to do with their similar position in knowledge bases. They each
have a name and a knowledge base they belong to. They also have two kinds
of modifiable data, a comment string and an arbitrary piece of information,
that are not managed by NeoClassic. This common functionality is provided by a
mechanism that is not visible to the user.
2/ Knowledge Bases
A knowledge base in NeoClassic contains a collection of consistent
information. This information is stored in the form of roles, concepts,
rules, and classic individuals. Each knowledge base also has a name.
When a knowledge base is created, it contains only the definitions of the
built in NeoClassic concepts. These are
Thing
ClassicThing (alias classic-thing)
HostThing (alias host-thing)
String
Number
Integer
Real
A knowledge base continually computes the consequences of all information
it contains. Any operation that would result in an inconsistent knowledge
base is rejected. Part of this information is a classification and
instantiation taxonomy of concepts and classic individuals.
The roles, concepts, rules, and classic individuals in a knowledge base can
be retrieved by name.
3/ The Knowledge Base Collection
NeoClassic also maintains a collection of named knowledge bases. In the
normal course of events every knowledge base is in this collection of
knowledge bases. There are operations to add a named knowledge base to
this collection, to remove a knowledge base from this collection, and to
find a knowledge base in this collection given a name. One of the
knowledge bases in this collection is the current knowledge base. There
are operations to return the current knowledge base and to make a knowledge
base be the current knowledge base. The current knowledge base is used in
several operations, including when coercing a symbol to a role, concept,
rule, or classic individual.
There are also operations to initialize the collection of knowledge bases,
to reinitialize it, and clean it up by destroying all the knowledge bases
in the collection. The newly initialized or reinitialized collection
contains a single fresh knowledge base, which is the current knowledge
base.
4/ Descriptions
A description in NeoClassic is a formal object that represents a collection
of the objects of a model or interpretation. Objects that are in the
collection are said to satisfy the description. A description is said to
subsume another description if for every model the collection it represents
is a superset of the collection the other description represents. A
description is said to be incoherent if the collection it represents is
empty in all models.
NeoClassic divides descriptions into concepts and constructed descriptions.
Concepts are defined in a particular knowledge base in terms of a
description and primitive information. Constructed descriptions are formed
by one of the description constructors.
NeoClassic also divides descriptions into thing descriptions, classic
descriptions, host descriptions, and incoherent descriptions. The
collection of objects represented by a classic description must come only
from the classic objects of the model, and the collection of objects
represented by a host description must come only from the host objects of
the model. The host objects of a model are strings, integers, and floats.
The classic objects of a model are all the other objects in the model.
Thing descriptions represent the union of all classic objects and host
objects; incoherent descriptions structurally represent the empty set.
(Note that it is possible to have classic descriptions and host
descriptions that represent the empty set.)
5/ Roles
A role in NeoClassic is a formal object that represents a relation from the
classic domain of a model to the entire domain. Roles are created in
knowledge bases. Roles can be tagged as attributes, i.e., a role whose
relation is a (partial) function.
Currently roles are atomic entities, but a role hierarchy will be added in
a future release.
6/ Concepts
A concept in NeoClassic is a formal object that represents a collection of
objects of a model. Concepts are defined in a knowledge base. Concepts
are divided into thing concepts, whose definition is a thing description;
classic concepts, whose definition is a classic description plus some
primitive information; and host concepts, whose definition is a host
description. Definitions of concepts must refer only to concepts that have
already been defined in the knowledge base.
The representation of a host concept is precisely the representation of its
definition. The representation of a classic concept is a subset of the
representation of the description in its definition. If the classic
concept is not primitive then its representation is precisely the
representation of this description. If it is primitive then the
representation must also be disjoint from selected other primitive
concepts.
7/ Rules
A rule in NeoClassic is a formal object that represents a mapping between
the representation of its antecedent and the representation of its
consequent. A rule requires that all classic individuals in the knowledge
base that belong to its antecedent also belong to its consequent. Rules
are created in knowledge bases.
The consequent of a rule can be specified as a description, as a function
from classic individuals to descriptions, or as a function from classic
individuals and roles to sets of individuals. In the first case the
consequent of the rule is the description provided, in the second case it
is the description returned when the function is run, and in the third case
the description is a fills description created from the role and the set of
individuals.
8/ Individuals
Individuals in NeoClassic are either Classic Individuals or Host Individuals.
A classic individual is a formal object that represents a classic object in
a model. Classic Individuals are created in knowledge bases, and
information can be added to them and removed from them. This information
is either in the form of a description or a role closing. Adding a
description means that the classic individual is required to satisfy the
description. Adding a role closing means that the only fillers for the
role on the individual are the ones currently known.
Classic Individuals that belong to a knowledge base must be consistent, as
knowledge bases are consistent. However, operations that would have
resulted in an inconsistent knowledge base return inconsistent individuals
to encode the inconsistent relevant state that would have resulted if the
operation was performed.
A host individual is both a formal object that represents a host object in
a model and a data structure in C++. Host individuals are thus either
strings, integers, or reals. They exist in all knowledge bases and, of
course, cannot be changed.
NeoClassic Interface Functionality
NeoClassic currently provides three low-level interfaces, a character-based
interface (CI), a graphical user interface (GUI), and a C++ application
program interface (API). All three interfaces can exercise the full
knowledge representation capabilities of NeoClassic. This document
includes information on all the user-callable NeoClassic functions, giving
both their C++ signature and their syntax in the character interface.
In the character interface commands are given to NeoClassic over a
character stream, and responses are given back on another character stream.
Many character interface functions accept a set as a last argument. This
can either be entered as a sequence of arguments, each of which become
an element of the set, like
(fills role ind1 ind2 ind3 ind4)
or as a single argument, which becomes the set itself, like
(fills role (getInstances C))
In the descriptions below, functions like this are written as follows
(fills role ClassicIndividual...)
The C++ application programming interface to NeoClassic exposes the
object-oriented implementation of NeoClassic, but in a way that does not
(easily) allow subverting the semantics of NeoClassic objects. There is
some functionality that only makes sense using the application programming
interface and thus does not show up in the character interface, and vice
versa.
Many of the character interface function names are provided solely for
compatability with C-Classic. Such names are marked with ``[ccc]''. A few
character interface function names are provided as shorthand, and should
not be used except when typing directly into the character interface. Such
function names are marked with ``[shd]''.
The application programming interface does not print error messages.
Exceptional conditions are signalled through return values. Some functions
return null objects, which indicate some sort of non-knowledge exceptional
condition, such as trying to create a concept when the name is already in
use for another concept in the knowledge base. Knowledge exceptional
conditions are those that would result in an illegal state of affairs in a
knowledge base (including creating an incoherent concept in the knowledge
base, making the knowledge base inconsistent, etc.) are signalled by
returning an incoherent or inconsistent object. Exceptional return values
are prominently indicated below. Note that passing a null object into
another function may generate abnormal behavior, including dumping core.
The character interface does print messages. In particular it checks for
exceptional returns and prints a message explaining the exceptional return.
The character interface also does not continue evaluating a form if a
sub-form produced a null object.
1/ Interface-Visible Classes Provided or Used by NeoClassic
NeoClassic provides or uses a number of C++ classes that are visible in the
two interfaces. In the following list of classes
Sub : Super...
means Sub is a child class of each of the Supers.
Most of the C++ classes provided by NeoClassic are organized under the
class NeoPtrObject.
NeoPtrObject
KnowledgeBase : NeoPtrObject
Description : NeoPtrObject
ThingDescription: Description
ClassicDescription : Description
HostDescription : Description
Construct : Description
ThingConstruct: Construct, ThingDescription
ClassicConstruct : Construct, ClassicDescription
HostConstruct : Construct, HostDescription
IncoherentConstruct : Construct
Role : NeoPtrObject
Concept : Description
ThingConcept : Concept, ThingDescription
ClassicConcept : Concept, ClassicDescription
HostConcept : Concept, HostDescription
Rule : NeoPtrObject
ClassicIndividual : NeoPtrObject
The following C++ classes or enumerations provided or used by NeoClassic
are not (seen to be) subclasses of NeoPtrObject.
String
Symbol
Boolean { false, true }
HostType { negativeInfinity, positiveInfinity,
integerType, floatType, stringType }
TestVal { testFalse, testMaybe, testTrue }
KBSymbol
NeoSet
IndividualSet
ClassicOneOf
HostOneOf
MinOrMax
HostIndividual
IntOrFloat
Primitive
RuleConsequent
ClassicDescriptionConsequent : RuleConsequent
ComputedDescription : RuleConsequent
ComputedFillers : RuleConsequent
ClassicTestGenerate
HostTestGenerate
ComputedDescriptionGenerate
ComputedFillersGenerate
ClassicTestDetail
HostTestDetail
ComputedDescriptionDetail
ComputedFillersDetail
ClassicTest
HostTest
NeoObject
Descriptions of some of the classes above are given here. Descriptions of
the other classes are given later in this document.
class NeoPtrObject
The class NeoPtrObject forms the root of a hierarchy of classes
that are made visible by NeoClassic. It is a ``smart pointer''
class with reference counting. Therefore all subclasses of
NeoPtrObject act as smart pointers, so copies of an object under
NeoPtrObject refer to the same data structure and the storage used
is reclaimed when the last reference to it goes away.
NeoPtrObjects can be compared, just like regular pointers.
There are ``null objects'' possible under NeoPtrObject, i.e.,
objects that do not point to any data. A null object can be
checked for in the usual way (by comparison with 0). Functions
that can return such null objects are prominently indicated.
Boolean NeoPtrObject::isCLASS() const
(isCLASS NeoPtrObject) -> Boolean
For each subclass CLASS of NeoPtrObject there is a Boolean function
that determines whether an object actually is (points to) an
instance of that class.
CLASS NeoPtrObject::DCAST(CLASS) const
Because NeoPtrObject is a smart pointer class, the type of the actual
data structure may be more specific than the declared type of the
object. For each subclass CLASS of NeoPtrObject there is a
conditional ``downcasting'' function that coerces an object of type
NeoPtrObject to an object of (pointer to) the subclass.
[NULL return] If the object does not actually belong to the
subclass, a null object is returned.
class String
class Symbol
These classes provide support for strings of characters and objects
whose value is a string but that can be quickly compared for
equality. Their interface is compatible with the standard
components library.
enum Boolean { false, true }
A type for boolean values.
enum TestVal {testFalse, testMaybe, testTrue}
The values that are returned by test functions.
enum HostType { negativeInfinity=-2, positiveInfinity=-1,
integerType, floatType, stringType }
An enumeration of the types of host individuals.
template class NeoSet
The template class NeoSet implements reference-counted sets. Its
interface is compatible with interface for sets in the standard
components library.
class IndividualSet
An individual set is a set consisting of either classic or host
individuals. It supports all reasonable set operations.
class ClassicOneOf
class HostOneOf
A classic one-of and a host one-of are sets of classic or host
(respectively) individuals that can also be a universal set.
They support all reasonable set operations.
Boolean ClassicOneOf::universe() const
Boolean HostOneOf::universe() const
Determine whether a one-of is a universal set.
NeoSet ClassicOneOf::getElements() const
NeoSet HostOneOf::getElements() const
Return the elements of the one-of, unless it is a universal set, in
which case an empty set is returned.
class RuleConsequent
class ClassicDescriptionConsequent : public RuleConsequent
class ComputedDescription : public RuleConsequent
class ComputedFillers : public RuleConsequent
These classes hold the consequent of a rule.
class ClassicTestGenerate
class HostTestGenerate
class ComputedDescriptionGenerate
class ComputedFillersGenerate
class ClassicTestDetail
class HostTestDetail
class ComputedDescriptionDetail
class ComputedFillersDetail
class ClassicTest
class HostTest
These classes implement user functions.
class NeoObject
NeoObject is a discriminated union of several different kinds of
information, currently including int, float, String, Symbol,
Boolean, IndividualSet, Primitive, NeoPtrObject, and a list of
NeoObjects. There are conversion operators to and from NeoObject
for each of these and also for the subclasses of NeoPtrObject.
NeoSet -> Primitive
NeoClassic provides conditional coercion of String, Symbol, and char* into
Role, Concept, ClassicConcept, HostConcept, Rule, and ClassicIndividual by
look-up in the current knowledge base. If there is no object of the
correct type in the current knowledge base, a null object is returned.
In the Character Interface, more-general classes are conditionally coerced
into more-specific classes. For example, if a function requires a
ClassicDescription, but its argument produces a Description, the Character
Interface will check to see if the result of evaluating the argument is
actually a ClassicDescription, and will use it if so. If the result is not
a ClassicDescription, the Character Interface will report an error.
In the Character Interface, Symbols can be coerced into ClassicTestGenerate,
HostTestGenerate, ComputedDescriptionGenerate, and ComputedFillersGenerate by
looking the symbol up in tables. These tables are populated as a
side-effect of creating objects in ClassicTestGenerate, HostTestGenerate,
ComputedDescriptionGenerate, and ComputedFillersGenerate.
2/ Knowledge Bases
class KnowledgeBase : public NeoPtrObject
A knowledge base is a collection of information that is managed by
NeoClassic. The logic operations of NeoClassic are performed on
knowledge bases or on the major components of knowledge bases.
Every knowledge base starts out with several pre-defined concepts.
Concept Name Definition
Thing Description::and()
ClassicThing Description::and(NeoSet())
HostThing Description::and(NeoSet())
Number Description::testH(numberp)
Integer Description::and(Number,testH(integerp))
Float Description::and(Number,testH(floatp))
String Description::testH(stringp)
a) Managing the Collection of Knowledge Bases
There is a single collection of all knowledge bases, maintained as a
map from symbols to knowledge bases. There is also a current knowledge
base, which is one of the knowledge bases in this collection. The
collection of knowledge bases is initialized to contain a single
knowledge base, which is the current knowledge base, when
NeoEnvironment::init is called.
Knowledge bases only really exist as members of this collection.
Whenever a knowledge base is removed from the collection, all
information is removed from it. The knowledge base should not be
modified or accessed thereafter.
static void KnowledgeBase::reinitCollection()
(reinitCollection)
(reset) [ccc]
Remove all knowledge bases from the collection of knowledge bases
and then intialize as during NeoEnvironment::init.
static KnowledgeBase KnowledgeBase::getCurrent()
(getCurrentKnowledgeBase) -> KnowledgeBase
(getCurrent) -> KnowledgeBase
Return the current knowledge base.
[NULL return] If there is no current knowledge base, return a null
knowledge base.
static KnowledgeBase KnowledgeBase::setCurrent(const Symbol&)
(setCurrentKnowledgeBase Symbol) -> KnowledgeBase
(setCurrent Symbol) -> KnowledgeBase
Set the current knowledge base to the one with the given name and
return it.
[NULL return] If there is no knowledge base with this name, then
don't change the current knowledge base and return a null knowledge
base.
static KnowledgeBase KnowledgeBase::setCurrent(KnowledgeBase)
(setCurrentKnowledgeBase KnowledgeBase) -> KnowledgeBase
(setCurrent KnowledgeBase) -> KnowledgeBase
Set the current knowledge base and return it.
[NULL return] If the argument is null, then don't change the
current knowledge base and return a null knowledge base.
static KnowledgeBase KnowledgeBase::create(const Symbol &)
(createKnowledgeBase Symbol) -> KnowledgeBase
Create and return a new knowledge base with a given name. If the
name is an empty string, generate a new name for the knowledge
base.
[NULL return] If a knowledge base with that name already exists,
then return a null knowledge base.
static KnowledgeBase KnowledgeBase::find (const Symbol&)
(findKnowledgeBase Symbol) -> KnowledgeBase
Find the knowledge base with a given name in the collection of
knowledge bases. If the name is an empty string, return the
current knowledge base instead.
[NULL return] If there is no knowledge base with the name, return a
null knowledge base.
static Boolean KnowledgeBase::remove(const Symbol&)
(removeKnowledgeBase Symbol) -> Boolean
Remove the knowledge base with a given name from the collection of
knowledge bases. If there is no such knowledge base, return false.
If the current knowledge base is deleted, set the current knowledge
base to another knowledge base.
It is impossible to make the knowledge base collection empty with
this function, as another knowledge base will be created in this case.
static Boolean KnowledgeBase::remove(KnowledgeBase)
(removeKnowledgeBase KnowledgeBase) -> Boolean
Remove the given knowledge base from the collection of knowledge
bases. If the knowledge base is null, return false. If the
current knowledge base is deleted, set the current knowledge base
to another knowledge base.
It is impossible to make the knowledge base collection empty with
this function, as another knowledge base will be created in this case.
Symbol KnowledgeBase::getName() const
(getName KnowledgeBase) -> Symbol
(getName) -> Symbol
Return the name of a knowlege base.
The argumentless version of the function in the character interface
returns the name of the current knowledge base.
b) Retrieving built-in concepts
The built-in concepts can be retrieved using these functions. They can
also be retrieved by name.
ThingConcept KnowledgeBase::thing() const
ClassicConcept KnowledgeBase::classicThing() const
HostConcept KnowledgeBase::hostThing() const
HostConcept KnowledgeBase::numberConcept() const
HostConcept KnowledgeBase::integerConcept() const
HostConcept KnowledgeBase::floatConcept() const
HostConcept KnowledgeBase::stringConcept() const
c) Retrieving Information by Name
The information in a knowledge base is maintained in maps from
symbols to several different kinds of information. There is one map
for roles, one for concepts, one for rules, and one for classic
individuals.
Role KnowledgeBase::symbolToRole(const Symbol&)
(symbolToRole Symbol) -> Role
(role Symbol) -> Role [ccc]
Return the role in the knowledge base with a particular name.
The character interface versions uses the current knowledge base.
[NULL return] If there is no such role, return a null role.
Concept KnowledgeBase::symbolToConcept(const Symbol&)
(symbolToConcept Symbol) -> Concept
(concept Symbol) -> Concept [ccc]
Return the concept in the knowledge base with a particular name.
The character interface versions use the current knowledge base.
[NULL return] If there is no such concept, return a null concept.
Concept KnowledgeBase::symbolToClassicConcept(const Symbol&)
(symbolToClassicConcept Symbol) -> ClassicConcept
(classic-concept Symbol) -> ClassicConcept [ccc]
Return the classic concept in the knowledge base with a particular
name.
The character interface versions use the current knowledge base.
[NULL return] If there is no such classic concept, return a null
classic concept.
Concept KnowledgeBase::symbolToHostConcept(const Symbol&)
(symbolToHostConcept Symbol) -> HostConcept
(host-concept Symbol) -> HostConcept [ccc]
Return the host concept in the knowledge base with a particular
name.
The character interface versions use the current knowledge base.
[NULL return] If there is no such host concept, return a null host
concept.
Rule KnowledgeBase::symbolToRule(const Symbol&)
(symbolToRule Symbol) -> Rule
(rule Symbol) -> Rule
Return the rule in the knowledge base with a particular name.
The character interface versions use the current knowledge base.
[NULL return] If there is no such rule, return a null rule.
ClassicIndividual KnowledgeBase::symbolToClassicIndividual(const Symbol&)
(symbolToClassicIndividual Symbol) -> ClassicIndividual
(classic-individual Symbol) -> ClassicIndividual [ccc]
Return the classic individual in the knowledge base with a
particular name.
The character interface versions use the current knowledge base.
[NULL return] If there is no such classic individual, return a null
classic individual.
d) Creating Objects in a Knowledge Base
One way to add information to a knowledge base is to add a new role,
concept, rule, or classic individual to the knowledge base.
Role KnowledgeBase::createRole(const Symbol & name,
const Boolean & attribute = false)
(createRole Symbol [Boolean]) -> Role
(define-role Symbol) -> Role [ccc]
(define-attribute Symbol) -> Role [ccc]
Add a new role with a given name to the knowledge base. If the
name is the empty string, generate a new name for the role. If
attribute is true, the role will be an attribute, i.e., any object
can have at most one filler for it.
The character interface function use the current knowledge base.
The define-attribute version sets the attribute argument to true.
[NULL return] If there already is a role with that name, return a
null role.
ClassicConcept KnowledgeBase::createConcept(const Symbol& name,
const ClassicDescription& defntn,
const Primitive & primitive=false)
ClassicConcept KnowledgeBase::createConcept(const Symbol& name,
const ClassicDescription& defntn,
const Boolean & primitive)
ClassicConcept KnowledgeBase::createConcept(const Symbol & name,
const ClassicDescription& defntn,
const NeoSet & primitive)
(createConcept Symbol ClassicDescription [Boolean]) -> ClassicConcept
(createConcept Symbol ClassicDescription Symbol...) -> ClassicConcept
(define-concept Symbol ClassicDescription) -> ClassicConcept [ccc]
(define-primitive Symbol ClassicDescription) -> ClassicConcept [ccc]
(define-disjoint-primitive Symbol ClassicDescription Symbol...) ->
ClassicConcept [ccc]
Add a new classic concept with a given name, given definition, and
given primitive information to the knowledge base. If the
primitive information is not specified, create a defined concept.
If the name is the empty string, generate a new name for the
concept.
The character interface versions use the current knowledge base.
The define-primitive version sets the primitive argument to true.
[NULL return] If there already is a concept with that name, return
a null classic concept.
[INCOHERENT return] If the concept is incoherent, do not add it to
the knowledge base.
HostConcept KnowledgeBase::createConcept(const Symbol & name,
const HostDescription& definition)
(createConcept Symbol HostDescription) -> HostConcept
(define-concept Symbol HostDescription) -> HostConcept [ccc]
Add a new host concept with a given name and given definition to
the knowledge base. If the name is the empty string, generate a
new name for the concept.
The character interface versions use the current knowledge base.
[NULL return] If there already is a concept with that name, return
a null host concept.
[INCOHERENT return] If the concept is incoherent, do not add it to
the knowledge base.
Rule KnowledgeBase::createRule(const Symbol& name,
const ClassicConcept& antecedent,
const ClassicDescription& consequent)
Rule KnowledgeBase::createRule(const Symbol& name,
const ClassicConcept& antecedent,
const RuleConsequent& consequent)
(createRule Symbol ClassicConcept ClassicDescription) -> Rule
(define-rule Symbol ClassicConcept ClassicDescription) -> Rule [ccc]
(createRule Symbol ClassicConcept RuleConsequent) -> Rule
(define-rule Symbol ClassicConcept RuleConsequent) -> Rule [ccc]
Add a new rule with a given name and given antecedent and
consequent to the knowledge base. If the name is the empty string,
generate a new name for the rule. Run the rule on all instances of the
antecedent.
The character interface versions use the current knowledge base.
[NULL return] If there already is a rule with that name, return a
null rule.
[INCONSISTENT return] If running the rule on instances of the
antecedent results in an inconsistent knowledge base, do not change
the knowledge base. In this case return an inconsistent rule that
contains the relevant state of the knowledge base that would have
resulted if the rule had been added.
ClassicIndividual KnowledgeBase::createIndividual(const Symbol& name)
ClassicIndividual KnowledgeBase::createIndividual(const Symbol& name,
const ClassicDescription&)
(createIndividual Symbol) -> ClassicIndividual
(define-individual Symbol) -> ClassicIndividual [ccc]
(createIndividual Symbol ClassicDescription) -> ClassicIndividual
(define-individual Symbol ClassicDescription) -> ClassicIndividual [ccc]
Add a new classic individual with a given name and given definition
to the knowledge base. If the name is the empty string, generate a
new name for the classic individual. If no definition is provided,
use ClassicThing.
The character interface versions use the current knowledge base.
[NULL return] If there already is a classic individual with that
name, return a null classic individual.
[INCONSISTENT return] If adding the classic individual makes the
knowledge base inconsistent, do not change the knowledge base. In
this case return an inconsistent classic individual that contains
the relevant state of the knowledge base that would have resulted
if the classic individual had been added.
e) Writing a Knowledge Base to a file
void KnowledgeBase::write(ostream &os) const
(writeKnowledgeBase String)
(writeKnowledgeBase KnowledgeBase String)
Write the information in the current or specified Knowledge Base to a
stream or to the file with the given name. The file can be read using
loadFile, but should NOT be modified as it may contain some internal
NeoClassic function calls that can produce corrupted knowledge bases if
not used correctly.
3/ Descriptions
class Description : public NeoPtrObject
Descriptions encode most of the actual information in NeoClassic.
Descriptions are divided into subclasses in several ways.
a) Subclasses of Descriptions
First, descriptions are divided into realms, that is those descriptions
that can describe any object in a domain, those descriptions that can
only describe the classic objects in a domain, and those descriptions
that can only describe the host objects in a domain.
class ThingDescription: public virtual Description
class ClassicDescription : public virtual Description
class HostDescription : public virtual Description
Second, descriptions are divided between concepts, that is named
descriptions in a knowledge base; and constructs, that is constructed
descriptions. The distinction between concepts and constructs is not
very important, and Construct is only mentioned because some functions
return Constructs. User code should just cast these Constructs into
Descriptions.
class Construct : public virtual Description
class Concept : public virtual Description
Constructs and Concepts are likewise both divided into realms.
class ThingConstruct : public Construct, ThingDescription
class ClassicConstruct : public Construct, ClassicDescription
class HostConstruct : public Construct, HostDescription
class IncoherentConstruct : public Construct
class ThingConcept : public Concept, ThingDescription
class ClassicConcept : public Concept, ClassicDescription
class HostConcept : public Concept, HostDescription
b) Creating Constructed Descriptions
Constructed Descriptions (Constructs) are created by means of various
functions, one for each of the constructors defined in the description
logic underlying NeoClassic.
static ThingDescription Description::and()
(and) -> ThingDescription
static Description Description::and(const NeoSet&)
(and Description...) -> Description
These two constructors can also return a Concept, so their return
type is Description.
static Construct Description::oneOf(const IndividualSet&)
(oneOf) -> Construct
(one-of) -> Construct [ccc]
static ClassicDescription Description::and(const NeoSet&)
static ClassicConstruct Description::oneOf(const NeoSet&)
(oneOf ClassicIndividual...) -> ClassicConstruct
(one-of ClassicIndividual...) -> ClassicConstruct [ccc]
(oneOf Symbol...) -> ClassicConstruct
(one-of Symbol...) -> ClassicConstruct [ccc]
static ClassicConstruct Description::atLeast(unsigned int min, const Role&)
(atLeast unsigned_int Role) -> ClassicConstruct
(at-least unsigned_int Role) -> ClassicConstruct [ccc]
static ClassicConstruct Description::atMost(unsigned int max, const Role&)
(atMost unsigned_int Role) -> ClassicConstruct
(at-most unsigned_int Role) -> ClassicConstruct [ccc]
static ClassicConstruct Description::fills(const Role&,const IndividualSet&)
(fills Role ClassicIndividual...) -> ClassicConstruct
(fills Role Symbol...) -> ClassicConstruct
(fills Role HostIndividual...) -> ClassicConstruct
static ClassicConstruct Description::all(const Role&, const Description&)
(all Role Description) -> ClassicConstruct
static ClassicConstruct Description::testC(const ClassicTestGenerate * prot,
const List& parameters = List())
(testC ClassicTestGenerate [NeoObject...]) -> ClassicConstruct
(test-c ClassicTestGenerate [NeoObject...]) -> ClassicConstruct [ccc]
static HostDescription Description::and(const NeoSet&)
static HostConstruct Description::oneOf(const NeoSet&)
(oneOf HostIndividual...) -> HostConstruct
(one-of HostIndividual...) -> HostConstruct [ccc]
static HostConstruct Description::minimum(const IntOrFloat& min)
(minimum IntOrFloat) -> HostConstruct
(lower-limit IntOrFloat) -> HostConstruct [ccc]
static HostConstruct Description::maximum(const IntOrFloat& max)
(maximum IntOrFloat) -> HostConstruct
(upper-limit IntOrFloat) -> HostConstruct [ccc]
static HostConstruct Description::testH(const HostTestGenerate * proto,
const List& parameters = List())
(testH HostTestGenerate [NeoObject...]) -> ClassicConstruct
(test-h HostTestGenerate [NeoObject...]) -> ClassicConstruct [ccc]
c) Queries
Boolean Description::incoherent() const
(incoherent Description) -> Boolean
Determine whether a description is incoherent.
Boolean Description::subsumes(const Description&) const
(subsumes Description Description) -> Boolean
(subsumes? Description Description) -> Boolean [ccc]
Boolean Description::subsumes(const ClassicIndividual&) const
(subsumes Description ClassicIndividual) -> Boolean
(subsumes? Description ClassicIndividual) -> Boolean [ccc]
Boolean Description::subsumes(const HostIndividual&) const
(subsumes Description HostIndividual) -> Boolean
(subsumes? Description HostIndividual) -> Boolean [ccc]
Determine whether one description subsumes another, or a classic or
host individual.
d) Told Retrievals
The following functions retrieve various information that was TOLD about
the description. In several cases there are two versions of a function,
one that returns a set of the told information and one that returns this
told information combined into one piece.
NeoSet ClassicDescription::toldParents() const
(toldParents ClassicDescription) -> NeoSet
(concept-told-parents ClassicDescription) -> NeoSet [ccc]
NeoSet ClassicDescription::toldAtLeasts(const Role&) const
(toldAtLeasts ClassicDescription Role) -> NeoSet
unsigned int ClassicDescription::toldAtLeast(const Role &) const
(toldAtLeast ClassicDescription Role) -> unsigned int
NeoSet ClassicDescription::toldAtMosts(const Role&) const
(toldAtMosts ClassicDescription Role) -> NeoSet
unsigned int ClassicDescription::toldAtMost(const Role&) const
(toldAtMost ClassicDescription Role) -> unsigned int
IndividualSet ClassicDescription::toldFillers(const Role&) const
(toldFillers ClassicDescription Role) -> IndividualSet
NeoSet
ClassicDescription::toldValueDescriptions(const Role&) const
(toldValueDescriptions ClassicDescription Role)-> NeoSet
Description ClassicDescription::toldValueDescription(const Role &) const
(toldValueDescription ClassicDescription Role) -> Description
NeoSet> ClassicDescription::toldOneOfs() const
(toldOneOfs ClassicDescription) -> NeoSet>
ClassicOneOf ClassicDescription::toldOneOf() const
(toldOneOf ClassicDescription) -> ClassicOneOf
(concept-told-one-of ClassicDescription) -> ClassicOneOf [ccc]
NeoSet ClassicDescription::toldTests() const
(toldTests ClassicDescription) -> NeoSet
(concept-told-tests ClassicDescription) -> NeoSet [ccc]
NeoSet HostDescription::toldParents() const
(toldParents HostDescription) -> NeoSet
(concept-told-parents HostDescription) -> NeoSet [ccc]
NeoSet> HostDescription::toldOneOfs() const
(toldOneOfs HostDescription) -> NeoSet>
HostOneOf HostDescription::toldOneOf() const
(toldOneOf HostDescription) -> HostOneOf
(concept-told-one-of HostDescription) -> HostOneOf [ccc]
NeoSet HostDescription::toldMinimums() const
(toldMinimums HostDescription) -> NeoSet
MinOrMax HostDescription::toldMinimum() const
(toldMinimum HostDescription) -> MinOrMax
NeoSet HostDescription::toldMaximums() const
(toldMaximums HostDescription) -> NeoSet
MinOrMax HostDescription::toldMaximum() const
(toldMaximum HostDescription) -> MinOrMax
NeoSet HostDescription::toldTests() const
(toldTests HostDescription) -> NeoSet
(concept-told-tests HostDescription) -> NeoSet [ccc]
e) Derived Retrievals
The following functions retrieve various information that was DERIVED
about the description, that is a combination of the told information plus
any information that could be inferred.
NeoSet ClassicDescription::derivedPrimitives() const
(derivedPrimitives ClassicDescription) -> NeoSet
unsigned int ClassicDescription::derivedAtLeast(const Role &) const
(derivedAtLeast ClassicDescription Role) -> unsigned int
(concept-role-description-min ClassicDescription Role) -> unsigned int [ccc]
unsigned int ClassicDescription::derivedAtMost(const Role &) const
(derivedAtMost ClassicDescription Role) -> unsigned int
(concept-role-description-max ClassicDescription Role) -> unsigned int [ccc]
IndividualSet ClassicDescription::derivedFillers(const Role &) const
(derivedFillers ClassicDescription Role) -> IndividualSet
(concept-role-fillers ClassicDescription Role) -> IndividualSet [ccc]
Description ClassicDescription::derivedValueDescription(const Role &) const
(derivedValueDescription ClassicDescription Role) -> Description
(concept-role-description-value ClassicDescription Role) -> Description [ccc]
ClassicOneOf ClassicDescription::derivedOneOf() const
(derivedOneOf ClassicDescription) -> ClassicOneOf
(concept-one-of ClassicDescription) -> ClassicOneOf [ccc]
NeoSet ClassicDescription::derivedTests() const
(derivedTests ClassicDescription) -> NeoSet
(concept-tests ClassicDescription) -> NeoSet [ccc]
Boolean ClassicDescription::derivedFullRole() const
(derivedFullRole ClassicDescription Role) -> Boolean
A role is full on an individual or concept if it has as many
fillers on the role as its atMost description on the role. Note
that this is different from the role being closed. (A closed role
is full, but a role may be full without having been closed.)
HostOneOf HostDescription::derivedOneOf() const
(derivedOneOf HostDescription) -> HostOneOf
(concept-one-of HostDescription) -> HostOneOf [ccc]
MinOrMax HostDescription::derivedMinimum() const
(derivedMinimum HostDescription) -> MinOrMax
MinOrMax HostDescription::derivedMaximum() const
(derivedMaximum HostDescription) -> MinOrMax
NeoSet HostDescription::derivedTests() const
(derivedTests HostDescription) -> NeoSet
(concept-tests HostDescription) -> NeoSet [ccc]
4/ Named Objects
The classes Role, Concept, Rule, and ClassicIndividual share
functionality having to do with their position in a knowledge base.
For various reasons there is no C++ class for named objects.
Role::Role(const Symbol & name)
Role::Role(const String & name)
Role::Role(const char* name)
Concept::Concept(const Symbol & name)
Concept::Concept(const String & name)
Concept::Concept(const char* name)
ClassicConcept::ClassicConcept(const Symbol & name)
ClassicConcept::ClassicConcept(const String & name)
ClassicConcept::ClassicConcept(const char* name)
HostConcept::HostConcept(const Symbol & name)
HostConcept::HostConcept(const String & name)
HostConcept::HostConcept(const char* name)
Rule::Rule(const Symbol & name)
Rule::Rule(const String & name)
Rule::Rule(const char* name)
ClassicIndividual::ClassicIndividual(const Symbol & name)
ClassicIndividual::ClassicIndividual(const String & name)
ClassicIndividual::ClassicIndividual(const char* name)
Return the role, concept, classic concept, host concept, rule, or
classic individual with the given name in the current knowledge
base.
[NULL return] If such a role, concept, classic concept, host
concept, rule, or classic individual does not exist; return a null
role, concept, classic concept, host concept, rule, or classic
individual, as appropriate.
KnowledgeBase Role::getKnowledgeBase() const
(getKnowledgeBase Role) -> KnowledgeBase
(getKB Role) -> KnowledgeBase [shd]
KnowledgeBase Concept::getKnowledgeBase() const
(getKnowledgeBase Concept) -> KnowledgeBase
(getKB Concept) -> KnowledgeBase [shd]
KnowledgeBase Rule::getKnowledgeBase() const
(getKnowledgeBase Rule) -> KnowledgeBase
(getKB Rule) -> KnowledgeBase [shd]
KnowledgeBase ClassicIndividual::getKnowledgeBase() const
(getKnowledgeBase ClassicIndividual) -> KnowledgeBase
(getKB ClassicIndividual) -> KnowledgeBase [shd]
Return the knowledge base that the object belongs to.
[NULL return] If the object does not belong to a knowledge base, a
null knowledge base is returned. This should only happen for
incoherent or inconsistent objects or objects that have been
``destroyed'' by being removed from their knowledge base or by
having their knowledge base destroyed.
Symbol Role::getName() const
(getName Role) -> Symbol
Symbol Concept::getName() const
(getName Concept) -> Symbol
Symbol Rule::getName() const
(getName Rule) -> Symbol
String ClassicIndividual::getName() const
(getName ClassicIndividual) -> Symbol
Return the name of the object.
void Role::setComment(String)
(setComment Role String)
(set-descriptor Role String) [ccc]
void Concept::setComment(String)
(setComment Concept String)
(set-descriptor Concept String) [ccc]
void Rule::setComment(String)
(setComment Rule String)
(set-descriptor Rule String) [ccc]
void ClassicIndividual::setComment(String)
(setComment ClassicIndividual String)
(set-descriptor ClassicIndividual String) [ccc]
Set the comment field of the object. The comment field is not used
by NeoClassic.
String Role::getComment() const
(getComment Role) -> String
(descriptor Role) -> String [ccc]
String Concept::getComment() const
(getComment Concept) -> String
(descriptor Concept) -> String [ccc]
String Rule::getComment() const
(getComment Rule) -> String
(descriptor Rule) -> String [ccc]
String ClassicIndividual::getComment() const
(getComment ClassicIndividual) -> String
(descriptor ClassicIndividual) -> String [ccc]
Return the comment field of the object
void Role::setUserData(void *)
void Concept::setUserData(void *)
void Rule::setUserData(void *)
void ClassicIndividual::setUserData(void *)
Set the user-data field of the object. The user-data field is not
used by NeoClassic.
void * Role::getUserData()
void * Concept::getUserData()
void * Rule::getUserData()
void * ClassicIndividual::getUserData()
Return the user-data field of the object
5/ Roles
class Role : public NeoPtrObject
A role represents a relationship from classic objects in a domain to
objects in a domain.
Boolean Role::isAttribute() const
(isAttribute Role) -> Boolean
(attribute? Role) -> Boolean [ccc]
Return whether this role is an attribute.
6/ Concepts
class Concept : public Description
class ThingConcept : public Concept, ThingDescription
class ClassicConcept : public Concept, ClassicDescription
class HostConcept : public Concept, HostDescription
A concept represents a subset of a domain. As mentioned above,
concepts are divided into realms. Thing concepts represent the entire
domain; a classic concept represents a subset of the classic portion of
a domain; a host concept represents a subset of the host portion
of a domain.
a) Primitives
class Primitive
Primitives provide extra information when defining classic concepts. A
defined or non-primitive classic concept represents precisely the
representation of the description that is used to define it. A
primitive classic concept represents some undefined subset of
this description. A disjoint-primitive classic concept is further
disjoint from all other disjoint-primitive classic concepts that mention
any element of disjointness tags.
Primitive::Primitive()
Non-primitive.
Primitive::Primitive(Boolean)
Coerce a boolean into a primitive. True becomes primitive, false
becomes defined or non-primitive.
Primitive::Primitive(NeoSet & disjoint)
Create a disjoint primitive with the given disjointness tags.
operator Primitive::Boolean() const
Return whether the primitive is really primitive.
const NeoSet & Primitive::getDisjoint() const
Return the set of disjointness tags.
b) Simple Retrievals
const Description& Concept::getDescription () const
(getDescription Concept) -> Description
Return the description that was used to define the concept.
Primitive Concept::getPrimitive() const
(getPrimitive Concept) -> Primitive
Return the primitive information that was used to define the
concept. Host concepts are, by definition, never primitive, so the
equivalent of ``not primitive'' is returned for them.
Boolean Concept::isPrimitive() const
(isPrimitive Concept) -> Boolean
Return whether this concept is primitive. Host concepts are, by
definition, never primitive, so false is returned for them.
const ClassicDescription& ClassicConcept::getDefinition() const
(getDefinition ClassicConcept) -> ClassicDescription
Return the classic description that was used to define the concept.
const HostDescription& HostConcept::getDefinition() const
(getDefinition HostConcept) -> HostDescription
Return the host description that was used to define the concept.
const NeoSet& ClassicConcept::getRules () const
(getRules ClassicConcept) -> NeoSet
(concept-rules ClassicConcept) -> NeoSet [ccc]
Return the rules that are defined on this concept. Rules can only
be defined on classic concepts, so host concepts will return an
empty set.
c) Taxonomy Retrievals
NeoSet ClassicConcept::getParents () const
(getParents ClassicConcept) -> NeoSet
(concept-parents ClassicConcept) -> NeoSet [ccc]
Return the minimal elements of the set of classic concepts in the
knowledge base that subsume the concept.
NeoSet ClassicConcept::getAncestors () const
(getAncestors ClassicConcept) -> NeoSet
(concept-ancestors ClassicConcept) -> NeoSet [ccc]
Return the maximal elements of the set of classic concepts in the
knowledge base that subsume the concept.
NeoSet ClassicConcept::getChildren () const
(getChildren ClassicConcept) -> NeoSet
(concept-children ClassicConcept) -> NeoSet [ccc]
Return the minimal elements of the set of classic concepts in the
knowledge base that are subsumed by the concept.
NeoSet ClassicConcept::getDescendants () const
(getDescendants ClassicConcept) -> NeoSet
(concept-descendants ClassicConcept) -> NeoSet [ccc]
Return the maximal elements of the set of classic concepts in the
knowledge base that are subsumed by the concept.
NeoSet ClassicConcept::getEquivalents () const
(getEquivalents ClassicConcept) -> NeoSet
Return the set of classic concepts in the knowledge base that are
equivalent to the concept (including the concept itself).
const NeoSet& ClassicConcept::getDirectInstances() const
(getDirectInstances ClassicConcept)
(concept-direct-instances ClassicConcept) [ccc]
Return the classic individuals in the knowledge base that are
instances of the concept but not instances of any of its children.
NeoSet ClassicConcept::getInstances() const
(getInstances ClassicConcept)
(concept-instances ClassicConcept) [ccc]
Return the classic individuals in the knowledge base that are
instances of the concept (including instances of any of its
desendants).
*NOTE*: This function may construct and return a large set.
NeoSet HostConcept::getParents() const
(getParents HostConcept) -> NeoSet
(concept-parents HostConcept) -> NeoSet [ccc]
Return the minimal elements of the set of host concepts in the
knowledge base that subsume the concept.
NeoSet HostConcept::getAncestors () const
(getAncestors HostConcept) -> NeoSet
(concept-ancestors HostConcept) -> NeoSet [ccc]
Return the maximal elements of the set of host concepts in the
knowledge base that subsume the concept.
NeoSet HostConcept::getChildren() const
(getChildren HostConcept) -> NeoSet
Return the maximal elements of the set of host concepts in the
knowledge base that are subsumed by the concept.
NeoSet HostConcept::getDescendants () const
(getDescendants HostConcept) -> NeoSet
(concept-descendants HostConcept) -> NeoSet [ccc]
Return the maximal elements of the set of host concepts in the
knowledge base that are subsumed by the concept.
NeoSet HostConcept::getEquivalents () const
(getEquivalents HostConcept) -> NeoSet
Return the set of host concepts in the knowledge base that are
equivalent to the concept (including the concept itself).
7/ Rules
Rules represent simple forward-chaining rules that run only on named
classic individuals in a domain.
class Rule : public Description
a) Simple Retrievals
const ClassicConcept& Rule::getAntecedent() const
(getAntecedent Rule) -> ClassicConcept
(rule-antecedent Rule) -> ClassicConcept [ccc]
Return the antecedent of the rule.
const RuleConsequent& Rule::getConsequent() const
(getConsequent Rule) -> RuleConsequent
(rule-consequent Rule) -> RuleConsequent [ccc]
Return the consequent of the rule.
b) Queries
Boolean Rule::inconsistent() const
(inconsistent Rule) -> Boolean
Return whether a rule is inconsistent. Inconsistent rules are
never actually part of a knowledge base, but are instead used to
represent relevant portions of the knowledge base that would have
resulted from operations that would have made the knowledge base
inconsistent.
const ClassicIndividual & Rule::getInconsistent() const
(getInconsistent Rule) -> ClassicIndividual
Return the classic individual where the inconsistency on a rule was
discovered. This is only well-defined if the rule is inconsistent.
c) Rule Consequents
class RuleConsequent
class ClassicDescriptionConsequent : public RuleConsequent
class ComputedDescription : public RuleConsequent
class ComputedFillers : public RuleConsequent
The consequent of a rule can either be a classic description or the
result of a user rule function.
static ClassicDescriptionConsequent
ClassicDescriptionConsequent::create(const ClassicDescription& r)
Create a rule consequent from a classic description.
static ComputedDescription
ComputedDescription::create(const ComputedDescriptionGenerate * dtl,
const List & params)
(computedDescription ComputedDescriptionGenerate [NeoObject...])
(computed-concept ComputedDescriptionGenerate [NeoObject...]) [ccc]
static ComputedFillers
ComputedFillers::create(const ComputedFillersGenerate * dtl,
const List & params)
(computedFillers ComputedFillersGenerate [NeoObject...])
(computed-fillers ComputedFillersGenerate [NeoObject...]) [ccc]
Create a rule consequent from a user rule function and a list of
parameters.
8/ Classic Individuals
class ClassicIndividual : public NeoPtrObject
Classic individuals represent classic objects in a domain.
a) Simple Retrievals
const ClassicDescription& ClassicIndividual::getDefinition() const
(getDefinition ClassicIndividual) -> ClassicDescription
(individual-descriptor ClassicIndividual) -> ClassicDescription [ccc]
Return the current definition of the classic individual.
b) Adding and Removing Information from Classic Individuals
Another way of modifying the information in a knowledge base is by
adding and removing information from the classic individuals in the
knowledge base.
[INCONSISTENT return] If any of these operations would make the
knowledge base inconsistent, the operation is not performed. Instead
an inconsistent classic individual is returned. This classic
individual contains the relevant inconsistent state of the knowledge
base that would have resulted from performing the operation.
ClassicIndividual ClassicIndividual::addToldInformation
(const ClassicDescription&)
(addToldInformation ClassicIndividual ClassicDescription) -> ClassicIndividual
(individual-add ClassicIndividual ClassicDescription) -> ClassicIndividual
[ccc]
Add information to a classic individual.
ClassicIndividual ClassicIndividual::removeToldInformation
(const ClassicDescription&)
(removeToldInformation ClassicIndividual ClassicDescription)
-> ClassicIndividual
(individual-remove ClassicIndividual ClassicDescription) -> ClassicIndividual
[ccc]
Remove previously told information from a classic individual. If
information being removed is not on the individual, do nothing.
ClassicIndividual ClassicIndividual::closeRole(const Role&)
(closeRole ClassicIndividual Role) -> ClassicIndividual
(individual-close-role ClassicIndividual Role) -> ClassicIndividual [ccc]
Close a role on a classic individual. Note that it is not an error
to close a role twice. Also, closing a role with fewer known
fillers than the mininum derived number of fillers for that role
will result in an inconsistent object.
ClassicIndividual ClassicIndividual::uncloseRole(const Role&)
(uncloseRole ClassicIndividual Role) -> ClassicIndividual
(individual-unclose-role ClassicIndividual Role)->ClassicIndividual [ccc]
Unclose a previously-closed role on a classic individual. Note
that it is not an error to unclose a role that was not closed.
c) Queries
Boolean ClassicIndividual::inconsistent() const
(inconsistent ClassicIndividual) -> Boolean
Return whether a classic individual is inconsistent. Inconsistent
individuals are never actually part of a knowledge base, but are
instead used to represent relevant portions of the knowledge base
that would have resulted from operations that would have made the
knowledge base inconsistent.
d) Taxonomy Retrieval
NeoSet ClassicIndividual::getParents () const
(getParents ClassicIndividual) -> NeoSet
(individual-parents ClassicIndividual) -> NeoSet [ccc]
Return the minimal elements of the set of classic concepts in the
knowledge base of the individual that have the individual as an
instance.
e) Told Retrievals
The following functions retrieve various information that was TOLD
about the individual. In several cases there are two versions of
a function, one that returns a set of the told information and one
that returns this told information combined into one piece.
NeoSet ClassicIndividual::toldParents() const
(toldParents ClassicIndividual) -> NeoSet
(individual-told-parents ClassicIndividual) -> NeoSet [ccc]
NeoSet ClassicIndividual::toldAtLeasts(const Role &) const
(toldAtLeasts ClassicIndividual Role) -> NeoSet
unsigned int ClassicIndividual::toldAtLeast(const Role &) const
(toldAtLeast ClassicIndividual Role) -> unsigned int
NeoSet ClassicIndividual::toldAtMosts(const Role &) const
(toldAtMosts ClassicIndividual Role) -> NeoSet
unsigned int ClassicIndividual::toldAtMost(const Role &) const
(toldAtMost ClassicIndividual Role) -> unsigned int
IndividualSet ClassicIndividual::toldFillers(const Role &) const
(toldFillers ClassicIndividual Role) -> IndividualSet
NeoSet ClassicIndividual::toldValueDescriptions(const Role&)const
(toldValueDescriptions ClassicIndividual Role)-> NeoSet
Description ClassicIndividual::toldValueDescription(const Role &) const
(toldValueDescription ClassicIndividual Role) -> Description
NeoSet> ClassicIndividual::toldOneOfs() const
(toldOneOfs ClassicIndividual) -> NeoSet>
ClassicOneOf ClassicIndividual::toldOneOf() const
(toldOneOf ClassicIndividual) -> ClassicOneOf
NeoSet ClassicIndividual::toldTests() const
(toldTests ClassicIndividual) -> NeoSet
(individual-told-tests ClassicIndividual) -> NeoSet [ccc]
Boolean ClassicIndividal::roleClosed(const Role &) const
(roleClosed ClassicIndividual Role) -> Boolean
(individual-closed-role? ClassicIndividual Role) -> Boolean [ccc]
Individuals can also have their role closed. The previous
function determines whether a particular role was closed on the
individual. Note that this is different from having a full role.
f) Derived Retrievals
The following functions retrieve various information that was
DERIVED about the individual, that is a combination of the told
information plus any information that could be inferred.
NeoSet ClassicIndividual::derivedPrimitives() const
(derivedPrimitives ClassicIndividual) -> NeoSet
unsigned int ClassicIndividual::derivedAtLeast(const Role &) const
(derivedAtLeast ClassicIndividual Role) -> unsigned int
(individual-role-description-min ClassicIndividual Role) -> unsigned int [ccc]
unsigned int ClassicIndividual::derivedAtMost(const Role &) const
(derivedAtMost ClassicIndividual Role) -> unsigned int
(individual-role-description-max ClassicIndividual Role) -> unsigned int [ccc]
IndividualSet ClassicIndividual::derivedFillers(const Role &) const
(derivedFillers ClassicIndividual Role) -> IndividualSet
(individual-role-fillers ClassicIndividual Role) -> IndividualSet [ccc]
Description ClassicIndividual::derivedValueDescription(const Role &) const
(derivedValueDescription ClassicIndividual Role) -> Description
(individual-role-description-value ClassicIndividual Role)-> Description [ccc]
ClassicOneOf ClassicIndividual::derivedOneOf() const
(derivedOneOf ClassicIndividual) -> ClassicOneOf
NeoSet ClassicIndividual::derivedTests() const
(derivedTests ClassicIndividual) -> NeoSet
(individual-tests ClassicIndividual) -> NeoSet [ccc]
Boolean ClassicIndividual::derivedFullRole() const
(derivedFullRole ClassicIndividual Role) -> Boolean
9/ Host Individuals and related classes
The class HostIndividual is used to represent host programming elements of
the domain. The classes MinOrMax and IntOrFloat are used internally by
NeoClassic, but are also visible in the C++ application programming
interface. All three classes share a common implementation, so they are
discussed together here.
class MinOrMax
A class used to hold an integer or real number, or positive or
negative infinity. (Actually MinOrMax can also hold a String,
because it is a superclass of HostIndividual, but this is never
used.)
MinOrMax::MinOrMax(int value)
MinOrMax::MinOrMax(float value)
static MinOrMax::infiniteMinimum()
static MinOrMax::infiniteMaximum()
Create a value of class MinOrMax.
HostType MinOrMax::getType() const
Return the type of value stored in a MinOrMax
operator MinOrMax::int() const
operator MinOrMax::float() const
Coerce a MinOrMax value into an int or float. If the value in the
MinOrMax is not of the appropriate type, some "neutral" value is
returned.
Boolean MinOrMax::isInfinity() const
Return whether the MinOrMax is an infinite value
class HostIndividual : public MinOrMax
Host individuals represent elements of the domain taken from the host
programming language. Currently these elements must be strings,
integers, or real numbers. Host individuals that are not strings can
be compared as numbers.
HostIndividual::HostIndividual(int value)
HostIndividual::HostIndividual(float value)
HostIndividual::HostIndividual(const String& value)
Create a value of class HostIndividual.
HostType HostIndividual::getType() const
Return the type of the host individual.
operator HostIndividual::int() const
operator HostIndividual::float() const
operator HostIndividual::String() const
Coerce a host individual back to an int, float, or string. If the
host individual is not of an appropriate type, some "neutral" value
is returned.
class IntOrFloat : public HostIndividual
A class used to hold an integer or real number.
IntOrFloat::IntOrFloat(int value)
IntOrFloat::IntOrFloat(float value)
Create a value of class IntOrFloat
HostType IntOrFloat::getType() const
Return the type of the IntOrFloat.
operator IntOrFloat::int() const
operator IntOrFloat::float() const
Coerce an IntOrFloat back to an integer or real number. If the
IntOrFloat is not of an appropriate type, some "neutral" value is
returned.
10/ User Functions
class ClassicTestGenerate
class HostTestGenerate
class ComputedDescriptionGenerate
class ComputedFillersGenerate
class ClassicTestDetail
class HostTestDetail
class ComputedDescriptionDetail
class ComputedFillersDetail
class ClassicTest
class HostTest
Note: Most of these classes are actually template instantiations,
but this implementation detail does not affect their use.
User Functions are C++ functions that are called at appropriate places
within NeoClassic, and are used to extend the functionality of
NeoClassic. There are two kinds of user functions: test functions, which
extend descriptions; and rule functions, which extend rules.
Each kind of user function is actually a subclass of ClassicTestDetail,
HostTestDetail, ComputedDescriptionDetail, or ComputedFillersDetail.
Creating a user function involves calling the create member function of a
subclass of ClassicTestGenerate, HostTestGenerate,
ComputedDescriptionGenerate, or ComputedFillersGenerate. The creation
function takes a collection of parameters, which are stored in the new
instance of a subclass of ClassicTestDetail, HostTestDetail,
ComputedDescriptionDetail, or ComputedFillersDetail. Running the user
function involves calling the run member function of this new instance.
This member function can access the information retained in the instance.
The different user functions have different behavior, based on where the
object they are embedded in is placed in NeoClassic.
ClassicTestDetail and HostTestDetail are placed in descriptions created
by testC and testH, respectively. Their run functions are responsible
for determinining whether a classic or host individual is known to belong
to the test description, in which case the function returns testTrue;
whether the individual is known not to belong to the description, in
which case it returns testFalse; or whether the individual is neither
known to belong nor not known to belong, in which case it returns
testMaybe. Once a ClassicTestDetail or HostTestDetail is placed in a
description, it is no longer directly accessible but its data can be
retrieved in the application programming interface via the ClassicTest
and HostTest classes that are returned from the toldTests and
derivedTests functions.
const Symbol & ClassicTest::getName() const
const Symbol & HostTest::getName() const
Return the name of a test.
List ClassicTest::getArguments() const
List HostTest::getArguments() const
Return the arguments for a test.
ComputedDescriptionDetail and ComputedFillersDetail are placed in the
consequent of rules. They are responsible for determining the
description to be added to a classic individual as a result of running
the rule. The run function for ComputedDescriptionDetail returns this
classic description directly, whereas the run function for
ComputedFillersDetail returns an IndividualSet that is added to the
fillers of a role on the individual. This role is the role that was
specified as the first parameter for the ComputedFillersDetail.
The character interface creates user functions by means of tables that map
symbols into user function prototype. These prototypes are instances of
the ...Generate classes, and are responsible for checking if the
parameters supplied are appropriate, for creating new user functions, and
for generating usage messages.
There are four built-in user functions that can be used in the
character interface without doing any C++ programming. They are all
HostTestGenerate functions that are used to create host test
descriptions.
Character Interface Name Description
numberp is a host individual a number?
integerp is a host individual an integer?
floatp is a host individual a float?
stringp is a host individual a string?
Most of the work of defining kinds of user functions is done by macros
and templates. The only function that has to be written by users is the
run function.
Consider this example:
ClassicTestFunction2(AtLeastTest,atLeast,unsigned int,Role);
TestVal AtLeastTest::run(const ClassicIndividual& ind,
Set *,
Set *) const {
ClassicIndividualDescription def = ind.getDefinition();
unsigned int indmin = def.derivedAtLeast(arg2);
unsigned int indmax = def.derivedAtMost(arg2);
if (indmin >= arg1) {
return testTrue;
} else if (indmax < arg1) {
return testFalse;
} else {
return testMaybe;
}
}
The macro ClassicTestFunction2 creates a subclass of ClassicTestDetail,
AtLeastTest. This subclass has a data member called arg1 with type
unsigned int and a data member called arg2 with type Role.
The macro also creates a prototype object that is an instance of (a
subclass of) ClassicTestGenerate. The prototype ensures that a creation
of an AtLeastTest via a call to testC has two parameters, and that the
first one can be converted into an unsigned int and that the second one
can be converted into a Role. The create function of the prototype
converts the parameters to the correct type, if necessary, and determines
which knowledge base, if any, the description will belong to. Then the
create function calls a constructor for AtLeastTest that stores the name,
knowledge base, and parameters in the new instance. Finally the create
function returns the new instance of AtLeastTest. The usage function of
the prototype print an appropriate string.
The macro provides a number of member functions for the AtLeast class.
The == member operator that the name and all the parameters are the same.
The print member function prints the name and the parameters. The getKB
and getName member functions return the stored knowledge base and name.
The run member function has to be supplied by the user, as above. This
run member function takes a classic individual and two pointers to sets,
and returns a TestVal, as do all ClassicTestFun1ctions. The run member
function here checks to see if there are enough fillers for the role
parameter on the individual. It ignores the set pointers, which are used
to communicate dependencies, as it does not produce any dependencies.
The following macros are defined for creating user functions. Each
create data members, argi, for each parameter. Note that ComputedFillers
has an implicit first parameter, which is a role. The meaning of the
suffix on the macros is the number of parameters, followed by L if a list
of the trailing parameters is wanted.
ClassicTestFunction0(CLASS,NAME)
ClassicTestFunction1(CLASS,NAME,ARG1)
ClassicTestFunction2(CLASS,NAME,ARG1,ARG2)
ClassicTestFunction1L(CLASS,NAME,ARG1)
ClassicTestFunction2L(CLASS,NAME,ARG1,ARG2)
HostTestFunction0(CLASS,NAME)
HostTestFunction1(CLASS,NAME,ARG1)
HostTestFunction2(CLASS,NAME,ARG1,ARG2)
HostTestFunction1L(CLASS,NAME,ARG1)
HostTestFunction2L(CLASS,NAME,ARG1,ARG2)
ComputedDescription0(CLASS,NAME)
ComputedDescription1(CLASS,NAME,ARG1)
ComputedDescription2(CLASS,NAME,ARG1,ARG2)
ComputedDescription1L(CLASS,NAME,ARG1)
ComputedDescription2L(CLASS,NAME,ARG1,ARG2)
ComputedFillers1(CLASS,NAME)
ComputedFillers2(CLASS,NAME,ARG2)
ComputedFillers2L(CLASS,NAME,ARG2)
The above macros both declare and define the user function. To be able
to refer to the user function in more than one file, there are
declaration and definition versions of the above macros. The declaration
versions have the above names suffixed with Declare; the definition
versions are suffixed with Define.
The run functions have the following signature
virtual TestVal
ClassicTestDetail::run(const ClassicIndividual& ind,
Set* pdeps,
Set* ndeps) const
virtual TestVal
HostTestDetail::run(const HostIndividual& ind) const
virtual ClassicDescription
ComputedDescriptionDetail::run(const ClassicIndividual& ind) const
virtual IndividualSet
ComputedFillersDetail::run(const ClassicIndividual& ind) const
These run functions have a number of severe descriptions placed on them.
First, they must not modify the knowledge base. Second, the test
functions must be monotonic---that is, if they return testTrue or
testMaybe they must return the same result in a knowledge base with more
information. Third, the rule functions must be constant---that is, they
must return the same answer in a knowledge base with more information.
Fourth, if adding information to some other classic individual could
cause an answer returned from a classic test function, then that
individual must be added to the pdeps argument, provided that that
argument is non-null; if removing information from some other classic
individual could cause an answer returned from a classic test function,
then that individual must be added to the ndeps argument, provided that
that argument is non-null.
Underlying the above macros are the following member functions for the
...Generate and ...Detail classes.
On the ...Generate side there is:
virtual int incompatible (const List & form) const
This function takes a form and determines whether it is suitable
for the particular kind of user function. The form is the entire
form that is being evaluated, starting with the name of the
character interface function, then a pointer to the prototype being run,
then the parameters for the user function creation. This function
is called by the evaluator before the create function is run.
Values to return are
0 if everything is OK
+n if the n'th arg cannot be converted
-n if the n'th arg can be converted several ways
tooManyArguments too many arguments supplied
tooFewArguments too few arguments supplied
otherProblem some other problem
virtual ...Detail * create(const List & parameters) const
This function takes a list of parameters and creates the actual
user function.
virtual void usage ( const NeoForm & form, ostream & os ) const
Print a usage message for this kind of user function. This
function is called by the evaluator when the parameters are
determined to not be compatible with the user function.
On the ...Detail side there is:
virtual int operator ==(const UserFunctionDetail &) const
This function determines whether two user functions are equal.
virtual void print(ostream & os) const
Print a user function on a stream.
KnowledgeBase getKB() const
Return the knowledge base associated with a user function.
Symbol getName() const
Return the name of the user function.
virtual ... run(...) const
This function does the actual work for the user function.
11/ Errors
There are four kinds of errors in NeoClassic. The first two kinds of
errors are specific to the character interface, and encompass anything
that can go wrong there. (See the documentation on the character
interface for more on these kinds of errors.) The third kind of error is
illegal calls to NeoClassic functions, such as trying to return the role
that has a particular name when there is no such role. The fourth kind
of error is an actual knowledge error, such as trying to add information
to a classic individual that makes the knowledge base inconsistent.
There is a fifth kind of ``unusual'' return from NeoClassic that is not
really an error. This return value is an incoherent description. There
is nothing wrong with creating an incoherent description unless that
description is used as the definition of a concept or individual, so this
return does not by itself signal an error.
Illegal calls to NeoClassic functions generally result in null returns.
Illegal calls to NeoClassic include:
- downcasting to a type that does not match the actual type of the object
pointed to by a NeoPtrObject
CLASS NeoPtrObject::DCAST
- finding an object in a knowledge base by name when there is no such
object of the desired type with that name
Role KnowledgeBase::symbolToRole
Concept KnowledgeBase::symbolToConcept
Concept KnowledgeBase::symbolToClassicConcept
Concept KnowledgeBase::symbolToHostConcept
Rule KnowledgeBase::symbolToRule
ClassicIndividual KnowledgeBase::symbolToClassicIndividual
- trying to create an object in a knowledge base when there is already an
object of that type in the knowledge base
Role KnowledgeBase::createRole
ClassicConcept KnowledgeBase::createConcept
HostConcept KnowledgeBase::createConcept
Rule KnowledgeBase::createRule
ClassicIndividual KnowledgeBase::createIndividual
- retrieving a knowledge base by name when there is no knowledge base
with that name
static KnowledgeBase KnowledgeBase::find(const Symbol&)
static KnowledgeBase KnowledgeBase::setCurrent(const Symbol&)
- trying to set the current knowledge base to a null knowledge base
static KnowledgeBase KnowledgeBase::setCurrent(KnowledgeBase)
- creating a knowledge base when there already is a knowledge base with
that name
static KnowledgeBase KnowledgeBase::create
Knowledge errors result in returned objects that are incoherent or
inconsistent. The requested operation is not performed, i.e., the
knowledge base is not changed. Explanation can be used to determine why
the object is incoherent or inconsistent. Calls that produce knowledge
errors include:
- creating a concept with an incoherent definition
ClassicConcept KnowledgeBase::createConcept
HostConcept KnowledgeBase::createConcept
- creating a rule that results in an incoherent set of rules on a concept
**not currently detected**
Rule KnowledgeBase::createRule
- creating a rule that results in an inconsistent knowledge base
Rule KnowledgeBase::createRule
- creating a classic individual that results in an inconsistent
knowledge base
ClassicIndividual KnowledgeBase::createIndividual
- changing an individual in a manner that results in an inconsistent
knowledge base
ClassicIndividual ClassicIndividual::addToldInformation
ClassicIndividual ClassicIndividual::removeToldInformation
ClassicIndividual ClassicIndividual::closeRole
ClassicIndividual ClassicIndividual::uncloseRole
12/ Explanation
Explanation is in the process of being implemented. Documentation will
be provided when explanation is complete.
13/ Hooks
Hooks are designed to allow a User Interface, or some other program, to
monitor the changes to a NeoClassic knowledge base. They allow user
functions to be run in response to knowledge base changes. Hooks are
implemented as a collection of function pointers, to reduce overhead, as
data members of the class Hook, to reduce namespace pollution.
To incorporate your hooks into NeoClassic, create a file with the hook
functions you require. Assign pointers to these functions to the
appropriate members of the class Hook. You have to assign values for all
the members of the class Hook given below; unused hooks can be set to 0.
There are two different kinds of changes that can be monitored, requests
to add or remove information from the knowledge base and deductions made
in response to these requests. The former kinds of changes may be
rejected by NeoClassic because they would make the knowledge base
inconsistent or create an incoherent concept. Therefore, there are
several hooks for each such change. The latter kinds of changes just
happen, but it is possible for several deductions to be made in response
to a request, an inconsistency discovered, and then the changes undone.
a) User Request Hooks
The hooks that monitor most requests come in threes, one that signals the
start of the request, that is when the request is started to be
performed; and two that monitor the end of the request, one that signals
successful request and one that signals failed requests. Some requests
never fail and so have only two hooks; some happen indivisibly and so
only have one hook. Requests that are rejected for name-space reasons,
such as trying to create a concept with a name that is already in use in
the knowledge base, do not cause any hook to be called.
Hooks that signal the creations of objects in a knowledge base have as
arguments the knowledge base in which the request is being made, the name
of the new object, and the creation arguments. Hooks that signal the end
of such requests have as argument the new object, which is an error
object for failed requests.
static void (*Hooks::createKnowledgeBase)(const KnowledgeBase &kb)
static void (*Hooks::destroyKnowledgeBase)(const KnowledgeBase &kb);
These two hooks monitor the creation and destruction of knowledge
bases. The first is run after the knowledge base is added to the
collection of knowledge bases; the second is run after the
knowledge base is removed from the collection of knowledge bases.
static void (*Hooks::startCreateRole)(const KnowledgeBase &kb,
const Symbol & name,
const Boolean & attribute);
static void (*Hooks::successCreateRole)(const Role &role);
These two hooks monitor the creation of roles.
static void (*Hooks::startCreateClassicConcept)(const KnowledgeBase &kb,
const Symbol & name,
const ClassicDescription & def,
const Primitive & primitive);
static void (*Hooks::successCreateClassicConcept)(const ClassicConcept &);
static void (*Hooks::failureCreateClassicConcept)(const ClassicConcept &);
static void (*Hooks::startCreateHostConcept)(const KnowledgeBase &kb,
const Symbol & name,
const HostDescription & def);
static void (*Hooks::successCreateHostConcept)(const HostConcept &concept);
static void (*Hooks::failureCreateHostConcept)(const HostConcept &concept);
These hooks monitor the creation of classic and host concepts.
static void (*Hooks::startCreateRule)(const KnowledgeBase &kb,
const Symbol & name,
const ClassicConcept & antecedent,
const RuleConsequent & consequent);
static void (*Hooks::successCreateRule)(const Rule &rule);
static void (*Hooks::failureCreateRule)(const Rule &rule);
These hooks monitor the creation of rules.
static void (*Hooks::startCreateClassicIndividual)(const KnowledgeBase &kb,
const Symbol & name,
const ClassicDescription & def);
static void (*Hooks::successCreateClassicIndividual)(const ClassicIndividual &ind);
static void (*Hooks::failureCreateClassicIndividual)(const ClassicIndividual &ind);
These hooks monitor the creation of classic individuals.
static void (*Hooks::startAddToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
static void (*Hooks::successAddToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
static void (*Hooks::failureAddToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
static void (*Hooks::startRemoveToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
static void (*Hooks::successRemoveToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
static void (*Hooks::failureRemoveToldInformation)(const ClassicIndividual &ind,
const ClassicDescription & info);
These hooks monitor the addition and removal of information from
classic individuals. The completion hooks have as extra argument
the information added or retracted.
static void (*Hooks::startCloseRole)(const ClassicIndividual &ind,
const Role & r);
static void (*Hooks::successCloseRole)(const ClassicIndividual &ind,
const Role& r);
static void (*Hooks::failureCloseRole)(const ClassicIndividual &ind,
const Role& r);
static void (*Hooks::startUncloseRole)(const ClassicIndividual &ind,
const Role& r);
static void (*Hooks::successUncloseRole)(const ClassicIndividual& ind,
const Role&r);
static void (*Hooks::failureUncloseRole)(const ClassicIndividual& ind,
const Role&r);
These hooks monitor the closing and unclosing of roles on classic
individuals. The completion hooks have as extra argument the role
being closed or unclosed. In the unclosing case, the hooks are
only called if the role was initially closed.
b) Deduction Hooks
The hooks that monitor deductions are called when the deductions are
made, i. e., when NeoClassic is in the middle of processing a request.
This means that the knowledge base is in an unsual state---some
deductions will be made and others will not. Therefore these hook
functions have to be particularly careful. In particular, such a hook
function should not change the knowledge base in ANY way. Any violation
of this requirement is likely to result in malformed knowledge bases,
core dumps, or infinite loops. Accessing the knowledge base is allowed,
but the exact current state of the knowledge base will be seen, so there
may be inconsistent individuals in the knowledge base, etc., etc.
Further, the points at which the hook functions are called and the
arguments passed have been chosen to minimize the impact on NeoClassic.
static void (*Hooks::addParents)(const ClassicIndividual & ind,
const ClassicConcept & parent,
const Set & otherParents);
This hook is called when a group of new parents is discovered for
an individual. Both parent and otherParents are being added.
static void (*Hooks::removeParents)(const ClassicIndividual & ind,
const Concept & parent,
const Set & otherParents);
This hook is called when a group of concepts are no longer parents
for an individual because more-specific parents have been found.
Both parent and otherParents are being removed. This hook is not
called when all derived information is being removed from an
individual!
static void (*Hooks::propagation)(const ClassicIndividual & to,
const ClassicDescription & what,
const RolePath & path,
const ClassicIndividual & from);
This hook is called when a propagation of information from one
individual to another occurs.
static void (*Hooks::ruleFiring)(const ClassicIndividual & ind,
const Rule & rule,
const ClassicDescription & consequent);
This hook is called when a new rule is run on an individual.
The third argument is the actual description being added to the
individual.
static void (*Hooks::removeDerived)(const ClassicIndividual & ind);
This hook is called when the derived information, including
taxonomy information, on an individual has to be recomputed, either
because an inconsistency was discovered or told information is
being removed or a role is being unclosed. Part of removing
derived information is removing the parents of an individual; this
removal is not separately signalled.
14/ Environmental Concerns
The class NeoEnvironment, which has only static members, contains several
functions relating to the environment of NeoClassic. These functions are
only available through the API, as they must be performed outside of the
character interface, or have analogues inside the character interface.
static void NeoEnvironment::init()
static void NeoEnvironment::init(const String &outfn, const String &errfn)
Initialize the NeoClassic environment. This must be called before
any other NeoClassic function, and should not be called until after
cleanup is called. The first version sets the output and error
streams to cout and cerr, the second sets them to write to the
given file names (which can be the same).
static void NeoEnvironment::cleanup()
Cleanup the NeoClassic environment. No NeoClassic functions can
be called after this function is called, unless NeoClassic::init is
again called.
static void NeoEnvironment::readFile(const String & filename)
Read and process a file in the character interface.
static void NeoEnvironment::readFile()
Read and process the standard input in the character interface.
15/ Future Functionality
The following functionality will be supported in future releases of
NeoClassic:
- Meta Information
- Role Hierarchies
Character Interface
The NeoClassic Character Interface is a simple interface that allows access
to the capabilities of NeoClassic without having to write C++ code. The
character interface reads commands from a stream, evaluates these commands,
and (optionally) prints the results obtained.
The functions in the character interface are described in the interface
documentation.
1/ Input Syntax
The character interface inputs a sequence of forms, in the following grammar:
Form ::= LispModeForm | CModeForm
LispModeForm ::= (Symbol LispModeArg*)
LispModeArg ::= Variable | Boolean | Int | Float |
String | Symbol | KBSymbol |
LispModeForm
CModeForm ::= Symbol ( CModeArg* )
CModeArg ::= Variable | Boolean | Int | Float |
String | Symbol | KBSymbol |
CModeForm
Boolean ::= `true' | `false'
Int ::= [`+'|`-']Digit+
Float ::= [Int]`.'Digit*
String ::= `"'Char*`"'
variable ::= `$'char*
Symbol ::= Alpha AlphaDigit*
KBSymbol ::= Symbol`:'Symbol
Alpha ::= `a'|`b'|`c'|...|`z'|`A'|`B'|`C'|...|`Z'|`?'|...
AlphaDigit ::= Alpha | `0' | ... | `9'
Abmiguities are resolved by taking the first alternative. (That is, the
argument `$A' is a Variable, not a Symbol; and the argument `true' is a
Boolean, not a Symbol.)
The syntax for the CI allows two ways of grouping a function with its
arguments. Parentheses may be placed around the arguments only or
parentheses may be placed around the function name as well as the
arguments. Many CI functions can take an arbitrary number of arguments
that are grouped into a set or list.
2/ Evaluation
A form is evaluated by first evaluating its arguments. Then all character
interface functions for the first symbol in the form that are compatible
with the actual arguments in the form are found. If there is exactly one,
it is executed on these arguments.
A character interface function is compatible with a list of arguments if
the arguments can be converted into the types of objects that the function
wants. If the function has a Set or List as its last argument, a Set or
List is made from the sequence of trailing actual arguments.
Variables are replaced by their values before evaluation starts.
3/ Special Functionality
In the character interface, more-general classes are conditionally coerced
into more-specific classes. For example, if a function requires a
ClassicDescription, but its argument produces a Description, the Character
Interface will check to see if the result of evaluating the argument is
actually a ClassicDescription, and will coerce it if so. If the result is
not a ClassicDescription, the character interface will report an error.
Other conversions are also performed, including
- converting an unsigned int to an int, float, IntOrFloat, or HostIndividual
- converting an int to an unsigned int if it is non-negative
- converting an int to a float, IntOrFloat, or HostIndividual
Symbols are conditionally converted into NeoPtrObject, Role, Concept,
ClassicConcept, HostConcept, or Rule, by looking them up in the current
knowledge base. KBSymbols are conditionally converted into NeoPtrObject,
Role, Concept, ClassicConcept, HostConcept, or Rule, by looking them up in
their knowledge base. Symbols are conditionally converted into
ClassicTestDetail, HostTestDetail, ComputedDescriptionDetail, or
ComputedFillersDetail by looking the symbol up in the appropriate table.
In addition, the fills and oneOf functions will automatically create
ClassicIndividuals if given a symbol for which no classic individual
exists.
Operations that are member functions of KnowledgeBase work on the current
knowledge base in the character interface, so no knowledge base
``argument'' is required.
Variables can be set and retrieved. The values of the last three forms
that produced values are available as the values of the variables $, $$,
and $$$.
4/ Printing
The different types of objects in the character interface and their printed
representation are as follows:
Type Printed Representation
int sequence of numerals
float sequence of numerals and .
Boolean false or true
String sequence of characters
Symbol sequence of characters
KBSymbol two sequences of characters separated by :
NeoSet elements enclosed in { and }
IndividualSet elements enclosed in { and }
ClassicOneOf or elements enclosed in { and }
HostOneOf or elements enclosed in { and }
MinOrMax +INF, -INF, or as int or float
HostIndividual as int or float or String
IntOrFloat as int or float
Primitive false, true, or set of symbols
RuleConsequent form that is equivalent to the consequent
ClassicTestGenerate name of the generator
HostTestGenerate name of the generator
ComputedDescriptionGenerate name of the generator
ComputedFillersGenerate name of the generator
KnowledgeBase name of the knowledge base
Description form that is equivalent to the description
Role (primary) name of the role
Concept (primary) name of the concept
Rule (primary) name of the rule
ClassicIndividual (primary) name of the classic individual
Further, if a Concept is incoherent, or a Rule or ClassicIndividual is
inconsistent, the inference that caused the incoherency or inconsistency is
shown when the object is printed as the result of evaluation.
5/ Errors
Parsing and evaluating errors are signalled by printing an error message on
the standard error. If input is from a file, this message includes the
file name and line number where the error was detected
Parsing errors indicate a problem with parsing the input. Forms that have
parsing errors are not evaluated. As soon as a parse error is detected the
rest of the input line is discarded. Parsing errors include:
- missing '(' in form, e.g., foo
- extra '(' in form, e.g., foo( bar () ())
- empty form, e.g., ()
Evaluator errors indicate a problem with evaluating a form. As soon as an
evaluator error occurs, the evaluation of the entire form is aborted.
Evaluator errors include:
- an empty form
- a null argument in a form
- a form whose function position is not a symbol
- a form whose function symbol has no interpreter functions
- a form whose function symbol has no compatible interpreter functions
- a form whose function symbol has more than one compatible interpreter function
- a form that has an ambiguous conversion to a compatible interpreter function
- a form evaluating to a non-existing NeoPtrObject
- a form that causes a user function compatability problem
User functions do their own compatability checking, initiated by the
evaluator. If the user function is not compatible with the supplied
parameters this is considered an evaluator error.
NeoClassic errors indicate some problem within NeoClassic. These are not
necessarily real errors, but instead may indicate some sort of exceptional
condition in a NeoClassic knowledge base.
NeoClassic errors include:
- non-existant NeoPtrObject returns
- incoherent/inconsistent NeoPtrObject returns
A non-existant NeoPtrObject return generally indicates some sort of problem
having to do with the name space of a knowledge base, such as trying to
look up a non-existent concept or trying to create a role with a name that
is already used for another role. An incoherent NeoPtrObject return
indicates some operation that would have created an incoherent concept.
An inconsistent NeoPtrObject return indicates some operation that would
have made a knowledge base inconsistent. In both these two latter cases
the operation is not performed. See the documentation on individual
NeoClassic operations for more information on NeoClassic errors.
5/ Special Functions
(readFile String)
(load String)
Read and evaluate from the file whose name is String. At end of
file or quit revert back to the current input stream.
(setPrinting Boolean)
Turn printing on or off when reading from a file.
(set Symbol NeoObject)
Set the value of the variable with name Symbol to NeoObject.
(select NeoObject unsigned int) -> NeoObject
Select an element from a NeoObject that is (like a) set. The
elements are most likely to be counted in printing order, but there
are NO guarantees! If the NeoObject is not like a set or does not
have enough elements the NeoObject itself is returned.
(print NeoObject)
Send the print version of the item to the current output.
(printInfo Role)
(printInfo Concept)
(printInfo Rule)
(printInfo ClassicIndividual)
Send information on the object to the current output.
(explain Concept)
(explain ClassicIndividual)
Calculate the inferences which produced all the information in
the object. Print the result in a structured manner, and only
print the relevant inferences (not those which were overridden).
(explainVerbose Concept)
(explainVerbose ClassicIndividual)
Calculate the inferences which produced all the information in
the object. Print all the inferences, in an unstructured manner.
(quit)
(exit)
(bye)
If reading from a file, quit reading from that file. If not inside
a readFile, quit NeoClassic.
6/ Testing Functions
The following functions are used for testing the correct behavior of
NeoClassic, and should not be used in normal code.
(testResult NeoObject NeoObject [String])
(testResultSet NeoObject NeoObject...)
Determine if the two non-string arguments are the same. If not,
print an error message (for testResult). testResultSet is defined
on only certain kinds of NeoObjects, namely those that are like sets.