RubyGems - treetop - Versions diffs - 1.4.14 → 1.4.15 - Mend

treetop 1.4.14 → 1.4.15

Files changed (25) hide show

data/README.md +17 -15
data/Rakefile +5 -1
data/doc/tt.1 +83 -0
data/lib/treetop/ruby_extensions/string.rb +8 -12
data/lib/treetop/version.rb +1 -1
data/spec/compiler/character_class_spec.rb +1 -1
data/spec/compiler/grammar_compiler_spec.rb +22 -0
data/spec/compiler/test_grammar_magic_coding.treetop +8 -0
data/spec/compiler/test_grammar_magic_encoding.treetop +8 -0
data/spec/spec_helper.rb +1 -1
data/treetop.gemspec +5 -15
metadata +6 -16
data/doc/site/contribute.html +0 -124
data/doc/site/images/bottom_background.png +0 -0
data/doc/site/images/middle_background.png +0 -0
data/doc/site/images/paren_language_output.png +0 -0
data/doc/site/images/pivotal.gif +0 -0
data/doc/site/images/top_background.png +0 -0
data/doc/site/index.html +0 -102
data/doc/site/pitfalls_and_advanced_techniques.html +0 -68
data/doc/site/robots.txt +0 -5
data/doc/site/screen.css +0 -134
data/doc/site/semantic_interpretation.html +0 -245
data/doc/site/syntactic_recognition.html +0 -278
data/doc/site/using_in_ruby.html +0 -123

data/doc/site/syntactic_recognition.html DELETED Viewed

@@ -1,278 +0,0 @@
-<html><head><link href="./screen.css" rel="stylesheet" type="text/css" />
-          <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
-          </script>
-          <script type="text/javascript">
-          _uacct = "UA-3418876-1";
-          urchinTracker();
-          </script>
-        </head><body><div id="top"><div id="main_navigation"><ul><li>Documentation</li><li><a href="contribute.html">Contribute</a></li><li><a href="index.html">Home</a></li></ul></div></div><div id="middle"><div id="main_content"><div id="secondary_navigation"><ul><li>Syntax</li><li><a href="semantic_interpretation.html">Semantics</a></li><li><a href="using_in_ruby.html">Using In Ruby</a></li><li><a href="pitfalls_and_advanced_techniques.html">Advanced Techniques</a></li></ul></div><div id="documentation_content"><h1>Syntactic Recognition</h1>
-<p>Treetop grammars are written in a custom language based on parsing expression grammars. Literature on the subject of <a href="http://en.wikipedia.org/wiki/Parsing_expression_grammar">parsing expression grammars</a> (PEGs) is useful in writing Treetop grammars.</p>
-<p>PEGs have no separate lexical analyser (since the algorithm has the same time-complexity guarantees as the best lexical analysers) so all whitespace and other lexical niceties (like comments) must be explicitly handled in the grammar. A further benefit is that multiple PEG grammars may be seamlessly composed into a single parser.</p>
-<h1>Grammar Structure</h1>
-<p>Treetop grammars look like this:</p>
-<pre><code>require "my_stuff"
-grammar GrammarName
-  include Module::Submodule
-  rule rule_name
-    ...
-  end
-  rule rule_name
-    ...
-  end
-  ...
-end
-</code></pre>
-<p>The main keywords are:</p>
-<ul>
-<li><p><code>grammar</code> : This introduces a new grammar. It is followed by a constant name to which the grammar will be bound when it is loaded.</p></li>
-<li><p><code>include</code>: This causes the generated parser to include the referenced Ruby module (which may be another parser)</p></li>
-<li><p><code>require</code>: This must be at the start of the file, and is passed through to the emitted Ruby grammar</p></li>
-<li><p><code>rule</code> : This defines a parsing rule within the grammar. It is followed by a name by which this rule can be referenced within other rules. It is then followed by a parsing expression defining the rule.</p></li>
-</ul>
-<p>A grammar may be surrounded by one or more nested <code>module</code> statements, which provides a namespace for the generated Ruby parser.</p>
-<p>Treetop will emit a module called <code>GrammarName</code> and a parser class called <code>GrammarNameParser</code> (in the module namespace, if specified).</p>
-<h1>Parsing Expressions</h1>
-<p>Each rule associates a name with a <em>parsing expression</em>. Parsing expressions are a generalization of vanilla regular expressions. Their key feature is the ability to reference other expressions in the grammar by name.</p>
-<h2>Terminal Symbols</h2>
-<h3>Strings</h3>
-<p>Strings are surrounded in double or single quotes and must be matched exactly.</p>
-<ul>
-<li><code>"foo"</code></li>
-<li><code>'foo'</code></li>
-</ul>
-<h3>Character Classes</h3>
-<p>Character classes are surrounded by brackets. Their semantics are identical to those used in Ruby's regular expressions.</p>
-<ul>
-<li><code>[a-zA-Z]</code></li>
-<li><code>[0-9]</code></li>
-</ul>
-<h3>The Anything Symbol</h3>
-<p>The anything symbol is represented by a dot (<code>.</code>) and matches any single character.</p>
-<h3>Ellipsis</h3>
-<p>An empty string matches at any position and consumes no input. It's useful when you wish to treat a single symbol as part of a sequence, for example when an alternate rule will be processed using shared code.</p>
-<pre>
-    rule alts
-      ( foo bar / baz '' )
-      {
-        def value
-          elements.map{|e| e.text_value }
-        end
-      }
-    end
-</pre>
-<h2>Nonterminal Symbols</h2>
-<p>Nonterminal symbols are unquoted references to other named rules. They are equivalent to an inline substitution of the named expression.</p>
-<pre><code>rule foo
-  "the dog " bar
-end
-rule bar
-  "jumped"
-end
-</code></pre>
-<p>The above grammar is equivalent to:</p>
-<pre><code>rule foo
-  "the dog jumped"
-end
-</code></pre>
-<h2>Ordered Choice</h2>
-<p>Parsers attempt to match ordered choices in left-to-right order, and stop after the first successful match.</p>
-<pre><code>"foobar" / "foo" / "bar"
-</code></pre>
-<p>Note that if <code>"foo"</code> in the above expression came first, <code>"foobar"</code> would never be matched.
-Note also that the above rule will match <code>"bar"</code> as a prefix of <code>"barbie"</code>.
-Care is required when it's desired to match language keywords exactly.</p>
-<h2>Sequences</h2>
-<p>Sequences are a space-separated list of parsing expressions. They have higher precedence than choices, so choices must be parenthesized to be used as the elements of a sequence.</p>
-<pre><code>"foo" "bar" ("baz" / "bop")
-</code></pre>
-<h2>Zero or More</h2>
-<p>Parsers will greedily match an expression zero or more times if it is followed by the star (<code>*</code>) symbol.</p>
-<ul>
-<li><code>'foo'*</code> matches the empty string, <code>"foo"</code>, <code>"foofoo"</code>, etc.</li>
-</ul>
-<h2>One or More</h2>
-<p>Parsers will greedily match an expression one or more times if it is followed by the plus (<code>+</code>) symbol.</p>
-<ul>
-<li><code>'foo'+</code> does not match the empty string, but matches <code>"foo"</code>, <code>"foofoo"</code>, etc.</li>
-</ul>
-<h2>Optional Expressions</h2>
-<p>An expression can be declared optional by following it with a question mark (<code>?</code>).</p>
-<ul>
-<li><code>'foo'?</code> matches <code>"foo"</code> or the empty string.</li>
-</ul>
-<h2>Repetition count</h2>
-<p>A generalised repetition count (minimum, maximum) is also available.</p>
-<ul>
-<li><code>'foo' 2..</code> matches <code>'foo'</code> two or more times</li>
-<li><code>'foo' 3..5</code> matches <code>'foo'</code> from three to five times</li>
-<li><code>'foo' ..4</code> matches <code>'foo'</code> from zero to four times</li>
-</ul>
-<h2>Lookahead Assertions</h2>
-<p>Lookahead assertions can be used to make parsing expressions context-sensitive.
-The parser will look ahead into the buffer and attempt to match an expression without consuming input.</p>
-<h3>Positive Lookahead Assertion</h3>
-<p>Preceding an expression with an ampersand <code>(&amp;)</code> indicates that it must match, but no input will be consumed in the process of determining whether this is true.</p>
-<ul>
-<li><code>"foo" &amp;"bar"</code> matches <code>"foobar"</code> but only consumes up to the end <code>"foo"</code>. It will not match <code>"foobaz"</code>.</li>
-</ul>
-<h3>Negative Lookahead Assertion</h3>
-<p>Preceding an expression with a bang <code>(!)</code> indicates that the expression must not match, but no input will be consumed in the process of determining whether this is true.</p>
-<ul>
-<li><code>"foo" !"bar"</code> matches <code>"foobaz"</code> but only consumes up to the end <code>"foo"</code>. It will not match <code>"foobar"</code>.</li>
-</ul>
-<p>Note that a lookahead assertion may be used on any rule, not just a string terminal.</p>
-<pre><code>rule things
-  thing (!(disallowed / ',') following)*
-end
-</code></pre>
-<p>Here's a common use case:</p>
-<pre><code>rule word
-  [a-zA-Z]+
-end
-rule conjunction
-  primitive ('and' ' '+ primitive)*
-end
-rule primitive
-  (!'and' word ' '+)*
-end
-</code></pre>
-<p>Here's the easiest way to handle C-style comments:</p>
-<pre><code>rule c_comment
-  '/*'
-  (
-    !'*/'
-    (. / "\n")
-  )*
-  '*/'
-end
-</code></pre>
-<h2>Semantic predicates (positive and negative)</h2>
-<p>Sometimes you must execute Ruby code during parsing in order to decide how to proceed.
-This is an advanced feature, and must be used with great care, because it can change the
-way a Treetop parser backtracks in a way that breaks the parsing algorithm. See the
-notes below on how to use this feature safely.</p>
-<p>The code block is the body of a Ruby lambda block, and should return true or false, to cause this
-parse rule to continue or fail (for positive sempreds), fail or continue (for negative sempreds).</p>
-<ul>
-<li><code>&amp;{ ... }</code> Evaluate the block and fail this rule if the result is false or nil</li>
-<li><code>!{ ... }</code> Evaluate the block and fail this rule if the result is not false or nil</li>
-</ul>
-<p>The lambda is passed a single argument which is the array of syntax nodes matched so far in the
-current sequence. Note that because the current rule has not yet succeeded, no syntax node has
-yet been constructed, and so the lambda block is being run in a context where the <code>names</code> of the
-preceding rules (or as assigned by labels) are not available to access the sub-rules.</p>
-<pre><code>rule id
-  [a-zA-Z][a-zA-Z0-9]*
-  {
-    def is_reserved
-      ReservedSymbols.include? text_value
-    end
-  }
-end
-rule foo_rule
-  foo id &amp;{|seq| seq[1].is_reserved } baz
-end
-</code></pre>
-<p>Match "foo id baz" only if <code>id.is_reserved</code>. Note that <code>id</code> cannot be referenced by name from <code>foo_rule</code>,
-since that rule has not yet succeeded, but <code>id</code> has completed and so its added methods are available.</p>
-<pre><code>rule test_it
-  foo bar &amp;{|s| debugger; true } baz
-end
-</code></pre>
-<p>Match <code>foo</code> then <code>bar</code>, stop to enter the debugger (make sure you have said <code>require "ruby-debug"</code> somewhere),
-then continue by trying to match <code>baz</code>.</p>
-<p>Treetop, like other PEG parsers, achieves its performance guarantee by remembering which rules it has
-tried at which locations in the input, and what the result was. This process, called memoization,
-requires that the rule would produce the same result (if run again) as it produced the first time when
-the result was remembered. If you violate this principle in your semantic predicates, be prepared to
-fight Cerberus before you're allowed out of Hades again.</p></div></div></div><div id="bottom"></div></body></html>

data/doc/site/using_in_ruby.html DELETED Viewed

@@ -1,123 +0,0 @@
-<html><head><link href="./screen.css" rel="stylesheet" type="text/css" />
-          <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
-          </script>
-          <script type="text/javascript">
-          _uacct = "UA-3418876-1";
-          urchinTracker();
-          </script>
-        </head><body><div id="top"><div id="main_navigation"><ul><li>Documentation</li><li><a href="contribute.html">Contribute</a></li><li><a href="index.html">Home</a></li></ul></div></div><div id="middle"><div id="main_content"><div id="secondary_navigation"><ul><li><a href="syntactic_recognition.html">Syntax</a></li><li><a href="semantic_interpretation.html">Semantics</a></li><li>Using In Ruby</li><li><a href="pitfalls_and_advanced_techniques.html">Advanced Techniques</a></li></ul></div><div id="documentation_content"><h1>Using Treetop Grammars in Ruby</h1>
-<h2>Using the Command Line Compiler</h2>
-<p>You can compile <code>.treetop</code> files into Ruby source code with the <code>tt</code> command line script. <code>tt</code> takes an list of files with a <code>.treetop</code> extension and compiles them into <code>.rb</code> files of the same name. You can then <code>require</code> these files like any other Ruby script. Alternately, you can supply just one <code>.treetop</code> file and a <code>-o</code> flag to name specify the name of the output file. Improvements to this compilation script are welcome.</p>
-<pre><code>tt foo.treetop bar.treetop
-tt foo.treetop -o foogrammar.rb
-</code></pre>
-<h2>Loading A Grammar Directly</h2>
-<p>The Polyglot gem makes it possible to load <code>.treetop</code> or <code>.tt</code> files directly with <code>require</code>. This will invoke <code>Treetop.load</code>, which automatically compiles the grammar to Ruby and then evaluates the Ruby source. If you are getting errors in methods you define on the syntax tree, try using the command line compiler for better stack trace feedback. A better solution to this issue is in the works.</p>
-<p>In order to use Polyglot dynamic loading of <code>.treetop</code> or <code>.tt</code> files though, you need to require the Polyglot gem before you require the Treetop gem as Treetop will only create hooks into Polyglot for the treetop files if Polyglot is already loaded.  So you need to use:</p>
-<pre><code>require 'polyglot'
-require 'treetop'
-</code></pre>
-<p>in order to use Polyglot auto loading with Treetop in Ruby.</p>
-<h2>Instantiating and Using Parsers</h2>
-<p>If a grammar by the name of <code>Foo</code> is defined, the compiled Ruby source will define a <code>FooParser</code> class.
-To parse input, create an instance and call its <code>parse</code> method with a string.
-The parser will return the syntax tree of the match or <code>nil</code> if there is a failure.
-Note that by default, the parser will fail unless <em>all</em> input is consumed.</p>
-<pre><code>Treetop.load "arithmetic"
-parser = ArithmeticParser.new
-if parser.parse('1+1')
-  puts 'success'
-else
-  puts 'failure'
-end
-</code></pre>
-<h2>Parser Options</h2>
-<p>A Treetop parser has several options you may set.
-Some are settable permanently by methods on the parser, but all may be passed in as options to the <code>parse</code> method.</p>
-<pre><code>parser = ArithmeticParser.new
-input = 'x = 2; y = x+3;'
-# Temporarily override an option:
-result1 = parser.parse(input, :consume_all_input =&gt; false)
-puts "consumed #{parser.index} characters"
-parser.consume_all_input = false
-result1 = parser.parse(input)
-puts "consumed #{parser.index} characters"
-# Continue the parse with the next character:
-result2 = parser.parse(input, :index =&gt; parser.index)
-# Parse, but match rule `variable` instead of the normal root rule:
-parser.parse(input, :root =&gt; :variable)
-parser.root = :variable # Permanent setting
-</code></pre>
-<p>If you have a statement-oriented language, you can save memory by parsing just one statement at a time,
-and discarding the parse tree after each statement.</p>
-<h2>Learning From Failure</h2>
-<p>If a parse fails, it returns nil. In this case, you can ask the parser for an explanation.
-The failure reasons include the terminal nodes which were tried at the furthermost point the parse reached.</p>
-<pre><code>parser = ArithmeticParser.new
-result = parser.parse('4+=3')
-if !result
-  puts parser.failure_reason
-  puts parser.failure_line
-  puts parser.failure_column
-end
-=&gt;
-Expected one of (, - at line 1, column 3 (byte 3) after +
-1
-3
-</code></pre>
-<h2>Using Parse Results</h2>
-<p>Please don't try to walk down the syntax tree yourself, and please don't use the tree as your own convenient data structure.
-It contains many more nodes than your application needs, often even more than one for every character of input.</p>
-<pre><code>parser = ArithmeticParser.new
-p parser.parse('2+3')
-=&gt;
-SyntaxNode+Additive1 offset=0, "2+3" (multitive):
-  SyntaxNode+Multitive1 offset=0, "2" (primary):
-    SyntaxNode+Number0 offset=0, "2":
-      SyntaxNode offset=0, ""
-      SyntaxNode offset=0, "2"
-      SyntaxNode offset=1, ""
-    SyntaxNode offset=1, ""
-  SyntaxNode offset=1, "+3":
-    SyntaxNode+Additive0 offset=1, "+3" (multitive):
-      SyntaxNode offset=1, "+"
-      SyntaxNode+Multitive1 offset=2, "3" (primary):
-        SyntaxNode+Number0 offset=2, "3":
-          SyntaxNode offset=2, ""
-          SyntaxNode offset=2, "3"
-          SyntaxNode offset=3, ""
-        SyntaxNode offset=3, ""
-</code></pre>
-<p>Instead, add methods to the root rule which return the information you require in a sensible form.
-Each rule can call its sub-rules, and this method of walking the syntax tree is much preferable to
-attempting to walk it from the outside.</p></div></div></div><div id="bottom"></div></body></html>