parslet 0.9.0 → 0.10.1

data/lib/parslet/atoms/sequence.rb

@@ -0,0 +1,37 @@
+# A sequence of parslets, matched from left to right. Denoted by '>>'
+#
+# Example: 
+#
+#   str('a') >> str('b')  # matches 'a', then 'b'
+#
+class Parslet::Atoms::Sequence < Parslet::Atoms::Base
+  attr_reader :parslets
+  def initialize(*parslets)
+    @parslets = parslets
+  end
+  
+  def >>(parslet)
+    @parslets << parslet
+    self
+  end
+  
+  def try(io)
+    [:sequence]+parslets.map { |p| 
+      # Save each parslet as potentially offending (raising an error). 
+      @offending_parslet = p
+      p.apply(io) 
+    }
+  rescue Parslet::ParseFailed
+    error(io, "Failed to match sequence (#{self.inspect})")
+  end
+      
+  precedence SEQUENCE
+  def to_s_inner(prec)
+    parslets.map { |p| p.to_s(prec) }.join(' ')
+  end
+
+  def error_tree
+    Parslet::ErrorTree.new(self).tap { |t|
+      t.children << @offending_parslet.error_tree if @offending_parslet }
+  end
+end

data/lib/parslet/atoms/str.rb

@@ -0,0 +1,26 @@
+# Matches a string of characters. 
+#
+# Example: 
+# 
+#   str('foo') # matches 'foo'
+#
+class Parslet::Atoms::Str < Parslet::Atoms::Base
+  attr_reader :str
+  def initialize(str)
+    @str = str
+  end
+  
+  def try(io)
+    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
+  end
+  
+  def to_s_inner(prec)
+    "'#{str}'"
+  end
+end
+

data/lib/parslet/error_tree.rb

@@ -20,7 +20,6 @@ class Parslet::ErrorTree
   def cause
     parslet.cause || "Unknown error in #{parslet.inspect}"
   end
-  alias :to_s :cause
   
   # Returns an ascii tree representation of the causes of this node and its
   # children. 
@@ -30,10 +29,11 @@ class Parslet::ErrorTree
       recursive_ascii_tree(self, io, [true]) }.
       string
   end
+  alias to_s ascii_tree
 private
   def recursive_ascii_tree(node, stream, curved)
     append_prefix(stream, curved)
-    stream.puts node
+    stream.puts node.cause
     
     node.children.each do |child|
       last_child = (node.children.last == child)

data/lib/parslet/expression.rb

@@ -0,0 +1,41 @@
+
+# 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. 
+# 
+# NOT FINISHED & EXPERIMENTAL
+#
+class Parslet::Expression
+  include Parslet
+  
+  autoload :Treetop, 'parslet/expression/treetop'
+  
+  def initialize(str, opts={})
+    @type = opts[:type] || :treetop
+    @exp = str
+    @parslet = transform(
+      parse(str))
+  end
+  
+  # Transforms the parse tree into a parslet expression. 
+  #
+  def transform(tree)
+    transform = Treetop::Transform.new
+    
+    pp tree
+    transform.apply(tree)
+  end
+  
+  # Parses the string and returns a parse tree.
+  #
+  def parse(str)
+    parser = Treetop::Parser.new
+    parser.parse(str)
+  end
+
+  # Turns this expression into a parslet.
+  #
+  def to_parslet
+    @parslet
+  end
+end

data/lib/parslet/expression/treetop.rb

@@ -0,0 +1,53 @@
+class Parslet::Expression::Treetop
+  class Parser < Parslet::Parser
+    root(:expression)
+    
+    rule(:expression) {
+      alternatives
+    }
+    
+    rule(:alternatives) {
+      simple >> (spaced('/') >> alternatives) |
+      simple
+    }
+    
+    rule(:simple) {
+      perhaps.repeat
+    }
+
+    rule(:perhaps) {
+      atom.as(:maybe) >> spaced('?') | 
+      atom
+    }
+    
+    rule(:atom) { 
+      spaced('(') >> expression.as(:unwrap) >> spaced(')') |
+      string 
+    }
+
+    rule(:string) {
+      str('\'') >> 
+      (
+        (str('\\') >> any) |
+        (str("'").absnt? >> any)
+      ).repeat.as(:string) >> 
+      str('\'') >> space?
+    }
+    
+    rule(:space) { match("\s").repeat(1) }
+    rule(:space?) { space.maybe }
+    
+    def spaced(str)
+      str(str) >> space?
+    end
+  end
+  
+  class Transform < Parser::Transform
+    rule(:unwrap => simple(:u)) { u }
+    rule(sequence(:s))          { |d| Parslet::Atoms::Sequence.new(*d[:s]) }
+    rule(:maybe => simple(:m))  { |d| d[:m].maybe }
+    rule(:string => simple(:s)) { |d| str(d[:s]) }
+  end
+  
+end
+

data/lib/parslet/parser.rb

@@ -0,0 +1,17 @@
+
+# The base class for all your parsers. Use as follows: 
+#
+#   require 'parslet'
+#        
+#   class MyParser < Parslet::Parser
+#     rule(:a) { str('a').repeat }
+#     root(:a)        
+#   end
+#        
+#   pp MyParser.new.parse('aaaa')   # => 'aaaa'
+#   pp MyParser.new.parse('bbbb')   # => Parslet::Atoms::ParseFailed: 
+#                                   #    Don't know what to do with bbbb at line 1 char 1.
+#
+class Parslet::Parser 
+  include Parslet
+end

data/lib/parslet/pattern.rb

@@ -1,4 +1,3 @@
-
 # Matches trees against expressions. Trees are formed by arrays and hashes
 # for expressing membership and sequence. The leafs of the tree are other
 # classes. 
@@ -20,6 +19,8 @@
 # to match recursively. To do that, please use Parslet::Transform. 
 #
 class Parslet::Pattern
+  autoload :Context, 'parslet/pattern/context'
+  
   def initialize(pattern)
     @pattern = pattern
   end
@@ -36,9 +37,11 @@ class Parslet::Pattern
   #   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)
-        block.call(bindings) if block
+        call_on_match(subtree, bindings, block)
       end
     end
     
@@ -53,6 +56,23 @@ class Parslet::Pattern
     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. 
+  #
+  def call_on_match(tree, 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
+  
+  # Handles preorder, depth-first recursion through the +expr+ given. 
+  #
   def recurse_into(expr, &block)
     # p [:attempt_match, expr]
     block.call(expr)
@@ -131,14 +151,4 @@ class Parslet::Pattern
     # Match succeeds
     return true
   end
-      
-  # Called on a bind variable, returns the variable name without the _
-  #
-  def variable_name(bind_var)
-    str = bind_var.to_s
-    
-    if str.size>1
-      str[1..-1].to_sym
-    end
-  end
 end

data/lib/parslet/pattern/binding.rb

@@ -2,25 +2,38 @@
 # Used internally for representing a bind placeholder in a Parslet::Transform
 # pattern. This is the superclass for all bindings. 
 #
-class Parslet::Pattern::Bind
-  attr_reader :symbol
-  def initialize(symbol)
-    @symbol = symbol
-  end
-
+# 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)
   def variable_name
     symbol
   end
+  
+  def inspect
+    "#{bind_type_name}(#{symbol.inspect})"
+  end
+  
+  def can_bind?(subtree)
+    true
+  end
+
+private 
+  def bind_type_name 
+    if md=self.class.name.match(/(\w+)Bind/)
+      md.captures.first.downcase
+    else
+      # This path should never be used, but since this is for inspection only, 
+      # let's not raise.
+      'unknown_bind'
+    end
+  end
 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::Bind
-  def inspect
-    "simple(#{symbol.inspect})"
-  end
-  
+class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind
   def can_bind?(subtree)
     not [Hash, Array].include?(subtree.class)
   end
@@ -28,11 +41,7 @@ end
 
 # Binds a symbol to a sequence of simple leafs ([element1, element2, ...])
 #
-class Parslet::Pattern::SequenceBind < Parslet::Pattern::Bind
-  def inspect
-    "sequence(#{symbol.inspect})"
-  end
-  
+class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind
   def can_bind?(subtree)
     subtree.kind_of?(Array) &&
       (not subtree.any? { |el| [Hash, Array].include?(el.class) })

data/lib/parslet/pattern/context.rb

@@ -0,0 +1,24 @@
+require 'blankslate'
+
+# Provides a context for tree transformations to run in. The context allows
+# accessing each of the bindings in the bindings hash as local method.
+#
+# Example: 
+#
+#   ctx = Context.new(:a => :b)
+#   ctx.instance_eval do 
+#     a # => :b
+#   end
+#
+class Parslet::Pattern::Context < BlankSlate
+  def initialize(bindings)
+    @bindings = bindings
+  end
+  
+  def method_missing(sym, *args, &block)
+    super unless args.empty?
+    super unless @bindings.has_key?(sym.to_sym)
+    
+    @bindings[sym]
+  end
+end

data/lib/parslet/transform.rb

@@ -20,36 +20,30 @@ require 'parslet/pattern'
 #
 # Example: 
 #
-#   transform = Parslet::Transform.new
-#   transform.rule(
-#     :string => simple(:x)       # (1)
-#   ) { |d| 
-#     StringLiteral.new(d[:x])    # (2)
-#   }
-#
-#   # Transforms the tree
-#   transform.apply(tree) 
+#   class Example < Parslet::Transform
+#     rule(:string => simple(:x)) {  # (1)
+#       StringLiteral.new(x)
+#     }
+#   end
 #
 # A tree transform (Parslet::Transform) is defined by a set of rules. Each
 # rule can be defined by calling #rule with the pattern as argument. The block
 # given will be called every time the rule matches somewhere in the tree given
 # to #apply. It is passed a Hash containing all the variable bindings of this
 # pattern match. 
-#  
-# In the above example, (1) illustrates a simple matching rule. In general,
-# such rules are composed of strings ("foobar"), arrays (["a", "b"]) and 
-# hashes like in the example above. 
+#   
+# In the above example, (1) illustrates a simple matching rule. 
 #
-# Let's say you want to parse matching parentheses and distill a maximum 
-# nest depth. You would probably write a parser like the one in example/parens.rb; 
+# Let's say you want to parse matching parentheses and distill a maximum nest
+# depth. You would probably write a parser like the one in example/parens.rb;
 # here's the relevant part: 
 #
 #   rule(:balanced) {
 #     str('(').as(:l) >> balanced.maybe.as(:m) >> str(')').as(:r)
 #   }
 #
-# If you now apply this to a string like '(())', you get a intermediate 
-# parse tree that looks like this: 
+# If you now apply this to a string like '(())', you get a intermediate parse
+# tree that looks like this: 
 #
 #   {
 #     :l => "(", 
@@ -61,20 +55,64 @@ require 'parslet/pattern'
 # This parse tree is good for debugging, but what we would really like to have
 # is just the nesting depth. This transformation rule will produce that: 
 #
-#   t.rule(:l => '(', :m => simple(:x), :r => ')') { |d| 
-#     depth = d[:x]
-#  
-#     depth.nil? ? 1 : depth+1 
+#   rule(:l => '(', :m => simple(:x), :r => ')') { 
+#     # innermost :m will contain nil
+#     x.nil? ? 1 : x+1
 #   }
-#   t.apply(tree) # => 2
 #
+# = Usage patterns
+#
+# There are four ways of using this class. The first one is very much
+# recommended, followed by the second one for generality. The other ones are
+# omitted here. 
+#
+# Recommended usage is as follows: 
+#
+#   class MyTransformator < Parslet::Transform
+#     rule(...) { ... }
+#     rule(...) { ... }
+#     # ...
+#   end
+#   MyTransformator.new.apply(tree)
+#
+# Alternatively, you can use the Transform class as follows: 
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { ... }
+#   end
+#   transform.apply(tree)
 #
 class Parslet::Transform
-  def initialize
+  # FIXME: Maybe only part of it? Or maybe only include into constructor
+  # context?
+  include Parslet   
+
+  class << self
+    # FIXME: Only do this for subclasses?
+    include Parslet
+    
+    # Define a rule for the transform subclass. 
+    #
+    def rule(expression, &block)
+      @__transform_rules ||= []
+      @__transform_rules << [Parslet::Pattern.new(expression), block]
+    end
+    
+    # Allows accessing the class' rules
+    #
+    def rules
+      @__transform_rules || []
+    end
+  end
+  
+  def initialize(&block)
     @rules = []
+    
+    if block
+      instance_eval(&block)
+    end
   end
   
-  attr_reader :rules
   def rule(expression, &block)
     @rules << [
       Parslet::Pattern.new(expression), 
@@ -95,11 +133,18 @@ class Parslet::Transform
     )
   end
   
+  # Allow easy access to all rules, the ones defined in the instance and the 
+  # ones predefined in a subclass definition. 
+  #
+  def rules
+    self.class.rules + @rules
+  end
+  
   def transform_elt(elt)
     rules.each do |pattern, block|
       if bindings=pattern.match(elt)
         # Produces transformed value
-        return block.call(bindings)
+        return pattern.call_on_match(elt, bindings, block)
       end
     end