third_party/lisp/npg/README - depot - monorepo for the virus lounge


		     NPG a Naive Parser Generator
			   for Common Lisp

	 Copyright (C) 2003-2006, 2010 by Walter C. Pelissero
	 Copyright (C) 2021 by the TVL Authors

Vendored into depot as it is a dependency of mime4cl and upstream has
become inactive. Upstream and depot version may diverge.

Upstream Website: http://wcp.sdf-eu.org/software/#npg
Vendored Tarball: http://wcp.sdf-eu.org/software/npg-20150517T144652.tbz

This library is  free software; you can redistribute  it and/or modify
it  under  the terms  of  the GNU  Lesser  General  Public License  as
published by the  Free Software Foundation; either version  2.1 of the
License,  or (at  your option)  any  later version.   This library  is
distributed  in the  hope  that it  will  be useful,  but WITHOUT  ANY
WARRANTY;  without even  the  implied warranty  of MERCHANTABILITY  or
FITNESS FOR A  PARTICULAR PURPOSE.  See the GNU  Lesser General Public
License for more details.  You should  have received a copy of the GNU
Lesser General Public  License along with this library;  if not, write
to the  Free Software  Foundation, Inc., 59  Temple Place,  Suite 330,
Boston, MA 02111-1307 USA


This library generates on the fly (no external representation of the
parser is produced) a recursive descent parser based on the grammar
rules you have fed it with.  The parser object can then be used to
scan tokenised input.  Although a facility to produce a lexical
analiser is not provided, to write such a library is fairly easy for
most languages.  NPG parsers require your lexer to adhere to a certain
protocol to be able to communicate with them.  Examples are provided
that explain these requirements.

While quite possibly not producing the fastest parsers in town, it's
fairly simple and hopefully easy to debug.  It accepts a lispy EBNF
grammar description of arbitrary complexity with the exception of
mutually left recursive rules (watch out, they produce undetected
infinite recursion) and produces a backtracking recursive descent
parser.  Immediate left recursive rules are properly simplified,
though.

Multiple concurrent parsers are supported.

To compile, an ASDF and nix file are provided.

See the examples directory for clues on how to use it.