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*)
  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. OPOSSUM currently does not implement memoization, but this will
  96    be fixed soon. 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