ZILF

Version 0.3, April 2010

Introduction

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.

Usage

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.

Syntax

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.

Compiler Mode

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.

Interpreter Mode

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.

Compiler Targets

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

Debugging

ZILF offers two tools for debugging games: runtime tracing and debug file generation.

Runtime Tracing

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.

Debug File Generation

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.

Library

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.

License

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:

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

ZILF History

0.3 — April 18, 2010

0.2 — July 21, 2009