README.txt

   1 = Walrat =
   2
   3 Walrat is a Parsing Expression Grammar (PEG) parser generator, written in Ruby,
   4 that produces "packrat" (memoizing) parsers capable of lexing, parsing and
   5 building arbitrarily complex Abstract Syntax Trees (ASTs).
   6
   7 Walrat was originally written in 2007 as part of the Walrus object-oriented
   8 templating system. In 2010 it was extracted into a separate gem for easier
   9 reuse in other projects. The Walrus grammar is an excellent example of some of
  10 the more advanced parsing techniques that can be achieved using Walrat,
  11 including:
  12
  13 * dynamic parser generation at runtime via a simple DSL
  14 * standard PEG constructs such as ordered choice, concatenation, repetition
  15 and predicates
  16 * string and regular-expression based "parslets"
  17 * arbitrarily complex proc/lambda based "parslets"
  18 * convenient and customizable inter-token skipping behavior (whitespace
  19 skipping)
  20 * left-recursion
  21 * left-associative and right associative productions
  22 * dynamic AST node synthesis
  23 * addition of custom behavior to AST nodes (such as compilation behavior)
  24 through custom Ruby code
  25 * multiline comments, including nested multiline comments
  26 * "island" parsers for processing "here" documents and include files
  27
  28
  29 == Example ==
  30
  31     require 'rubygems'
  32     require 'walrat'
  33
  34     class MySuperGrammar < Walrat::Grammar
  35       starting_symbol :sequence
  36       skipping        :whitespace
  37       rule            :whitespace, /\s+/
  38       rule            :sequence, :digits & (',' & :digits).zero_or_more
  39       rule            :digits, /\d+/
  40     end
  41
  42     grammar = MySuperGrammar.new
  43
  44     begin
  45       grammar.parse 'hello!'
  46     rescue Walrat::ParseError => e
  47       puts "bad input: failed to parse (#{e})"
  48     end
  49
  50     result = grammar.parse '123, 456, 789'
  51     puts "good input: parsed (#{result})"
  52
  53 Running this file produces the following output:
  54
  55     bad input: failed to parse (non-matching characters "hello!" while parsing regular expression "/\A(?-mix:\d+)/")
  56     good input: parsed (123,456,789)
  57
  58
  59 == System requirements ==
  60
  61 Walrat currently only supports Ruby 1.8, although Ruby 1.9 compatibility work
  62 is underway. JRuby is not yet officially supported, although many complex
  63 grammars (such as the Walrus grammar) have already been successfully tested.
  64
  65
  66 == Installation ==
  67
  68     sudo gem install walrat
  69
  70
  71 == Development ==
  72
  73     $ git clone git://git.wincent.com/walrat.git
  74     $ cd walrat
  75     $ bundle install --binstubs
  76     $ bin/spec spec
  77
  78
  79 == Website ==
  80
  81 The official website can be found at:
  82
  83   https://wincent.com/products/walrat
  84
  85 The official Git repository can be browsed at:
  86
  87   http://git.wincent.com/walrat.git
  88
  89 The repository is mirrored hourly to GitHub and Gitorious:
  90
  91   http://github.com/wincent/walrat
  92   http://gitorious.org/walrat/walrat
  93
  94
  95 == Author ==
  96
  97 Walrat is written and maintained by Wincent Colaiuta <win@wincent.com>.
  98
  99
 100 == Donations ==
 101
 102 Walrat is free software released under the terms of the BSD license.
 103 If you would like to support further development you can make a donation via
 104 PayPal to win@wincent.com:
 105
 106   https://wincent.com/products/walrat/donations
 107
 108
 109 == License ==
 110
 111 Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
 112
 113 Redistribution and use in source and binary forms, with or without
 114 modification, are permitted provided that the following conditions are met:
 115
 116 1. Redistributions of source code must retain the above copyright notice,
 117    this list of conditions and the following disclaimer.
 118 2. Redistributions in binary form must reproduce the above copyright notice,
 119    this list of conditions and the following disclaimer in the documentation
 120    and/or other materials provided with the distribution.
 121
 122 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 123 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 124 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 125 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
 126 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 127 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 128 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 129 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 130 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 131 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 132 POSSIBILITY OF SUCH DAMAGE.