# KEHOME/doc/KEtutorial.txt
# Feb/20/2003

#=============================#
# Knowledge Explorer Tutorial #
# version 5.0                 #
#                             #
# Richard H. McCullough       #
#=============================#
For more details, see KEHOME/doc/KRgrammar.txt
and KEHOME/doc/KRtoken.txt.  Additional details
may be found in KEHOME/doc/userman.htm, but I
have not updated it since 1999.

Contents
#======#
I. Knowledge Representation
    1. propositions
    2. attributes & values
    3. actions & events
    4. relations & infons
    5. parts
    6. hierarchies

    7. conditionals & iteration
    8. methods

II. Knowledge Explorer
     9. input/output
    10. questions
    11. commands
    12. assignments
    13. exploring

III. Concept Formation
    14. context
    15. definitions
    16. integration & differentiation
    17. measurement & classification
    18. units & primitives
    19. individual concepts & collective concepts



I. Knowledge Representation
#=========================#

1. propositions
#=============#
My knowledge representation language, MKR, characterizes
knowledge as a sequence of propositions with the format

	at context { sentence };

The context is specified by space, time, view (see
section 14).  A sentence is a statement, question, command,
assignment, or a proposition list enclosed in {}.
This section briefly describes the basic statement formats. 
Subsequent sections describe questions, commands, assignments,
input/output (see sections 9 - 13) and definitions,
concept formation (see sections 15 - 19).

Comments begin with a sharp sign and extend to the end
of the line, e.g.:

	# this is a comment

An assignment has the format

	set variable = value;

Assignments are used to change the values of parameters
which control options in representing and processing
knowledge.

There are five basic statement formats.

	subject is object;

	subject has attribute;
	
	subject do action
		with action characteristic
		out  product			# product := subject do ... done
		od   direct object		# argument
		from initial characteristic 
		to   final   characteristic
		done;

	subject rel object with attribute;

	gname is begin group;
	unit1
	unit2
	...
	end group gname;

For example:

	John, Mary do walk to the store done;

where

	subject: John, Mary
	action:  walk
	final:   the store    # space = the store

In general, subject, object, attribute, action, initial, final
may be comma-separated lists of phrases.

NOTE:
In some cases, e.g., the value of the "format" attribute,
the list is enclosed in square brackets []. 
In other cases, e.g., the value of the "meaning" attribute,
the list of propositions is enclosed in braces {}.

A phrase is a consecutive sequence of words separated 
by white space.  A word is a consecutive sequence of
characters which does not include any separators.
The separators are listed below.

	white space (blank tab return newline newpage)
	#
	" '
	[ ] { } ( ) < >
	= += -= *= :=
	& | ~
	, ;

NOTE:
The following characters may be included in a word:

	/ \ $ . * ? !

Statements are automatically continued to the next line when
there is an incomplete syntactic structure, e.g.:

	do/done
	if/fi
	list with separator = "," or ";"
	expressions with & | ~
	[...]
	{...}
	<...>
	subject rel object;
	    rel ::= is isin isa isc ... causes means ...
	preposition phrase
	    preposition ::= at of with out od from to



The relation block format (see section 4) is

	relname is begin relation;
	argument1; argument2; ...; argumentN
	...
	end relation relname;

The hierarchy block format (see section 6) is

	honame is begin hierarchy;
	genus1
	    /  concept1
		//  species1
		    ...
		//  species2
		    ...
	    /  concept2
		...
	genus2
	    ...
	end hierarchy honame;

The number of "/"s specifies the level in the hierarchy.
White space before and after the "/"s is ignored, and is
used to make the outline more readable.  You can also
specify a path from bottom to top of the hierarchy
by using "\" instead of "/".

The directory block format is

	dirname is begin directory; 
	file1
	file2
	...
	filen
	end directory dirname;


2. attributes & values
#====================#
The simplest type of statement specifies an attribute
of an entity, e.g.:

	John has sex=male;
	Mary has sex=female;

"John" and "Mary" are entities; "sex" is an attribute;
"male" and "female" are its values.

Boolean attributes have a value of true or false,
e.g.:

	John has alive=true;
	Bill has alive=false;

or the equivalent statements

	John has alive;
	Bill has not alive;


3. actions & events
#=================#
Actions characterize changes in attributes.
An event is an occurrence (instance) of an action.
Only entities can perform actions;
any existent can have attributes.

Here is an example of the general action/event format:

	John do move = move_123
		od table, chairs
		from dining room
		to living room
		done;

"move" is the action; "move_123" is the event.
An event is the occurrence of an action; it identifies
this particular instance of the action.

Here are a few more examples:

	Mary do walk from home to store done;
	John do run from 10:00am to 10:15am done;
	Bill do hit od the ball to the fence done;

The product of an action is expressed as:

	knowledge := man do identify od existent done;

":=" means "is the product of"; i.e., "knowledge" is
the result produced by "man" performing the action
"identify" on the object "existent".


MKR distinguishes an action declaration (meaning that
an entity has the capability, or "power", to perform
the action) from an event (an occurence of the action).
An action declaration adds a "*" suffix to the "do" verb
and the event name.  Here are some examples of action
declarations
	
	John has power=talk;
	John do* talk done;
	John do* walk=walk_123*
		from home to store
		done;

and events

	John do talk done;
	John do walk=walk_456
		from home to store
		done;


4. relations & infons
#===================#
General relations of entities have a format similar to
attributes and actions, e.g.:

	John isin phonebook = [123-456-7890; John];

"phonebook" is the relation, and "[123-456-7890; John]"
is the infon (instance of the relation, or relation unit).


The relations that specify attributes and actions are
special relations, for which "format" and "meaning"
are the same.  The definition of a general relation must
explicitly specify the meaning of a relation unit ("infon")
in the current view, e.g.:

	phonebook is relation with
		automatic="isa",
		format=[phone:1, person:2],
		meaning={$2 has phone=$1;};

Meaning is a list of propositions or a method which defines
the statements which are to executed for each infon in the
relation.  (Methods also have format and meaning attributes.)
Once the relation is defined, the infons are specified
as follows:

	phonebook is begin relation;
	123-456-7890; John
	987-654-3210; Mary
	end relation phonebook;

which produces:
	
	123-456-7890,John isin phonebook=[123-456-7890; John];
	987-654-3210,Mary isin phonebook=[987-654-3210; Mary];
	John has phone=123-456-7890;
	Mary has phone=987-654-3210;

and

	123-456-7890 isa phone;
	John isa person;
	987-654-3210 isa phone;
	Mary isa person;

The second group of statements consists of all
the "automatic" declarations.  Sometimes these
cause problems, i.e., more than one genus for
the argument.  To avoid such problems, you can
change the "automatic" attribute of a relation. 
For example,

	phonebook has automatic="isa*";

produces the declarations

	123-456-7890 isa* phone;
	John isa* person;
	987-654-3210 isa* phone;
	Mary isa* person;

and

	phonebook has automatic="none";

produces no automatic declarations.

A concept has only one genus, but has many classes.
(The "*" suffix denotes 0 or more levels in the
hierarchy; thus any concept at or above John in
the hierarchy is a class of John:
	John isa* class;
See section 6.) 

Relations may be stored in files and read into
Knowledge Explorer using the read command (see
section 9).  For example:

	phonebook is relation with
		format=[phone:1; person:2],
		meaning={$2 has phone=$1;};
	do read from phonebook.rel done;


5. parts
#======#
Attributes, actions and relations are "inseparable"
characteristics of entities.  Parts are "separable"
characteristics.  Parts can be physically separated
from the entity.  Entities and their parts are expressed
in the same form as other ke characteristics, e.g.

	John haspart leg;
	leg  isapart John;

	television set haspart
	    picture tube = x19_005,
	    tuner = y75;


6. hierarchies
#============#
Knowledge is organized into lists of propositions,
which are the basic knowledge units (knits).
These knits can be conveniently displayed as
entity-concept-proposition hierarchies,  Such
ECP-hierarchies consist of mutually exclusive concepts,
e.g.:

	person iseither John or Mary or Bill;

(For the present, we will consider only individual concepts;
collective concepts will be discussed in section 19.)

This statement can be abbreviated as

	person isc John, Mary, Bill;

or

	John, Mary, Bill isa person;

Hierarchies can also be expressed in outline format, e.g.:

	person is begin hierarchy;
	person
	/  John
	/  Mary
	/  Bill
	end hierarchy person;

A complete hierarchy for the knowledge unit (knit) of section 2 is

	existent is begin hierarchy;
	existent
	/	person
	//		John
	//		Mary
	//		Bill
	/	attribute
	//		sex
	///			male
	///			female
	//		alive
	///			true
	///			false
	/	statement
	//		s_attribute
	///			s_sex
	////				{John has sex=male;}
	////				{Mary has sex=female;}
	///			s_alive
	////				{John has alive;}
	////				{Bill has not alive;}
	//		s_hierarchy
	///			{John, Mary, Bill isa person;}
	end hierarchy existent

Hierarchies may be stored in files and read into
Knowledge Explorer using the read command (see
section 9).  For example:

	do read from person.ho done;

The structure of the hierarchy can be changed by
integration and differentiation (see section 16).

Each hierarchy represents a particular view of knowledge,
a knit, and is labeled with a view name, e.g.:

	at view = myview;

The initial contents of a new knit are copied from the
knit which contains the "at" statement.  The knit that
contains all other knits is named tabula_rasa.

The "isc" and "isa" verbs denote relations between adjacent
levels of the hierarchy.  To specify multilevel relations, the
following suffixes are used:

	**n	n levels
	*	0 or more levels
	+	1 or more levels

For example:

	John isa**2 entity;

means that John is two levels below entity in the hierarchy,
and

	John isa* x;

means that John is at or below x in the hierarchy.  Any concept
x which satisfies this relation is called a "class" of John. 


7. conditionals & iteration
#=========================#
(Some examples in this section use methods, questions,
and commands.  See sections 8, 10, 11, 13.)

A conditional statement has the format:

	if sentence1 then sentence2 else sentence3 fi;

For example:

	if unit1 isa concept2
	   and unit1 has attribute3;
	then concept2 has attribute3;
	fi;

	if John isin phonebook;
	then set . = John; do call od $phone done;
	else do print od "John not in phonebook" done;
	fi;

Iteration statements have the format:

	every generator { proposition list };

where generator has one of these formats:

	variable in    concept1, ...
	variable isa   genus
	variable isalt exgroup
	variable ismem ingroup
	variable isin  relation

and sentence uses $variable to denote the particular
value of variable, and $1,$2,... to denote the arguments
of the particular infon $variable of a relation.

For example:

	every x in person, event {
	    $x isc* ?;  # subhierarchy
	};

	every p isa person {
	    do char od $p done;
	};

	every pb ismem phonebook {
	    set . = $pb;                # see section 13
	    do print od "$2; $1" done;  # reverse order
	};


8. methods
#========#
A method is a user-defined action, with arguments.
A method is defined in the same way a relation
is defined (see section 4).
A method is executed in the same way that a
KE command is executed (see section 11).

Here are two simple examples:

	char is method with
		format=[existent:1],
		meaning={$1 is ?; $1 has ?; $1 do ?; $1 isin ?;};
	do char od Mary done;

	delete is method with
		format=[existent:1],
		meaning={$1 isd nonexistent;};  # "isd" - see section 16
	do delete od John Doe done;


II. Knowledge Explorer
#====================#

9. input/output
#=============#
If Knowledge Explorer is executed using

	ke myfile.ku

(or by clicking on myfile.ku) the following files are opened:

	input  file <myfile.ku>
	output file <myfile.out>
	error  file <myfile.err>
	log    file <myfile.log>

If ke is executed with no arguments

	ke

(or by clicking on ke) the following files are opened:

	input  file <input>	# keyboard
	output file <output>	# display
	error  file <errout>	# display
	log    file <input.log>

The output file will contain:

	input sentences (unless "set echo=off;")
	answers to user questions
	output from user commands
	output from "check" command
		(unless "set hcheck=no;" or "exit;")
	concepts in hfocus list
		(unless "exit;")

The error file will contain:

	"ERROR" messages
	critical "WARNING" messages

The log file will contain:

	"INFO" messages requested by "set debug=xxx" assignment
	"INFO" messages automatically generated by KE
	non-critical "WARNING" messages
	"Internal ERROR" messages

You can access other files using the read and write commands.
The read command has the format:

	do read from filename done;

You can include a "with" phrase to access files whose contents
do not follow the usual conventions, e.g.:

	do read with relseparator=":"
		from /etc/passwd
	done;

reads the UNIX "passwd" file, which contains the "password"
relation, using a relation separator of ":" instead of the
default KE separator ";".

The extension of a file has no effect on how Knowledge Explorer
processes the file.  The file extension is simply a user-friendly
way to document what kind of knowledge the file contains. 
For example

	.ku		knit
	.cu		chit (see section 3)
	.rel		relation (see section 4)
	.ho		hierarchy outline (see section 6)
	.dir		file system directory hierarchy
	.html,.htm	knit (HTML commands are ignored)
	.rdf		Resource Description Framework file
	.mkr		MKR script


NOTE:
An internal format variable, kformat, is used to change the
input parser's definition of a phrase while processing group
(e.g., relation, hierarchy, directory) definitions. 
In older versions of KE, kformat was set/reset on file
boundaries based on the file extension.
In the current version of KE, file boundaries are completely
transparent; the begin/end blocks cause kformat to be set/reset
according to the type of block -- relation, hierarchy, directory.

Concepts from the current view may be saved in a file using the
write command:

	set hfocus = concept1, ...;	# concept list
	do write od $hfocus
		to filename.fmt		# fmt: ku or rel or ho or dir
	done;

For example:

	set hfocus = person,event;
	do write od $hfocus to save.ho done;
	
writes the "person" subhierarchy and the "event" subhierarchy
to the file "save.ho".  This can also be written as

	do write od person,event to save.ho done;


10. questions
#===========#
Questions have the same format as statements, but with
one or more elements replaced by "?" ("form-based questions".)
In addition, one can form a true-false question by appending
a "?" to any statement.

For example:

	John ? Mary;
	John has ?;
	? has sex;
	? has sex=female;
	John do ? done;

	John isa man ?;

Several more complex formats are allowed, e.g.:

	sex isa**? existent;	# number of hierarchy levels
	? is ?;			# dictionary
	? has ?;		# all attributes of all concepts

Here are some examples using multilevel verbs (see section 6):

	John isa* ?;

produces the list of concepts from John to existent (the top of the
hierarchy), and

	animal isc* ?;

produces the animal subhierarchy, and

	existent isc**2 ?;

produces levels 0,1,2 of the existent subhierarchy.


11. commands
#==========#
Commands are predefined Knowledge Explorer actions which you can
execute using sentences of the form

	do cmdname
		with cmdname characteristic
		out  product
		od   argument1, ..., argumentN
		from initial characteristic
		to   final   characteristic
	done;

Note that

	do cmdname ... done;

is really just a shorthand notation for

	ke do cmdname ... done;

Likewise, you can use

	! cmdname ... done;

as a shorthand notation for executing a shell command

	sh do cmdname ... done;


Example commands:

	do usize od person done;

counts the number of persons (units of person), and

	do check od definition done;

checks for undefined concepts, and

	password isa relation;
	do read od password from /etc/passwd
		with kformat=rel,relseparator=":"
	done;

reads the UNIX passwd file (see section 9) into password.

The complete list of KE commands is obtained by entering:

	ke do ? done;

The definition of any command is obtained by entering:

	cmdname is ?;

Most commands are executed only in the current knit.
These two commands access knowledge in all knits:

	vdo exec od {sentence} done;
	vdo find od name done;	# "*" is wildcard

User-defined commands (see section 8) are defined as
methods, e.g.:

	mycommand is method with ...;
	do mycommand ... done;


12. assignments
#=============#
An assignment has the form

	set variable = value;

which is a shorthand notation for

	 ke has variable = value;

Assignments are used to change the values of KE attributes,
which in turn control various options in processing
knowledge.  For example,

	set hfocus = [person, event, hierarchy];

changes the list of concepts which will be written to the
output file by the write command.  To obtain a complete list
of KE attributes, enter:

	ke has ?;

To obtain the definition of any particular attribute, enter:

	variable is ?;

To obtain the values of KE attributes, enter:

	ke has variable = ?;	# current value
	set variable = ?;	# current value
	do help od value done;	# legal values
	variable isall ?;	# values used


13. exploring
#===========#
To facilitate the exploration of hierarchies (or lattices)
the following variables (ke attributes) are defined:

	/	existent
	..	current genus of current concept
	.	current concept
	...	current species of current concept

/ is a read-only variable.  The other (dot) variables can
be changed using:

	set ..  = next;		# next genus of current concept
	set .   = myconcept;	# change current concept
	set ... = next;		# next unit of current concept

When . is changed, set stores the attributes, actions, etc. of the
current concept in dollar variables.  If the current concept
is a relation infon, set also stores the argument values in
$1,$2,...  See KE User Manual for details.

Here's an example:
(Note that ke input prompt is enclosed by <>,
and echo of input sentence is enclosed by <>.)

	$ ke

	... startup messages from ke ...

	<v_input:.=existent> at view=myview;
	# context <at view=myview>

	... input knowledge for myview ...

	<myview:.=existent> set . = person;
	# assignment <set . = person>
	<myview:.=person> set .. = next;
	# assignment <set .. = next>
	<myview:..=animal> set ... = next;
	# assignment <set ... = next>
	<myview:...=John> set ... = next;
	# assignment <set ... = next>
	<myview:...=Mary> set . = ...;
	# assignment <set . = ...>
	<myview:.=Mary> $. isa* ?;
	# question <Mary isa* ?>
	Mary
	\  person
	\\    animal
	\\\      entity
	\\\\        existent
	<myview:.=Mary> $. has ?; $. do ? done;
	# question <Mary has ?>
	Mary has sex=female
	# question <Mary do ? done>
	Mary do walk from home to store done
	<myview:.=Mary> exit;
	# exit <exit>
	##### exit #####
	$



III. Concept Formation
#====================#

14. context
#=========#
Context is specified by

	at space=s,time=t,view=v;

where
	s denotes where action occurs
	t denotes when  action occurs
	v denotes knowledge unit


15. definitions
#=============#
A concept or unit (see section 18) definition has the format

	# genus-differentia
	concept iss genus with differentia;
	unit    isu genus with differentia;
or
	# ostensive
	genus isg concept1, concept2, ..., conceptn;
	genus isp unit1,    unit2,    ..., unitn;
or
	# production
	concept := entity do action ... done;
	unit    := entity do action ... done;

where
	"iss" and "isu" specify that the genus is on the
	next hierarchy level above the concept or unit

	differentia is a set of essential characteristics --
	characteristics (or relations of characteristics)
	which distinguish the concept/unit from all other
	concepts/units with the same genus

	ostensive is a complete enumeration of all
	concepts/units which are subsumed by the genus

	":=" means "is the product of", i.e., the
	concept/unit is the result produced by performing
	the specified action


NOTE:
It is important to distinguish between units (concretes) and
concepts (abstractions).  If the context makes this distinction
clear, we can use either of these forms

	x is  genus with differentia
	x isa genus with differentia

NOTE:
The definition by enumeration for relations, hierarchies,
primitives uses the begin-end block.

Here are a few examples:
(attributes, actions and relations are characteristics)

	# context
	animal do live,move done;
	man has sex, rational;
	man do identify done;

	# definition
	animal isa entity with live, move;
	man is animal with rational;
	knowledge := man do identify od existent done;
	sex isp male, female;
	hierarchy iss group with order="isa", genus=single;
	lattice   iss group with order="isa", genus=multiple;


16. integration & differentiation
#===============================#
The "isd" and "isi" verbs are used to change relations
between existing concepts, which were established with
"isa" and "isc".  For example,

	John, Mary isa person;
	person isc engineer, teacher;
	John isa engineer;
	Mary isa teacher;

yields the lattice

	person
	/	John
	/	Mary
	/	engineer
	//		John
	/	teacher
	//		Mary

Applying the "corrections"

	John isd engineer;
	Mary isd teacher;

yields the hierarchy

	person
	/	engineer
	//		John
	/	teacher
	//		Mary

The isd and isi commands are used to create
new concepts in an existing hierarchy, using the
attributes of existing concepts.  The general
format of these commands is

	do isi od unit1, ... with attribute1, ... done;
	do isd od concept with attribute1, ... done;

Here is an example (with "engineer" and "teacher"
now being "profession"s instead of "person"s):

	John, Mary, Sue, Tom isa person;
	John, Sue has profession=engineer;
	Mary, Tom has profession=teacher;
	do isd od person with profession done;

yields

	person
	/	person/profession_engineer
	//		John
	//		Sue
	/	person/profession_teacher
	//		Mary
	//		Tom


17. measurement & classification
#==============================#
The measure command is used to determine new attributes
for existing concepts.  The format is

	do measure od concept with attribute1, ... done;

The measure command executes a (user-supplied) method
to calculate each new attribute:

	set echo = off;
	every cname isa concept {
	    every attrname in attribute1, ... {
		do measure_$attrname od $cname done;
			# result stored in $Command
		$cname has $attrname=$Command;
	    };
	};
	set echo = on;

The classify command is used to place an "unknown"
concept into an existing hierarchy.  The format is

	do classify od newconcept to oldconcept with attribute1, ... done;

For example:

	Nancy has profession=engineer;
	do classify od Nancy to person with profession done;

yields

	person
	/	person/profession_engineer
	//		John
	//		Nancy
	//		Sue
	/	person/profession_teacher
	//		Mary
	//		Tom


18. units & primitives
#====================#
Ayn Rand defines a unit as

	A unit is an existent regarded as
	a separate member of a group of
	two or more similar members.

Units are concretes viewed as members of
an abstract group.  The group is a "primitive" concept.
When higher-level concepts are formed from primitives,
the units are also units of the higher-level concepts.

The MKR syntax for units is

	unit,...  isu primitive;
	primitive isp unit,...;

It is important to distinguish between
units (concretes) and concepts (abstractions).
A concept with no units is a nonexistent, i.e.,
a contradiction.  A concept whose units have not
been identified is a "floating abstraction".

To specify the analogous relations between
higher level concepts, the MKR syntax is

	species,... iss genus;
	genus       isg species,...;

To include both cases, the MKR syntax (as used
in earlier sections) is

	x,...   isa concept;
	concept isc x,...;


A unithierarchy outline can be used to specify
the unit-primitive relations:

	myprim is begin unithierarchy;
	genus
	/  unit1
	/  unit2
	...
	end unithierarchy myprim;


Multi-level verbs are useful in questions:

	cname isc* ?;	# all species & units
	cname isg* ?;	# species only
	cname isp* ?;	# units   only


19. individual concepts & collective concepts
#===========================================#
Ayn Rand defines a concept as

	A concept is a mental integration of two or
	more units possessing the same distinguishing
	characteristics, with their particular
	measurements omitted.

The mental integration may either be exclusive (individual)
or inclusive (collective).

For the moment, let's talk about groups instead of concepts.
A group can be either exclusive (exgroup) or inclusive (ingroup).
The existents which are viewed as members of the group are
called units.  Thus

	An exgroup is any one of two or more similar units.
	An ingroup is all of two or more similar units.

In my MKR language, these are expressed as

	exgroup isany unit1 or  unit2 or ...;
	ingroup isall unit1 and unit2 and ...;

For example

	dogz isany Dutchess or  Reno or  ...;
	dogs isall Dutchess and Reno and ...;
	dog  isc   Dutchess,    Reno,    ...;

Note that the corresponding exgroup-hierarchy,
ingroup-hierarchy, group-hierarchy appear to be
the same, but the relationship of the units is
different.

	dogz
	    Dutchess
	    Reno
	    ...

	dogs
	    Dutchess
	    Reno
	    ...

	dog
	    Dutchess
	    Reno
	    ...

By definition, the group, exgroup and ingroup
which subsume the same units are related by

	dogs is all dog;
	dogz is any dog;
	dogs isall  dogz;
	dogz isany  dogs;

The shorthand formats for groups

	group isc unit1, unit2, ...;
	unit1, unit2, ... isa group;

have been used throughout this tutorial.
Where the distinction between ingroup
and exgroup is important, we will use
the following shorthand formats

	exgroup isany alternative1, alternative2, ...;
	alternative1, alternative2, ... isalt exgroup;

	ingroup isall member1, member2, ...;
	member1, member2, ... ismem ingroup;


Returning to concepts, we may now note that

	individual concept isa exgroup;
	collective concept isa ingroup;

Other common abstract groups are

	enumeration is  exgroup with order = none;
	set         is  ingroup with order = none;
	list        is  ingroup with order = space; 
	sequence    is  ingroup with order = time;
	hierarchy   is  group   with order = "isa", genus=single;
	lattice     is  group   with order = "isa", genus=multiple;
	filesystem  isa hierarchy;
