; -*- mode:     Text -*- --------------------------------------------------- ;
; File:         README
; Author:       Joachim H. Laubsch
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; *************************************************************************
;;; Copyright (c) 1989, Hewlett-Packard Company
;;; All rights reserved.
;;;
;;; Use and copying of this software and preparation of derivative works
;;; based upon this software are permitted.  Any distribution of this
;;; software or derivative works must comply with all applicable United
;;; States export control laws.
;;; 
;;; This software is made available AS IS, and Hewlett-Packard Company
;;; makes no warranty about the software, its performance or its conformity
;;; to any specification.
;;; 
;;; Suggestions, comments and requests for improvements are welcome
;;; and should be mailed to laubsch@hplabs.hpl.hp.com
;;; *************************************************************************

Zebu is a kind of YACC, and was originally implemented in Scheme by
William M. Wells III.  It generates an LALR(1) parsing table. To parse
a string with a grammar, only this table and a driver need to be
loaded.

The present version of Zebu is an extension, rewritten in Common Lisp.
It contains the ability to define several grammars and parsers
simultaneously, a declarative framework for specifying the semantics,
capabilities to define and use meta-grammars (grammars to express a
grammar in), generation of unparsers (generators) using a 'reversible
grammar' notation, as well as efficiency related improvements.  

The current version compiles a grammar with 300 productions (including
dumping of the tables to disk) in approx 2 minutes and 30 seconds on a
HP 9000/370.

This implementation has been tested in Lucid CL, Allegro CL, and
MCL 2.0b.

For documentation look into the doc/ directory:

	zebu.text 	contains an introduction to the original
			 Scheme version.
	Zebu_intro.tex 	contains an introduction to the Common Lisp
			 version and the enhancements.  This is a
	                 LaTeX file.

The test/ directory contains a few examples.

The CL version uses a simpler grammar specification language, which
somewhat resembles Refine's DIALECT facility.

Other features, like grammar-names, string- or symbol-delimiters,
parameterization of lexical analysis, and modes of interpretation of
the grammar actions are also documented in zebu-loader.l

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;                                Installation
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

The Zebu runtime system is all you need if you want to use the
parser/generator that was produced by the compiler (in form of a .tab
file).

The Zebu-compiler is necessary in order to convert the external
grammar description (in form of a .zb file) into a LALR(1) parsing
table (in form of a .tab file), and associated printers and semantic
functions (in form of a <grammar-name>-domain.l file).

There are 2 ways to install Zebu:

(1) Installation using DEFSYSTEM

This makes it easier to load and compile grammars, since one does not
need to remember the location of a module in a directory structure.
 
To install follow the directions in ZEBU-sys.lisp.  You need the portable
DEFSYS for that.  This is available as DEFSYS.tar.Z at the same place
as Zebu.tar.Z.

The file ZEBU-sys.lisp is used to load or compile Zebu, which actually
consists of two systems (defined by defsystem)

	Zebu		        the runtime system
	Zebu-compiler	        the compiler

(2) Installation without DEFSYSTEM

 If you don't want to use defsystem, load the file COMPILE-ZEBU.lisp,
which compiles the files in the right order.  You should check whether
the pathname for the Zebu directory is correct in your installation.


After loading the file ZEBU-init.l you can call:

       (zb:zebu)                to load the runtime system
or
       (zb:zebu-compiler)       to load the grammar compiler

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

If you need help or have suggestions, send a message to

         laubsch@hplabs.hpl.hp.com

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;                                End of README
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
