Code cleanup againt SBCL, CMUCL and ECL.
[cl-opossum.git] / package.lisp
blobd1915224c4e66dc34bfce294b845a76d4c7752e5
1 ;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Base: 10; -*-
2 ;;;
3 ;;; package.lisp --- cl-opossum package definition file
5 ;; Copyright (C) 2008 Utz-Uwe Haus <lisp@uuhaus.de>
6 ;;
7 ;; $Id$
8 ;;
9 ;; This code is free software; you can redistribute it and/or modify
10 ;; it under the terms of the version 2.1 of the GNU Lesser General
11 ;; Public License as published by the Free Software Foundation, as
12 ;; clarified by the lisp prequel found in LICENSE.
14 ;; This code is distributed in the hope that it will be useful, but
15 ;; without any warranty; without even the implied warranty of
16 ;; merchantability or fitness for a particular purpose. See the GNU
17 ;; Lesser General Public License for more details.
19 ;; Version 2.1 of the GNU Lesser General Public License is in the file
20 ;; LICENSE that was distributed with this file. If it is not
21 ;; present, you can access it from
22 ;; http://www.gnu.org/copyleft/lgpl.txt (until superseded by a
23 ;; newer version) or write to the Free Software Foundation, Inc., 59
24 ;; Temple Place, Suite 330, Boston, MA 02111-1307 USA
26 ;; Commentary:
28 ;;
30 ;;; Code:
34 (defpackage #:opossum
35 (:use #:CL)
36 ;; types
37 (:export #:context)
38 ;; special variables
39 (:export #:*context* #:*trace*)
40 ;; low-level user interface
41 (:export #:generate-parser-file #:generate-parser-package
42 #:get-string-parser #:get-file-parser #:get-stream-parser
43 #:parse-file #:parse-string #:parse-stream
44 #:read-stream #:read-file)
45 ;; high-level user interface
46 (:export #:make-string-parser
47 #:make-file-parser
48 #:make-stream-parser)
49 (:documentation
50 "This package provides a parser generator for Parsing Expression Grammars (PEGs) for Common Lisp.
52 The canonical project home page is @a[http://primaldual.de/cl-opossum/]{here}, the
53 @a[http://git.or.cz/]{GIT repository} is hosted on @a[http://repo.or.cz/]{repo.or.cz} under the
54 project @a[http://repo.or.cz/w/cl-opossum.git]{cl-opossum.git}. You can download a
55 snapshot of the current master branch head @a[http://repo.or.cz/w/cl-opossum.git?a=snapshot]{here}.
57 @begin[Installation]{section}
58 To make use of this package you will need
59 @begin{itemize}
60 @item{A Common Lisp Environment. @a[http://sbcl.sourceforge.net/]{SBCL} is a good free candidate. See
61 the @a[http://wiki.alu.org/Implementation]{ALU Wiki} for a list of choices.}
62 @item{(Optionally) @a[http://www.gnu.org/emacs]{Emacs} with @a[http://common-lisp.net/project/slime/]{SLIME} installed.}
63 @item{The @a[http://www.cliki.net/asdf]{ASDF} System definition package. If you chose SBCL above then you already have it.}
64 @item{This package, either as a @a[http://repo.or.cz/w/cl-opossum.git?a=snapshot]{snapshot} or through
65 git by @a[git://repo.or.cz/cl-opossum.git]{git protocol} or @a[http://repo.or.cz/r/cl-opossum.git]{http}.}
66 @end{itemize}
68 If you are using @a[http://www.debian.org]{Debian GNU/Linux} you can fetch the prerequistites by
69 @pre{apt-get install emacs slime sbcl}
70 A one-step solution may be @a[http://www.gigamonkeys.com/lispbox/]{Lispbox}.
72 If any of the above does not make sense to you, you may want to
73 start learning more about Common Lisp by reading Peter Seibel's
74 @em{Practical Common Lisp}, a great Lisp book suitable as
75 online <a href=\"http://www.gigamonkeys.com/book/\">Common Lisp tutorial</a>
76 but also available in printed form with ISBN 978-1590592397.
77 @end{section}
79 @begin[Quick start]{section}
80 If you want to get a quick start, load the package into your lisp and evaluate
81 @begin{pre}
82 CL-USER> (asdf:operate 'asdf:load-op :opossum)
83 ; registering #<SYSTEM OPOSSUM> as OPOSSUM
84 NIL
85 CL-USER> (setq *p* (opossum:make-string-parser \"example.peg\"))
86 \[lots of output scrolling by\]
87 CL-USER> (setq *t* (funcall *p* \"14+7*(1+1)*2\"))
88 ...
89 CL-USER>(eval *t*)
90 @end{pre}
91 @end{section}
93 @begin[Literature]{section}
94 PEG parsers are a family of recursive descent parsers suitable to parsing context free grammars,
95 in linear time if memoization is used.
96 See @a[http://pdos.csail.mit.edu/~baford/packrat/]{Bryan Ford}'s home page for details.
97 @end{section}
98 @begin[Authors]{section}
99 This code is released under the GNU Lesser Public License with Lisp clarifications and
100 copyrighted by
101 @a[http://www.math.uni-magdeburg.de/~haus/]{Utz-Uwe Haus}
102 Please see the file @code{LICENSE} in the distribution for details.
103 @end{section}