Version 0.3, April 2010
ZILF, the ZIL implementation of the Future, is an interpreter and compiler for the ZIL language. It can produce Z-machine assembler code for use with ZAPF, or it can interpret top-level ZIL constructs without compiling, similar to an MDL interpreter.
ZILF is a managed application and has been tested under Microsoft .NET (on Windows) as well as Mono (on Linux and Mac OS X).
To use ZILF, you should be familiar with the ZIL language: refer to the ZIL Language Guide.
The simplest way to compile a game called "foo.zil" is with the command:
zilf foo.zil
Or, if using Mono:
mono zilf.exe foo.zil
This will generate ZAP assembly code with no debugging information and save a series of output files: a main file, "foo.zap", and a few associated files. To produce a playable game:
zapf foo.zap
More options are available: start ZILF with the "/?" or "--help" switches for details. In particular, you can change the output filename by specifying a new name after the input filename, and you can turn on debugging information with the "-d" switch or runtime tracing with "-tr".
To use ZILF as an interpreter, you can start it with no parameters to enter interactive mode. Type <QUIT> to exit. You can also interpret code from the command line or from a file with the "-e" and "-x" switches.
For a full description of the ZIL language syntax, see the ZIL Language Guide.
ZILF is case-insensitive by default. Atoms can be entered with any capitalization, and they will be printed back the way they were first entered. To run ZILF in case sensitive mode, use the "-s" switch.
ZILF defaults to Z-machine version 3, and also supports versions 4, 5, and 8. Use VERSION at top level to change the Z-machine version.
When compiling, the values obtained by evaluating all the top-level expressions are ignored: only the resulting compilation state matters. The compiled game will start by executing a ROUTINE called GO, which must be defined and may not define any local atoms.
In the interpreter modes, ZILF allows calls to compiler-oriented SUBRs such as ROUTINE, SYNTAX, and OBJECT, but their parameters may not be fully evaluated since code and data generation does not occur. In particular, this means macro calls inside routine and object definitions may not be expanded.
In interactive mode ("-i"), ZILF reads lines from the console until a complete ZIL expression is entered, then evaluates all the expressions and prints the result of the last one. Entering multiple expressions on one line will only show the result of the last expression.
In command line mode ("-e"), again, ZILF evaluates all expressions and prints the result of the last one.
In file mode ("-x"), ZILF evaluates all expressions but ignores the results. Nothing is printed unless the ZIL code calls an output SUBR such as PRINC.
By default, ZILF generates ZAPF assembly code for a version 3 game. To select another version, use the VERSION directive:
<VERSION 3> or <VERSION ZIP> <VERSION 4> or <VERSION EZIP> <VERSION 5> or <VERSION XZIP> <VERSION 8>
Define the constant RELEASEID to set the release number of the game. (This is mandatory for version 5 and above.)
ZILF produces up to four assembly files: a file called "cloak.zil" will be compiled into "cloak.zap" (main file, with routines), "cloak_data.zap" (constants, objects, and tables), "cloak_str.zap" (strings), and possibly "cloak_freq.zap" (dummy abbreviations, only created if it doesn't already exist).
ZILF offers two tools for debugging games: runtime tracing and debug file generation.
The "-tr" switch causes ZILF to generate code that prints the name and parameters of each routine call. The resulting game file will work in any interpreter. However, this adds to the size of the game code.
The "-d" switch causes ZILF to generate annotations that ZAPF can use to produce an Inform-style debugging information file. The debug file can be used with an interpreter that supports it (such as Nitfol or ZLR) to provide source-level debugging: stepping through the game one line at a time, setting breakpoints, inspecting variables, and so on. This option does not change the game at all: the annotations cause a separate debug file to be produced, but the game itself is identical.
ZILF includes a library of code for writing interactive fiction, implementing a parser and world model similar to that described in Learning ZIL by Steve Meretzky (though only a subset at present). To include it:
<INSERT-FILE "parser">
See the included game source code for an example of using the library.
The ZILF compiler is distributed under the terms of the GNU General Public License version 3 (GPLv3). See COPYING.txt for details.
The ZILF library is distributed under the following terms:
"ZILF Library Copyright (C) 2010 Jesse McGrew and Josh Lawrence
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. In the case of a binary z-code file compiled by the ZILF compiler, the appearance of the library version number within the text of the introductory title credits of your game (text that is displayed to a person who plays your z-code file via a z-code interpreter) is sufficient to satisfy the requirements for redistribution of said binary z-code file. (By default, using <V-VERSION> in your game's source code will display the library version number to a person playing your game on a z-code interpreter.)
- The names of the authors may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."