parslet 1.5.0 → 1.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a03d43eaaf0b663727e308d79395c84019d63d0b
+  data.tar.gz: 2d39731312fe20e6640077b1cfb3b4a9c4ff34fd
+SHA512:
+  metadata.gz: 5aacc9ac06b08230c6301ededf169dba75ea056c082531d62120a380a536df66e4bd310fd8ae609578cd0da8c74989c4c2d71d50ffa4acd394074e36166fd305
+  data.tar.gz: 8b7151423f165f532c24b6f5a3b3a0ce88e990c95749a7b5c918451ad5d2ed59368b528f66f5a39312495b7d33bb3ff1e3da69aadcc135a968881de0b84754ce

data/HISTORY.txt

@@ -2,8 +2,29 @@
   
   - prsnt? and absnt? are now finally banned into oblivion. Wasting vocals for
     the win. 
+
+= 1.6 / ??
+
+  + EXPERIMENTAL: Parslet accelerators permit replacing parts of your parser 
+    with optimized atoms using pattern matching. Look at 
+    examples/optimized_erb.rb or the introduction to the feature in 
+    qed/accelerators.md.
+
+  + infix_expression permits to declare an infix expression parser (think 
+    calculator) directly. This will solve many of the problems we have 
+    more elegantly. 
+
+  + Rspec 3 syntax, though hideous, should now work. 
+
+  - Drops 1.8.7 compatibility. 
+
+  ! A performance anomaly when parsing multibyte characters has been detected
+    and fixed with the help of Zach Moazeni (@zmoazeni).
+
+  ! A few small bug fixes and optimisations have been introduced. API should 
+    remain unchanged. 
     
-= 1.5 / ??
+= 1.5 / 27Dec2012
     
   + Handles unconsumed input at end of parse completely differently. Instead
     of generating a toplevel error, it now raises an error in every branch

data/LICENSE

@@ -1,5 +1,4 @@
-
- Copyright (c) 2010 Kaspar Schiess
+ Copyright (c) 2010-2014 Kaspar Schiess
 
  Permission is hereby granted, free of charge, to any person
  obtaining a copy of this software and associated documentation

data/README

@@ -51,20 +51,23 @@ SYNOPSIS
   # and then
   Smalltalk.new.parse('smalltalk')
 
-COMPATIBILITY
+FEATURES
 
-This library should work with most rubies. I've tested it with MRI 1.8 
-(except 1.8.6), 1.9, rbx-head, jruby. Please report as a bug if you encounter 
-issues.
+  * Tools for every part of the parser chain
+  * Transformers generate Abstract Syntax Trees
+  * Accelerators transform parsers, making them quite a bit faster
+  * Pluggable error reporters
+  * Graphviz export for your parser
+  * Rspec testing support rig
+  * Simply Ruby, composable and hackable
 
-Note that due to Ruby 1.8 internals, Unicode parsing is not supported on that 
-version. 
+COMPATIBILITY
 
-On Mac OS X Lion, ruby-1.8.7-p352 has been known to segfault. Use
-ruby-1.8.7-p334 for better results.
+This library is intended to work with Ruby variants >= 1.9. I've tested it on 
+MRI 1.9, rbx-head, jruby. Please report as a bug if you encounter issues.
 
 STATUS 
 
 Production worthy.
 
-(c) 2010, 2011, 2012 Kaspar Schiess
+(c) 2010-2014 Kaspar Schiess

data/example/big.erb

@@ -0,0 +1,73 @@
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+<%= erb tag %>
+
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
+consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

data/example/email_parser.rb

@@ -44,9 +44,11 @@ end
 parser = EmailParser.new
 sanitizer = EmailSanitizer.new
 
-unless ARGV[0]
+input = ARGV[0] || begin
+  default = "a.b.c.d@gmail.com"
   STDERR.puts "usage: #{$0} \"EMAIL_ADDR\""
-  STDOUT.puts "since you haven't specified any EMAIL_ADDR, for testing purposes we're using a.b.c.d@gmail.com"
+  STDOUT.puts "since you haven't specified any EMAIL_ADDR, for testing purposes we're using #{default}"
+  default
 end
 
-p sanitizer.apply(parser.parse_with_debug(ARGV[0] || 'a.b.c.d@gmail.com'))
+p sanitizer.apply(parser.parse_with_debug(input))

data/example/optimized_erb.rb

@@ -0,0 +1,42 @@
+# Please also look at the more naive 'erb.rb'. This shows how to optimize an
+# ERB like parser using parslet. 
+
+$:.unshift File.join(File.dirname(__FILE__), "/../lib")
+
+require 'parslet'
+require './qed/applique/gobbleup'
+require 'parslet/accelerator'
+
+class ErbParser < Parslet::Parser
+  rule(:ruby) { (str('%>').absent? >> any).repeat.as(:ruby) }
+  
+  rule(:expression) { (str('=') >> ruby).as(:expression) }
+  rule(:comment) { (str('#') >> ruby).as(:comment) }
+  rule(:code) { ruby.as(:code) }
+  rule(:erb) { expression | comment | code }
+  
+  rule(:erb_with_tags) { str('<%') >> erb >> str('%>') }
+  rule(:text) { (str('<%').absent? >> any).repeat(1) }
+  
+  rule(:text_with_ruby) { (text.as(:text) | erb_with_tags).repeat.as(:text) }
+  root(:text_with_ruby)
+end
+
+parser = ErbParser.new
+
+A = Parslet::Accelerator
+optimized = A.apply(parser, 
+  A.rule((A.str(:x).absent? >> A.any).repeat(1)) { GobbleUp.new(x, 1) }, 
+  A.rule((A.str(:x).absent? >> A.any).repeat(0)) { GobbleUp.new(x, 0) })
+
+input = File.read(File.dirname(__FILE__) + "/big.erb")
+
+# Remove the comment marks here to see what difference the optimisation makes.
+# Commented out for the acceptance tests to run. 
+#
+# require 'benchmark'
+# Benchmark.bm(7) do |bm|
+#   bm.report('original') { parser.parse(input) }
+#   bm.report('gobble') { optimized.parse(input) }
+# end
+p optimized.parse(input)

data/example/output/optimized_erb.out

@@ -0,0 +1 @@
+{:text=>[{:text=>"Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\n"@0}, {:expression=>{:ruby=>" erb tag "@2685}}, {:text=>"\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"@2696}]}

data/example/output/prec_calc.out

@@ -0,0 +1,5 @@
+a = 1
+b = 2
+c = 3 * 25
+d = 100 + 3*4
+{:a=>1, :b=>2, :c=>75, :d=>112}

data/example/prec_calc.rb

@@ -0,0 +1,71 @@
+
+# A demonstration of the new precedence climbing infix expression parser. 
+
+$:.unshift File.dirname(__FILE__) + "/../lib"
+
+require 'pp'
+require 'rspec'
+require 'parslet'
+require 'parslet/rig/rspec'
+require 'parslet/convenience'
+
+class InfixExpressionParser < Parslet::Parser
+  root :variable_assignment_list
+
+  rule(:space) { match[' '] }
+
+  def cts atom
+    atom >> space.repeat
+  end
+  def infix *args
+    Infix.new(*args)
+  end
+
+  # This is the heart of the infix expression parser: real simple definitions
+  # for all the pieces we need. 
+  rule(:mul_op) { cts match['*/'] }
+  rule(:add_op) { cts match['+-'] }
+  rule(:digit) { match['0-9'] }
+  rule(:integer) { cts digit.repeat(1).as(:int) }
+
+  rule(:expression) { infix_expression(integer, 
+    [mul_op, 2, :left], 
+    [add_op, 1, :right]) }
+
+  # And now adding variable assignments to that, just to a) demonstrate this
+  # embedded in a bigger parser, and b) make the example interesting. 
+  rule(:variable_assignment_list) { 
+    variable_assignment.repeat(1) }
+  rule(:variable_assignment) {
+    identifier.as(:ident) >> equal_sign >> expression.as(:exp) >> eol }
+  rule(:identifier) {
+    cts (match['a-z'] >> match['a-zA-Z0-9'].repeat) }
+  rule(:equal_sign) {
+    cts str('=') }
+  rule(:eol) {
+    cts(str("\n")) | any.absent? }
+end
+
+class InfixInterpreter < Parslet::Transform
+  rule(int: simple(:int)) { Integer(int) }
+  rule(ident: simple(:ident), exp: simple(:result)) { |d| 
+    d[:doc][d[:ident].to_s.strip.to_sym] = d[:result] }
+
+  rule(l: simple(:l), o: /^\*/, r: simple(:r)) { l * r }
+  rule(l: simple(:l), o: /^\+/, r: simple(:r)) { l + r }
+end
+
+input = <<ASSIGNMENTS
+a = 1
+b = 2
+c = 3 * 25
+d = 100 + 3*4
+ASSIGNMENTS
+
+puts input
+
+int_tree = InfixExpressionParser.new.parse_with_debug(input)
+bindings = {}
+result   = InfixInterpreter.new.apply(int_tree, doc: bindings)
+
+pp bindings

data/lib/parslet.rb

@@ -199,6 +199,38 @@ module Parslet
     Parslet::Atoms::Dynamic.new(block)
   end
   module_function :dynamic
+
+  # Returns a parslet atom that parses infix expressions. Operations are 
+  # specified as a list of <atom, precedence, associativity> tuples, where 
+  # atom is simply the parslet atom that matches an operator, precedence is 
+  # a number and associativity is either :left or :right. 
+  # 
+  # Higher precedence indicates that the operation should bind tighter than
+  # other operations with lower precedence. In common algebra, '+' has 
+  # lower precedence than '*'. So you would have a precedence of 1 for '+' and
+  # a precedence of 2 for '*'. Only the order relation between these two 
+  # counts, so any number would work. 
+  #
+  # Associativity is what decides what interpretation to take for strings that
+  # are ambiguous like '1 + 2 + 3'. If '+' is specified as left associative, 
+  # the expression would be interpreted as '(1 + 2) + 3'. If right 
+  # associativity is chosen, it would be interpreted as '1 + (2 + 3)'. Note 
+  # that the hash trees output reflect that choice as well. 
+  #
+  # Example:
+  #   infix_expression(integer, [add_op, 1, :left])
+  #   # would parse things like '1 + 2'
+  #
+  # @param element [Parslet::Atoms::Base] elements that take the NUMBER position
+  #    in the expression
+  # @param operations [Array<(Parslet::Atoms::Base, Integer, {:left, :right})>]
+  #  
+  # @see Parslet::Atoms::Infix
+  #
+  def infix_expression(element, *operations)
+    Parslet::Atoms::Infix.new(element, operations)
+  end
+  module_function :infix_expression
   
   # A special kind of atom that allows embedding whole treetop expressions
   # into parslet construction. 
@@ -254,7 +286,7 @@ module Parslet
     Pattern::SubtreeBind.new(symbol)
   end
   module_function :subtree
-  
+
   autoload :Expression, 'parslet/expression'
 end
 

data/lib/parslet/accelerator.rb

@@ -0,0 +1,161 @@
+
+
+# Optimizes the parsers by pattern matching on the parser atoms and replacing
+# matches with better versions. See the file qed/accelerators.md for a more
+# in-depth description.
+#
+# Example: 
+#   quote = str('"')
+#   parser = quote >> (quote.absent? >> any).repeat >> quote
+#
+#   A = Accelerator # for making what follows a bit shorter
+#   optimized_parser = A.apply(parser, 
+#     A.rule( (A.str(:x).absent? >> A.any).repeat ) { GobbleUp.new(x) })
+#
+#   optimized_parser.parse('"Parsing is now fully optimized! (tm)"')
+#
+module Parslet::Accelerator
+
+  # An expression to match against a tree of parser atoms. Normally, an
+  # expression is produced by Parslet::Accelerator.any, 
+  # Parslet::Accelerator.str or Parslet::Accelerator.re.
+  #
+  # Expressions can be chained much like parslet atoms can be: 
+  #
+  #   expr.repeat(1)      # matching repetition
+  #   expr.absent?        # matching absent?
+  #   expr.present?       # matching present?
+  #   expr1 >> expr2      # matching a sequence
+  #   expr1 | expr2       # matching an alternation
+  # 
+  # @see Parslet::Accelerator.str
+  # @see Parslet::Accelerator.re
+  # @see Parslet::Accelerator.any
+  #
+  # @see Parslet::Accelerator
+  # 
+  class Expression
+    attr_reader :type
+    attr_reader :args
+
+    def initialize(type, *args)
+      @type = type
+      @args = args
+    end
+
+    # @return [Expression]
+    def >> other_expr
+      join_or_new :seq, other_expr
+    end
+
+    # @return [Expression]
+    def | other_expr
+      join_or_new :alt, other_expr
+    end
+
+    # @return [Expression]
+    def absent?
+      Expression.new(:absent, self)
+    end
+    # @return [Expression]
+    def present?
+      Expression.new(:present, self)
+    end
+
+    # @return [Expression]
+    def repeat min=0, max=nil
+      Expression.new(:rep, min, max, self)
+    end
+
+    # @return [Expression]
+    def as name
+      Expression.new(:as, name)
+    end
+
+    # @api private
+    # @return [Expression]
+    def join_or_new tag, other_expr
+      if type == tag
+        @args << other_expr
+      else
+        Expression.new(tag, self, other_expr)
+      end
+    end
+  end
+
+module_function 
+  # Returns a match expression that will match `str` parslet atoms.
+  #
+  # @return [Parslet::Accelerator::Expression]
+  #
+  def str variable, *constraints
+    Expression.new(:str, variable, *constraints)
+  end
+
+  # Returns a match expression that will match `match` parslet atoms.
+  #
+  # @return [Parslet::Accelerator::Expression]
+  #
+  def re variable, *constraints
+    Expression.new(:re, variable, *constraints)
+  end
+
+  # Returns a match expression that will match `any` parslet atoms.
+  #
+  # @return [Parslet::Accelerator::Expression]
+  #
+  def any
+    Expression.new(:re, ".")
+  end
+
+  # Given a parslet atom and an expression, will determine if the expression
+  # matches the atom. If successful, returns the bindings into the pattern
+  # that were made. If no bindings had to be made to make the match successful, 
+  # the empty hash is returned. 
+  #
+  # @param atom [Parslet::Atoms::Base] parslet atom to match against
+  # @param expr [Parslet::Accelerator::Expression] expression to match
+  # @return [nil, Hash] bindings for the match, nil on failure
+  #
+  def match atom, expr
+    engine = Engine.new
+
+    return engine.bindings if engine.match(atom, expr)
+  end
+
+  # Constructs an accelerator rule. A rule is a matching expression and the
+  # code that should be executed once the expression could be bound to a 
+  # parser. 
+  #
+  # Example: 
+  #   Accelerator.rule(Accelerator.any) { Parslet.match('.') }
+  #
+  def rule expression, &action
+    [expression, action]
+  end
+
+  # Given a parslet atom and a set of rules, tries to match the rules 
+  # recursively through the parslet atom. Once a rule could be matched, 
+  # its action block will be called.
+  #
+  # Example: 
+  #   quote = str('"')
+  #   parser = quote >> (quote.absent? >> any).repeat >> quote
+  #
+  #   A = Accelerator # for making what follows a bit shorter
+  #   optimized_parser = A.apply(parser, 
+  #     A.rule( (A.str(:x).absent? >> A.any).repeat ) { GobbleUp.new(x) })
+  #
+  #   optimized_parser.parse('"Parsing is now fully optimized! (tm)"')
+  #
+  # @param atom [Parslet::Atoms::Base] a parser to optimize
+  # @param *rules [Parslet::Accelerator::Rule] rules produced by .rule
+  # @return [Parslet::Atoms::Base] optimized parser
+  #
+  def apply atom, *rules
+    Application.new(atom, rules).call
+  end
+end
+
+require 'parslet/accelerator/engine'
+require 'parslet/accelerator/application'