parslet 1.0.1 → 1.1.0

data/lib/parslet/atoms/lookahead.rb

@@ -9,44 +9,32 @@ class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
   attr_reader :bound_parslet
   
   def initialize(bound_parslet, positive=true) # :nodoc:
+    super()
+    
     # Model positive and negative lookahead by testing this flag.
     @positive = positive
     @bound_parslet = bound_parslet
+    @error_msgs = {
+      :positive => "lookahead: #{bound_parslet.inspect} didn't match, but should have", 
+      :negative => "negative lookahead: #{bound_parslet.inspect} matched, but shouldn't have"
+    }
   end
   
-  def try(io) # :nodoc:
-    pos = io.pos
-
-    failed = true
-    catch(:error) {
-      bound_parslet.apply(io)
-      failed = false
-    }
-    return failed ? fail(io) : success(io)
+  def try(source, context) # :nodoc:
+    pos = source.pos
 
+    value = bound_parslet.apply(source, context)
+    return success(nil) if positive ^ value.error?
+    
+    return error(source, @error_msgs[:positive]) if positive
+    return error(source, @error_msgs[:negative])
+    
+  # This is probably the only parslet that rewinds its input in #try.
+  # Lookaheads NEVER consume their input, even on success, that's why. 
   ensure 
-    io.pos = pos
+    source.pos = pos
   end
   
-  # TODO Both of these will produce results that could be reduced easily. 
-  # Maybe do some shortcut reducing here?
-  def fail(io) # :nodoc:
-    if positive
-      error(io, "lookahead: #{bound_parslet.inspect} didn't match, but should have")
-    else
-      return nil
-    end
-  end
-  def success(io) # :nodoc:
-    if positive
-      return nil
-    else
-      error(
-        io, 
-        "negative lookahead: #{bound_parslet.inspect} matched, but shouldn't have")
-    end
-  end
-
   precedence LOOKAHEAD
   def to_s_inner(prec) # :nodoc:
     char = positive ? '&' : '!'

data/lib/parslet/atoms/named.rb

@@ -8,13 +8,18 @@
 class Parslet::Atoms::Named < Parslet::Atoms::Base
   attr_reader :parslet, :name
   def initialize(parslet, name) # :nodoc:
+    super()
+
     @parslet, @name = parslet, name
   end
   
-  def apply(io) # :nodoc:
-    value = parslet.apply(io)
-    
-    produce_return_value value
+  def apply(source, context) # :nodoc:
+    value = parslet.apply(source, context)
+
+    return value if value.error?
+    success(
+      produce_return_value(
+        value.result))
   end
   
   def to_s_inner(prec) # :nodoc:
@@ -26,6 +31,6 @@ class Parslet::Atoms::Named < Parslet::Atoms::Base
   end
 private
   def produce_return_value(val) # :nodoc:
-    { name => flatten(val) }
+    { name => flatten(val, true) }
   end
 end

data/lib/parslet/atoms/re.rb

@@ -1,6 +1,6 @@
 # Matches a special kind of regular expression that only ever matches one
-# character at a time. Useful members of this family are: character ranges, 
-# \w, \d, \r, \n, ...
+# character at a time. Useful members of this family are: <code>character
+# ranges, \\w, \\d, \\r, \\n, ...</code>
 #
 # Example: 
 #
@@ -10,15 +10,24 @@
 class Parslet::Atoms::Re < Parslet::Atoms::Base
   attr_reader :match, :re
   def initialize(match) # :nodoc:
+    super()
+
     @match = match
     @re    = Regexp.new(match, Regexp::MULTILINE)
+    @error_msgs = {
+      :premature  => "Premature end of input", 
+      :failed     => "Failed to match #{match.inspect[1..-2]}"
+    }
   end
 
-  def try(io) # :nodoc:
-    s = io.read(1)
-    error(io, "Premature end of input") unless s
-    error(io, "Failed to match #{match.inspect[1..-2]}") unless s.match(re)
-    return s
+  def try(source, context) # :nodoc:
+    error_pos = source.pos
+    s = source.read(1)
+    
+    return error(source, @error_msgs[:premature], error_pos) unless s
+    return error(source, @error_msgs[:failed], error_pos) unless s.match(re)
+    
+    return success(s)
   end
 
   def to_s_inner(prec) # :nodoc:

data/lib/parslet/atoms/repetition.rb

@@ -9,29 +9,36 @@
 class Parslet::Atoms::Repetition < Parslet::Atoms::Base  
   attr_reader :min, :max, :parslet
   def initialize(parslet, min, max, tag=:repetition)
+    super()
+
     @parslet = parslet
     @min, @max = min, max
     @tag = tag
+    @error_msgs = {
+      :minrep  => "Expected at least #{min} of #{parslet.inspect}"
+    }
   end
   
-  def try(io) # :nodoc:
+  def try(source, context) # :nodoc:
     occ = 0
     result = [@tag]   # initialize the result array with the tag (for flattening)
-    catch(:error) {
-      result << parslet.apply(io)
+    start_pos = source.pos
+    loop do
+      value = parslet.apply(source, context)
+      break if value.error?
+
       occ += 1
+      result << value.result
       
       # If we're not greedy (max is defined), check if that has been 
       # reached. 
-      return result if max && occ>=max
-      redo
-    }
+      return success(result) if max && occ>=max
+    end
     
     # Greedy matcher has produced a failure. Check if occ (which will
     # contain the number of sucesses) is in {min, max}.
-    # p [:repetition, occ, min, max]
-    error(io, "Expected at least #{min} of #{parslet.inspect}") if occ < min
-    return result
+    return error(source, @error_msgs[:minrep], start_pos) if occ < min
+    return success(result)
   end
   
   precedence REPETITION

data/lib/parslet/atoms/sequence.rb

@@ -7,7 +7,12 @@
 class Parslet::Atoms::Sequence < Parslet::Atoms::Base
   attr_reader :parslets
   def initialize(*parslets)
+    super()
+
     @parslets = parslets
+    @error_msgs = {
+      :failed  => "Failed to match sequence (#{self.inspect})"
+    }
   end
   
   def >>(parslet) # :nodoc:
@@ -15,16 +20,17 @@ class Parslet::Atoms::Sequence < Parslet::Atoms::Base
     self
   end
   
-  def try(io) # :nodoc:
-    catch(:error) {
-      return [:sequence]+parslets.map { |p| 
-        # Save each parslet as potentially offending (raising an error). 
-        @offending_parslet = p
-        p.apply(io) 
-      }
-    }
+  def try(source, context) # :nodoc:
+    success([:sequence]+parslets.map { |p| 
+      # Save each parslet as potentially offending (raising an error). 
+      @offending_parslet = p
+
+      value = p.apply(source, context) 
+
+      return error(source, @error_msgs[:failed]) if value.error?
 
-    error(io, "Failed to match sequence (#{self.inspect})")
+      value.result
+    })
   end
       
   precedence SEQUENCE

data/lib/parslet/atoms/str.rb

@@ -7,16 +7,26 @@
 class Parslet::Atoms::Str < Parslet::Atoms::Base
   attr_reader :str
   def initialize(str)
+    super()
+
     @str = str
+    @error_msgs = {
+      :premature  => "Premature end of input", 
+      :failed     => "Expected #{str.inspect}, but got "
+    }
   end
   
-  def try(io) # :nodoc:
-    old_pos = io.pos
-    s = io.read(str.size)
-    error(io, "Premature end of input") unless s && s.size==str.size
-    error(io, "Expected #{str.inspect}, but got #{s.inspect}", old_pos) \
-      unless s==str
-    return s
+  def try(source, context) # :nodoc:
+    error_pos = source.pos
+    s = source.read(str.size)
+
+    return success(s) if s == str
+    
+    # assert: s != str
+
+    # Failures: 
+    return error(source, @error_msgs[:premature]) unless s && s.size==str.size
+    return error(source, @error_msgs[:failed]+s.inspect, error_pos) 
   end
   
   def to_s_inner(prec) # :nodoc:

data/lib/parslet/atoms/visitor.rb

@@ -0,0 +1,75 @@
+# Augments all parslet atoms with an accept method that will call back 
+# to the visitor given.
+
+# 
+module Parslet::Atoms
+  class Base
+    def accept(visitor)
+      raise NotImplementedError, "No visit method on #{self.class.name}."
+    end
+  end
+  
+  class Str
+    # Call back visitors #str method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.str(str)
+    end
+  end
+  
+  class Entity
+    # Call back visitors #entity method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.entity(name, context, block)
+    end
+  end
+  
+  class Named
+    # Call back visitors #named method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.named(name, parslet)
+    end
+  end
+  
+  class Sequence
+    # Call back visitors #sequence method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.sequence(parslets)
+    end
+  end
+  
+  class Repetition
+    # Call back visitors #repetition method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.repetition(min, max, parslet)
+    end
+  end
+  
+  class Alternative
+    # Call back visitors #alternative method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.alternative(alternatives)
+    end
+  end
+  
+  class Lookahead
+    # Call back visitors #lookahead method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.lookahead(positive, bound_parslet)
+    end
+  end
+  
+  class Re
+    # Call back visitors #re method. See parslet/export for an example. 
+    #
+    def accept(visitor)
+      visitor.re(match)
+    end
+  end
+end

data/lib/parslet/atoms.rb

@@ -1,3 +1,6 @@
+
+# This is where parslets name comes from: Small parser atoms.
+#
 module Parslet::Atoms
   # The precedence module controls parenthesis during the #inspect printing
   # of parslets. It is not relevant to other aspects of the parsing. 
@@ -12,14 +15,15 @@ module Parslet::Atoms
     OUTER      = (prec+=1)    # printing is done here.
   end
   
-  autoload :Base,         'parslet/atoms/base'
-  autoload :Named,        'parslet/atoms/named'
-  autoload :Lookahead,    'parslet/atoms/lookahead'
-  autoload :Alternative,  'parslet/atoms/alternative'
-  autoload :Sequence,     'parslet/atoms/sequence'
-  autoload :Repetition,   'parslet/atoms/repetition'
-  autoload :Re,           'parslet/atoms/re'
-  autoload :Str,          'parslet/atoms/str'
-  autoload :Entity,       'parslet/atoms/entity'
+  require 'parslet/atoms/context'
+  require 'parslet/atoms/base'
+  require 'parslet/atoms/named'
+  require 'parslet/atoms/lookahead'
+  require 'parslet/atoms/alternative'
+  require 'parslet/atoms/sequence'
+  require 'parslet/atoms/repetition'
+  require 'parslet/atoms/re'
+  require 'parslet/atoms/str'
+  require 'parslet/atoms/entity'
 end
 

data/lib/parslet/convenience.rb

@@ -0,0 +1,33 @@
+class Parslet::Parser
+  
+  # Packages the common idiom
+  #    
+  #    begin
+  #      tree = parser.parse('something')
+  #    rescue Parslet::ParseFailed => error
+  #      puts error
+  #      puts parser.root.error_tree
+  #    end
+  #
+  # into a convenient method.
+  #
+  # Usage:
+  #   
+  #   require 'parslet'
+  #   require 'parslet/convenience'
+  #   
+  #   class FooParser < Parslet::Parser
+  #     rule(:foo) { str('foo') }
+  #     root(:foo)
+  #   end
+  #   
+  #   FooParser.new.parse_with_debug('bar')
+  #
+  def parse_with_debug str
+    parse str
+  rescue Parslet::ParseFailed => error
+    puts error
+    puts root.error_tree
+  end
+
+end

data/lib/parslet/export.rb

@@ -0,0 +1,162 @@
+# Allows exporting parslet grammars to other lingos. 
+
+require 'set'
+require 'parslet/atoms/visitor'
+
+class Parslet::Parser
+  module Visitors
+    class Citrus
+      attr_reader :context, :output
+      def initialize(context)
+        @context = context
+      end
+      
+      def str(str)
+        "\"#{str.inspect[1..-2]}\""
+      end
+      def re(match)
+        match.to_s
+      end
+
+      def entity(name, ctx, block)
+        context.deferred(name, [ctx, block])
+
+        "(#{context.mangle_name(name)})"
+      end
+      def named(name, parslet)
+        parslet.accept(self)
+      end
+
+      def sequence(parslets)
+        '(' <<
+        parslets.
+          map { |el| el.accept(self) }.
+          join(' ') <<
+        ')'
+      end
+      def repetition(min, max, parslet)
+        parslet.accept(self) << "#{min}*#{max}"
+      end
+      def alternative(alternatives)
+        '(' <<
+        alternatives.
+          map { |el| el.accept(self) }.
+          join(' | ') <<
+        ')'
+      end
+
+      def lookahead(positive, bound_parslet)
+        (positive ? '&' : '!') <<
+        bound_parslet.accept(self)
+      end
+    end
+
+    class Treetop < Citrus
+      def repetition(min, max, parslet)
+        parslet.accept(self) << "#{min}..#{max}"
+      end
+
+      def alternative(alternatives)
+        '(' <<
+        alternatives.
+          map { |el| el.accept(self) }.
+          join(' / ') <<
+        ')'
+      end
+    end
+  end
+
+  # A helper class that formats Citrus and Treetop grammars as a string. 
+  #
+  class PrettyPrinter # :nodoc:
+    attr_reader :visitor
+    def initialize(visitor_klass)
+      @visitor = visitor_klass.new(self)
+    end
+
+    # Pretty prints the given parslet using the visitor that has been
+    # configured in initialize. Returns the string representation of the
+    # Citrus or Treetop grammar.
+    #
+    def pretty_print(name, parslet) # :nodoc:
+      output = "grammar #{name}\n"
+      
+      output << rule('root', parslet)
+      
+      seen = Set.new
+      loop do
+        # @todo is constantly filled by the visitor (see #deferred). We 
+        # keep going until it is empty.
+        break if @todo.empty?
+        name, (context, block) = @todo.shift
+
+        # Track what rules we've already seen. This breaks loops.
+        next if seen.include?(name)
+        seen << name
+
+        output << rule(name, context.instance_eval(&block))
+      end
+      
+      output << "end\n"
+    end
+    
+    # Formats a rule in either dialect. 
+    #
+    def rule(name, parslet)
+      "  rule #{mangle_name name}\n" << 
+      "    " << parslet.accept(visitor) << "\n" <<
+      "  end\n"
+    end
+    
+    # Whenever the visitor encounters an rule in a parslet, it defers the
+    # pretty printing of the rule by calling this method. 
+    #
+    def deferred(name, content) # :nodoc:
+      @todo ||= []
+      @todo << [name, content]
+    end
+
+    # Mangles names so that Citrus and Treetop can live with it. This mostly
+    # transforms some of the things that Ruby allows into other patterns. If
+    # there is collision, we will not detect it for now. 
+    #
+    def mangle_name(str) # :nodoc:
+      str.to_s.sub(/\?$/, '_p')
+    end
+  end
+
+  # Exports the current parser instance as a string in the Citrus dialect. 
+  #
+  # Example: 
+  #
+  #   require 'parslet/export'
+  #   class MyParser < Parslet::Parser
+  #     root(:expression)
+  #     rule(:expression) { str('foo') }
+  #   end
+  #   
+  #   MyParser.new.to_citrus # => a citrus grammar as a string
+  #
+  def to_citrus
+    PrettyPrinter.new(Visitors::Citrus).
+      pretty_print(self.class.name, root)
+  end
+
+  # Exports the current parser instance as a string in the Treetop dialect. 
+  #
+  # Example: 
+  #
+  #   require 'parslet/export'
+  #   class MyParser < Parslet::Parser
+  #     root(:expression)
+  #     rule(:expression) { str('foo') }
+  #   end
+  #   
+  #   MyParser.new.to_treetop # => a treetop grammar as a string
+  #
+  def to_treetop
+    PrettyPrinter.new(Visitors::Treetop).
+      pretty_print(self.class.name, root)
+  end
+end
+

data/lib/parslet/expression.rb

@@ -1,14 +1,14 @@
 
 # Allows specifying rules as strings using the exact same grammar that treetop
-# does, minus the actions. This is on one hand a good example of a fully fledged
-# parser and on the other hand might even turn out really useful. 
+# does, minus the actions. This is on one hand a good example of a fully
+# fledged parser and on the other hand might even turn out really useful. 
 #
 # This can be viewed as an extension to parslet and might even be hosted in
 # its own gem one fine day. 
 # 
 # NOT FINISHED & EXPERIMENTAL
 #
-class Parslet::Expression # :nodoc:
+class Parslet::Expression
   include Parslet
   
   autoload :Treetop, 'parslet/expression/treetop'

data/lib/parslet/pattern.rb

@@ -99,8 +99,8 @@ class Parslet::Pattern
   end
   
   def element_match_hash(tree, exp, bindings)
-    # Early failure when not all of the hash keys are matched.
-    return false unless exp.keys == tree.keys
+    # Early failure when one hash is bigger than the other
+    return false unless exp.size == tree.size
     
     # We iterate over expected pattern, since we demand that the keys that
     # are there should be in tree as well.

data/lib/parslet/rig/rspec.rb

@@ -13,12 +13,12 @@ RSpec::Matchers.define(:parse) do |input|
   failure_message_for_should do |is|
     "expected " << (@result ?
       "output of parsing #{input.inspect} with #{is.inspect} to equal #{@as.inspect}, but was #{@result.inspect}" :
-      "expected #{is.inspect} to be able to parse #{input.inspect}")
+      "#{is.inspect} to be able to parse #{input.inspect}")
   end
 
   failure_message_for_should_not do |is|
     "expected " << (@as ?
       "output of parsing #{input.inspect} with #{is.inspect} not to equal #{@as.inspect}" :
-      "expected #{is.inspect} to be able to parse #{input.inspect}")
+      "#{is.inspect} to not parse #{input.inspect}, but it did")
   end
 end