parslet 1.1.1 → 1.2.0

data/lib/parslet/atoms/entity.rb

@@ -9,12 +9,11 @@
 # using the structuring method Parslet.rule.
 #
 class Parslet::Atoms::Entity < Parslet::Atoms::Base
-  attr_reader :name, :context, :block
-  def initialize(name, context, block) # :nodoc:
+  attr_reader :name, :block
+  def initialize(name, &block) # :nodoc:
     super()
     
     @name = name
-    @context = context
     @block = block
   end
 
@@ -23,7 +22,7 @@ class Parslet::Atoms::Entity < Parslet::Atoms::Base
   end
   
   def parslet
-    @parslet ||= context.instance_eval(&block).tap { |p| 
+    @parslet ||= @block.call.tap { |p| 
       raise_not_implemented unless p
     }
   end

data/lib/parslet/atoms/lookahead.rb

@@ -2,7 +2,7 @@
 #
 # Example: 
 #
-#   str('foo').prsnt?   # matches when the input contains 'foo', but leaves it
+#   str('foo').present? # matches when the input contains 'foo', but leaves it
 #
 class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
   attr_reader :positive

data/lib/parslet/atoms/re.rb

@@ -12,8 +12,8 @@ class Parslet::Atoms::Re < Parslet::Atoms::Base
   def initialize(match) # :nodoc:
     super()
 
-    @match = match
-    @re    = Regexp.new(match, Regexp::MULTILINE)
+    @match = match.to_s
+    @re    = Regexp.new(self.match, Regexp::MULTILINE)
     @error_msgs = {
       :premature  => "Premature end of input", 
       :failed     => "Failed to match #{match.inspect[1..-2]}"

data/lib/parslet/atoms/str.rb

@@ -9,7 +9,7 @@ class Parslet::Atoms::Str < Parslet::Atoms::Base
   def initialize(str)
     super()
 
-    @str = str
+    @str = str.to_s
     @error_msgs = {
       :premature  => "Premature end of input", 
       :failed     => "Expected #{str.inspect}, but got "
@@ -17,6 +17,9 @@ class Parslet::Atoms::Str < Parslet::Atoms::Base
   end
   
   def try(source, context) # :nodoc:
+    # NOTE: Even though it doesn't look that way, this is the hotspot, the
+    # contents of parslets inner loop. Changes here affect parslets speed 
+    # enormously.
     error_pos = source.pos
     s = source.read(str.size)
 
@@ -26,7 +29,7 @@ class Parslet::Atoms::Str < Parslet::Atoms::Base
 
     # Failures: 
     return error(source, @error_msgs[:premature]) unless s && s.size==str.size
-    return error(source, @error_msgs[:failed]+s.inspect, error_pos) 
+    return error(source, [@error_msgs[:failed], s], error_pos) 
   end
   
   def to_s_inner(prec) # :nodoc:

data/lib/parslet/atoms/transform.rb

@@ -0,0 +1,75 @@
+
+require 'parslet/atoms/visitor'
+
+# A helper class that allows transforming one grammar into another. You can
+# use this class as a base class: 
+#
+# Example: 
+#   class MyTransform < Parslet::Atoms::Transform
+#     def visit_str(str)
+#       # mangle string here
+#       super(str)
+#     end
+#   end
+#
+# Note that all the methods in a Transform must return parser atoms. The
+# quickest way to do so is to call super with your own arguments. This will
+# just create the same kind of atom that was just visited. 
+#
+# In essence, this base class performs what is called an 'identity transform'
+# with one small caveat: It returns a brand new grammar composed of brand new
+# parser atoms. This is like a deep clone of your grammar. 
+#
+# But nothing stops you from doing something that is far from a deep clone. 
+# You can totally transform the language your grammar accepts. Or maybe
+# turn all repetitions into non-greedy ones? Go wild. 
+#
+class Parslet::Atoms::Transform
+  # Applies a transformation to a grammar and returns a new grammar that 
+  # is the result of the transform.
+  #
+  # Example: 
+  #   Parslet::Atoms::Transform.new.apply(my_grammar) # => deep clone of my_grammar
+  #
+  def apply(grammar)
+    grammar.accept(self)
+  end
+  
+  def visit_str(str)
+    Parslet.str(str)
+  end
+  
+  def visit_sequence(parslets)
+    parslets[1..-1].inject(parslets[0]) { |a,p| a >> p.accept(self) }
+  end
+  
+  def visit_re(match)
+    Parslet.match(match)
+  end
+  
+  def visit_alternative(parslets)
+    parslets[1..-1].inject(parslets[0]) { |a,p| a | p.accept(self) }
+  end
+  
+  def visit_lookahead(positive, parslet)
+    Parslet::Atoms::Lookahead.new(positive, parslet.accept(self))
+  end
+  
+  def visit_entity(name, block)
+    # NOTE: This is kinda tricky. We return a new entity that keeps a reference
+    # to the transformer around. Once somebody accesses the parslet in that
+    # entity, the original block will produce the original parslet, and then
+    # we transform that then and there. Its lazy and futuristic!
+    transformer = self
+    transformed_block = proc { block.call.accept(transformer) }
+    Parslet::Atoms::Entity.new(name, &transformed_block)
+  end
+  
+  def visit_named(name, parslet)
+    parslet.accept(self).as(name)
+  end
+  
+  def visit_repetition(min, max, parslet)
+    parslet.accept(self).repeat(min, max)
+  end
+end

data/lib/parslet/atoms/visitor.rb

@@ -5,7 +5,7 @@
 module Parslet::Atoms
   class Base
     def accept(visitor)
-      raise NotImplementedError, "No visit method on #{self.class.name}."
+      raise NotImplementedError, "No #accept method on #{self.class.name}."
     end
   end
   
@@ -13,7 +13,7 @@ module Parslet::Atoms
     # Call back visitors #str method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.str(str)
+      visitor.visit_str(str)
     end
   end
   
@@ -21,7 +21,7 @@ module Parslet::Atoms
     # Call back visitors #entity method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.entity(name, context, block)
+      visitor.visit_entity(name, block)
     end
   end
   
@@ -29,7 +29,7 @@ module Parslet::Atoms
     # Call back visitors #named method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.named(name, parslet)
+      visitor.visit_named(name, parslet)
     end
   end
   
@@ -37,7 +37,7 @@ module Parslet::Atoms
     # Call back visitors #sequence method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.sequence(parslets)
+      visitor.visit_sequence(parslets)
     end
   end
   
@@ -45,7 +45,7 @@ module Parslet::Atoms
     # Call back visitors #repetition method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.repetition(min, max, parslet)
+      visitor.visit_repetition(min, max, parslet)
     end
   end
   
@@ -53,7 +53,7 @@ module Parslet::Atoms
     # Call back visitors #alternative method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.alternative(alternatives)
+      visitor.visit_alternative(alternatives)
     end
   end
   
@@ -61,7 +61,7 @@ module Parslet::Atoms
     # Call back visitors #lookahead method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.lookahead(positive, bound_parslet)
+      visitor.visit_lookahead(positive, bound_parslet)
     end
   end
   
@@ -69,7 +69,7 @@ module Parslet::Atoms
     # Call back visitors #re method. See parslet/export for an example. 
     #
     def accept(visitor)
-      visitor.re(match)
+      visitor.visit_re(match)
     end
   end
 end

data/lib/parslet/convenience.rb

@@ -1,4 +1,4 @@
-class Parslet::Parser
+class Parslet::Atoms::Base
   
   # Packages the common idiom
   #    
@@ -6,7 +6,7 @@ class Parslet::Parser
   #      tree = parser.parse('something')
   #    rescue Parslet::ParseFailed => error
   #      puts error
-  #      puts parser.root.error_tree
+  #      puts parser.error_tree
   #    end
   #
   # into a convenient method.
@@ -27,7 +27,7 @@ class Parslet::Parser
     parse str
   rescue Parslet::ParseFailed => error
     puts error
-    puts root.error_tree
+    puts error_tree
   end
 
 end

data/lib/parslet/export.rb

@@ -11,33 +11,33 @@ class Parslet::Parser
         @context = context
       end
       
-      def str(str)
+      def visit_str(str)
         "\"#{str.inspect[1..-2]}\""
       end
-      def re(match)
+      def visit_re(match)
         match.to_s
       end
 
-      def entity(name, ctx, block)
-        context.deferred(name, [ctx, block])
+      def visit_entity(name, block)
+        context.deferred(name, block)
 
         "(#{context.mangle_name(name)})"
       end
-      def named(name, parslet)
+      def visit_named(name, parslet)
         parslet.accept(self)
       end
 
-      def sequence(parslets)
+      def visit_sequence(parslets)
         '(' <<
         parslets.
           map { |el| el.accept(self) }.
           join(' ') <<
         ')'
       end
-      def repetition(min, max, parslet)
+      def visit_repetition(min, max, parslet)
         parslet.accept(self) << "#{min}*#{max}"
       end
-      def alternative(alternatives)
+      def visit_alternative(alternatives)
         '(' <<
         alternatives.
           map { |el| el.accept(self) }.
@@ -45,18 +45,18 @@ class Parslet::Parser
         ')'
       end
 
-      def lookahead(positive, bound_parslet)
+      def visit_lookahead(positive, bound_parslet)
         (positive ? '&' : '!') <<
         bound_parslet.accept(self)
       end
     end
 
     class Treetop < Citrus
-      def repetition(min, max, parslet)
+      def visit_repetition(min, max, parslet)
         parslet.accept(self) << "#{min}..#{max}"
       end
 
-      def alternative(alternatives)
+      def visit_alternative(alternatives)
         '(' <<
         alternatives.
           map { |el| el.accept(self) }.
@@ -88,13 +88,13 @@ class Parslet::Parser
         # @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
+        name, 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))
+        output << rule(name, block.call)
       end
       
       output << "end\n"

data/lib/parslet/expression/treetop.rb

@@ -33,7 +33,7 @@ class Parslet::Expression::Treetop
     rule(:char_class) {
       (str('[') >>
         (str('\\') >> any |
-        str(']').absnt? >> any).repeat(1) >>
+        str(']').absent? >> any).repeat(1) >>
       str(']')).as(:match) >> space?
     }
     
@@ -45,7 +45,7 @@ class Parslet::Expression::Treetop
       str('\'') >> 
       (
         (str('\\') >> any) |
-        (str("'").absnt? >> any)
+        (str("'").absent? >> any)
       ).repeat.as(:string) >> 
       str('\'') >> space?
     }

data/lib/parslet/parser.rb

@@ -12,6 +12,60 @@
 #   pp MyParser.new.parse('bbbb')   # => Parslet::Atoms::ParseFailed: 
 #                                   #    Don't know what to do with bbbb at line 1 char 1.
 #
-class Parslet::Parser 
+# Parslet::Parser is also a grammar atom. This means that you can mix full 
+# fledged parsers freely with small parts of a different parser. 
+#
+# Example: 
+#   class ParserA < Parslet::Parser
+#     root :aaa
+#     rule(:aaa) { str('a').repeat(3,3) }
+#   end
+#   class ParserB < Parslet::Parser
+#     root :expression
+#     rule(:expression) { str('b') >> ParserA.new >> str('b') }
+#   end
+#
+# In the above example, ParserB would parse something like 'baaab'. 
+#
+class Parslet::Parser < Parslet::Atoms::Base
   include Parslet
+
+  class <<self # class methods
+    # Define the parsers #root function. This is the place where you start 
+    # parsing; if you have a rule for 'file' that describes what should be 
+    # in a file, this would be your root declaration: 
+    #
+    #   class Parser
+    #     root :file
+    #     rule(:file) { ... }
+    #   end
+    #
+    # #root declares a 'parse' function that works just like the parse 
+    # function that you can call on a simple parslet, taking a string as input
+    # and producing parse output. 
+    #
+    # In a way, #root is a shorthand for: 
+    #
+    #   def parse(str)
+    #     your_parser_root.parse(str)
+    #   end
+    #
+    def root(name)
+      define_method(:root) do
+        self.send(name)
+      end
+    end
+  end
+  
+  def try(source, context) # :nodoc:
+    root.try(source, context)
+  end
+  
+  def error_tree # :nodoc:
+    root.error_tree
+  end
+  
+  def to_s_inner(prec) # :nodoc:
+    root.to_s(prec)
+  end
 end

data/lib/parslet/rig/rspec.rb

@@ -1,24 +1,50 @@
-RSpec::Matchers.define(:parse) do |input|
-  chain(:as) { |as| @as = as }
-
+RSpec::Matchers.define(:parse) do |input, opts|
   match do |parser|
     begin
       @result = parser.parse(input)
-      @as == @result or @as.nil?
+      @block ? 
+        @block.call(@result) : 
+        (@as == @result || @as.nil?)
     rescue Parslet::ParseFailed
+      @trace = parser.error_tree.ascii_tree if opts && opts[:trace]
       false
     end
   end
 
   failure_message_for_should do |is|
-    "expected " << (@result ?
-      "output of parsing #{input.inspect} with #{is.inspect} to equal #{@as.inspect}, but was #{@result.inspect}" :
-      "#{is.inspect} to be able to parse #{input.inspect}")
+    if @block
+      "expected output of parsing #{input.inspect}" <<
+      " with #{is.inspect} to meet block conditions, but it didn't"
+    else
+      "expected " << 
+        (@as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} to equal #{@as.inspect}, but was #{@result.inspect}" : 
+          "#{is.inspect} to be able to parse #{input.inspect}") << 
+        (@trace ? 
+          "\n"+@trace : 
+          '')
+    end
   end
 
   failure_message_for_should_not do |is|
-    "expected " << (@as ?
-      "output of parsing #{input.inspect} with #{is.inspect} not to equal #{@as.inspect}" :
-      "#{is.inspect} to not parse #{input.inspect}, but it did")
+    if @block
+      "expected output of parsing #{input.inspect} with #{is.inspect} not to meet block conditions, but it did"
+    else
+      "expected " << 
+        (@as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} not to equal #{@as.inspect}" :
+          
+          "#{is.inspect} to not parse #{input.inspect}, but it did")
+    end
+  end
+
+  # NOTE: This has a nodoc tag since the rdoc parser puts this into 
+  # Object, a thing I would never allow. 
+  def as(expected_output = nil, &block) # :nodoc: 
+    @as = expected_output
+    @block = block
+    self
   end
 end