walrat 0.1

data/lib/walrat/parslet_combination.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 ParsletCombination
+    include Walrat::ParsletCombining
+    include Walrat::Memoizing
+
+    def to_parseable
+      self
+    end
+  end # module ParsletCombination
+end # module Walrat

data/lib/walrat/parslet_combining.rb

@@ -0,0 +1,190 @@
+# 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 ParsletCombining module, together with the ParsletCombination class and
+  # its subclasses, provides simple container classes for encapsulating
+  # relationships among Parslets. By storing this information outside of the
+  # Parslet objects themselves their design is kept clean and they can become
+  # immutable objects which are much more easily copied and shared among
+  # multiple rules in a Grammar.
+  module ParsletCombining
+    # Convenience method.
+    def memoizing_parse string, options = {}
+      self.to_parseable.memoizing_parse string, options
+    end
+
+    # Convenience method.
+    def parse string, options = {}
+      self.to_parseable.parse string, options
+    end
+
+    # Defines a sequence of Parslets (or ParsletCombinations).
+    # Returns a ParsletSequence instance.
+    def sequence first, second, *others
+      Walrat::ParsletSequence.new first.to_parseable,
+        second.to_parseable, *others
+    end
+
+    # Shorthand for ParsletCombining.sequence(first, second).
+    def &(next_parslet)
+      self.sequence self, next_parslet
+    end
+
+    # Defines a sequence of Parslets similar to the sequence method but with
+    # the difference that the contents of array results from the component
+    # parslets will be merged into a single array rather than being added as
+    # arrays. To illustrate:
+    #
+    #   'foo' & 'bar'.one_or_more   # returns results like ['foo', ['bar', 'bar', 'bar']]
+    #   'foo' >> 'bar'.one_or_more  # returns results like ['foo', 'bar', 'bar', 'bar']
+    #
+    def merge first, second, *others
+      Walrat::ParsletMerge.new first.to_parseable,
+        second.to_parseable, *others
+    end
+
+    # Shorthand for ParsletCombining.sequence(first, second)
+    def >>(next_parslet)
+      self.merge self, next_parslet
+    end
+
+    # Defines a choice of Parslets (or ParsletCombinations).
+    # Returns a ParsletChoice instance.
+    def choice left, right, *others
+      Walrat::ParsletChoice.new left.to_parseable,
+        right.to_parseable, *others
+    end
+
+    # Shorthand for ParsletCombining.choice(left, right)
+    def |(alternative_parslet)
+      self.choice self, alternative_parslet
+    end
+
+    # Defines a repetition of the supplied Parslet (or ParsletCombination).
+    # Returns a ParsletRepetition instance.
+    def repetition parslet, min, max
+      Walrat::ParsletRepetition.new parslet.to_parseable, min, max
+    end
+
+    # Shorthand for ParsletCombining.repetition.
+    def repeat min = nil, max = nil
+      self.repetition self, min, max
+    end
+
+    def repetition_with_default parslet, min, max, default
+      Walrat::ParsletRepetitionDefault.new parslet.to_parseable, min,
+        max, default
+    end
+
+    def repeat_with_default min = nil, max = nil, default = nil
+      self.repetition_with_default self, min, max, default
+    end
+
+    # Shorthand for ParsletCombining.repetition(0, 1).
+    # This method optionally takes a single parameter specifying what object
+    # should be returned as a placeholder when there are no matches; this is
+    # useful for packing into ASTs where it may be better to parse an empty
+    # Array rather than nil. The specified object is cloned and returned in the
+    # event that there are no matches. As a convenience, the specified object
+    # is automatically extended using the LocationTracking module (this is a
+    # convenience so that you can specify empty Arrays, "[]", rather than
+    # explicitly passing an "ArrayResult.new")
+    def optional default_return_value = NoParameterMarker.instance
+      if default_return_value == NoParameterMarker.instance
+        self.repeat 0, 1 # default behaviour
+      else
+        self.repeat_with_default 0, 1, default_return_value
+      end
+    end
+
+    # Alternative to optional.
+    def zero_or_one
+      self.optional
+    end
+
+    # possible synonym "star"
+    def zero_or_more default_return_value = NoParameterMarker.instance
+      if default_return_value == NoParameterMarker.instance
+        self.repeat 0 # default behaviour
+      else
+        self.repeat_with_default 0, nil, default_return_value
+      end
+    end
+
+    # possible synonym "plus"
+    def one_or_more
+      self.repeat 1
+    end
+
+    # Parsing Expression Grammar support.
+    # Succeeds if parslet succeeds but consumes no input (throws an
+    # :AndPredicateSuccess symbol).
+    def and_predicate parslet
+      Walrat::AndPredicate.new parslet.to_parseable
+    end
+
+    # Shorthand for and_predicate
+    # Strictly speaking, this shorthand breaks with established Ruby practice
+    # that "?" at the end of a method name should indicate a method that
+    # returns true or false.
+    def and?
+      self.and_predicate self
+    end
+
+    # Parsing Expression Grammar support.
+    # Succeeds if parslet fails (throws a :NotPredicateSuccess symbol).
+    # Fails if parslet succeeds (raise a ParseError).
+    # Consumes no output.
+    # This method will almost invariably be used in conjuntion with the &
+    # operator, like this:
+    #       rule :foo, :p1 & :p2.not_predicate
+    #       rule :foo, :p1 & :p2.not!
+    def not_predicate parslet
+      Walrat::NotPredicate.new parslet.to_parseable
+    end
+
+    # Shorthand for not_predicate.
+    # Strictly speaking, this shorthand breaks with established Ruby practice
+    # that "!" at the end of a method name should indicate a destructive
+    # behaviour on (mutation of) the receiver.
+    def not!
+      self.not_predicate self
+    end
+
+    # Succeeds if parsing succeeds, consuming the output, but doesn't actually
+    # return anything.
+    #
+    # This is for elements which are required but which shouldn't appear in the
+    # final AST.
+    def omission parslet
+      Walrat::ParsletOmission.new parslet.to_parseable
+    end
+
+    # Shorthand for ParsletCombining.omission
+    def skip
+      self.omission self
+    end
+  end # module ParsletCombining
+end # module Walrat

data/lib/walrat/parslet_merge.rb

@@ -0,0 +1,96 @@
+# 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 ParsletMerge < ParsletSequence
+    def parse string, options = {}
+      raise ArgumentError if string.nil?
+      state       = ParserState.new string, options
+      last_caught = nil # keep track of the last kind of throw to be caught
+      @components.each do |parseable|
+        catch :ProcessNextComponent do
+          catch :NotPredicateSuccess do
+            catch :AndPredicateSuccess do
+              catch :ZeroWidthParseSuccess do
+                begin
+                  parsed = parseable.memoizing_parse state.remainder, state.options
+                  if parsed.respond_to? :each
+                    parsed.each { |element| state.parsed element }
+                  else
+                    state.parsed(parsed)
+                  end
+                rescue SkippedSubstringException => e
+                  state.skipped(e)
+                # rescue ParseError => e # failed, will try to skip; save original error in case skipping fails
+                #   if options.has_key?(:skipping_override) : skipping_parslet = options[:skipping_override]
+                #   elsif options.has_key?(:skipping)       : skipping_parslet = options[:skipping]
+                #   else                                      skipping_parslet = nil
+                #   end
+                #   raise e if skipping_parslet.nil?        # no skipper defined, raise original error
+                #   begin
+                #     # guard against self references (possible infinite recursion) here?
+                #     parsed = skipping_parslet.memoizing_parse(state.remainder, state.options)
+                #     state.skipped(parsed)
+                #     redo              # skipping succeeded, try to redo
+                #   rescue ParseError
+                #     raise e           # skipping didn't help either, raise original error
+                #   end
+                end
+                last_caught = nil
+                throw :ProcessNextComponent # can't use "next" here because it will only break out of innermost "do"
+              end
+              last_caught = :ZeroWidthParseSuccess
+              throw :ProcessNextComponent
+            end
+            last_caught = :AndPredicateSuccess
+            throw :ProcessNextComponent
+          end
+          last_caught = :NotPredicateSuccess
+        end
+      end
+
+      if state.results.respond_to? :empty? and state.results.empty? and
+       throw last_caught
+      else
+        state.results
+      end
+    end
+
+    def eql?(other)
+      return false if not other.instance_of? ParsletMerge
+      other_components = other.components
+      return false if @components.length != other_components.length
+      for i in 0..(@components.length - 1)
+        return false unless @components[i].eql? other_components[i]
+      end
+      true
+    end
+
+  private
+
+    def hash_offset
+      53
+    end
+  end # class ParsletMerge
+end # module Walrat

data/lib/walrat/parslet_omission.rb

@@ -0,0 +1,74 @@
+# 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 ParsletOmission < ParsletCombination
+    attr_reader :hash
+
+    # Raises an ArgumentError if parseable is nil.
+    def initialize parseable
+      raise ArgumentError, 'nil parseable' if parseable.nil?
+      @parseable = parseable
+
+      # fixed offset to avoid unwanted collisions with similar classes
+      @hash = @parseable.hash + 46
+    end
+
+    def parse string, options = {}
+      raise ArgumentError, 'nil string' if string.nil?
+      substring = StringResult.new
+      substring.start = [options[:line_start], options[:column_start]]
+      substring.end   = [options[:line_start], options[:column_start]]
+
+      # possibly should catch these here as well
+      #catch :NotPredicateSuccess do
+      #catch :AndPredicateSuccess do
+      # one of the fundamental problems is that if a parslet throws such a
+      # symbol any info about already skipped material is lost (because the
+      # symbols contain nothing)
+      # this may be one reason to change these to exceptions...
+      catch :ZeroWidthParseSuccess do
+        substring = @parseable.memoizing_parse(string, options)
+      end
+
+      # not enough to just return a ZeroWidthParseSuccess here; that could
+      # cause higher levels to stop parsing and in any case there'd be no
+      # clean way to embed the scanned substring in the symbol
+      raise SkippedSubstringException.new(substring,
+                                          :line_start   => options[:line_start],
+                                          :column_start => options[:column_start],
+                                          :line_end     => substring.line_end,
+                                          :column_end   => substring.column_end)
+    end
+
+    def eql?(other)
+      other.instance_of? ParsletOmission and other.parseable.eql? @parseable
+    end
+
+  protected
+
+    # For determining equality.
+    attr_reader :parseable
+  end # class ParsletOmission
+end # module Walrat

data/lib/walrat/parslet_repetition.rb

@@ -0,0 +1,114 @@
+# 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 ParsletRepetition < ParsletCombination
+    attr_reader :hash
+
+    # Raises an ArgumentError if parseable or min is nil.
+    def initialize parseable, min, max = nil
+      raise ArgumentError, 'nil parseable' if parseable.nil?
+      raise ArgumentError, 'nil min' if min.nil?
+      @parseable = parseable
+      self.min = min
+      self.max = max
+    end
+
+    def parse string, options = {}
+      raise ArgumentError, 'nil string' if string.nil?
+      state = ParserState.new string, options
+      catch :ZeroWidthParseSuccess do             # a zero-width match is grounds for immediate abort
+        while @max.nil? or state.length < @max    # try forever if max is nil; otherwise keep trying while match count < max
+          begin
+            parsed = @parseable.memoizing_parse state.remainder, state.options
+            state.parsed parsed
+          rescue SkippedSubstringException => e
+            state.skipped e
+          rescue ParseError => e # failed, will try to skip; save original error in case skipping fails
+            if options.has_key?(:skipping_override)
+              skipping_parslet = options[:skipping_override]
+            elsif options.has_key?(:skipping)
+              skipping_parslet = options[:skipping]
+            else
+              skipping_parslet = nil
+            end
+            break if skipping_parslet.nil?
+            begin
+              # guard against self references (possible infinite recursion) here?
+              parsed = skipping_parslet.memoizing_parse state.remainder, state.options
+              state.skipped parsed
+              redo  # skipping succeeded, try to redo
+            rescue ParseError
+              break # skipping didn't help either, give up
+            end
+          end
+        end
+      end
+
+      # now assess whether our tries met the requirements
+      if state.length == 0 and @min == 0 # success (special case)
+        throw :ZeroWidthParseSuccess
+      elsif state.length < @min          # matches < min (failure)
+        raise ParseError.new('required %d matches but obtained %d while parsing "%s"' % [@min, state.length, string],
+                             :line_end    => state.options[:line_end],
+                             :column_end  => state.options[:column_end])
+      else                              # success (general case)
+        state.results                   # returns multiple matches as an array, single matches as a single object
+      end
+    end
+
+    def eql?(other)
+      other.instance_of? ParsletRepetition and
+        @min == other.min and
+        @max == other.max and
+        @parseable.eql? other.parseable
+    end
+
+  protected
+
+    # For determining equality.
+    attr_reader :parseable, :min, :max
+
+  private
+
+    def hash_offset
+      87
+    end
+
+    def update_hash
+      # fixed offset to minimize risk of collisions
+      @hash = @min.hash + @max.hash + @parseable.hash + hash_offset
+    end
+
+    def min=(min)
+      @min = (min.clone rescue min)
+      update_hash
+    end
+
+    def max=(max)
+      @max = (max.clone rescue max)
+      update_hash
+    end
+  end # class ParsletRepetition
+end # module Walrat