]> git.wincent.com - walrat.git/blob - README.txt
Add comment about Walrus-specific :origin key
[walrat.git] / 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.