parslet 1.2.1 → 1.2.3

data/Gemfile

@@ -1,15 +1,16 @@
-# A sample Gemfile
 source "http://rubygems.org"
 
+gem 'rake'
 gem 'blankslate', '~> 2'
 
 group :development do
   gem 'rspec'
   gem 'flexmock'
-  
+
+  gem 'rdoc'
   gem 'sdoc'
   
   gem 'guard'
   gem 'guard-rspec'
   gem 'growl'
-end
+end

data/HISTORY.txt

@@ -3,9 +3,13 @@
   - prsnt? and absnt? are now finally banned into oblivion. Wasting vocals for
     the win. 
     
-= 1.3.0 / ???
+= 1.2.3 / 22Sep2011
 
-  Next bigger release, features not clear yet. Probably heredoc-parsing. 
+  + Transform#apply can now be called with a hash as second argument. This 
+    provides bindings and a way to inject context.
+
+  ! Fixes a bug thar modified parslet atoms in place, defeating oop chaining. 
+    (#50)
     
 = 1.2.1 / 6Jun2011
 

data/README

@@ -2,13 +2,13 @@ INTRODUCTION
 
 Parslet makes developing complex parsers easy. It does so by
 
-* providing the best <b>error reporting</b> possible
-* <b>not generating</b> reams of code for you to debug
+* providing the best error reporting possible
+* not generating reams of code for you to debug
 
-Parslet takes the long way around to make <b>your job</b> easier. It allows
-for incremental language construction. Often, you start out small,
-implementing the atoms of your language first; _parslet_ takes pride in making
-this possible.
+Parslet takes the long way around to make your job easier. It allows for
+incremental language construction. Often, you start out small, implementing
+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
@@ -48,8 +48,11 @@ issues.
 Note that due to Ruby 1.8 internals, Unicode parsing is not supported on that 
 version. 
 
+On Mac OS X Lion, ruby-1.8.7-p352 has been known to segfault. Use
+ruby-1.8.7-p334 for better results.
+
 STATUS 
 
-At version 1.2.1 - See HISTORY.txt for changes.
+At version 1.2.3 - See HISTORY.txt for changes.
 
 (c) 2010 Kaspar Schiess

data/Rakefile

@@ -1,7 +1,8 @@
-require "rubygems"
-require "rake/rdoctask"
+require 'rdoc/task'
+require 'sdoc'
+
 require 'rspec/core/rake_task'
-require "rake/gempackagetask"
+require "rubygems/package_task"
 
 desc "Run all tests: Exhaustive."
 RSpec::Core::RakeTask.new
@@ -15,10 +16,8 @@ end
 
 task :default => :spec
 
-require 'sdoc'
-
 # Generate documentation
-Rake::RDocTask.new do |rdoc|
+RDoc::Task.new do |rdoc|
   rdoc.title    = "parslet - construction of parsers made easy"
   rdoc.options << '--line-numbers'
   rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
@@ -36,7 +35,7 @@ task :gem => :spec
 spec = eval(File.read('parslet.gemspec'))
 
 desc "Generate the gem package."
-Rake::GemPackageTask.new(spec) do |pkg|
+Gem::PackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 

data/example/ignore.rb

@@ -0,0 +1,33 @@
+# A small example on how to make parslet ignore parts of the parse tree. 
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+require 'parslet'
+
+class IgnoreParslet < Parslet::Atoms::Base
+  def initialize(parslet)
+    @parslet = parslet
+  end
+  def to_s_inner(prec)
+    @parslet.to_s(prec)
+  end
+  def try(source, context)
+    result = @parslet.try(source, context)
+    
+    return success(nil) unless result.error?
+    return result
+  end
+  
+end
+module IgnoreDSL
+  def ignore
+    IgnoreParslet.new(self)
+  end
+end
+
+class Parslet::Atoms::Base
+  include IgnoreDSL
+end
+
+include Parslet
+p (str('a') >> str('b').ignore >> str('c')).
+  parse('abc')

data/example/output/ignore.out

@@ -0,0 +1 @@
+"ac"@0

data/example/output/parens.out

@@ -4,5 +4,5 @@
 
           ((((())))): {:l=>"("@0, :m=>{:l=>"("@1, :m=>{:l=>"("@2, :m=>{:l=>"("@3, :m=>{:l=>"("@4, :m=>nil, :r=>")"@5}, :r=>")"@6}, :r=>")"@7}, :r=>")"@8}, :r=>")"@9} (5 parens)
 
-               ((()): Failed to match sequence (l:'(' m:(BALANCED?)) at line 1 char 6.
+               ((()): Failed to match sequence (l:'(' m:(BALANCED?) r:')') at line 1 char 6.
 

data/lib/parslet/atoms/alternative.rb

@@ -27,8 +27,7 @@ class Parslet::Atoms::Alternative < Parslet::Atoms::Base
   # all here. This reduces the number of objects created.
   #+++
   def |(parslet) # :nodoc:
-    @alternatives << parslet
-    self
+    self.class.new(*@alternatives + [parslet])
   end
   
   def try(source, context) # :nodoc:

data/lib/parslet/atoms/base.rb

@@ -97,6 +97,10 @@ class Parslet::Atoms::Base
   # Takes a mixed value coming out of a parslet and converts it to a return
   # value for the user by dropping things and merging hashes. 
   #
+  # Named is set to true if this result will be embedded in a Hash result from 
+  # naming something using <code>.as(...)</code>. It changes the folding 
+  # semantics of repetition.
+  #
   def flatten(value, named=false) # :nodoc:
     # Passes through everything that isn't an array of things
     return value unless value.instance_of? Array

data/lib/parslet/atoms/sequence.rb

@@ -16,8 +16,7 @@ class Parslet::Atoms::Sequence < Parslet::Atoms::Base
   end
   
   def >>(parslet) # :nodoc:
-    @parslets << parslet
-    self
+    self.class.new(* @parslets+[parslet])
   end
   
   def try(source, context) # :nodoc:

data/lib/parslet/pattern.rb

@@ -18,37 +18,23 @@
 # Note that Parslet::Pattern only matches at a given subtree; it wont try 
 # to match recursively. To do that, please use Parslet::Transform. 
 #
-class Parslet::Pattern
-  autoload :Context, 'parslet/pattern/context'
-  
+class Parslet::Pattern  
   def initialize(pattern)
     @pattern = pattern
   end
 
   # Decides if the given subtree matches this pattern. Returns the bindings
-  # made on a successful match or nil if the match fails. 
+  # made on a successful match or nil if the match fails. If you specify 
+  # bindings to be a hash, the mappings in it will be treated like bindings
+  # made during an attempted match. 
   #
-  def match(subtree)
-    bindings = {}
-    return bindings if element_match(subtree, @pattern, bindings)
-  end
-
-  # Executes the block on the bindings obtained by #match, if such a match
-  # can be made. Contains the logic that will switch to instance variables
-  # depending on the arity of the block. 
+  # Example: 
   #
-  #---
-  # TODO This method should be in Transform. 
+  #   Pattern.new('a').match('a', :foo => 'bar') # => { :foo => 'bar' }
   #
-  def call_on_match(bindings, block)
-    if block
-      if block.arity == 1
-        return block.call(bindings)
-      else
-        context = Context.new(bindings)
-        return context.instance_eval(&block)
-      end
-    end
+  def match(subtree, bindings=nil)
+    bindings = bindings && bindings.dup || Hash.new
+    return bindings if element_match(subtree, @pattern, bindings)
   end
   
   # Returns true if the tree element given by +tree+ matches the expression

data/lib/parslet/slice.rb

@@ -3,16 +3,6 @@
 # any other string, except that it remembers where it came from (offset in
 # original input).
 #
-# Some slices also know what parent slice they are a small part of. This
-# allows the slice to be concatenated to other slices from the same buffer by
-# reslicing it against that original buffer.
-#
-# Why the complexity? Slices allow retaining offset information. This will
-# allow to assign line and column to each small bit of output from the parslet
-# parser. Also, while we keep that information, we might as well try to do
-# something useful with it. Reslicing the same buffers should in theory keep
-# buffer copies and allocations down.
-#
 # == Extracting line and column
 #
 # Using the #line_and_column method, you can extract the line and column in
@@ -32,27 +22,16 @@
 # These omissions are somewhat intentional. Rather than maintaining a full
 # delegation, we opt for a partial emulation that gets the job done.
 #
-# Note also that there are some things that work with strings that will never
-# work when using slices. For instance, you cannot concatenate slices that
-# aren't from the same source or that don't join up:
-#
-# Example:
-#   big_slice = 'abcdef'
-#   a = big_slice.slice(0, 2)   # => "ab"@0
-#   b = big_slice.slice(4, 2)   # => "ef"@4
-#
-#   a + b # raises Parslet::InvalidSliceOperation
-#
-# This avoids creating slices with impossible offsets or that are
-# discontinous.
-#
 class Parslet::Slice
   attr_reader :str, :offset
-  attr_reader :source
+  attr_reader :line_cache
 
-  def initialize(string, offset, source=nil)
+  # Construct a slice using a string, an offset and an optional line cache. 
+  # The line cache should be able to answer to the #line_and_column message. 
+  #
+  def initialize(string, offset, line_cache=nil)
     @str, @offset = string, offset
-    @source = source
+    @line_cache = line_cache
   end
 
   # Compares slices to other slices or strings.
@@ -78,16 +57,16 @@ class Parslet::Slice
   # as the one of this slice. 
   #
   def +(other)
-    self.class.new(str + other.to_s, offset, source)
+    self.class.new(str + other.to_s, offset, line_cache)
   end
 
   # Returns a <line, column> tuple referring to the original input.
   #
   def line_and_column
-    raise ArgumentError, "No source was given, cannot infer line and column." \
-      unless source
+    raise ArgumentError, "No line cache was given, cannot infer line and column." \
+      unless line_cache
 
-    source.line_and_column(self.offset)
+    line_cache.line_and_column(self.offset)
   end
 
 

data/lib/parslet/source.rb

@@ -20,8 +20,7 @@ class Parslet::Source
   # Reads n chars from the input and returns a Range instance. 
   #
   def read(n)
-    raise ArgumentError, "Cannot read <= 1 characters at a time." \
-      if n < 1
+    raise ArgumentError, "Cannot read < 1 characters at a time." if n < 1
     read_slice(n)
   end
   
@@ -51,7 +50,7 @@ private
     # cache line ends
     @line_cache.scan_for_line_endings(start, buf)
     
-    Parslet::Slice.new(buf || '', start, self)
+    Parslet::Slice.new(buf || '', start, @line_cache)
   end
   
   if RUBY_VERSION !~ /^1.9/
@@ -62,7 +61,7 @@ private
       # cache line ends
       @line_cache.scan_for_line_endings(start, buf)
 
-      Parslet::Slice.new(buf || '', start, self)
+      Parslet::Slice.new(buf || '', start, @line_cache)
     end
   end
-end
+end

data/lib/parslet/source/line_cache.rb

@@ -70,7 +70,6 @@ class Parslet::Source
       left = 0
       right = size - 1 
 
-      n = 10
       loop do
         mid = left + (right - left) / 2
 
@@ -87,4 +86,4 @@ class Parslet::Source
       end
     end
   end
-end
+end

data/lib/parslet/transform.rb

@@ -85,10 +85,38 @@ require 'parslet/pattern'
 #   end
 #   transform.apply(tree)
 #
+# = Execution context
+#
+# The execution context of action blocks differs depending on the arity of 
+# said blocks. This can be confusing. It is however somewhat intentional. You 
+# should not create fat Transform descendants containing a lot of helper methods, 
+# instead keep your AST class construction in global scope or make it available
+# through a factory. The following piece of code illustrates usage of global
+# scope: 
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { AstNode.new(a_variable) }
+#     rule(...) { Ast.node(a_variable) } # modules are nice
+#   end
+#   transform.apply(tree)
+#
+# And here's how you would use a class builder (a factory):
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { builder.add_node(a_variable) }
+#     rule(...) { |d| d[:builder].add_node(d[:a_variable]) }
+#   end
+#   transform.apply(tree, :builder => Builder.new)
+#
+# As you can see, Transform allows you to inject local context for your rule
+# action blocks to use. 
+#
 class Parslet::Transform
   # FIXME: Maybe only part of it? Or maybe only include into constructor
   # context?
   include Parslet   
+  
+  autoload :Context, 'parslet/transform/context'
 
   class << self
     # FIXME: Only do this for subclasses?
@@ -133,19 +161,45 @@ class Parslet::Transform
   # or a simple parslet. Transformation will proceed down the tree, replacing
   # parts/all of it with new objects. The resulting object will be returned. 
   #
-  def apply(obj)
+  def apply(obj, context=nil)
     transform_elt(
       case obj
         when Hash
-          recurse_hash(obj)
+          recurse_hash(obj, context)
         when Array
-          recurse_array(obj)
+          recurse_array(obj, context)
       else
         obj
-      end
+      end, 
+      context
     )
   end
   
+  # Executes the block on the bindings obtained by Pattern#match, if such a match
+  # can be made. Depending on the arity of the given block, it is called in 
+  # one of two environments: the current one or a clean toplevel environment.
+  #
+  # If you would like the current environment preserved, please use the 
+  # arity 1 variant of the block. Alternatively, you can inject a context object
+  # and call methods on it (think :ctx => self).
+  #
+  # Example:
+  #   # the local variable a is simulated
+  #   t.call_on_match(:a => :b) { a } 
+  #   # no change of environment here
+  #   t.call_on_match(:a => :b) { |d| d[:a] }
+  #
+  def call_on_match(bindings, block)
+    if block
+      if block.arity == 1
+        return block.call(bindings)
+      else
+        context = Context.new(bindings)
+        return context.instance_eval(&block)
+      end
+    end
+  end
+  
   # Allow easy access to all rules, the ones defined in the instance and the 
   # ones predefined in a subclass definition. 
   #
@@ -153,24 +207,24 @@ class Parslet::Transform
     self.class.rules + @rules
   end
   
-  def transform_elt(elt) # :nodoc: 
+  def transform_elt(elt, context) # :nodoc: 
     rules.each do |pattern, block|
-      if bindings=pattern.match(elt)
+      if bindings=pattern.match(elt, context)
         # Produces transformed value
-        return pattern.call_on_match(bindings, block)
+        return call_on_match(bindings, block)
       end
     end
     
     # No rule matched - element is not transformed
     return elt
   end
-  def recurse_hash(hsh) # :nodoc: 
+  def recurse_hash(hsh, ctx) # :nodoc: 
     hsh.inject({}) do |new_hsh, (k,v)|
-      new_hsh[k] = apply(v)
+      new_hsh[k] = apply(v, ctx)
       new_hsh
     end
   end
-  def recurse_array(ary) # :nodoc: 
-    ary.map { |elt| apply(elt) }
+  def recurse_array(ary, ctx) # :nodoc: 
+    ary.map { |elt| apply(elt, ctx) }
   end
 end

data/lib/parslet/{pattern → transform}/context.rb

@@ -10,7 +10,7 @@ require 'blankslate'
 #     a # => :b
 #   end
 #
-class Parslet::Pattern::Context < BlankSlate # :nodoc:
+class Parslet::Transform::Context < BlankSlate # :nodoc:
   def initialize(bindings)
     @bindings = bindings
   end

metadata

@@ -1,70 +1,78 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: parslet
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 1.2.3
   prerelease: 
-  version: 1.2.1
 platform: ruby
-authors: 
+authors:
 - Kaspar Schiess
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-05 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-09-22 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: blankslate
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70142555622900 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "2.0"
+      - !ruby/object:Gem::Version
+        version: '2.0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70142555622900
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70142555622120 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: *70142555622120
+- !ruby/object:Gem::Dependency
   name: flexmock
+  requirement: &70142555621000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *70142555621000
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &70142555620020 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: sdoc
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *70142555620020
+- !ruby/object:Gem::Dependency
+  name: sdoc
+  requirement: &70142555618980 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
+  prerelease: false
+  version_requirements: *70142555618980
 description: 
 email: kaspar.schiess@absurd.li
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README
-files: 
+files:
 - Gemfile
 - HISTORY.txt
 - LICENSE
@@ -91,12 +99,12 @@ files:
 - lib/parslet/expression.rb
 - lib/parslet/parser.rb
 - lib/parslet/pattern/binding.rb
-- lib/parslet/pattern/context.rb
 - lib/parslet/pattern.rb
 - lib/parslet/rig/rspec.rb
 - lib/parslet/slice.rb
 - lib/parslet/source/line_cache.rb
 - lib/parslet/source.rb
+- lib/parslet/transform/context.rb
 - lib/parslet/transform.rb
 - lib/parslet.rb
 - example/boolean_algebra.rb
@@ -105,6 +113,7 @@ files:
 - example/email_parser.rb
 - example/empty.rb
 - example/erb.rb
+- example/ignore.rb
 - example/ip_address.rb
 - example/json.rb
 - example/local.rb
@@ -116,6 +125,7 @@ files:
 - example/output/email_parser.out
 - example/output/empty.err
 - example/output/erb.out
+- example/output/ignore.out
 - example/output/ip_address.out
 - example/output/json.out
 - example/output/local.out
@@ -136,31 +146,31 @@ files:
 - example/test.lit
 homepage: http://kschiess.github.com/parslet
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --main
 - README
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4497395910031021567
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.5
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Parser construction library with great error reporting in Ruby.
 test_files: []
-