walrat 0.1

data/lib/walrat.rb

@@ -0,0 +1,70 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# Ruby 1.9 support
+require 'continuation' unless Kernel.respond_to?(:callcc)
+
+module Walrat
+  major, minor = RUBY_VERSION.split '.'
+  if major == '1' and minor == '8'
+    $KCODE  = 'U' # UTF-8 (necessary for Unicode support)
+  end
+
+  autoload :AndPredicate,                 'walrat/and_predicate'
+  autoload :ArrayResult,                  'walrat/array_result'
+  autoload :ContinuationWrapperException, 'walrat/continuation_wrapper_exception'
+  autoload :Grammar,                      'walrat/grammar'
+  autoload :LeftRecursionException,       'walrat/left_recursion_exception'
+  autoload :LocationTracking,             'walrat/location_tracking'
+  autoload :MatchDataWrapper,             'walrat/match_data_wrapper'
+  autoload :Memoizing,                    'walrat/memoizing'
+  autoload :MemoizingCache,               'walrat/memoizing_cache'
+  autoload :Node,                         'walrat/node'
+  autoload :NoParameterMarker,            'walrat/no_parameter_marker'
+  autoload :NotPredicate,                 'walrat/not_predicate'
+  autoload :ParseError,                   'walrat/parse_error'
+  autoload :ParserState,                  'walrat/parser_state'
+
+  # TODO: move these into subdirectory? directory for predicates also?
+  autoload :Parslet,                      'walrat/parslet'
+  autoload :ParsletChoice,                'walrat/parslet_choice'
+  autoload :ParsletCombination,           'walrat/parslet_combination'
+  autoload :ParsletCombining,             'walrat/parslet_combining'
+  autoload :ParsletMerge,                 'walrat/parslet_merge'
+  autoload :ParsletOmission,              'walrat/parslet_omission'
+  autoload :ParsletRepetition,            'walrat/parslet_repetition'
+  autoload :ParsletRepetitionDefault,     'walrat/parslet_repetition_default'
+  autoload :ParsletSequence,              'walrat/parslet_sequence'
+  autoload :Predicate,                    'walrat/predicate'
+  autoload :ProcParslet,                  'walrat/proc_parslet'
+  autoload :RegexpParslet,                'walrat/regexp_parslet'
+  autoload :SkippedSubstringException,    'walrat/skipped_substring_exception'
+  autoload :StringEnumerator,             'walrat/string_enumerator'
+  autoload :StringParslet,                'walrat/string_parslet'
+  autoload :StringResult,                 'walrat/string_result'
+  autoload :SymbolParslet,                'walrat/symbol_parslet'
+end # module Walrat
+
+require 'walrat/additions/proc'
+require 'walrat/additions/regexp'
+require 'walrat/additions/string'
+require 'walrat/additions/symbol'

data/lib/walrat/additions/proc.rb

@@ -0,0 +1,32 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+class Proc
+  include Walrat::ParsletCombining
+
+  # Returns a ProcParslet based on the receiver
+  def to_parseable
+    Walrat::ProcParslet.new self
+  end
+end # class Proc

data/lib/walrat/additions/regexp.rb

@@ -0,0 +1,33 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+class Regexp
+  require 'walrat/parslet_combining'
+  include Walrat::ParsletCombining
+
+  # Returns a RegexpParslet based on the receiver
+  def to_parseable
+    Walrat::RegexpParslet.new self
+  end
+end # class Regexp

data/lib/walrat/additions/string.rb

@@ -0,0 +1,99 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+# Additions to String class for Unicode support.
+# Parslet combining methods.
+# Convenience methods (to_parseable).
+# Conversion utility methods.
+class String
+  alias old_range []
+
+  def jlength
+    chars.to_a.length
+  end
+
+  # NOTE: this is a totally Walrat-specific implementation that is
+  # unlikely to be of use anywhere else. It is used in only 1 place
+  # in the codebase, and works around the fact that the MatchData
+  # made available by the index method gets clobbered by the
+  # "chars.to_a" call. The same thing happens for alternative
+  # methods of counting the chars, such as using jlength or a manual
+  # scan.
+  #
+  # One workaround is for the caller to re-perform the index call just
+  # to get the MatchData again, but that is inefficient. So here we
+  # just do the addition before returning the result to the caller.
+  def jindex_plus_length arg
+    if i = index(arg)
+      $~[0].length + unpack('C*')[0...i].pack('C*').chars.to_a.length
+    end
+  end
+
+  # Unlike the normal rindex method, the MatchData in $~ set by the inner
+  # rindex call gets clobbered (by the "chars.to_a" call) and is not visible to
+  # the caller of this method.
+  def jrindex arg, offset = Walrat::NoParameterMarker.instance
+    if offset == Walrat::NoParameterMarker.instance
+      i = rindex arg
+    else
+      i = rindex arg, offset
+    end
+    i ? unpack('C*')[0...i].pack('C*').chars.to_a.length : nil
+  end
+
+  # multi-byte friendly [] implementation
+  def [](range, other = Walrat::NoParameterMarker.instance)
+    if other == Walrat::NoParameterMarker.instance
+      if range.kind_of? Range
+        chars.to_a[range].join
+      else
+        old_range range
+      end
+    else
+      old_range range, other
+    end
+  end
+
+  # Returns a character-level enumerator for the receiver.
+  def enumerator
+    Walrat::StringEnumerator.new self
+  end
+
+  # Rationale: it's ok to add "&" and "|" methods to string because they don't
+  # exist yet (they're not overrides).
+  include Walrat::ParsletCombining
+
+  # Returns a StringParslet based on the receiver
+  def to_parseable
+    Walrat::StringParslet.new self
+  end
+
+  # Converts the receiver of the form "foo_bar" to "FooBar". Specifically, the
+  # receiver is split into pieces delimited by underscores, each component is
+  # then converted to captial case (the first letter is capitalized and the
+  # remaining letters are lowercased) and finally the components are joined.
+  def to_class_name
+    self.split('_').collect { |component| component.capitalize}.join
+  end
+end # class String

data/lib/walrat/additions/symbol.rb

@@ -0,0 +1,42 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+class Symbol
+  include Walrat::ParsletCombining
+
+  # Returns a SymbolParslet based on the receiver.
+  # Symbols can be used in Grammars when specifying rules and productions to
+  # refer to other rules and productions that have not been defined yet.
+  # They can also be used to allow self-references within rules and productions
+  # (recursion); for example:
+  #
+  #   rule :thing & :thing.optional & :other_thing
+  #
+  # Basically these SymbolParslets allow deferred evaluation of a rule or
+  # production (deferred until parsing takes place) rather than being evaluated
+  # at the time a rule or production is defined.
+  def to_parseable
+    Walrat::SymbolParslet.new self
+  end
+end # class Symbol

data/lib/walrat/and_predicate.rb

@@ -0,0 +1,49 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+module Walrat
+  class AndPredicate < Predicate
+    def parse string, options = {}
+      raise ArgumentError if string.nil?
+      catch :ZeroWidthParseSuccess do
+        begin
+          parsed = @parseable.memoizing_parse string, options
+        rescue ParseError
+          raise ParseError.new('predicate not satisfied (expected "%s") while parsing "%s"' % [@parseable.to_s, string],
+                               :line_end => options[:line_start],
+                               :column_end => options[:column_start])
+        end
+      end
+
+      # getting this far means that parsing succeeded
+      throw :AndPredicateSuccess
+    end
+
+  private
+
+    def hash_offset
+      12
+    end
+  end
+end # module Walrat

data/lib/walrat/array_result.rb

@@ -0,0 +1,29 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+module Walrat
+  class ArrayResult < Array
+    include LocationTracking
+  end # class ArrayResult
+end # module Walrat

data/lib/walrat/continuation_wrapper_exception.rb

@@ -0,0 +1,35 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+
+module Walrat
+  class ContinuationWrapperException < Exception
+    attr_reader :continuation
+
+    def initialize continuation
+      raise ArgumentError, 'nil continuation' if continuation.nil?
+      super self.class.to_s
+      @continuation = continuation
+    end
+  end # class ContinuationWrapperException
+end # module Walrat

data/lib/walrat/grammar.rb

@@ -0,0 +1,259 @@
+# Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require 'walrat'
+require 'walrat/additions/string.rb'
+
+module Walrat
+  class Grammar
+    class << self
+      # Lazy reader for the rules hash.
+      #
+      # Initializes the hash the first time it is accessed.
+      def rules
+        @rules or @rules = Hash.new do |hash, key|
+          raise "no rule for key '#{key}'"
+        end
+      end
+
+      # Lazy reader for the productions hash.
+      #
+      # Initializes the hash the first time it is accessed.
+      def productions
+        @productions or @productions = Hash.new do |hash, key|
+          raise "no production for key '#{key}'"
+        end
+      end
+
+      # Lazy reader for the skipping overrides hash.
+      #
+      # Initializes the hash the first time it is accessed.
+      def skipping_overrides
+        @skipping_overrides or @skipping_overrides = Hash.new do |hash, key|
+          raise "no skipping override for key '#{key}'"
+        end
+      end
+
+      # Sets the starting symbol.
+      #
+      # @param [Symbol] symbol a symbol which refers to a rule
+      def starting_symbol symbol
+        raise ArgumentError, 'starting symbol already set' if @starting_symbol
+        @starting_symbol = symbol
+      end
+
+      # Returns the starting symbol.
+      #
+      # Note that the "starting_symbol" method can't be used as an accessor
+      # because it is already used as part of the grammar-definition DSL.
+      def start_rule
+        @starting_symbol
+      end
+
+      # Sets the default parslet that is used for skipping inter-token
+      # whitespace, and can be used to override the default on a rule-by-rule
+      # basis.
+      #
+      # This allows for simpler grammars which do not need to explicitly put
+      # optional whitespace parslets (or any other kind of parslet) between
+      # elements.
+      #
+      # There are two modes of operation for this method. In the first mode
+      # (when only one parameter is passed) the rule_or_parslet parameter is
+      # used to define the default parslet for inter-token skipping.
+      # rule_or_parslet must refer to a rule which itself is a Parslet or
+      # ParsletCombination and which is responsible for skipping. Note that the
+      # ability to pass an arbitrary parslet means that the notion of what
+      # consitutes the "whitespace" that should be skipped is completely
+      # flexible. Raises if a default skipping parslet has already been set.
+      #
+      # In the second mode of operation (when two parameters are passed) the
+      # rule_or_parslet parameter is interpreted to be the rule to which an
+      # override should be applied, where the parslet parameter specifies the
+      # parslet to be used in this case. If nil is explicitly passed then this
+      # overrides the default parslet; no parslet will be used for the purposes
+      # of inter-token skipping. Raises if an override has already been set for
+      # the named rule.
+      #
+      # The inter-token parslet is passed inside the "options" hash when
+      # invoking the "parse" methods. Any parser which fails will retry after
+      # giving this inter-token parslet a chance to consume and discard
+      # intervening whitespace.
+      #
+      # The initial, conservative implementation only performs this fallback
+      # skipping for ParsletSequence and ParsletRepetition combinations.
+      #
+      # Raises if rule_or_parslet is nil.
+      def skipping rule_or_parslet, parslet = NoParameterMarker.instance
+        raise ArgumentError, 'nil rule_or_parslet' if rule_or_parslet.nil?
+        if parslet == NoParameterMarker.instance
+          # first mode of operation: set default parslet
+          raise 'default skipping parslet already set' if @skipping
+          @skipping = rule_or_parslet
+        else
+          # second mode of operation: override default case
+          raise ArgumentError,
+            "skipping override already set for rule '#{rule_or_parslet}'" if
+            skipping_overrides.has_key? rule_or_parslet
+          raise ArgumentError,
+            "non-existent rule '#{rule_or_parslet}'" unless
+            rules.has_key? rule_or_parslet
+          skipping_overrides[rule_or_parslet] = parslet
+        end
+      end
+
+      # Returns the default skipping rule.
+      #
+      # Note that we can't use "skipping" as the accessor method here because
+      # it is already used as part of the grammar-definition DSL.
+      def default_skipping_rule
+        @skipping
+      end
+
+      # Defines a rule and stores it
+      #
+      # Expects an object that responds to the parse message, such as a Parslet
+      # or ParsletCombination. As this is intended to work with Parsing
+      # Expression Grammars, each rule may only be defined once. Defining a
+      # rule more than once will raise an ArgumentError.
+      def rule symbol, parseable
+        raise ArgumentError, 'nil symbol' if symbol.nil?
+        raise ArgumentError, 'nil parseable' if parseable.nil?
+        raise ArgumentError,
+          "rule '#{symbol}' already defined" if rules.has_key? symbol
+        rules[symbol] = parseable
+      end
+
+      # Dynamically creates a Node subclass inside the namespace of the current
+      # grammar.
+      #
+      # This is used to create classes in a class hierarchy where no custom
+      # behavior is required and therefore no actual file with an impementation
+      # need be provided; an example from the Walrus grammar:
+      #
+      #     module Walrus
+      #       class Grammar < Walrat::Grammar
+      #         class Literal < Walrat::Node
+      #           class StringLiteral < Literal
+      #             class DoubleQuotedStringLiteral < StringLiteral
+      #
+      # In this example hiearchy the "Literal" class has custom behavior which
+      # is shared by all subclasses, and the custom behavior is implemented in
+      # the file "walrus/grammar/literal". The subclasses, however, have no
+      # custom behavior and no associated file. They are dynamically
+      # synthesized when the Walrus::Grammar class is first evaluated.
+      def node new_class_name, parent_class = Node
+        raise ArgumentError, 'nil new_class_name' if new_class_name.nil?
+        new_class_name = new_class_name.to_s.to_class_name # camel-case
+        unless parent_class.kind_of? Class
+          parent_class = const_get parent_class.to_s.to_class_name
+        end
+        const_set new_class_name, Class.new(parent_class)
+      end
+
+      # Specifies that a Node subclass will be used to encapsulate results
+      # for the rule identified by the symbol, rule_name. The class name is
+      # derived by converting the rule_name to camel-case.
+      #
+      # If no additional params are supplied then the class is assumed to
+      # accept a single  parameter named "lexeme" in its initialize method.
+      #
+      # If additional params are supplied then the class is expected to
+      # accept the named params in its initialize method.
+      #
+      # As a convenience, the params will be sent to the specified class using
+      # the "production" method, which sets up an appropriate initializer.
+      #
+      # For example:
+      #
+      #     # accepts a single parameter, "lexeme"
+      #     production :symbol_literal
+      #
+      #     # accepts a single parameter, "content"
+      #     production :multiline_comment, :content
+      #
+      #     # accepts three parameters, "identifier", "params" and "content"
+      #     production :block_directive, :identifier, :params, :content
+      #
+      def production rule_name, *results
+        raise ArgumentError, 'nil rule_name' if rule_name.nil?
+        raise ArgumentError,
+          "production already defined for rule '#{rule_name}'" if
+          productions.has_key?(rule_name)
+        raise ArgumentError, "non-existent rule '#{rule_name}'" unless
+          rules.has_key?(rule_name)
+        results = results.empty? ? [:lexeme] : results
+        const_get(rule_name.to_s.to_class_name).production *results
+        productions[rule_name] = results
+      end
+
+      # This method is called by the ParsletSequence and SymbolParslet classes
+      # to possibly wrap a parse result in a production node.
+      def wrap result, rule_name
+        if productions.has_key? rule_name.to_sym
+          node_class          = const_get rule_name.to_s.to_class_name
+          param_count         = productions[rule_name.to_sym].length
+          if param_count == 1
+            node              = node_class.new result
+          else
+            node              = node_class.new *result
+          end
+          node.start          = (result.outer_start or result.start)              # propagate the start information
+          node.end            = (result.outer_end or result.end)                  # and the end information
+          node.source_text    = (result.outer_source_text or result.source_text)  # and the original source text
+          node
+        else
+          result.start        = result.outer_start if result.outer_start
+          result.end          = result.outer_end if result.outer_end
+          result.source_text  = result.source_text if result.outer_source_text
+          result
+        end
+      end
+    end
+
+    attr_accessor :memoizing
+
+    def initialize
+      @memoizing = true
+    end
+
+    # TODO: consider making grammars copiable (could be used in threaded context then)
+    #def initialize_copy(from); end
+    #def clone; end
+    #def dupe; end
+
+    # Starts with starting_symbol.
+    def parse string, options = {}
+      raise ArgumentError, 'nil string' if string.nil?
+      raise 'starting symbol not defined' if self.class.start_rule.nil?
+      options[:grammar]       = self.class
+      options[:rule_name]     = self.class.start_rule
+      options[:skipping]      = self.class.default_skipping_rule
+      options[:line_start]    = 0 # "richer" information (more human-friendly) than that provided in "location"
+      options[:column_start]  = 0 # "richer" information (more human-friendly) than that provided in "location"
+      options[:memoizer]      = MemoizingCache.new if @memoizing
+      self.class.start_rule.to_parseable.memoizing_parse string, options
+    end
+
+    # TODO: pretty print method?
+  end # class Grammar
+end # module Walrus