package.lisp

   1 ;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Base: 10; -*-
   2 ;;;
   3 ;;; package.lisp --- cl-opossum package definition file
   4
   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.
  13 ;;
  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.
  18 ;;
  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
  25 ;;
  26 ;; Commentary:
  27
  28 ;;
  29
  30 ;;; Code:
  31
  32
  33
  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.
  51
  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}.
  56
  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}
  67
  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}.
  71
  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}
  78
  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}
  92
  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}
 104
 105    "))
 106
 107
 108 \f