parslet 1.3.0 → 1.4.0

data/HISTORY.txt

@@ -3,8 +3,45 @@
   - prsnt? and absnt? are now finally banned into oblivion. Wasting vocals for
     the win. 
     
-= 1.3.1 / ???
+= 1.4.0 / 25May2012
 
+  + Revised documentation. A few new API features have finally made it into
+    the documentation. Examples in the documentation are now curated and
+    run against the current code so that they really really work. 
+    Also, the website generation tools have been replaced with 2012-style
+    tools. Much less pain to update now. 
+
+  + Parslet::Source now doesn't hold a StringIO, it directly holds the 
+    buffer to be parsed. The api of Source has changed a tiny bit. This change
+    has been made for speed optimisation reasons.
+
+  + :reporter argument to parse, allowing to customize error reporting within
+    wide boundaries. See issue #64 for a discussion. 
+    Included are two error reporters, one (default) with the existing error
+    tree functionality, one reporting deepest errors as defined by the above
+    ticket.
+
+  + Optimistic parse: Parsing is two phase, with the first phase assuming 
+    there will be no errors. This yields ~ 20% speed improvement in the 
+    case where the parse succeeds.
+    Also, internal error handling is now using tuples. This and other 
+    optimizations have yielded ~ 30% overall improvement. 
+
+  ! #error_tree and #cause removed from all of parslet. The 
+    Parslet::ParseFailed exception now contains a #cause field that can
+    be asked for an #ascii_tree as before. 
+    Cleaner internal error handling, not stateful in atoms anymore. Some 
+    parsers will see correct error reporting for the first time. (issue #65)
+
+  + Made it possible to pass a custom Parslet::Source implementor to #parse.
+    (see #63)
+    
+  + #parse has now a second argument that is an options hash. See 
+    Parslet::Atoms::Base#parse for documentation.
+
+  - VM engine on the way out. No benefit except for the intellectual
+    challenge.
+    
 = 1.3.0 / 5Mar2012
 
   ! Parslet::Transform::Context is now much more well-behaved. It has

data/README

@@ -18,26 +18,38 @@ SYNOPSIS
   require 'parslet'
   include Parslet
 
-  # Constructs a parser using a Parser Expression Grammar like DSL: 
-  parser =  str('"') >> 
-            (
-              str('\\') >> any |
-              str('"').absnt? >> any
-            ).repeat.as(:string) >> 
-            str('"')
-  
-  # Parse the string and capture parts of the interpretation (:string above)        
-  tree = parser.parse('"This is a \\"String\\" in which you can escape stuff"')
-
-  tree # => {:string=>"This is a \\\"String\\\" in which you can escape stuff"}
-
-  # Here's how you can grab results from that tree:
-
-  transform = Parslet::Transform.new do
-    rule(:string => simple(:x)) { 
-      puts "String contents: #{x}" }
+  # parslet parses strings
+  str('foo').
+    parse('foo') # => "foo"@0
+
+  # it matches character sets
+  match['abc'].parse('a') # => "a"@0
+  match['abc'].parse('b') # => "b"@0
+  match['abc'].parse('c') # => "c"@0
+
+  # and it annotates its output
+  str('foo').as(:important_bit).
+    parse('foo') # => {:important_bit=>"foo"@0}
+
+  # you can construct parsers with just a few lines
+  quote = str('"')
+  simple_string = quote >> (quote.absent? >> any).repeat >> quote
+
+  simple_string.
+    parse('"Simple Simple Simple"') # => "\"Simple Simple Simple\""@0
+
+  # or by making a fuss about it 
+  class Smalltalk < Parslet::Parser
+    root :smalltalk
+
+    rule(:smalltalk) { statements }
+    rule(:statements) { 
+      # insert smalltalk parser here (outside of the scope of this readme)
+    }
   end
-  transform.apply(tree)
+
+  # and then
+  Smalltalk.new.parse('smalltalk')
 
 COMPATIBILITY
 
@@ -53,6 +65,6 @@ ruby-1.8.7-p334 for better results.
 
 STATUS 
 
-At version 1.3.0 - See HISTORY.txt for changes.
+At version 1.4.0 - See HISTORY.txt for changes.
 
-(c) 2010 Kaspar Schiess
+(c) 2010, 2011, 2012 Kaspar Schiess

data/example/deepest_errors.rb

@@ -0,0 +1,131 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+# This example demonstrates how to do deepest error reporting, as invented 
+# by John Mettraux (issue #64).
+
+require 'parslet'
+require 'parslet/convenience'
+
+def prettify(str)
+  puts " "*3 + " "*4 + "." + " "*4 + "10" + " "*3 + "." + " "*4 + "20"
+  str.lines.each_with_index do |line, index|
+    printf "%02d %s\n", 
+      index+1, 
+      line.chomp
+  end
+end
+
+class Parser < Parslet::Parser
+  # commons
+
+  rule(:space) { match('[ \t]').repeat(1) }
+  rule(:space?) { space.maybe }
+
+  rule(:newline) { match('[\r\n]') }
+
+  rule(:comment) { str('#') >> match('[^\r\n]').repeat }
+
+  rule(:line_separator) {
+    (space? >> ((comment.maybe >> newline) | str(';')) >> space?).repeat(1)
+  }
+
+  rule(:blank) { line_separator | space }
+  rule(:blank?) { blank.maybe }
+
+  rule(:identifier) { match('[a-zA-Z0-9_]').repeat(1) }
+
+  # res_statement
+
+  rule(:reference) {
+    (str('@').repeat(1,2) >> identifier).as(:reference)
+  }
+
+  rule(:res_action_or_link) {
+    str('.').as(:dot) >> (identifier >> str('?').maybe ).as(:name) >> str('()')
+  }
+
+  rule(:res_actions) {
+    (
+      reference
+    ).as(:resources) >>
+    (
+      res_action_or_link.as(:res_action)
+    ).repeat(0).as(:res_actions)
+  }
+
+  rule(:res_statement) {
+    res_actions >>
+    (str(':') >> identifier.as(:name)).maybe.as(:res_field)
+  }
+
+  # expression
+
+  rule(:expression) {
+    res_statement
+  }
+
+  # body
+
+  rule(:body) {
+    (line_separator >> (block | expression)).repeat(1).as(:body) >>
+    line_separator
+  }
+
+  # blocks
+
+  rule(:begin_block) {
+    (str('concurrent').as(:type) >> space).maybe.as(:pre) >>
+    str('begin').as(:begin) >>
+    body >>
+    str('end')
+  }
+
+  rule(:define_block) {
+    str('define').as(:define) >> space >>
+    identifier.as(:name) >> str('()') >>
+    body >>
+    str('end')
+  }
+
+  rule(:block) {
+    define_block | begin_block
+  }
+
+  # root
+
+  rule(:radix) {
+    line_separator.maybe >> block >> line_separator.maybe
+  }
+
+  root(:radix)
+end
+
+ds = [
+  %{
+    define f()
+      @res.name
+    end
+  },
+  %{
+    define f()
+      begin
+        @res.name
+      end
+    end
+  }
+]
+
+ds.each do |d|
+
+  puts '-' * 80
+  prettify(d)
+
+  parser = Parser.new
+
+  begin
+    parser.parse_with_debug(d, 
+      :reporter => Parslet::ErrorReporter::Deepest.new)
+  end
+end
+
+puts '-' * 80

data/example/email_parser.rb

@@ -4,6 +4,7 @@
 
 $:.unshift File.dirname(__FILE__) + "/../lib"
 require 'parslet'
+require 'parslet/convenience'
 
 class EmailParser < Parslet::Parser
   rule(:space) { match('\s').repeat(1) }
@@ -48,9 +49,4 @@ unless ARGV[0]
   STDOUT.puts "since you haven't specified any EMAIL_ADDR, for testing purposes we're using a.b.c.d@gmail.com"
 end
 
-begin
-  p sanitizer.apply(parser.parse(ARGV[0] || 'a.b.c.d@gmail.com'))
-rescue Parslet::ParseFailed => error
-  puts error
-  puts parser.error_tree
-end
+p sanitizer.apply(parser.parse_with_debug(ARGV[0] || 'a.b.c.d@gmail.com'))

data/example/ignore.rb

@@ -11,9 +11,9 @@ class IgnoreParslet < Parslet::Atoms::Base
     @parslet.to_s(prec)
   end
   def try(source, context)
-    result = @parslet.try(source, context)
+    success, value = result = @parslet.try(source, context)
     
-    return success(nil) unless result.error?
+    return succ(nil) if success
     return result
   end
   

data/example/json.rb

@@ -107,9 +107,6 @@ module MyJson
     out = transformer.apply(tree)
 
     out
-
-  rescue Parslet::ParseFailed => e
-    puts e, parser.root.error_tree
   end
 end
 

data/example/modularity.rb

@@ -0,0 +1,47 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'pp'
+require "parslet"
+
+# Demonstrates modular parsers, split out over many classes. Please look at
+# ip_address.rb as well.
+
+module ALanguage
+  include Parslet
+    
+  # Parslet rules are really a special kind of method. Mix them into your
+  # classes!
+  rule(:a_language) { str('aaa') }
+end
+
+# Parslet parsers are parslet atoms as well. Create an instance and chain them
+# to your other rules. 
+#
+class BLanguage < Parslet::Parser
+  root :blang
+  
+  rule(:blang) { str('bbb') }
+end
+
+# Parslet atoms are really Ruby values, pass them around. 
+c_language = Parslet.str('ccc')
+  
+class Language < Parslet::Parser
+  def initialize(c_language)
+    @c_language = c_language
+    super()
+  end
+  
+  root :root
+
+  include ALanguage
+  
+  rule(:root) { str('a(') >> a_language >> str(')') >> space |
+                str('b(') >> BLanguage.new >> str(')') >> space | 
+                str('c(') >> @c_language >> str(')') >> space }
+  rule(:space) { str(' ').maybe }
+end
+
+Language.new(c_language).parse('a(aaa)')
+Language.new(c_language).parse('b(bbb)')
+Language.new(c_language).parse('c(ccc)')

data/example/nested_errors.rb

@@ -0,0 +1,132 @@
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'parslet'
+require 'parslet/convenience'
+
+# This example demonstrates tree error reporting in a real life example. 
+# The parser code has been contributed by John Mettraux.
+
+def prettify(str)
+  puts " "*3 + " "*4 + "." + " "*4 + "10" + " "*3 + "." + " "*4 + "20"
+  str.lines.each_with_index do |line, index|
+    printf "%02d %s\n", 
+      index+1, 
+      line.chomp
+  end
+end
+
+class Parser < Parslet::Parser
+
+  # commons
+
+  rule(:space) { match('[ \t]').repeat(1) }
+  rule(:space?) { space.maybe }
+
+  rule(:newline) { match('[\r\n]') }
+
+  rule(:comment) { str('#') >> match('[^\r\n]').repeat }
+
+  rule(:line_separator) {
+    (space? >> ((comment.maybe >> newline) | str(';')) >> space?).repeat(1)
+  }
+
+  rule(:blank) { line_separator | space }
+  rule(:blank?) { blank.maybe }
+
+  rule(:identifier) { match('[a-zA-Z0-9_]').repeat(1) }
+
+  # res_statement
+
+  rule(:reference) {
+    (str('@').repeat(1,2) >> identifier).as(:reference)
+  }
+
+  rule(:res_action_or_link) {
+    str('.').as(:dot) >> (identifier >> str('?').maybe ).as(:name) >> str('()')
+  }
+
+  rule(:res_actions) {
+    (
+      reference
+    ).as(:resources) >>
+    (
+      res_action_or_link.as(:res_action)
+    ).repeat(0).as(:res_actions)
+  }
+
+  rule(:res_statement) {
+    res_actions >>
+    (str(':') >> identifier.as(:name)).maybe.as(:res_field)
+  }
+
+  # expression
+
+  rule(:expression) {
+    res_statement
+  }
+
+  # body
+
+  rule(:body) {
+    (line_separator >> (block | expression)).repeat(1).as(:body) >>
+    line_separator
+  }
+
+  # blocks
+
+  rule(:begin_block) {
+    (str('concurrent').as(:type) >> space).maybe.as(:pre) >>
+    str('begin').as(:begin) >>
+    body >>
+    str('end')
+  }
+
+  rule(:define_block) {
+    str('define').as(:define) >> space >>
+    identifier.as(:name) >> str('()') >>
+    body >>
+    str('end')
+  }
+
+  rule(:block) {
+    define_block | begin_block
+  }
+
+  # root
+
+  rule(:radix) {
+    line_separator.maybe >> block >> line_separator.maybe
+  }
+
+  root(:radix)
+end
+
+
+ds = [
+  %{
+    define f()
+      @res.name
+    end
+  },
+  %{
+    define f()
+      begin
+        @res.name
+      end
+    end
+  }
+]
+
+ds.each do |d|
+
+  puts '-' * 80
+  prettify(d)
+
+  parser = Parser.new
+
+  begin
+    parser.parse_with_debug(d)
+  end
+end
+
+puts '-' * 80