parslet 0.9.0

data/lib/parslet/error_tree.rb

@@ -0,0 +1,50 @@
+
+# A tree structure that contains parse error messages. This can be used to
+# give the user a detailed report on what went wrong during a parse. 
+#
+class Parslet::ErrorTree
+  # The parslet that caused the error stored here. 
+  attr_reader :parslet
+  # All errors that were encountered when parsing part of this +parslet+. 
+  attr_reader :children
+    
+  def initialize(parslet, *children)
+    @parslet = parslet
+    @children = children.compact
+  end
+  
+  def nodes
+    1 + children.inject(0) { |sum, node| sum + node.nodes }
+  end
+  
+  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. 
+  #
+  def ascii_tree
+    StringIO.new.tap { |io| 
+      recursive_ascii_tree(self, io, [true]) }.
+      string
+  end
+private
+  def recursive_ascii_tree(node, stream, curved)
+    append_prefix(stream, curved)
+    stream.puts node
+    
+    node.children.each do |child|
+      last_child = (node.children.last == child)
+
+      recursive_ascii_tree(child, stream, curved + [last_child])
+    end
+  end
+  def append_prefix(stream, curved)
+    curved[0..-2].each do |c|
+      stream.print c ? "   " : "|  "
+    end
+    stream.print curved.last ? "`- " : "|- "
+  end
+end

data/lib/parslet/pattern.rb

@@ -0,0 +1,144 @@
+
+# Matches trees against expressions. Trees are formed by arrays and hashes
+# for expressing membership and sequence. The leafs of the tree are other
+# classes. 
+#
+# A tree issued by the parslet library might look like this: 
+#
+#   { 
+#     :function_call => {
+#       :name => 'foobar', 
+#       :args => [1, 2, 3]
+#     }
+#   }
+#
+# A pattern that would match against this tree would be: 
+#
+#   { :function_call => { :name => simple(:name), :args => sequence(:args) }}
+#
+# 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
+  def initialize(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
+    recurse_into(tree) do |subtree|
+      if bindings=match(subtree)
+        block.call(bindings) if 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. 
+  #
+  def match(subtree)
+    bindings = {}
+    return bindings if element_match(subtree, @pattern, bindings)
+  end
+
+  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+. 
+  #
+  def element_match(tree, exp, bindings) 
+    # p [:elm, tree, exp]
+    case [tree, exp].map { |e| e.class }
+      when [Hash,Hash]
+        return element_match_hash(tree, exp, bindings)
+      when [Array,Array]
+        return element_match_ary_single(tree, exp, bindings)
+    else
+      # If elements match exactly, then that is good enough in all cases
+      return true if tree == exp
+      
+      # If exp is a bind variable: Check if the binding matches
+      if exp.respond_to?(:can_bind?) && exp.can_bind?(tree)
+        return element_match_binding(tree, exp, bindings)
+      end
+                  
+      # Otherwise: No match (we don't know anything about the element
+      # combination)
+      return false
+    end
+  end
+  
+  def element_match_binding(tree, exp, bindings)
+    var_name = exp.variable_name
+
+    # TODO test for the hidden :_ feature.
+    if var_name && bound_value = bindings[var_name]
+      return bound_value == tree
+    end
+    
+    # New binding: 
+    bindings.store var_name, tree
+    
+    return true
+  end
+  
+  def element_match_ary_single(sequence, exp, bindings)
+    return false if sequence.size != exp.size
+    
+    return sequence.zip(exp).all? { |elt, subexp|
+      element_match(elt, subexp, bindings) }
+  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]
+      
+      # Recurse into the values
+      unless element_match(tree_value, exp_value, bindings)
+        # Stop matching early
+        return false
+      end
+    end
+    
+    # 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

@@ -0,0 +1,40 @@
+
+# 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
+
+  def variable_name
+    symbol
+  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
+  
+  def can_bind?(subtree)
+    not [Hash, Array].include?(subtree.class)
+  end
+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
+  
+  def can_bind?(subtree)
+    subtree.kind_of?(Array) &&
+      (not subtree.any? { |el| [Hash, Array].include?(el.class) })
+  end
+end

data/lib/parslet/transform.rb

@@ -0,0 +1,118 @@
+
+require 'parslet/pattern'
+
+# Transforms an expression tree into something else. The transformation
+# performs a depth-first, post-order traversal of the expression tree. During
+# that traversal, each time a rule matches a node, the node is replaced by the
+# result of the block associated to the rule. Otherwise the node is accepted
+# as is into the result tree.
+#
+# This is almost what you would generally do with a tree visitor, except that
+# you can match several levels of the tree at once. 
+#
+# As a consequence of this, the resulting tree will contain pieces of the
+# original tree and new pieces. Most likely, you will want to transform the
+# original tree wholly, so this isn't a problem.
+#
+# You will not be able to create a loop, given that each node will be replaced
+# only once and then left alone. This means that the results of a replacement
+# will not be acted upon. 
+#
+# Example: 
+#
+#   transform = Parslet::Transform.new
+#   transform.rule(
+#     :string => simple(:x)       # (1)
+#   ) { |d| 
+#     StringLiteral.new(d[:x])    # (2)
+#   }
+#
+#   # Transforms the tree
+#   transform.apply(tree) 
+#
+# 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. 
+#
+# 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: 
+#
+#   {
+#     :l => "(", 
+#     :m => {
+#       :l=>"(", :m=>nil, :r=>")" }, 
+#     :r => ")"
+#   }
+#
+# 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 
+#   }
+#   t.apply(tree) # => 2
+#
+#
+class Parslet::Transform
+  def initialize
+    @rules = []
+  end
+  
+  attr_reader :rules
+  def rule(expression, &block)
+    @rules << [
+      Parslet::Pattern.new(expression), 
+      block
+    ]
+  end
+  
+  def apply(obj)
+    transform_elt(
+      case obj
+        when Hash
+          recurse_hash(obj)
+        when Array
+          recurse_array(obj)
+      else
+        obj
+      end
+    )
+  end
+  
+  def transform_elt(elt)
+    rules.each do |pattern, block|
+      if bindings=pattern.match(elt)
+        # Produces transformed value
+        return block.call(bindings)
+      end
+    end
+    
+    # No rule matched - element is not transformed
+    return elt
+  end
+  def recurse_hash(hsh)
+    hsh.inject({}) do |new_hsh, (k,v)|
+      new_hsh[k] = apply(v)
+      new_hsh
+    end
+  end
+  def recurse_array(ary)
+    ary.map { |elt| apply(elt) }
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification 
+name: parslet
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 0
+  version: 0.9.0
+platform: ruby
+authors: 
+- Kaspar Schiess
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-29 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: flexmock
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: 
+email: kaspar.schiess@absurd.li
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- Gemfile
+- HISTORY.txt
+- LICENSE
+- Rakefile
+- README
+- lib/parslet/atoms.rb
+- lib/parslet/error_tree.rb
+- lib/parslet/pattern/binding.rb
+- lib/parslet/pattern.rb
+- lib/parslet/transform.rb
+- lib/parslet.rb
+has_rdoc: true
+homepage: http://kschiess.github.com/parslet
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Parser construction library with great error reporting in Ruby.
+test_files: []
+