# Pyke Syntax

## Source Files

Pyke has three different kinds of source files for the three main types of knowledge bases:

1. Knowledge Fact Base (KFB) files for fact bases.
2. Knowledge Rule Base (KRB) files for rule bases.
3. Knowledge Question Base (KQB) files for question bases.

Each type of source file ends in a different file suffix: `.kfb`, `.krb` or `.kqb`.

Place all of these source files into a directory structure. Then include this directory as an argument to the knowledge_engine.engine constructor. This will recursively search your directory for these three types of source files, compile them, and load them into the engine. How you organize these files into subdirectories is up to you -- the directory structure does not matter to Pyke.

The `.kfb` and `.kqb` files are compiled into Python pickles with `.fbc` and `.qbc` suffixes.

The `.krb` files are compiled into up to three `.py` source files. The names of these `.py` files are the same as the `.krb` file, but with different endings:

- `_fc` (if there are any forward-chaining rules)
- `_bc` (if there are any backward-chaining rules) and
- `_plans` (if any of the backward-chaining rules have a plan)

These `.py` files are then automatically imported to define the rule base. This causes Python to compile them into `.pyc` or `.pyo` files.

Subsequent runs of the knowledge_engine.engine constructor only recompile the Pyke source files that have changed since the last time they were compiled.

The name of each knowledge base is the filename of the Pyke source file with the suffix removed. This must be a legal Python identifier.

## Syntax Legend

To describe this syntax, the following punctuation is used:

'any_chars'
  Required punctuation or keyword: any_chars.
a | b
  Alternation: a or b.
[a]
  Optional a.
{a}
  One or more a's. But it is understood that if a ends in a comma, the last comma is optional.
IDENTIFIER
  Any legal Python identifier. Example: foobar
NUMBER
  Any legal Python integer or floating point literal. Examples: 123, 3.14.
STRING
  Any legal Python string literal. Examples: 'Hi Mom!', u"Hi Dad!\n", r'''don't gobble my \'s!''', ur"""leave \'s alone!""".
TEXT
  Only used in KQB files. This signifies any text (any characters) other than the delimiter characters containing the `TEXT`.
PARAMETRIZED_TEXT
  Only used in KQB files. This signifies any text (any characters) through the end of the line and all text on subsequent lines that are indented at least as much as the first `PARAMETRIZED_TEXT` character on the first line. All `PARAMETRIZED_TEXT` is treated as a string.Template and may include `$IDENTIFIER` or `${IDENTIFIER}` parameters. All other `$` characters must be doubled (`$$`).
REGEXP_TEXT
  Only used in KQB files. This signifies any text (any characters) excluding an unescaped backslash (`\`) at the end. These are given to the Python's `re` module as regular expressions and must follow Python's regular expression syntax.
NL
  One or more newlines.
INDENT
  The following text must be indented to a higher level (more) than the previous text.
DEINDENT
  The following text must be indented one less level than the previous text.

## Lexical Structure

The lexical structure is much like Python. Like Python, indenting is significant. It uses the same commenting, line continuation and literal formats for strings and numbers (but doesn't use complex numbers). It also uses the same rules for forming identifiers.

The two notable exceptions to Python conventions are:

1. Identifiers may be used as strings, without requiring quotes.
   - So `foobar` is the same as `'foobar'`.
2. Singleton tuples do not require a trailing comma.
   - So `(1)` is the same as `(1,)`.

Copyright © 2007-2009 Bruce Frederiksen

Page last modified Mon, Oct 27 2008.