## KE Text

E-Mail Comments to: opencyc-doc@cyc.com
Copyright© 1997-2002 Cycorp. All rights reserved.

Return to Table of Contents

- Introduction
- KE Text Syntax
- Notation

- Variables
- Constants
- Strings
- Keywords
- Symbols

- Expressions
- Directives

- Reserved Words

- Constant
- In Mt
- Default Mt
- Truth Value
- Direction
- Formula
- Enter
- Delete
- Rename
- Kill

- Predicate Directives

- Comments in KE Text
- Order of Expressions
- Another Example
- KE Tools

- Processing KE Text in the Cyc Web Interface

- Appendix A - KE Text History

# Introduction

KE Text (Knowledge E Text, where the E stands for Editing, which is historically correct, or Entry, which is intuitively correct) is an ASCII text format for specifying changes to a Cyc KB. The text is parsed into KB operations (asserts, unasserts, renames, etc.) that are then evaluated. KE Text is processed through the browser through the Compose KE Text page, which allows typing in KE Text.

The KE Text facilities allow authors to compose a set of KB changes in text and add them to a Cyc KB in a single batch operation. Choosing to use KE Text is strictly a matter of convenience. Operations entered using KE Text do not differ in the KB from those entered via other browser tools. Most users find it convenient in situations where many similar changes need to be made or when they are adding a related set of new constants and assertions.

# KE Text Syntax

KE Text syntax is just a syntactic/notational variation of CycL. Many people find it easier and faster to write some types of CycL expressions using KE Text syntax than using "canonical" FOPC-in-Lisp CycL syntax, which partly explains why KE Text syntax continues to be supported by knowledge entry tools.

## Notation

### Variables

  Variables occurring anywhere in a KE text (e.g., inside rule statements) must begin with a question mark (?). This convention signals the knowledge entry facilities to treat the object as a variable, rather than as a constant.

### Constants

  It is not necessary to include the initial "#$" in references to known constants (i.e., constants which Cyc already knows to exist), though it is not disallowed. For example, one could use either #$Siegel or Siegel; #$KeithsHouse or KeithsHouse. Accepted practice is to write KE text without the "#$" prefix.

### Strings

  Strings referred to in KE text (such as entries on the #$comment predicate for a constant) must be delimited by double quotes (e.g., "This is a string."), as in Common Lisp and C.

  To use double quotes inside comments, prefix them with a backslash. (e.g. "This comment \"contains\" double quotes.")

  KE text preserves tab and return/newline/linefeed characters that occur inside strings, but will remove any non-printing characters.

### Keywords

  Keywords occuring in formulas must be prefixed with a colon. (e.g. "f: (genKeyword PublicConstant :PUBLIC-CONSTANT).")

### Symbols

  Symbols occuring in formulas must be prefixed with a single quote. (e.g. "f: (afterAdding genls 'GENLS-AFTER-ADDING).")

## Expressions

A complete, meaningful syntactic unit of Cyc KE text is an "expression". Expressions in KE Text syntax are somewhat analogous to sentences in a natural language, or more closely, to expressions in a programming language such as Lisp or C. In C, the end of an expression is indicated by a semi-colon (;). In Lisp, the end of an expression is indicated by a right parenthesis that balances a corresponding left parenthesis. In KE Text syntax, each expression must end with a period (.), and the period must be outside of a comment or a string. The general form of an expression in KE Text syntax is as follows:

    <directive>: <data-object-or-object-sequence>.

## Directives

There are two types of objects which may fill the <directive> position in a KE text expression: reserved words and predicates.

### Reserved Words

The first type comprises reserved words (analogous to reserved words in a programming language), which are as follows:

- Constant
- In Mt
- Default Mt
- Truth Value (or TV)
- Direction (or D)
- Formula
- Enter
- Delete
- Rename
- Kill

The syntax for all reserved words except Enter, Delete, and Rename is the same. Each reserved word is followed by a colon delimiter, exactly one data object, and a period. That is, the form of a reserved word expression in KE Text syntax is:

         <reserved-word>: <data-object>.

Note that reserved word directive names are not case-sensitive. For example, "constant" works just as well as "Constant".

Enter and Delete have the following syntax:

         <reserved-word>.

Rename has the following syntax:

         <reserved-word>: <old-constant-name> <new-name-string>.

#### Constant

If the reserved word is "Constant", the data object following the colon delimiter must be the name of a Cyc constant (e.g., Pittman, or MarksHouse, or some other Cyc constant). For example:

         Constant: Pittman.
         Constant: Murray.

If the data object following the colon delimiter is not already known (by Cyc) to be a Cyc constant, the user will be asked if he/she wants to create a new constant with that name.

When an expression beginning with a Constant directive is evaluated, it causes the default entry constant (the "current" constant) to be set to the named constant, the default truth value to be set to :unknown, the default direction to also be set to :unknown, and the default entry microtheory to be set to the BaseKB. The only exception to this is if the microtheory has previously been set via the Default Mt directive, in which case the use of the Constant directive leaves the microtheory unchanged. All of the settings made by the Constant directive persist until they are changed by some other (implicit or explicit) directive.

#### In Mt

If the reserved word is "In Mt", the data object following the colon delimiter must be a known (i.e., already existing) microtheory.

Example:

In Mt: HumanActivitiesMt.

When an expression beginning with an In Mt directive is evaluated, it causes the default entry microtheory to be set to the named microtheory. This setting persists until the next occurrence of an In Mt directive, a Default Mt directive, or a Constant directive.

#### Default Mt

If the reserved word is "Default Mt", the data object following the colon delimiter must be a known (i.e., already existing) microtheory. For example:

        Default Mt: HumanActivitiesMt.

When an expression beginning with a Default Mt directive is evaluated, is causes the entry/delete microtheory to be set to the named microtheory. This setting persists until the next occurrence of a Default Mt or In Mt directive, or the end of the file/text being processed. Once a directive has been overriden by another directive, the scope of the original directive is no longer valid, even if the second directive is itself overriden later. Note that this directive, unlike the In Mt directive, prevents each occurrence of a Constant directive from resetting the default microtheory to BaseKB. This directive makes it easier to process all (or most) of the expressions in a file/text segment in the same microtheory.

#### Truth Value

If the reserved word is "Truth Value" (or "TV"), the data object following the colon delimiter must be one of the keywords :default, :monotonic, or :unknown. (It's also OK to omit the colon).

(Check the glossary for a quick description of the difference between default true and monotonically true.)

Examples:

         Truth Value: :monotonic.
         TV: monotonic.

It should only very rarely be necessary for a user to use a Truth Value directive. KE Text assigns truth values to entry expressions automatically. If an entry expression begins with a predicate which is an instance of DefaultMonotonicPredicate (including isa and genls), the expression is automatically assigned a truth value of :monotonic. All other entry expressions are automatically assigned a truth value of :default.

The only reason to use a Truth Value directive is if you want to override these built-in defaults.

When an expression beginning with a Truth Value directive is evaluated, it causes the entry truth value for the following expression to be set to the indicated truth value. (Note that an expression might comprise several assertions. This will be explained more fully below). After the expression to be entered is evaluated, the setting immediately reverts to :unknown, until the next entry expression is encountered (and the truth value is automatically set to :default or :monotonic), or until another Truth Value directive is read.

When would you want to use this directive? Suppose you wanted to enter a rule with a truth value of :monotonic. Since the default setting for rules is :default, in your KE text you would want to precede the rule with this expression:

Truth Value: :monotonic.

#### Direction

If the reserved word is "Direction" (or "D"), the data object following the colon delimiter must be one of the keywords :forward (to indicate forward propagation), :backward (to indicate backward propagation), or :unknown. (It's also OK to omit the colon).

Examples:

         Direction: :forward.
         d: backward.

KE Text assigns directions to entry expressions automatically. Expressions beginning with a simple predicate (ground atomic formulas) are assigned a direction of :forward. All other entry expressions (most notably, all rules) are assigned a direction of :backward.

The only reason to use a Direction directive is if you want to override these built-in defaults.

When an expression beginning with a Direction directive is evaluated, it causes the direction for the following entry expression to be set to the indicated direction. After the expression to be entered is read, the setting immediately reverts to :unknown, until the next entry expression is encountered or another Direction directive is read.

The most common use for this directive is to enter rules with a direction of :forward.

#### Formula

If the reserved word is "F" (for "formula"), the data object following the colon delimiter must be a well-formed CycL Formula.

The constants referred to in the CycL formula must already be known to Cyc (i.e., must already exist, perhaps as a result of being created at some previous point in the KE text).

(KE Text will also accept the directive "EL" to specify a CycL Formula. "EL" stands for "Epistemological Level", as distinct from "HL", which stands for "Heuristic Level".)

Examples:

         F: (implies
    	    (isa ?cat Tiger)
    	    (hasVisibleSurfacePatternType ?cat StripedPattern)).

         F:  (holdsIn (Year 1995) (owns Goolsbey KeithsHouse)).

         F: (likesAsFriend SimoneSiegel KathyBurns).

#### Enter

If the reserved word is "Enter", it must be followed by a period. All of the expressions following this reserved word until an occurrence of the reserved word "Delete" (or the end of the file/text) will be processed assuming that the resulting assertions should be entered into the Cyc KB. For example:

        Enter.

        F : (holdsIn (Year 1995) (owns Goolsbey KeithsHouse)).

The default processing mode for the KE Text facilitiy (Compose) is entry mode, so you don't have to use this reserved word unless you want to start entering assertions after a region of text in which the processing mode was set to delete (see below).

#### Delete

If the reserved word is "Delete", it must be followed by a period. All of the expressions following this reserved word until an occurrence of the reserved word "Enter" (or the end of the file/text) will be processed assuming that the resulting assertions should be removed from the Cyc KB. For example:

        Delete.

        F: (holdsIn (Year 1996) (owns Goolsbey KeithsOldCar)).

        Enter.

        F: (holdsIn (Year 1996) (owns Goolsbey KeithsNewCar)).

Since the default processing mode for the KE Text facilities (KE File, Compose) is entry mode, you must use use the "Delete" reserved word if you want to remove assertions from the Cyc KB by processing KE Text. If the assertion to be removed is a local assertion, the method (FI function) used is KE-UNASSERT. If the assertion to be removed is a remote assertion, the method used is KE-BLAST. Exercise caution in using this directive.

#### Rename

If the reserved word is "Rename", the colon delimiter must be followed by a constant name, a string indicating the new name, and a period. For example:

        Rename: NicksFirstKid "SimoneSiegel".

The Rename directive provides a convenient way to do a batch of constant renames in text.

A renamed constant does not become the "current" constant.

#### Kill

If the reserved word is "Kill", the colon delimiter must be followed by the name of the constant to be killed. For example:

        Kill: highestVolcanoInRegion.

### Predicate Directives

  The second type of directive comprises Cyc predicates occurring within the scope of a (previously occurring) Constant directive. The Constant directive sets the "current" constant, which then is understood to be the first argument to assertions generated from the following predicate directive expressions.

  (Note that predicate directive names, unlike reserved word directive names, are case-sensitive. After all, a predicate directive name is just the name of a CycL predicate, and CycL constant names are case-sensitive.)

  Each predicate directive is followed by a colon delimiter, one or more data objects, and a period. That is, the form of a predicate expression in KE Text syntax is

      <predicate>: <data-object-1> [<data-object-2>...<data-object-n>].

  The data objects following the colon delimiter comprise the additional argument(s) to the predicate in the predicate directive.

  Example:

           Constant: Goolsbey.
           isa: HumanCyclist ElectricalEngineer.
           feelsTowardsObject: (SimoneSiegel Affection Positive)
      			 (BillJ Curiosity Positive).
           comment: "Keith Goolsbey is a member of the Cycorp technical board.".

  In this example, the Constant directive sets the "current" constant to be Goolsbey. Goolsbey is then assumed to be the first argument to assertions formed from the three following predicate directive expressions (the expressions which begin with "isa", "feelsTowardsObject", and "comment").

  If the predicate directive is the name of a binary predicate (such as isa and comment), each of the data objects following the colon delimiter is assumed to be part of an assertion in which the predicate directive is the predicate, the default constant is the first argument, and the data object is the second argument.

  If the predicate directive is the name of an n-ary predicate where n is greater than 2 (such as #$feelsTowardsObject), each of the data objects following the colon delimiter must be a list. The elements in the list are assumed to be part of an assertion in which the predicate directive is the predicate, the default constant is the first argument, and the elements (in listed order) are the remaining arguments. So, when evaluated and processed, the KE text fragment in the example above would result in the addition of the following six assertions to the KB:

           (#$isa #$Goolsbey #$HumanCyclist)
           (#$isa #$Goolsbey #$ElectricalEngineer)
           (#$feelsTowardsObject #$Goolsbey #$SimoneSiegel #$Affection #$Positive)
           (#$feelsTowardsObject #$Goolsbey #$BillJ #$Curiosity #$Positive)
           (#$comment #$Goolsbey "Keith Goolsbey is a member of the Cycorp technical board.")

  Note that because any number of data objects may follow a colon delimiter preceded by a predicate directive, one KE text expression may result in several assertions being added to the knowledge base. Any reserved word directive immediately preceding such a compound KE text expression (i.e., an expression yielding more than one assertion) will apply to all of the assertions resulting from the expression.

  Also, note that since a "canonical" CycL Formula can be entered in KE text by using the F directive, the assertions resulting from the expressions in the example above are exactly the same as the assertions resulting from the expressions in the example immediately below.

  Example:

           F: (isa Goolsbey HumanCyclist).
           F: (isa Goolsbey ElectricalEngineer).
           F: (feelsTowardsObject Goolsbey SimoneSiegel Affection Positive).
           F: (feelsTowardsObject Goolsbey BillJ Curiosity Positive).
           F: (comment Goolsbey "Keith Goolsbey is a member of the Cycorp technical board.").

  If Cyc had the unary predicate "dog", indicating membership in the class of all dogs (or the quality of "dogness"), assertions using this predicate could be entered with an expression such as this:

           dog: Brandy .
           F: (dog Brandy) .

  ## Comments in KE Text

  Comments (text to be read by a human, but not interpreted or entered by a program) are allowed in KE text. The comment indicator is the semi-colon (;), as in Common Lisp. Lines beginning with a semi-colon will be ignored. More precisely, any sequence of characters following a semi-colon (and including the semi-colon) up until the next occurrence of a return (line-break, line-feed) character will be ignored, except when the semi-colon occurs inside a string (a character sequence delimited by double quotes) which is not itself inside a comment.

  ## Order of Expressions

  Expressions in KE text are evaluated and processed in the order of their occurrence in the text. In general, it's a good idea to write KE text expressions about a constant only after the point where a Constant directive for that constant occurs (unless, of course, the constant is already known to Cyc).

  ## Another Example

      Constant: BillJones.
      isa: HumanCyclist CulturalAnthropologist.

      In Mt: NaiveBiologicalDescentMt.
      children: JenniferJones.

      In Mt: LanguageAndWritingSystemMt.
      Direction: :forward.
      F: (implies
              (languageSpoken ?person EasternPahariLanguage)
              (likesAsFriend BillJones ?person)).

  Evaluation of the expressions above would result in the four assertions being added to the Cyc KB. In the BaseKB, we would have:

      (#$isa #$BillJones #$HumanCyclist)
      (#$isa #$BillJones #$CulturalAnthropologist)

  In the NaiveBiologicalDescentMt, we would have:

      (#$children #$BillJones #$JenniferJones)

  And in the LanguageAndWritingSystemMt, with direction :forward (forward propagation), we would have:

      (#$implies
         (#$languageSpoken ?person #$EasternPahariLanguage)
         (#$likesAsFriend #$BillJones ?person))

  ##

  ## KE Tools

  ## Processing KE Text in the Cyc Web Interface

  The Cyc Web Interface provides a facility for processing KE Text called the Compose page. It may be accessed from the "KE-File" section of the Cyc Navigator page or from the Tools menu.

  On the Compose page, you compose KE Text expressions in a large input pane. Clicking the "Eval" button submits the completed expressions for processing.

  The KE Text Parser will process your KE Text and present its results to you before making any changes to the KB.

  If it finds syntactic errors in your expressions, it will ask you to correct them before proceeding.

  If it finds that you have referred to constants which do not yet exist, it will ask you whether you want to create them.

  When the KE Text expressions parse without error or question, it will display the proposed changes as FI operations and ask for confirmation.

  If the changes are confirmed, the operations are queued for processing on the Cyc Server Machine.

  # Appendix A: KE Text History

  KE Text syntax is just a syntactic/notational variation of CycL. To some extent, it is a holdover from when Cyc was a frame-based system and CycL was a frame-based language. Many people find it easier and faster to write some types of CycL expressions using KE Text syntax than using "canonical" FOPC-in-Lisp CycL syntax, which partly explains why KE Text syntax continues to be supported by knowledge entry tools.

  There are some aliases for directives which are retained for backward compatibility with files written for older versions of KE Text:

  - Unit = Constant
  - Access Level or AL = Direction
    - 0 = :forward
    - 4 = :backward
  - EL = Formula

  In the past you could not include references to a constant in a file/text if the constant appears in a kill expression earlier in the file/text. This would cause problems when the resulting kill expressions are processed by the Cyc Agenda, since the following expressions would reference what is now a dead (non-existent) constant.

  Go to Top