# KEHOME/doc/MKEtutorial.html
# Aug/4/2003
MKR/MKE Tutorial

MKR/MKE Tutorial
version 6.0

For more details see
  KEHOME/doc/MKRgrammar.html
  KEHOME/doc/MKRtoken.html
  KEHOME/src/symbol.icn
  KEHOME/src/token.icn
  KEHOME/kb/tabrasa.def
  KEHOME/kb/ke.def
  KEHOME/doc/API*.*

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

    7. conditionals & iteration
    8. methods
    9. namespace stack

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

III. Concept Formation
    15. context
    16. definitions
    17. integration & differentiation
    18. measurement & classification
    19. units & primitives
    20. 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 15).
A sentence is a statement, question, command, or assignment.
The context or sentence may be omitted.  Nesting is allowed,
i.e., the sentence may be generalized to a proposition list.

This section briefly describes the basic sentence formats. 
Subsequent sections describe in more detail statements,
questions, commands, assignments, input/output, definitions
and concept formation.

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 ten basic statement formats.

    subject is object;			# identity/alias
    subject isa object with		# definition
		attribute = value;
    subject isa object;			# hierarchy: isa,ismem,...

    subject isin    relation  = value;	# n-ary relation
    subject rel     relation  = value;	# binary relation
    subject haspart part      = value;	# part
    subject has     attribute = value;	# attribute
	
    subject do action = event		# action
	with action characteristic
	out  product			# product := subject do ... done
	od   direct object
	from initial characteristic 
	to   final   characteristic
    done;

    subject causes object;		# interaction

    begin gtype gname;			# group: hierarchy,relation,triple,...
    groupstatement1;
    groupstatement2;
    ...
    end gtype gname;

For example, here is an action statement:

	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=value, etc.
may be comma-separated lists of phrases.

NOTE:
Values may be phrase lists enclosed in square brackets [], 
or proposition lists 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:

	/ \ $ . * ? !

All statements are terminated with a semicolon.
One statement may continue over many lines.
Many statements may be on one line. 


The relation group format (see section 4) is

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

The hierarchy group format (see section 6) is

	begin hierarchy honame;
	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 "/".


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
#===================#
Binary and n-ary relations of entities have a format
similar to attributes and actions, e.g.:

	John rel father = Sam;
	John isin phonebook = phonebook_001;

where "father" and "phonebook" are the relations, and
"Sam" and "phonebook_001" are the relation values.
"Sam" is an entity.  "phonebook_001" is a relation
"unit" (or "tuple" or "infon")

	123-456-7890, John;

The definition of an n-ary relation explicitly specifies
the meaning of a relation unit 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 enclosed in braces {},
or the name of a method.  (Methods also have format
and meaning attributes.) Once the relation is defined,
the units are specified as follows:

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

which produces:
	
	123-456-7890,John isin phonebook=phonebook_001;
	John has phone=123-456-7890;
	987-654-3210,Mary isin phonebook=phonebook_002;
	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 (ususally) 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 10).  For example:

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


5. parts & partvalues
#===================#
Attributes, actions and relations are "inseparable"
characteristics of entities.  Parts are "separable"
characteristics.  Parts can be physically separated
from the entity.  When separated, the part becomes
a  new physical 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-characteristic-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 20.)

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.:

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

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

	begin hierarchy existent;
	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 10).  For example:

	do read from person.ho done;

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

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, 11, 12, 14.)

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:
(Note: when is not implemented.)

	every generator { proposition list };
	when  event     { 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 proposition list 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 14
	    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 12).

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 17
	do delete od John Doe done;

9. namespace stack
#================#
KE maintains a stack of local argument names for each
invocation of a method, relation, and every loop.
For methods and relations, arguments can be referred to
by name or by number.  For example:

	move isa method with
	    format = {do move od existent:1 to genus:2 done;},
	    meaning = {
		$1 isd $2;
	    };

where the meaning could alternately be expressed as

	$existent isd $genus;


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

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

	ke myfile.ku

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

	input  file 
	output file 
	error  file 
	log    file 

If ke is executed with no arguments

	ke

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

	input  file 	# keyboard
	output file 	# display
	error  file 	# display
	log    file 

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)
	.nt		Ntriple file
	.rdf		Resource Description Framework file
	.mcf		TAP MCF file
	.mkr		MKR script


Concepts from the current view may be saved in a file using the
write command.  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;


11. questions
#===========#
True-false questions are constructed by enclosing a sentence within
"if" and "fi;".  For example:

	if John isa man; fi;

Form-based questions are constructed by replacing one or more elements
of a sentence by "?".  For example:

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

Here are some more complex examples.

	apple ? orange;		# relation between concepts
	sex isa**? existent;	# number of hierarchy levels
	? is ?;			# all definitions
	? has ?;		# all attributes
	John isa* ?;		# all concepts from John to existent
	animal isc* ?;		# animal subhierarchy
	existent isc**2 ?;	# levels 0,1,2 of existent subhierarchy


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

	do cmdname
		with command characteristics
		out  command products (outputs)
		od   command arguments (inputs)
		from initial characteristics
		to   final   characteristics
	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;	# count units of person
	do check od definition done;	# check for undefined concepts

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

(See section 10 re UNIX passwd file.)

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;


13. 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


14. 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 ...

	 at view=myview;
	# context 

	... input knowledge for myview ...

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



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

15. 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

A knowledge unit is a named proposition list.  It is stored
internally in an entity-characteristic-proposition hierarchy.


16. definitions
#=============#
A concept or unit (see section 19) 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,
unithierarchies uses the begin-end group.

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;


17. 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 differentiate and integrate 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 integrate od unit1, ... with attribute1, ... done;
	do differentiate 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 differentiate od person with profession done;

yields

	person
	/	person_profession_engineer
	//		John
	//		Sue
	/	person_profession_teacher
	//		Mary
	//		Tom

Using the identities

	person_profession_engineer is engineer;
	person_profession_teacher is teacher;

yields

	person
	/	engineer
	//		John
	//		Sue
	/	teacher
	//		Mary
	//		Tom


18. 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


19. 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:

	begin unithierarchy myprim;
	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


20. 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;

MKE home