-# Zork Implentation Language
-This document covers the Zork Implementation Language, as originally
-developed and used by Infocom for their games.
+# Introduction
+This document covers the Zork Implementation Language, or ZIL for
+short, as originally developed and used by Infocom for their games.
+
+ZIL is a subset of the MIT Design Language, or MDL for short, and
+pronounced as "Muddle". MDL is itself based on classic LISP.
## Format
This document is written using CommonMark, a markup language. More
<https://gnu.org/licenses/>.
## Definitions
-
A "definition" is used to describe a room, object, routine, etc. in or
used by the game. Each definition consists of a number of properties,
flags, and/or instructions. A program written in ZIL can be thought of
-as consisting of one or more of these definitions. Definitions,
-properties, flags, and instructions include brackets which must be
-correctly paired and nested.
+as consisting of two or more of these definitions. At a minimum, a
+program must define which version it is to be compiled for and contain
+at least one routine named GO from which execution begins.
+Definitions, properties, flags, and instructions include brackets
+which must be correctly paired and nested.
+
+## Z-machine versions
+Infocom made 6 versions of the Z-machine. The community made 2 more,
+for a total of 8, mostly to support larger story files. To define
+which version of the Z-machine a program is to be compiled for, it
+must contain a VERSION definition at the top level, outside any other
+definitions, in the following format, using this BNF-style syntax:
+
+ <version-definition> ::= "<" "VERSION" <version-number> ">"
+
+ <version-number> ::= "ZIP" | "EZIP" | "XZIP" | "YZIP" | "1" | "2"
+ | "3" | "4" | "5" | "6" | "7" | "8"
+
+ZIP is equivalent to version 3, EZIP to version 4, XZIP to version 5,
+and YZIP to version 6.
+
+## Comments
+Comments are ignored by the compiler. A comment begins with a
+semicolon (;) and continues until the end of the line. A multiline
+comment also begins with a semicolon but is enclosed in double quotes.
+However, single line comments may also be enclosed in double quotes.
+While comments may be placed anywhere in a source code file, a comment
+may not be placed inside an atom.
+
+## Parser
+The purpose of the parser is to receive and process the player's
+input. Its primary responsibility is to determine the player's
+intended action along with any objects that may be referred to.
+
+The player's action is referred to internally as the PRSA (think "A"
+for action like "EAT", the direct object as PRSO (think "O" for
+"object") and the indirect object as PRSI (think "I" for indirect.)
+
+For an example, the command "KILL TROLL WITH SWORD" would set the PRSA
+to KILL and the PRSO to TROLL and PRSI to SWORD. It is important to
+note that not all instructions from the player will necessarily have
+all three things, but a PRSA is required in all cases and you can't
+have a PRSI without also having a PRSO. In cases where there is no
+PRSI or PRSO, they are set to false.
+
+Note that the PRSA isn't simply the word that the player entered. The
+PRSA from a given sentence is determined by the syntax definitions in
+the game. An example being: The player might type "CONSUME APPLE" but
+in the game's syntax definitions, the PRSA associated with "consume"
+might be EAT.
## Syntax Definitions
Syntax definitions are used by the parser to determine valid sentence
-structures.
+structures. Each entry must correspond to this format:
A simple example might be:
Using this example, should the parser match the player's input to
"xyzzy" then the PRSA is set to magic. PRSI and PRSO would be set to
false.
+
+## Syntax Tokens
projects / substrate.git / blobdiff