walrat 0.1

data/lib/walrat/left_recursion_exception.rb

@@ -0,0 +1,34 @@
+# 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 LeftRecursionException < Exception
+    attr_accessor :continuation
+
+    def initialize continuation = nil
+      super self.class.to_s
+      @continuation = continuation
+    end
+  end # class LeftRecursionException
+end # module Walrat

data/lib/walrat/location_tracking.rb

@@ -0,0 +1,126 @@
+# 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
+  # Methods for embedding location information in objects returned (or
+  # exceptions raised) from parse methods.
+  module LocationTracking
+    attr_reader :source_text
+
+    # For occasions where a single item must serve as a carrier for array-like
+    # information (that is, its own start, end and source_text, as well as the
+    # "outer" equivalents). This can happen where a single node appears in a
+    # list context surrounded only by skipped content.
+    attr_accessor :outer_start, :outer_end, :outer_source_text
+
+    def source_text=(string)
+      @source_text = string.to_s.clone
+    end
+
+    # Sets @column_start to col.
+    # Sets @column_start to 0 if passed nil (for ease of use, users of classes
+    # that mix-in this module don't have to worry about special casing nil
+    # values).
+    def column_start=(column_start)
+      @column_start = column_start.to_i
+    end
+
+    # Returns 0 if @column_start is nil (for ease of use, users of classes that
+    # mix-in this module don't have to worry about special casing nil values).
+    def column_start
+      @column_start || 0
+    end
+
+    # Sets @line_start to line.
+    # Sets @line_start to 0 if passed nil (for ease of use, users of classes
+    # that mix-in this module don't have to worry about special casing nil
+    # values).
+    def line_start=(line_start)
+      @line_start = line_start.to_i
+    end
+
+    # Returns 0 if @line_start is nil (for ease of use, users of classes that
+    # mix-in this module don't have to worry about special casing nil values).
+    def line_start
+      @line_start || 0
+    end
+
+    # Convenience method for getting both line_start and column_start at once.
+    def start
+      [self.line_start, self.column_start]
+    end
+
+    # Convenience method for setting both line_start and column_start at once.
+    def start=(array)
+      raise ArgumentError if array.nil?
+      raise ArgumentError if array.length != 2
+      self.line_start    = array[0]
+      self.column_start  = array[1]
+    end
+
+    def line_end=(line_end)
+      @line_end = line_end.to_i
+    end
+
+    def line_end
+      @line_end || 0
+    end
+
+    def column_end=(column_end)
+      @column_end = column_end.to_i
+    end
+
+    def column_end
+      @column_end || 0
+    end
+
+    # Convenience method for getting both line_end and column_end at once.
+    def end
+      [self.line_end, self.column_end]
+    end
+
+    # Convenience method for setting both line_end and column_end at once.
+    def end=(array)
+      raise ArgumentError if array.nil?
+      raise ArgumentError if array.length != 2
+      self.line_end   = array[0]
+      self.column_end = array[1]
+    end
+
+    # Given another object that responds to column_end and line_end, returns
+    # true if the receiver is rightmost or equal.
+    # If the other object is farther to the right returns false.
+    def rightmost? other
+      if self.line_end > other.line_end
+        true
+      elsif other.line_end > self.line_end
+        false
+      elsif self.column_end >= other.column_end
+        true
+      else
+        false
+      end
+    end
+  end # module LocationTracking
+end # module Walrat

data/lib/walrat/match_data_wrapper.rb

@@ -0,0 +1,84 @@
+# 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
+  # Simple wrapper for MatchData objects that implements length, to_s and
+  # to_str methods.
+  #
+  # By implementing to_str, MatchDataWrappers can be directly compared with
+  # Strings using the == method. The original MatchData instance can be
+  # obtained using the match_data accessor. Upon creation a clone of the passed
+  # in MatchData object is stored; this means that the $~ global variable can
+  # be conveniently wrapped without having to worry that subsequent operations
+  # will alter the contents of the variable.
+  class MatchDataWrapper
+    include Walrat::LocationTracking
+
+    attr_reader :match_data
+
+    # Raises if data is nil.
+    def initialize data
+      raise ArgumentError, 'nil data' if data.nil?
+      self.match_data = data
+    end
+
+    # The definition of this method, in conjunction with the == method, allows
+    # automatic comparisons with String objects using the == method.
+    # This is because in a parser matches essentially are Strings (just like
+    # Exceptions and Pathnames); it's just that this class encapsulates a
+    # little more information (the match data) for those who want it.
+    def to_str
+      self.to_s
+    end
+
+    # Although this method explicitly allows for MatchDataWrapper to
+    # MatchDataWrapper comparisons, note that all such comparisons will return
+    # false except for those between instances which were initialized with
+    # exactly the same match data instance; this is because the MatchData class
+    # itself always returns false when compared with other MatchData instances.
+    def ==(other)
+      if other.kind_of? MatchDataWrapper
+        self.match_data == other.match_data
+      elsif other.respond_to? :to_str
+        self.to_str == other.to_str
+      else
+        false
+      end
+    end
+
+    def to_s
+      @match_data[0]
+    end
+
+    def jlength
+      self.to_s.jlength
+    end
+
+  private
+
+    def match_data=(data)
+      @match_data = (data.clone rescue data)
+    end
+  end # class MatchDataWrapper
+end # module Walrat

data/lib/walrat/memoizing.rb

@@ -0,0 +1,55 @@
+# 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
+  module Memoizing
+    # This method provides a clean, optional implementation of memoizing by
+    # serving as a wrapper for all parse invocations. Rather than calling the
+    # parse methods directly, this method should be called; if it is
+    # appropriate to use a memoizer then it will be invoked, otherwise control
+    # will fall through to the real parse method. Turning off memoizing is as
+    # simple as not passing a value with the :memoizer key in the options hash.
+    # This method defined is in a separate module so that it can easily be
+    # mixed in with all Parslets, ParsletCombinations and Predicates.
+    def memoizing_parse(string, options = {})
+      # will use memoizer if available and not instructed to ignore it
+      if options.has_key?(:memoizer) and not
+         (options.has_key?(:ignore_memoizer) and options[:ignore_memoizer])
+        options[:parseable] = self
+        options[:memoizer].parse string, options
+      else # otherwise will proceed as normal
+        options[:ignore_memoizer] = false
+        parse string, options
+      end
+    end
+
+    # Can only check for left recursion if memoizing is turned on (the help of
+    # the memoizer is needed).
+    def check_left_recursion parseable, options = {}
+      return unless options.has_key?(:memoizer)
+      options[:memoizer].check_left_recursion parseable, options
+    end
+  end # module Memoizing
+end # module Walrat
+

data/lib/walrat/memoizing_cache.rb

@@ -0,0 +1,126 @@
+# 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
+  # The MemoizingCache class memoizes the outcomes of parse operations. The
+  # functionality is implemented as a separate class so as to minimize the
+  # amount of "contamination" of other classes by memoizing code, and to allow
+  # memoizing to be cleanly turned on or off at will. If a MemoizingCache is
+  # passed to a Parslet, ParsletCombination or Predicate as a value for the
+  # :memoizer key in the options hash passed to a parse method, the class
+  # implementing that method will call the parse method on the cache rather
+  # than proceeding normally. The cache will either propagate the previously
+  # memoized result, or will defer back to the original class to obtain the
+  # result. A circular dependency is avoided by setting the :skip_memoizer flag
+  # in the options dictionary. If no MemoizingCache is passed then normal
+  # program flow takes place.
+  class MemoizingCache
+    # Singleton class that serves as a default value for unset keys in a Hash.
+    class NoValueForKey
+      require 'singleton'
+      include Singleton
+    end
+
+    def initialize
+      # The results of parse operations are stored (memoized) in a cache, keyed
+      # on a unique identifier comprising the Parslet, ParsletCombination or
+      # Predicate used in the parse operation, the location of the operation
+      # (the line_start and column_start), and the skipping override (if any).
+      # The values may be:
+      #
+      #   - ParseErrors raised during parsing
+      #   - SkippedSubstringExceptions raised during parsing
+      #   - :ZeroWidthParseSuccess symbols thrown during parsing
+      #   - :AndPredicateSuccess symbols thrown during parsing
+      #   - :NotPredicateSuccess symbols thrown during parsing
+      #   - String instances returned as parse results
+      #   - MatchDataWrapper instance returned as parse results
+      #   - Array instances containing ordered collections of parse results
+      #   - Node subclass instances containing AST productions
+      @cache = Hash.new NoValueForKey.instance
+    end
+
+    # The receiver checks whether there is already a stored result
+    # corresponding to that a unique identifier that specifies the
+    # "coordinates" of a parsing operation (location, parseable, skipping
+    # override). If found propogates the result directly to the caller rather
+    # than performing the parse method all over again. Here "propagation" means
+    # re-raising parse errors, re-throwing symbols, and returning object
+    # references. If not found, performs the parsing operation and stores the
+    # result in the cache before propagating it.
+    def parse string, options = {}
+      raise ArgumentError if string.nil?
+
+      # construct a unique identifier
+      identifier = [options[:parseable], options[:line_start], options[:column_start]]
+      identifier << options[:origin] if options.has_key? :origin
+      identifier << options[:skipping_override] if options.has_key? :skipping_override
+
+      if (result = @cache[identifier]) != NoValueForKey.instance
+        if result.kind_of? Symbol
+          throw result
+        elsif result.kind_of? Exception
+          raise result
+        else
+          return result
+        end
+      else
+        # first time for this parseable/location/skipping_override (etc)
+        # combination; capture result and propagate
+        catch :NotPredicateSuccess do
+          catch :AndPredicateSuccess do
+            catch :ZeroWidthParseSuccess do
+              begin
+                options[:ignore_memoizer] = true
+
+                # short-circuit left recursion here rather than infinite
+                # looping
+                if options[:parseable].kind_of? SymbolParslet
+                  check_left_recursion(options[:parseable], options)
+                  @last_seen_symbol_parslet             = options[:parseable]
+                  @last_seen_symbol_parslet_location    = [options[:line_start], options[:column_start]]
+                end
+
+                return @cache[identifier] = options[:parseable].memoizing_parse(string, options)  # store and return
+              rescue Exception => e
+                raise @cache[identifier] = e                  # store and re-raise
+              end
+            end
+            throw @cache[identifier] = :ZeroWidthParseSuccess # store and re-throw
+          end
+          throw @cache[identifier] = :AndPredicateSuccess     # store and re-throw
+        end
+        throw @cache[identifier] = :NotPredicateSuccess       # store and re-throw
+      end
+    end
+
+    def check_left_recursion parseable, options = {}
+      if parseable.kind_of? SymbolParslet and
+         @last_seen_symbol_parslet == parseable and
+         @last_seen_symbol_parslet_location == [options[:line_start], options[:column_start]]
+        raise LeftRecursionException
+      end
+    end
+  end # class MemoizingCache
+end # module Walrat

data/lib/walrat/no_parameter_marker.rb

@@ -0,0 +1,30 @@
+# 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 NoParameterMarker
+    require 'singleton'
+    include Singleton
+  end # class NoParameterMarker
+end # module Walrat