parslet 0.11.0 → 1.0.0

data/Gemfile

@@ -8,4 +8,8 @@ group :development do
   gem 'flexmock'
   
   gem 'sdoc'
+  
+  gem 'autotest'
+  gem 'autotest-fsevent'
+  gem 'autotest-growl'
 end

data/HISTORY.txt

@@ -1,3 +1,11 @@
+= 1.0.0 / 29Dez2010
+
+  - #each_match was removed. There was some duplication of code that even 
+    confused me - and we should not have 2 methods of achieving the same
+    goal. 
+    
+  + Full documentation. Fixed sdoc. 
+
 = 0.11.0 / 25Nov2010
 
   ! Bugfixes to tree handling. Let's hope that was the last such significant

data/README

@@ -2,10 +2,10 @@ INTRODUCTION
 
 Parslet makes developing complex parsers easy. It does so by
 
-* providing the best *error reporting* possible
-* *not generating* reams of code for you to debug
+* providing the best <b>error reporting</b> possible
+* <b>not generating</b> reams of code for you to debug
 
-Parslet takes the long way around to make *your job* easier. It allows for
+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. 
@@ -33,14 +33,8 @@ SYNOPSIS
 
   tree # => {:string=>"This is a \\\"String\\\" in which you can escape stuff"}
 
-  # Here's how you can grab results from that tree, two methods: 
+  # Here's how you can grab results from that tree:
 
-  # 1)
-  Pattern.new(:string => simple(:x)).each_match(tree) do |dictionary|
-    puts "String contents (method 1): #{dictionary[:x]}"
-  end
-
-  # 2)
   transform = Parslet::Transform.new do
     rule(:string => simple(:x)) { 
       puts "String contents (method 2): #{x}" }
@@ -53,6 +47,8 @@ This library should work with both ruby 1.8 and ruby 1.9.
 
 STATUS 
 
-On the road to 1.0; improving documentation, packaging and upgrading to rspec2.
+0.12.0 
+
+On the road to 1.0; improving documentation, trying to ease access to the API.
 
 (c) 2010 Kaspar Schiess

data/Rakefile

@@ -18,7 +18,7 @@ spec = Gem::Specification.new do |s|
 
   # Change these as appropriate
   s.name              = "parslet"
-  s.version           = "0.11.0"
+  s.version           = "1.0.0"
   s.summary           = "Parser construction library with great error reporting in Ruby."
   s.author            = "Kaspar Schiess"
   s.email             = "kaspar.schiess@absurd.li"
@@ -64,6 +64,8 @@ require 'sdoc'
 
 # Generate documentation
 Rake::RDocTask.new do |rdoc|
+  rdoc.title    = "parslet - construction of parsers made easy"
+  rdoc.options << '--line-numbers'
   rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
   rdoc.template = 'direct' # lighter template used on railsapi.com
   rdoc.main = "README"

data/lib/parslet.rb

@@ -21,18 +21,34 @@ require 'stringio'
 # Parslet is typically used in stages: 
 #
 # 
-# * Parsing the input string; this yields an intermediary tree
-# * Transformation of the tree into something useful to you
+# * Parsing the input string; this yields an intermediary tree, see
+#   Parslet.any, Parslet.match, Parslet.str, Parslet::ClassMethods#rule and
+#   Parslet::ClassMethods#root.
+# * Transformation of the tree into something useful to you, see
+#   Parslet::Transform, Parslet.simple, Parslet.sequence and Parslet.subtree.
 #
 # The first stage is traditionally intermingled with the second stage; output
 # from the second stage is usually called the 'Abstract Syntax Tree' or AST. 
 #
-# The stages are completely decoupled; You can change your grammar around 
-# and use the second stage to isolate the rest of your code from the changes
+# The stages are completely decoupled; You can change your grammar around and
+# use the second stage to isolate the rest of your code from the changes
 # you've effected. 
 #
+# == Further reading
+# 
+# All parslet atoms are subclasses of Parslet::Atoms::Base. You might want to
+# look at all of those: Parslet::Atoms::Re, Parslet::Atoms::Str,
+# Parslet::Atoms::Repetition, Parslet::Atoms::Sequence,
+# Parslet::Atoms::Alternative.
+#
+# == When things go wrong
+#
+# A parse that fails will raise Parslet::ParseFailed. A detailed explanation
+# of what went wrong can be obtained from the parslet involved or the root of
+# the parser instance. 
+#
 module Parslet
-  def self.included(base)
+  def self.included(base) # :nodoc:
     base.extend(ClassMethods)
   end
   
@@ -47,7 +63,7 @@ module Parslet
   #   begin
   #     parslet.parse(str)
   #   rescue Parslet::ParseFailed => failure
-  #     puts parslet.error_tree.ascii_tree
+  #     puts parslet.error_tree
   #   end
   #
   class ParseFailed < Exception
@@ -96,9 +112,7 @@ module Parslet
     #       bar >> bar
     #     end
     #
-    #     def parse(str)
-    #       twobar.parse(str)
-    #     end
+    #     root :twobar
     #   end
     #
     def rule(name, &definition)
@@ -109,23 +123,28 @@ module Parslet
       end
     end
   end
-  
-  # Allows for delayed construction of #match.
+
+  # Allows for delayed construction of #match. See also Parslet.match.
   #
-  class DelayedMatchConstructor
+  class DelayedMatchConstructor # :nodoc:
     def [](str)
       Atoms::Re.new("[" + str + "]")
     end
   end
   
-  # Returns an atom matching a character class. This is essentially a regular
-  # expression, but you should only match a single character. 
+  # Returns an atom matching a character class. All regular expressions can be
+  # used, as long as they match only a single character at a time. 
   #
   # Example: 
   #
   #   match('[ab]')     # will match either 'a' or 'b'
   #   match('[\n\s]')   # will match newlines and spaces
   #
+  # There is also another (convenience) form of this method: 
+  #
+  #   match['a-z']      # synonymous to match('[a-z]')
+  #   match['\n']       # synonymous to match('[\n]')
+  #
   def match(str=nil)
     return DelayedMatchConstructor.new unless str
     
@@ -144,7 +163,10 @@ module Parslet
   end
   module_function :str
   
-  # Returns an atom matching any character. 
+  # Returns an atom matching any character. It acts like the '.' (dot)
+  # character in regular expressions.
+  #
+  #   any.parse('a')    # => 'a'
   #
   def any
     Atoms::Re.new('.')
@@ -158,7 +180,7 @@ module Parslet
   #
   #   exp(%Q("a" "b"?))     # => returns the same as str('a') >> str('b').maybe
   #
-  def exp(str)
+  def exp(str) # :nodoc:
     Parslet::Expression.new(str).to_parslet
   end
   module_function :exp
@@ -202,6 +224,7 @@ module Parslet
   def subtree(symbol)
     Pattern::SubtreeBind.new(symbol)
   end
+  module_function :subtree
   
   autoload :Expression, 'parslet/expression'
 end

data/lib/parslet/atoms.rb

@@ -2,7 +2,7 @@ module Parslet::Atoms
   # The precedence module controls parenthesis during the #inspect printing
   # of parslets. It is not relevant to other aspects of the parsing. 
   #
-  module Precedence
+  module Precedence # :nodoc:
     prec = 0
     BASE       = (prec+=1)    # everything else
     LOOKAHEAD  = (prec+=1)    # &SOMETHING

data/lib/parslet/atoms/alternative.rb

@@ -8,16 +8,27 @@
 #
 class Parslet::Atoms::Alternative < Parslet::Atoms::Base
   attr_reader :alternatives
+  
+  # Constructs an Alternative instance using all given parslets in the order
+  # given. This is what happens if you call '|' on existing parslets, like 
+  # this: 
+  #
+  #   str('a') | str('b')
+  #
   def initialize(*alternatives)
     @alternatives = alternatives
   end
-  
-  def |(parslet)
+
+  #---
+  # Don't construct a hanging tree of Alternative parslets, instead store them
+  # all here. This reduces the number of objects created.
+  #+++
+  def |(parslet) # :nodoc:
     @alternatives << parslet
     self
   end
   
-  def try(io)
+  def try(io) # :nodoc:
     alternatives.each { |a|
       begin
         return a.apply(io)
@@ -29,11 +40,11 @@ class Parslet::Atoms::Alternative < Parslet::Atoms::Base
   end
 
   precedence ALTERNATE
-  def to_s_inner(prec)
-    alternatives.map { |a| a.to_s(prec) }.join(' | ')
+  def to_s_inner(prec) # :nodoc:
+    alternatives.map { |a| a.to_s(prec) }.join(' / ')
   end
 
-  def error_tree
+  def error_tree # :nodoc:
     Parslet::ErrorTree.new(self, *alternatives.
       map { |child| child.error_tree })
   end

data/lib/parslet/atoms/base.rb

@@ -4,6 +4,10 @@
 class Parslet::Atoms::Base
   include Parslet::Atoms::Precedence
   
+  # 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. 
+  #
   def parse(io)
     if io.respond_to? :to_str
       io = StringIO.new(io)
@@ -27,7 +31,7 @@ class Parslet::Atoms::Base
     return flatten(result)
   end
 
-  def apply(io)
+  def apply(io) # :nodoc:
     # p [:start, self, io.string[io.pos, 10]]
     
     old_pos = io.pos
@@ -43,30 +47,86 @@ class Parslet::Atoms::Base
       io.pos = old_pos; raise ex
     end
   end
-  
+
+  # Construct a new atom that repeats the current atom min times at least and
+  # at most max times. max can be nil to indicate that no maximum is present. 
+  #
+  # Example: 
+  #   # match any number of 'a's
+  #   str('a').repeat     
+  #
+  #   # match between 1 and 3 'a's
+  #   str('a').repeat(1,3)
+  #
   def repeat(min=0, max=nil)
     Parslet::Atoms::Repetition.new(self, min, max)
   end
+  
+  # Returns a new parslet atom that is only maybe present in the input. This
+  # is synonymous to calling #repeat(0,1). Generated tree value will be 
+  # either nil (if atom is not present in the input) or the matched subtree. 
+  #
+  # Example: 
+  #   str('foo').maybe
+  #
   def maybe
     Parslet::Atoms::Repetition.new(self, 0, 1, :maybe)
   end
+
+  # Chains two parslet atoms together as a sequence. 
+  #
+  # Example: 
+  #   str('a') >> str('b')
+  #
   def >>(parslet)
     Parslet::Atoms::Sequence.new(self, parslet)
   end
+
+  # Chains two parslet atoms together to express alternation. A match will
+  # always be attempted with the parslet on the left side first. If it doesn't
+  # match, the right side will be tried. 
+  #
+  # Example:
+  #   # matches either 'a' OR 'b'
+  #   str('a') | str('b')
+  #
   def |(parslet)
     Parslet::Atoms::Alternative.new(self, parslet)
   end
+  
+  # Tests for absence of a parslet atom in the input stream without consuming
+  # it. 
+  # 
+  # Example: 
+  #   # Only proceed the parse if 'a' is absent.
+  #   str('a').absnt?
+  #
   def absnt?
     Parslet::Atoms::Lookahead.new(self, false)
   end
+
+  # Tests for presence of a parslet atom in the input stream without consuming
+  # it. 
+  # 
+  # Example: 
+  #   # Only proceed the parse if 'a' is present.
+  #   str('a').prsnt?
+  #
   def prsnt?
     Parslet::Atoms::Lookahead.new(self, true)
   end
+
+  # Marks a parslet atom as important for the tree output. This must be used 
+  # to achieve meaningful output from the #parse method. 
+  #
+  # Example:
+  #   str('a').as(:b) # will produce {:b => 'a'}
+  #
   def as(name)
     Parslet::Atoms::Named.new(self, name)
   end
 
-  def flatten(value)
+  def flatten(value) # :nodoc:
     # Passes through everything that isn't an array of things
     return value unless value.instance_of? Array
 
@@ -88,12 +148,13 @@ class Parslet::Atoms::Base
     
     fail "BUG: Unknown tag #{tag.inspect}."
   end
-  def flatten_sequence(list)
+  
+  def flatten_sequence(list) # :nodoc:
     list.compact.inject('') { |r, e|        # and then merge flat elements
       merge_fold(r, e)
     }
   end
-  def merge_fold(l, r)
+  def merge_fold(l, r) # :nodoc:
     # equal pairs: merge. 
     if l.class == r.class
       if l.is_a?(Hash)
@@ -117,7 +178,7 @@ class Parslet::Atoms::Base
     fail "Unhandled case when foldr'ing sequence."
   end
 
-  def flatten_repetition(list)
+  def flatten_repetition(list) # :nodoc:
     if list.any? { |e| e.instance_of?(Hash) }
       # If keyed subtrees are in the array, we'll want to discard all 
       # strings inbetween. To keep them, name them. 
@@ -136,18 +197,18 @@ class Parslet::Atoms::Base
     list.inject('') { |s,e| s<<(e||'') }
   end
 
-  def self.precedence(prec)
+  def self.precedence(prec) # :nodoc:
     define_method(:precedence) { prec }
   end
   precedence BASE
-  def to_s(outer_prec)
+  def to_s(outer_prec=OUTER) # :nodoc:
     if outer_prec < precedence
       "("+to_s_inner(precedence)+")"
     else
       to_s_inner(precedence)
     end
   end
-  def inspect
+  def inspect # :nodoc:
     to_s(OUTER)
   end
 
@@ -155,7 +216,7 @@ class Parslet::Atoms::Base
   # of what went wrong with the parse. Not relevant if the parse succeeds, 
   # but needed for clever error reports. 
   #
-  def cause
+  def cause # :nodoc:
     @last_cause
   end
 
@@ -166,7 +227,7 @@ class Parslet::Atoms::Base
   def error_tree
     Parslet::ErrorTree.new(self) if cause?
   end
-  def cause?
+  def cause? # :nodoc:
     not @last_cause.nil?
   end
 private

data/lib/parslet/atoms/entity.rb

@@ -1,17 +1,16 @@
 # This wraps pieces of parslet definition and gives them a name. The wrapped
 # piece is lazily evaluated and cached. This has two purposes: 
 #     
-# a) Avoid infinite recursion during evaluation of the definition
-#
-# b) Be able to print things by their name, not by their sometimes
-#    complicated content.
+# * Avoid infinite recursion during evaluation of the definition
+# * 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
-# using the structuring method Parslet#rule.
+# using the structuring method Parslet.rule.
 #
 class Parslet::Atoms::Entity < Parslet::Atoms::Base
   attr_reader :name, :context, :block
-  def initialize(name, context, block)
+  def initialize(name, context, block) # :nodoc:
     super()
     
     @name = name
@@ -19,7 +18,7 @@ class Parslet::Atoms::Entity < Parslet::Atoms::Base
     @block = block
   end
 
-  def try(io)
+  def try(io) # :nodoc:
     parslet.apply(io)
   end
   
@@ -29,16 +28,16 @@ class Parslet::Atoms::Entity < Parslet::Atoms::Base
     }
   end
 
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     name.to_s.upcase
   end
 
-  def error_tree
+  def error_tree # :nodoc:
     parslet.error_tree
   end
   
 private 
-  def raise_not_implemented
+  def raise_not_implemented # :nodoc:
     trace = caller.reject {|l| l =~ %r{#{Regexp.escape(__FILE__)}}} # blatantly stolen from dependencies.rb in activesupport
     exception = NotImplementedError.new("rule(#{name.inspect}) { ... }  returns nil. Still not implemented, but already used?")
     exception.set_backtrace(trace)

data/lib/parslet/atoms/lookahead.rb

@@ -8,13 +8,13 @@ class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
   attr_reader :positive
   attr_reader :bound_parslet
   
-  def initialize(bound_parslet, positive=true)
-    # Model positive and negative lookahead by testing this flag.
+  def initialize(bound_parslet, positive=true) # :nodoc:
+    # Model positive and negative lookahead by testing this flag.
     @positive = positive
     @bound_parslet = bound_parslet
   end
   
-  def try(io)
+  def try(io) # :nodoc:
     pos = io.pos
     begin
       bound_parslet.apply(io)
@@ -26,7 +26,7 @@ class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
     return success(io)
   end
   
-  def fail(io)
+  def fail(io) # :nodoc:
     if positive
       error(io, "lookahead: #{bound_parslet.inspect} didn't match, but should have")
     else
@@ -34,7 +34,7 @@ class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
       return nil
     end
   end
-  def success(io)
+  def success(io) # :nodoc:
     if positive
       return nil  # see above, TODO
     else
@@ -45,13 +45,13 @@ class Parslet::Atoms::Lookahead < Parslet::Atoms::Base
   end
 
   precedence LOOKAHEAD
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     char = positive ? '&' : '!'
     
     "#{char}#{bound_parslet.to_s(prec)}"
   end
 
-  def error_tree
+  def error_tree # :nodoc:
     bound_parslet.error_tree
   end
 end

data/lib/parslet/atoms/named.rb

@@ -7,25 +7,25 @@
 #
 class Parslet::Atoms::Named < Parslet::Atoms::Base
   attr_reader :parslet, :name
-  def initialize(parslet, name)
+  def initialize(parslet, name) # :nodoc:
     @parslet, @name = parslet, name
   end
   
-  def apply(io)
+  def apply(io) # :nodoc:
     value = parslet.apply(io)
     
     produce_return_value value
   end
   
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     "#{name}:#{parslet.to_s(prec)}"
   end
 
-  def error_tree
+  def error_tree # :nodoc:
     parslet.error_tree
   end
 private
-  def produce_return_value(val)  
+  def produce_return_value(val) # :nodoc:
     { name => flatten(val) }
   end
 end

data/lib/parslet/atoms/re.rb

@@ -9,11 +9,11 @@
 #
 class Parslet::Atoms::Re < Parslet::Atoms::Base
   attr_reader :match
-  def initialize(match)
+  def initialize(match) # :nodoc:
     @match = match
   end
 
-  def try(io)
+  def try(io) # :nodoc:
     r = Regexp.new(match, Regexp::MULTILINE)
     s = io.read(1)
     error(io, "Premature end of input") unless s
@@ -21,7 +21,7 @@ class Parslet::Atoms::Re < Parslet::Atoms::Base
     return s
   end
 
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     match.inspect[1..-2]
   end
 end

data/lib/parslet/atoms/repetition.rb

@@ -14,7 +14,7 @@ class Parslet::Atoms::Repetition < Parslet::Atoms::Base
     @tag = tag
   end
   
-  def try(io)
+  def try(io) # :nodoc:
     occ = 0
     result = [@tag]   # initialize the result array with the tag (for flattening)
     loop do
@@ -36,18 +36,18 @@ class Parslet::Atoms::Repetition < Parslet::Atoms::Base
   end
   
   precedence REPETITION
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     minmax = "{#{min}, #{max}}"
     minmax = '?' if min == 0 && max == 1
 
     parslet.to_s(prec) + minmax
   end
 
-  def cause
+  def cause # :nodoc:
     # Either the repetition failed or the parslet inside failed to repeat. 
     super || parslet.cause
   end
-  def error_tree
+  def error_tree # :nodoc:
     if cause?
       Parslet::ErrorTree.new(self, parslet.error_tree)
     else

data/lib/parslet/atoms/sequence.rb

@@ -10,12 +10,12 @@ class Parslet::Atoms::Sequence < Parslet::Atoms::Base
     @parslets = parslets
   end
   
-  def >>(parslet)
+  def >>(parslet) # :nodoc:
     @parslets << parslet
     self
   end
   
-  def try(io)
+  def try(io) # :nodoc:
     [:sequence]+parslets.map { |p| 
       # Save each parslet as potentially offending (raising an error). 
       @offending_parslet = p
@@ -26,11 +26,11 @@ class Parslet::Atoms::Sequence < Parslet::Atoms::Base
   end
       
   precedence SEQUENCE
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     parslets.map { |p| p.to_s(prec) }.join(' ')
   end
 
-  def error_tree
+  def error_tree # :nodoc:
     Parslet::ErrorTree.new(self).tap { |t|
       t.children << @offending_parslet.error_tree if @offending_parslet }
   end

data/lib/parslet/atoms/str.rb

@@ -10,7 +10,7 @@ class Parslet::Atoms::Str < Parslet::Atoms::Base
     @str = str
   end
   
-  def try(io)
+  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
@@ -19,7 +19,7 @@ class Parslet::Atoms::Str < Parslet::Atoms::Base
     return s
   end
   
-  def to_s_inner(prec)
+  def to_s_inner(prec) # :nodoc:
     "'#{str}'"
   end
 end

data/lib/parslet/error_tree.rb

@@ -8,7 +8,7 @@ class Parslet::ErrorTree
   # All errors that were encountered when parsing part of this +parslet+. 
   attr_reader :children
     
-  def initialize(parslet, *children)
+  def initialize(parslet, *children) # :nodoc:
     @parslet = parslet
     @children = children.compact
   end
@@ -31,7 +31,7 @@ class Parslet::ErrorTree
   end
   alias to_s ascii_tree
 private
-  def recursive_ascii_tree(node, stream, curved)
+  def recursive_ascii_tree(node, stream, curved) # :nodoc:
     append_prefix(stream, curved)
     stream.puts node.cause
     
@@ -41,7 +41,7 @@ private
       recursive_ascii_tree(child, stream, curved + [last_child])
     end
   end
-  def append_prefix(stream, curved)
+  def append_prefix(stream, curved) # :nodoc:
     curved[0..-2].each do |c|
       stream.print c ? "   " : "|  "
     end

data/lib/parslet/expression.rb

@@ -8,12 +8,18 @@
 # 
 # NOT FINISHED & EXPERIMENTAL
 #
-class Parslet::Expression
+class Parslet::Expression # :nodoc:
   include Parslet
   
   autoload :Treetop, 'parslet/expression/treetop'
   
-  def initialize(str, opts={})
+  # Creates a parslet from a foreign language expression. 
+  #
+  # Example: 
+  #   
+  #   Parslet::Expression.new("'a' 'b'")
+  #
+  def initialize(str, opts={}, context=self)
     @type = opts[:type] || :treetop
     @exp = str
     @parslet = transform(
@@ -27,6 +33,9 @@ class Parslet::Expression
     
     # pp tree
     transform.apply(tree)
+  rescue 
+    warn "Could not transform: " + tree.inspect
+    raise
   end
   
   # Parses the string and returns a parse tree.

data/lib/parslet/expression/treetop.rb

@@ -1,5 +1,5 @@
 class Parslet::Expression::Treetop
-  class Parser < Parslet::Parser
+  class Parser < Parslet::Parser # :nodoc:
     root(:expression)
     
     rule(:expression) { alternatives }
@@ -10,18 +10,37 @@ class Parslet::Expression::Treetop
     }
     
     # sequence by simple concatenation 'a' 'b'
-    rule(:simple) { perhaps.repeat(1).as(:seq) }
-
-    rule(:perhaps) {
+    rule(:simple) { occurrence.repeat(1).as(:seq) }
+    
+    # occurrence modifiers
+    rule(:occurrence) {
+      atom.as(:repetition) >> spaced('*').as(:sign) |
+      atom.as(:repetition) >> spaced('+').as(:sign) |
+      atom.as(:repetition) >> repetition_spec |
+      
       atom.as(:maybe) >> spaced('?') | 
       atom
     }
-    
+        
     rule(:atom) { 
       spaced('(') >> expression.as(:unwrap) >> spaced(')') |
-      string 
+      dot |
+      string |
+      char_class
     }
-
+    
+    # a character class
+    rule(:char_class) {
+      (str('[') >>
+        (str('\\') >> any |
+        str(']').absnt? >> any).repeat(1) >>
+      str(']')).as(:match) >> space?
+    }
+    
+    # anything at all
+    rule(:dot) { spaced('.').as(:any) }
+    
+    # recognizing strings
     rule(:string) {
       str('\'') >> 
       (
@@ -31,6 +50,17 @@ class Parslet::Expression::Treetop
       str('\'') >> space?
     }
     
+    # repetition specification like {1, 2}
+    rule(:repetition_spec) {
+      spaced('{') >> 
+        integer.maybe.as(:min) >> spaced(',') >> 
+        integer.maybe.as(:max) >> spaced('}')
+    }
+    rule(:integer) {
+      match['0-9'].repeat(1)
+    }
+    
+    # whitespace handling
     rule(:space) { match("\s").repeat(1) }
     rule(:space?) { space.maybe }
     
@@ -39,12 +69,23 @@ class Parslet::Expression::Treetop
     end
   end
   
-  class Transform < Parser::Transform
-    rule(:alt => subtree(:alt)) { Parslet::Atoms::Alternative.new(*alt) }
-    rule(:seq => sequence(:s))  { Parslet::Atoms::Sequence.new(*s) }
-    rule(:unwrap => simple(:u)) { u }
-    rule(:maybe => simple(:m))  { |d| d[:m].maybe }
-    rule(:string => simple(:s)) { |d| str(d[:s]) }
+  class Transform < Parslet::Transform # :nodoc:
+    
+    rule(:repetition => simple(:rep), :sign => simple(:sign)) { 
+      min = sign=='+' ? 1 : 0
+      Parslet::Atoms::Repetition.new(rep, min, nil) }
+    rule(:repetition => simple(:rep), :min => simple(:min), :max => simple(:max)) { 
+      Parslet::Atoms::Repetition.new(rep, 
+        Integer(min || 0), 
+        max && Integer(max) || nil) }
+      
+    rule(:alt => subtree(:alt))       { Parslet::Atoms::Alternative.new(*alt) }
+    rule(:seq => sequence(:s))        { Parslet::Atoms::Sequence.new(*s) }
+    rule(:unwrap => simple(:u))       { u }
+    rule(:maybe => simple(:m))        { |d| d[:m].maybe }
+    rule(:string => simple(:s))       { Parslet::Atoms::Str.new(s) }
+    rule(:match => simple(:m))        { Parslet::Atoms::Re.new(m) }
+    rule(:any => simple(:a))          { Parslet::Atoms::Re.new('.') }
   end
   
 end

data/lib/parslet/pattern.rb

@@ -25,29 +25,6 @@ class Parslet::Pattern
     @pattern = pattern
   end
 
-  # Searches the given +tree+ for this pattern, yielding the subtrees that
-  # match to the block. 
-  #
-  # Example: 
-  #
-  #   tree = parslet.apply(input)
-  #   pat = Parslet::Pattern.new(:_x)
-  #   pat.each_match(tree) do |subtree|
-  #     # do something with the matching subtree here
-  #   end
-  #
-  def each_match(tree, &block) # :yield: subtree
-    raise ArgumentError, "Must pass a block" unless block
-    
-    recurse_into(tree) do |subtree|
-      if bindings=match(subtree)
-        call_on_match(subtree, bindings, block)
-      end
-    end
-    
-    return nil
-  end
-  
   # Decides if the given subtree matches this pattern. Returns the bindings
   # made on a successful match or nil if the match fails. 
   #
@@ -60,7 +37,10 @@ class Parslet::Pattern
   # can be made. Contains the logic that will switch to instance variables
   # depending on the arity of the block. 
   #
-  def call_on_match(tree, bindings, block)
+  #---
+  # TODO This method should be in Transform. 
+  #
+  def call_on_match(bindings, block)
     if block
       if block.arity == 1
         return block.call(bindings)
@@ -71,23 +51,9 @@ class Parslet::Pattern
     end
   end
   
-  # Handles preorder, depth-first recursion through the +expr+ given. 
-  #
-  def recurse_into(expr, &block)
-    # p [:attempt_match, expr]
-    block.call(expr)
-    
-    case expr
-      when Array
-        expr.each { |y| recurse_into(y, &block) }
-      when Hash
-        expr.each { |k,v| recurse_into(v, &block) }
-    end
-  end
-    
   # Returns true if the tree element given by +tree+ matches the expression
   # given by +exp+. This match must respect bindings already made in
-  # +bindings+. 
+  # +bindings+. Note that bindings is carried along and modified. 
   #
   def element_match(tree, exp, bindings) 
     # p [:elm, tree, exp]
@@ -111,7 +77,7 @@ class Parslet::Pattern
     end
   end
   
-  def element_match_binding(tree, exp, bindings)
+  def element_match_binding(tree, exp, bindings) # :nodoc:
     var_name = exp.variable_name
 
     # TODO test for the hidden :_ feature.
@@ -125,7 +91,7 @@ class Parslet::Pattern
     return true
   end
   
-  def element_match_ary_single(sequence, exp, bindings)
+  def element_match_ary_single(sequence, exp, bindings) # :nodoc:
     return false if sequence.size != exp.size
     
     return sequence.zip(exp).all? { |elt, subexp|
@@ -133,22 +99,18 @@ class Parslet::Pattern
   end
   
   def element_match_hash(tree, exp, bindings)
-    # For a hash to match, all keys must correspond and all values must 
-    # match element wise.
-    tree.each do |tree_key,tree_value|
-      return nil unless exp.has_key?(tree_key)
-      
-      # We know they both have tk as element.
-      exp_value = exp[tree_key]
+    # p [:emh, tree, exp, bindings]
+    
+    # We iterate over expected pattern, since we demand that the keys that
+    # are there should be in tree as well.
+    exp.each do |expected_key, expected_value|
+      return false unless tree.has_key? expected_key
       
-      # Recurse into the values
-      unless element_match(tree_value, exp_value, bindings)
-        # Stop matching early
-        return false
-      end
+      # Recurse into the value and stop early on failure
+      value = tree[expected_key]
+      return false unless element_match(value, expected_value, bindings)
     end
     
-    # Match succeeds
     return true
-  end
+  end  
 end

data/lib/parslet/pattern/binding.rb

@@ -5,7 +5,7 @@
 # It defines the most permissive kind of bind, the one that matches any subtree
 # whatever it looks like. 
 #
-class Parslet::Pattern::SubtreeBind < Struct.new(:symbol)
+class Parslet::Pattern::SubtreeBind < Struct.new(:symbol) # :nodoc:
   def variable_name
     symbol
   end
@@ -33,7 +33,7 @@ end
 # Binds a symbol to a simple subtree, one that is not either a sequence of
 # elements or a collection of attributes. 
 #
-class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind
+class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind # :nodoc:
   def can_bind?(subtree)
     not [Hash, Array].include?(subtree.class)
   end
@@ -41,7 +41,7 @@ end
 
 # Binds a symbol to a sequence of simple leafs ([element1, element2, ...])
 #
-class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind
+class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind # :nodoc:
   def can_bind?(subtree)
     subtree.kind_of?(Array) &&
       (not subtree.any? { |el| [Hash, Array].include?(el.class) })

data/lib/parslet/pattern/context.rb

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

data/lib/parslet/transform.rb

@@ -46,10 +46,13 @@ require 'parslet/pattern'
 # tree that looks like this: 
 #
 #   {
-#     :l => "(", 
-#     :m => {
-#       :l=>"(", :m=>nil, :r=>")" }, 
-#     :r => ")"
+#     l: '(', 
+#     m: {
+#       l: '(', 
+#       m: nil, 
+#       r: ')' 
+#     }, 
+#     r: ')' 
 #   }
 #
 # This parse tree is good for debugging, but what we would really like to have
@@ -100,12 +103,12 @@ class Parslet::Transform
     
     # Allows accessing the class' rules
     #
-    def rules
+    def rules # :nodoc: 
       @__transform_rules || []
     end
   end
   
-  def initialize(&block)
+  def initialize(&block) # :nodoc: 
     @rules = []
     
     if block
@@ -113,6 +116,12 @@ class Parslet::Transform
     end
   end
   
+  # Defines a rule to be applied whenever apply is called on a tree. A rule
+  # is composed of two parts: 
+  # 
+  # * an *expression pattern*
+  # * a *transformation block*
+  #
   def rule(expression, &block)
     @rules << [
       Parslet::Pattern.new(expression), 
@@ -120,6 +129,10 @@ class Parslet::Transform
     ]
   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. 
+  #
   def apply(obj)
     transform_elt(
       case obj
@@ -136,28 +149,28 @@ class Parslet::Transform
   # Allow easy access to all rules, the ones defined in the instance and the 
   # ones predefined in a subclass definition. 
   #
-  def rules
+  def rules # :nodoc: 
     self.class.rules + @rules
   end
   
-  def transform_elt(elt)
+  def transform_elt(elt) # :nodoc: 
     rules.each do |pattern, block|
       if bindings=pattern.match(elt)
         # Produces transformed value
-        return pattern.call_on_match(elt, bindings, block)
+        return pattern.call_on_match(bindings, block)
       end
     end
     
     # No rule matched - element is not transformed
     return elt
   end
-  def recurse_hash(hsh)
+  def recurse_hash(hsh) # :nodoc: 
     hsh.inject({}) do |new_hsh, (k,v)|
       new_hsh[k] = apply(v)
       new_hsh
     end
   end
-  def recurse_array(ary)
+  def recurse_array(ary) # :nodoc: 
     ary.map { |elt| apply(elt) }
   end
 end

metadata

@@ -3,10 +3,10 @@ name: parslet
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 11
   - 0
-  version: 0.11.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Kaspar Schiess
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-25 00:00:00 +01:00
+date: 2010-12-29 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency