parslet 1.6.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 48adca502f4d3fa08eeaa93ee6c2349866ec2028
-  data.tar.gz: d74a18ffbf0fa05cc3b9c6ba42d112ce7fcb218e
+  metadata.gz: d212114155ea2fce120ce17157dcd10a9bb81ebf
+  data.tar.gz: 07ad0296a6bea037a87594ffc565429b39e6258b
 SHA512:
-  metadata.gz: 0271bfb7536639b396e5203b52fa3d148f09534d08bd67d54c58efb4be4454be35761203b02270719bf32f4ab54313b63b3bb4321e4b993094248f36f7b7f88d
-  data.tar.gz: 56a0e3845d0e0dd7a553c6d901c7ed37863c89d5140bd460285dea2e81d63aeb917190f80a7f29f7a914ac2cb17f301874db2fbb7d4f2bcfc1e6715645541b64
+  metadata.gz: 704d66fde31caf3741fa202d2ac56eaf410ec3ed0cf9050bc834af92a115d847a14e72d61cd97b44c60ba8bc1e50bf792cfadff3257e2b789a7bc9550d0b944a
+  data.tar.gz: 6ae7e679bfe78d0de4f6c66f4d096f2985b23ece311d5705deb5fe9098ce516ba4d6a7ecb2df7f34d942c7c2370dac3b075d0a6c168e887ac1bdbbdc020a21b2

data/HISTORY.txt

@@ -3,9 +3,11 @@
   - prsnt? and absnt? are now finally banned into oblivion. Wasting vocals for
     the win. 
 
-= 1.7 / ???
+= 1.7 / 12Mar2015
 
   ! Small speed gains from improvements on the hot spots. 
+  + Contextual error reporter, a flavor of error reporting that emphasizes 
+    context. 
 
 = 1.6 / 1May2014, 13Okt14
 

data/README

@@ -11,7 +11,7 @@ the atoms of your language first; _parslet_ takes pride in making this
 possible.
 
 Eager to try this out? Please see the associated web site:
-http://kschiess.github.com/parslet
+http://kschiess.github.io/parslet
 
 SYNOPSIS
 

data/lib/parslet.rb

@@ -99,7 +99,7 @@ module Parslet
     #     root :twobar
     #   end
     #
-    def rule(name, &definition)
+    def rule(name, opts={}, &definition)
       define_method(name) do
         @rules ||= {}     # <name, rule> memoization
         return @rules[name] if @rules.has_key?(name)
@@ -109,7 +109,7 @@ module Parslet
           self.instance_eval(&definition)
         }
         
-        @rules[name] = Atoms::Entity.new(name, &definition_closure)
+        @rules[name] = Atoms::Entity.new(name, opts[:label], &definition_closure)
       end
     end
   end

data/lib/parslet/atoms/base.rb

@@ -7,7 +7,10 @@ class Parslet::Atoms::Base
   include Parslet::Atoms::Precedence
   include Parslet::Atoms::DSL
   include Parslet::Atoms::CanFlatten
-  
+
+  # Parslet label as provided in grammar
+  attr_accessor :label
+
   # Given a string or an IO object, this will attempt a parse of its contents
   # and return a result. If the parse fails, a Parslet::ParseFailed exception
   # will be thrown. 
@@ -83,6 +86,8 @@ class Parslet::Atoms::Base
     success, value = result = context.try_with_cache(self, source, consume_all)
 
     if success
+      # Notify context
+      context.succ(source)
       # If a consume_all parse was made and doesn't result in the consumption
       # of all the input, that is considered an error. 
       if consume_all && source.chars_left>0
@@ -132,10 +137,11 @@ class Parslet::Atoms::Base
   end
   precedence BASE
   def to_s(outer_prec=OUTER)
+    str = @label || to_s_inner(precedence)
     if outer_prec < precedence
-      "("+to_s_inner(precedence)+")"
+      "(#{str})"
     else
-      to_s_inner(precedence)
+      str
     end
   end
   def inspect

data/lib/parslet/atoms/context.rb

@@ -62,7 +62,15 @@ module Parslet::Atoms
       return [false, @reporter.err(*args)] if @reporter
       return [false, nil]
     end
-  
+
+    # Report a successful parse.
+    # @see ErrorReporter::Contextual
+    #
+    def succ(*args)
+      return [true, @reporter.succ(*args)] if @reporter
+      return [true, nil]
+    end
+
     # Returns the current captures made on the input (see
     # Parslet::Atoms::Base#capture). Use as follows: 
     # 

data/lib/parslet/atoms/entity.rb

@@ -5,15 +5,16 @@
 # * Be able to print things by their name, not by their sometimes
 #   complicated content.
 #
-# You don't normally use this directly, instead you should generated it by
+# You don't normally use this directly, instead you should generate it by
 # using the structuring method Parslet.rule.
 #
 class Parslet::Atoms::Entity < Parslet::Atoms::Base
   attr_reader :name, :block
-  def initialize(name, &block)
+  def initialize(name, label=nil, &block)
     super()
     
     @name = name
+    @label = label
     @block = block
   end
 
@@ -22,9 +23,11 @@ class Parslet::Atoms::Entity < Parslet::Atoms::Base
   end
   
   def parslet
-    @parslet ||= @block.call.tap { |p| 
-      raise_not_implemented unless p
-    }
+    return @parslet unless @parslet.nil?
+    @parslet = @block.call
+    raise_not_implemented if @parslet.nil?
+    @parslet.label = @label
+    @parslet
   end
 
   def to_s_inner(prec)

data/lib/parslet/atoms/sequence.rb

@@ -31,7 +31,7 @@ class Parslet::Atoms::Sequence < Parslet::Atoms::Base
       unless success
         return context.err(self, source, @error_msgs[:failed], [value]) 
       end
-      
+
       result[idx+1] = value
     end
     

data/lib/parslet/cause.rb

@@ -44,15 +44,22 @@ module Parslet
     def self.format(source, pos, str, children=[])
       self.new(str, source, pos, children)
     end
-    
+
+    # Update error message to include context provided by label
+    # Update all child causes too (the same context applies to all causes)
+    def set_label(l)
+      @context = " when parsing #{l}"
+      children.each { |c| c.set_label(l) }
+    end
+
     def to_s
       line, column = source.line_and_column(pos)
       # Allow message to be a list of objects. Join them here, since we now
-      # really need it. 
-      Array(message).map { |o| 
-        o.respond_to?(:to_slice) ? 
-          o.str.inspect : 
-          o.to_s }.join + " at line #{line} char #{column}."
+      # really need it.
+      Array(message).map { |o|
+        o.respond_to?(:to_slice) ?
+          o.str.inspect :
+          o.to_s }.join + " at line #{line} char #{column}#{@context}."
     end
     
     # Signals to the outside that the parse has failed. Use this in

data/lib/parslet/error_reporter.rb

@@ -4,4 +4,5 @@ module Parslet::ErrorReporter
 end
 
 require 'parslet/error_reporter/tree'
-require 'parslet/error_reporter/deepest'
+require 'parslet/error_reporter/deepest'
+require 'parslet/error_reporter/contextual'

data/lib/parslet/error_reporter/contextual.rb

@@ -0,0 +1,120 @@
+module Parslet
+  module ErrorReporter
+
+    # A reporter that tries to improve on the deepest error reporter by
+    # using heuristics to find the most relevant error and provide more
+    # context.
+    # The heuristic chooses the deepest error when parsing a sequence for which
+    # no alternative parsed successfully.
+    #
+    # Given the following parser:
+    #
+    # root(:call)
+    #
+    # rule(:call, label: 'call') {
+    #   identifier >> str('.') >> method
+    # }
+    #
+    # rule(:method, label: 'method call') {
+    #   identifier >> str('(') >> arguments.maybe >> str(')')
+    # }
+    #
+    # rule(:identifier, label: 'identifier') {
+    #   match['[:alnum:]'].repeat(1)
+    # }
+    #
+    # rule(:arguments, label: 'method call arguments') {
+    #   argument >> str(',') >> arguments | argument
+    # }
+    #
+    # rule(:argument) {
+    #    call | identifier
+    # }
+    #
+    # and the following source:
+    #
+    #   foo.bar(a,goo.baz(),c,)
+    #
+    # The contextual reporter returns the following causes:
+    #
+    # 0: Failed to match sequence (identifier '.' method call) at line 1 char 5
+    #    when parsing method call arguments.
+    # 1: Failed to match sequence (identifier '(' method call arguments? ')') at
+    #    line 1 char 22 when parsing method call arguments.
+    # 2: Failed to match [[:alnum:]] at line 1 char 23 when parsing method call
+    #    arguments.
+    #
+    # (where 2 is a child cause of 1 and 1 a child cause of 0)
+    #
+    # The last piece used by the reporter is the (newly introduced) ability
+    # to attach a label to rules that describe a sequence in the grammar. The
+    # labels are used in two places:
+    #   - In the "to_s" of Atom::Base so that any error message uses labels to
+    #     refer to atoms
+    #   - In the cause error messages to give information about which expression
+    #     failed to parse
+    #
+    class Contextual < Deepest
+
+      def initialize
+        @last_reset_pos = 0
+        reset
+      end
+
+      # A sequence expression successfully parsed, reset all errors reported
+      # for previous expressions in the sequence (an alternative matched)
+      # Only reset errors if the position of the source that matched is higher
+      # than the position of the source that was last successful (so we keep
+      # errors that are the "deepest" but for which no alternative succeeded)
+      #
+      def succ(source)
+        source_pos = source.pos.bytepos
+        return if source_pos < @last_reset_pos
+        @last_reset_pos = source_pos
+        reset
+      end
+
+      # Reset deepest error and its position and sequence index
+      #
+      def reset
+        @deepest_cause = nil
+        @label_pos = -1
+      end
+
+      # Produces an error cause that combines the message at the current level
+      # with the errors that happened at a level below (children).
+      # Compute and set label used by Cause to produce error message.
+      #
+      # @param atom [Parslet::Atoms::Base] parslet that failed
+      # @param source [Source] Source that we're using for this parse. (line
+      #   number information...)
+      # @param message [String, Array] Error message at this level.
+      # @param children [Array] A list of errors from a deeper level (or nil).
+      # @return [Cause] An error tree combining children with message.
+      #
+      def err(atom, source, message, children=nil)
+        cause = super(atom, source, message, children)
+        if (label = atom.respond_to?(:label) && atom.label)
+          update_label(label, source.pos.bytepos)
+          cause.set_label(@label)
+        end
+        cause
+      end
+
+      # Update error message label if given label is more relevant.
+      # A label is more relevant if the position of the matched source is
+      # bigger.
+      #
+      # @param label [String] label to apply if more relevant
+      # @param bytepos [Integer] position in source code of matched source
+      #
+      def update_label(label, bytepos)
+        if bytepos >= @label_pos
+          @label_pos = bytepos
+          @label = label
+        end
+      end
+
+    end
+  end
+end

data/lib/parslet/error_reporter/deepest.rb

@@ -50,6 +50,11 @@ module Parslet
       end
       
       # Returns the cause that is currently deepest. Mainly for specs. 
+
+      # Notification that an expression successfully parsed
+      # not used, see ErrorReporter::Contextual
+      def succ(source)
+      end
       #
       attr_reader :deepest_cause
       

data/lib/parslet/error_reporter/tree.rb

@@ -52,6 +52,12 @@ module Parslet
         position = pos
         Cause.format(source, position, message, children)
       end
+
+      # Notification that an expression successfully parsed
+      # not used, see ErrorReporter::Contextual
+      def succ(source)
+      end
+
     end
   end
-end
+end

data/lib/parslet/slice.rb

@@ -57,6 +57,8 @@ class Parslet::Slice
   def size
     str.size
   end
+
+  alias length size
   
   # Concatenate two slices; it is assumed that the second slice begins 
   # where the first one ends. The offset of the resulting slice is the same
@@ -105,4 +107,4 @@ class Parslet::Slice
 
     str.inspect << "@#{offset}"
   end
-end
+end

data/lib/parslet/transform.rb

@@ -124,7 +124,8 @@ class Parslet::Transform
     #
     def rule(expression, &block)
       @__transform_rules ||= []
-      @__transform_rules << [Parslet::Pattern.new(expression), block]
+      # Prepend new rules so they have higher precedence than older rules
+      @__transform_rules.unshift([Parslet::Pattern.new(expression), block])
     end
     
     # Allows accessing the class' rules
@@ -132,6 +133,11 @@ class Parslet::Transform
     def rules 
       @__transform_rules || []
     end
+
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@__transform_rules, rules.dup)
+    end
   end
   
   def initialize(&block) 
@@ -149,16 +155,31 @@ class Parslet::Transform
   # * a *transformation block*
   #
   def rule(expression, &block)
-    @rules << [
-      Parslet::Pattern.new(expression), 
-      block
-    ]
+    # Prepend new rules so they have higher precedence than older rules
+    @rules.unshift([Parslet::Pattern.new(expression), block])
   end
   
   # Applies the transformation to a tree that is generated by Parslet::Parser
   # or a simple parslet. Transformation will proceed down the tree, replacing
   # parts/all of it with new objects. The resulting object will be returned. 
   #
+  # Using the context parameter, you can inject bindings for the transformation.
+  # This can be used to allow access to the outside world from transform blocks,
+  # like so:
+  # 
+  #   document = # some class that you act on
+  #   transform.apply(tree, document: document)
+  #   
+  # The above will make document available to all your action blocks: 
+  #
+  #   # Variant A
+  #   rule(...) { document.foo(bar) }
+  #   # Variant B
+  #   rule(...) { |d| d[:document].foo(d[:bar]) }
+  #
+  # @param obj PORO ast to transform
+  # @param context start context to inject into the bindings. 
+  #
   def apply(obj, context=nil)
     transform_elt(
       case obj

metadata

@@ -1,33 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: parslet
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.0
 platform: ruby
 authors:
 - Kaspar Schiess
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-13 00:00:00.000000000 Z
+date: 2015-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: blankslate
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-    - - <=
+    - - "<="
       - !ruby/object:Gem::Version
         version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-    - - <=
+    - - "<="
       - !ruby/object:Gem::Version
         version: '4.0'
 description: 
@@ -39,50 +39,8 @@ extra_rdoc_files:
 files:
 - HISTORY.txt
 - LICENSE
-- Rakefile
 - README
-- lib/parslet/accelerator/application.rb
-- lib/parslet/accelerator/engine.rb
-- lib/parslet/accelerator.rb
-- lib/parslet/atoms/alternative.rb
-- lib/parslet/atoms/base.rb
-- lib/parslet/atoms/can_flatten.rb
-- lib/parslet/atoms/capture.rb
-- lib/parslet/atoms/context.rb
-- lib/parslet/atoms/dsl.rb
-- lib/parslet/atoms/dynamic.rb
-- lib/parslet/atoms/entity.rb
-- lib/parslet/atoms/infix.rb
-- lib/parslet/atoms/lookahead.rb
-- lib/parslet/atoms/named.rb
-- lib/parslet/atoms/re.rb
-- lib/parslet/atoms/repetition.rb
-- lib/parslet/atoms/scope.rb
-- lib/parslet/atoms/sequence.rb
-- lib/parslet/atoms/str.rb
-- lib/parslet/atoms/visitor.rb
-- lib/parslet/atoms.rb
-- lib/parslet/cause.rb
-- lib/parslet/context.rb
-- lib/parslet/convenience.rb
-- lib/parslet/error_reporter/deepest.rb
-- lib/parslet/error_reporter/tree.rb
-- lib/parslet/error_reporter.rb
-- lib/parslet/export.rb
-- lib/parslet/expression/treetop.rb
-- lib/parslet/expression.rb
-- lib/parslet/graphviz.rb
-- lib/parslet/parser.rb
-- lib/parslet/pattern/binding.rb
-- lib/parslet/pattern.rb
-- lib/parslet/position.rb
-- lib/parslet/rig/rspec.rb
-- lib/parslet/scope.rb
-- lib/parslet/slice.rb
-- lib/parslet/source/line_cache.rb
-- lib/parslet/source.rb
-- lib/parslet/transform.rb
-- lib/parslet.rb
+- Rakefile
 - example/big.erb
 - example/boolean_algebra.rb
 - example/calc.rb
@@ -140,30 +98,74 @@ files:
 - example/simple_xml.rb
 - example/string_parser.rb
 - example/test.lit
-homepage: http://kschiess.github.com/parslet
+- lib/parslet.rb
+- lib/parslet/accelerator.rb
+- lib/parslet/accelerator/application.rb
+- lib/parslet/accelerator/engine.rb
+- lib/parslet/atoms.rb
+- lib/parslet/atoms/alternative.rb
+- lib/parslet/atoms/base.rb
+- lib/parslet/atoms/can_flatten.rb
+- lib/parslet/atoms/capture.rb
+- lib/parslet/atoms/context.rb
+- lib/parslet/atoms/dsl.rb
+- lib/parslet/atoms/dynamic.rb
+- lib/parslet/atoms/entity.rb
+- lib/parslet/atoms/infix.rb
+- lib/parslet/atoms/lookahead.rb
+- lib/parslet/atoms/named.rb
+- lib/parslet/atoms/re.rb
+- lib/parslet/atoms/repetition.rb
+- lib/parslet/atoms/scope.rb
+- lib/parslet/atoms/sequence.rb
+- lib/parslet/atoms/str.rb
+- lib/parslet/atoms/visitor.rb
+- lib/parslet/cause.rb
+- lib/parslet/context.rb
+- lib/parslet/convenience.rb
+- lib/parslet/error_reporter.rb
+- lib/parslet/error_reporter/contextual.rb
+- lib/parslet/error_reporter/deepest.rb
+- lib/parslet/error_reporter/tree.rb
+- lib/parslet/export.rb
+- lib/parslet/expression.rb
+- lib/parslet/expression/treetop.rb
+- lib/parslet/graphviz.rb
+- lib/parslet/parser.rb
+- lib/parslet/pattern.rb
+- lib/parslet/pattern/binding.rb
+- lib/parslet/position.rb
+- lib/parslet/rig/rspec.rb
+- lib/parslet/scope.rb
+- lib/parslet/slice.rb
+- lib/parslet/source.rb
+- lib/parslet/source/line_cache.rb
+- lib/parslet/transform.rb
+homepage: http://kschiess.github.io/parslet
 licenses:
 - MIT
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --main
+- "--main"
 - README
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Parser construction library with great error reporting in Ruby.
 test_files: []
+has_rdoc: