plurimath-parslet 3.0.0

data/lib/parslet/scope.rb

@@ -0,0 +1,42 @@
+class Parslet::Scope
+  # Raised when the accessed slot has never been assigned a value. 
+  #
+  class NotFound < StandardError
+  end
+  
+  class Binding
+    attr_reader :parent
+    
+    def initialize(parent=nil)
+      @parent = parent
+      @hash = Hash.new
+    end
+    
+    def [](k)
+      @hash.has_key?(k) && @hash[k] ||
+        parent && parent[k] or 
+        raise NotFound
+    end
+    def []=(k,v)
+      @hash.store(k,v)
+    end
+  end
+  
+  def [](k)
+    @current[k]
+  end
+  def []=(k,v)
+    @current[k] = v
+  end
+  
+  def initialize
+    @current = Binding.new
+  end
+  
+  def push
+    @current = Binding.new(@current)
+  end
+  def pop
+    @current = @current.parent
+  end
+end

data/lib/parslet/slice.rb

@@ -0,0 +1,105 @@
+# A slice is a small part from the parse input. A slice mainly behaves like
+# any other string, except that it remembers where it came from (offset in
+# original input).
+#
+# == Extracting line and column
+#
+# Using the #line_and_column method, you can extract the line and column in
+# the original input where this slice starts.
+#
+# Example:
+#   slice.line_and_column # => [1, 13]
+#   slice.offset          # => 12
+#
+# == Likeness to strings
+#
+# Parslet::Slice behaves in many ways like a Ruby String. This likeness
+# however is not complete - many of the myriad of operations String supports
+# are not yet in Slice. You can always extract the internal string instance by
+# calling #to_s.
+#
+# These omissions are somewhat intentional. Rather than maintaining a full
+# delegation, we opt for a partial emulation that gets the job done.
+#
+class Parslet::Slice
+  attr_reader :str, :position, :line_cache
+
+  # Construct a slice using a string, an offset and an optional line cache.
+  # The line cache should be able to answer to the #line_and_column message.
+  #
+  def initialize(position, string, line_cache = nil)
+    @position = position
+    @str = string
+    @line_cache = line_cache
+  end
+
+  def offset
+    @position.charpos
+  end
+
+  # Compares slices to other slices or strings.
+  #
+  def ==(other)
+    str == other
+  end
+
+  # Match regular expressions.
+  #
+  def match(regexp)
+    str.match(regexp)
+  end
+
+  # Returns the slices size in characters.
+  #
+  def size
+    str.size
+  end
+
+  alias length size
+
+  # Concatenate two slices; it is assumed that the second slice begins
+  # where the first one ends. The offset of the resulting slice is the same
+  # as the one of this slice.
+  #
+  def +(other)
+    self.class.new(@position, str + other.to_s, line_cache)
+  end
+
+  # Returns a <line, column> tuple referring to the original input.
+  #
+  def line_and_column
+    raise ArgumentError, 'No line cache was given, cannot infer line and column.' \
+      unless line_cache
+
+    line_cache.line_and_column(@position.bytepos)
+  end
+
+  # Conversion operators -----------------------------------------------------
+  def to_str
+    str
+  end
+  alias to_s to_str
+
+  def to_slice
+    self
+  end
+
+  def to_sym
+    str.to_sym
+  end
+
+  def to_i
+    self.str.to_i
+  end
+
+  def to_f
+    str.to_f
+  end
+
+  # Inspection & Debugging ---------------------------------------------------
+
+  # Prints the slice as <code>"string"@offset</code>.
+  def inspect
+    str.inspect + "@#{offset}"
+  end
+end

data/lib/parslet/source/line_cache.rb

@@ -0,0 +1,99 @@
+
+
+class Parslet::Source
+  # A cache for line start positions. 
+  #
+  class LineCache 
+    def initialize
+      # Stores line endings as a simple position number. The first line always
+      # starts at 0; numbers beyond the biggest entry are on any line > size, 
+      # but probably make a scan to that position neccessary.
+      @line_ends = []
+      @line_ends.extend RangeSearch
+      @last_line_end = nil
+    end
+
+    # Returns a <line, column> tuple for the given input position. Input
+    # position must be given as byte offset into original string. 
+    #
+    def line_and_column(pos)
+      pos = pos.bytepos if pos.respond_to? :bytepos
+      eol_idx = @line_ends.lbound(pos)
+
+      if eol_idx
+        # eol_idx points to the offset that ends the current line.
+        # Let's try to find the offset that starts it: 
+        offset = eol_idx>0 && @line_ends[eol_idx-1] || 0
+        return [eol_idx+1, pos-offset+1]
+      else
+        # eol_idx is nil, that means that we're beyond the last line end that
+        # we know about. Pretend for now that we're just on the last line.
+        offset = @line_ends.last || 0
+        return [@line_ends.size+1, pos-offset+1]
+      end
+    end
+
+    def scan_for_line_endings(start_pos, buf)
+      return unless buf
+
+      buf = StringScanner.new(buf)
+      return unless buf.exist?(/\n/)
+
+      ## If we have already read part or all of buf, we already know about
+      ## line ends in that portion. remove it and correct cur (search index)
+      if @last_line_end && start_pos < @last_line_end
+        # Let's not search the range from start_pos to last_line_end again.
+        buf.pos = @last_line_end - start_pos
+      end
+
+      ## Scan the string for line endings; store the positions of all endings
+      ## in @line_ends. 
+      while buf.skip_until(/\n/)
+        @last_line_end = start_pos + buf.pos
+        @line_ends << @last_line_end
+      end
+    end
+  end
+
+  # Mixin for arrays that implicitly give a number of ranges, where one range
+  # begins where the other one ends.
+  # 
+  #   Example: 
+  #
+  #     [10, 20, 30]
+  #     # would describe [0, 10], (10, 20], (20, 30]
+  #
+  module RangeSearch 
+    def find_mid(left, right)
+      # NOTE: Jonathan Hinkle reported that when mathn is required, just
+      # dividing and relying on the integer truncation is not enough.
+      left + ((right - left) / 2).floor
+    end  
+    
+    # Scans the array for the first number that is > than bound. Returns the 
+    # index of that number. 
+    #
+    def lbound(bound)
+      return nil if empty?
+      return nil unless last > bound
+
+      left = 0
+      right = size - 1 
+
+      loop do
+        mid = find_mid(left, right)
+
+        if self[mid] > bound
+          right = mid
+        else
+          # assert: self[mid] <= bound
+          left = mid+1
+        end
+
+        if right <= left
+          return right
+        end
+      end
+    end
+  end
+end

data/lib/parslet/source.rb

@@ -0,0 +1,96 @@
+
+require 'stringio'
+require 'strscan'
+
+require 'parslet/position'
+require 'parslet/source/line_cache'
+
+module Parslet
+  # Wraps the input string for parslet. 
+  #
+  class Source
+    def initialize(str)
+      raise(
+        ArgumentError, 
+        "Must construct Source with a string like object."
+      ) unless str.respond_to?(:to_str)
+
+      @str = StringScanner.new(str)
+
+      # maps 1 => /./m, 2 => /../m, etc...
+      @re_cache = Hash.new { |h,k| 
+        h[k] = /(.|$){#{k}}/m }
+
+      @line_cache = LineCache.new
+      @line_cache.scan_for_line_endings(0, str)
+    end
+  
+    # Checks if the given pattern matches at the current input position. 
+    #
+    # @param pattern [Regexp] pattern to check for
+    # @return [Boolean] true if the pattern matches at #pos
+    #
+    def matches?(pattern)
+      @str.match?(pattern)
+    end
+    alias match matches?
+    
+    # Consumes n characters from the input, returning them as a slice of the
+    # input. 
+    #
+    def consume(n)
+      position = self.pos
+      slice_str = @str.scan(@re_cache[n])
+      slice = Parslet::Slice.new(
+        position, 
+        slice_str,
+        @line_cache)
+
+      return slice
+    end
+    
+    # Returns how many chars remain in the input. 
+    #
+    def chars_left
+      @str.rest_size
+    end
+
+    # Returns how many chars there are between current position and the 
+    # string given. If the string given doesn't occur in the source, then 
+    # the remaining chars (#chars_left) are returned. 
+    #
+    # @return [Fixnum] count of chars until str or #chars_left
+    #
+    def chars_until str
+      slice_str = @str.check_until(Regexp.new(Regexp.escape(str)))
+      return chars_left unless slice_str
+      return slice_str.size - str.size
+    end
+    
+    # Position of the parse as a character offset into the original string. 
+    #
+    # @note Please be aware of encodings at this point. 
+    #
+    def pos
+      Position.new(@str.string, @str.pos)
+    end
+    def bytepos
+      @str.pos
+    end
+
+    # @note Please be aware of encodings at this point. 
+    #
+    def bytepos=(n)
+      @str.pos = n
+    rescue RangeError
+    end
+
+    # Returns a <line, column> tuple for the given position. If no position is
+    # given, line/column information is returned for the current position
+    # given by #pos. 
+    #
+    def line_and_column(position=nil)
+      @line_cache.line_and_column(position || self.bytepos)
+    end
+  end
+end

data/lib/parslet/transform.rb

@@ -0,0 +1,265 @@
+
+require 'parslet/pattern'
+
+# Transforms an expression tree into something else. The transformation
+# performs a depth-first, post-order traversal of the expression tree. During
+# that traversal, each time a rule matches a node, the node is replaced by the
+# result of the block associated to the rule. Otherwise the node is accepted
+# as is into the result tree.
+#
+# This is almost what you would generally do with a tree visitor, except that
+# you can match several levels of the tree at once. 
+#
+# As a consequence of this, the resulting tree will contain pieces of the
+# original tree and new pieces. Most likely, you will want to transform the
+# original tree wholly, so this isn't a problem.
+#
+# You will not be able to create a loop, given that each node will be replaced
+# only once and then left alone. This means that the results of a replacement
+# will not be acted upon. 
+#
+# Example: 
+#
+#   class Example < Parslet::Transform
+#     rule(:string => simple(:x)) {  # (1)
+#       StringLiteral.new(x)
+#     }
+#   end
+#
+# A tree transform (Parslet::Transform) is defined by a set of rules. Each
+# rule can be defined by calling #rule with the pattern as argument. The block
+# given will be called every time the rule matches somewhere in the tree given
+# to #apply. It is passed a Hash containing all the variable bindings of this
+# pattern match. 
+#   
+# In the above example, (1) illustrates a simple matching rule. 
+#
+# Let's say you want to parse matching parentheses and distill a maximum nest
+# depth. You would probably write a parser like the one in example/parens.rb;
+# here's the relevant part: 
+#
+#   rule(:balanced) {
+#     str('(').as(:l) >> balanced.maybe.as(:m) >> str(')').as(:r)
+#   }
+#
+# If you now apply this to a string like '(())', you get a intermediate parse
+# tree that looks like this: 
+#
+#   {
+#     l: '(', 
+#     m: {
+#       l: '(', 
+#       m: nil, 
+#       r: ')' 
+#     }, 
+#     r: ')' 
+#   }
+#
+# This parse tree is good for debugging, but what we would really like to have
+# is just the nesting depth. This transformation rule will produce that: 
+#
+#   rule(:l => '(', :m => simple(:x), :r => ')') { 
+#     # innermost :m will contain nil
+#     x.nil? ? 1 : x+1
+#   }
+#
+# = Usage patterns
+#
+# There are four ways of using this class. The first one is very much
+# recommended, followed by the second one for generality. The other ones are
+# omitted here. 
+#
+# Recommended usage is as follows: 
+#
+#   class MyTransformator < Parslet::Transform
+#     rule(...) { ... }
+#     rule(...) { ... }
+#     # ...
+#   end
+#   MyTransformator.new.apply(tree)
+#
+# Alternatively, you can use the Transform class as follows: 
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { ... }
+#   end
+#   transform.apply(tree)
+#
+# = Execution context
+#
+# The execution context of action blocks differs depending on the arity of 
+# said blocks. This can be confusing. It is however somewhat intentional. You 
+# should not create fat Transform descendants containing a lot of helper methods, 
+# instead keep your AST class construction in global scope or make it available
+# through a factory. The following piece of code illustrates usage of global
+# scope: 
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { AstNode.new(a_variable) }
+#     rule(...) { Ast.node(a_variable) } # modules are nice
+#   end
+#   transform.apply(tree)
+#
+# And here's how you would use a class builder (a factory):
+#
+#   transform = Parslet::Transform.new do
+#     rule(...) { builder.add_node(a_variable) }
+#     rule(...) { |d| d[:builder].add_node(d[:a_variable]) }
+#   end
+#   transform.apply(tree, :builder => Builder.new)
+#
+# As you can see, Transform allows you to inject local context for your rule
+# action blocks to use. 
+#
+class Parslet::Transform
+  # FIXME: Maybe only part of it? Or maybe only include into constructor
+  # context?
+  include Parslet   
+  
+  class << self
+    # FIXME: Only do this for subclasses?
+    include Parslet
+    
+    # Define a rule for the transform subclass. 
+    #
+    def rule(expression, &block)
+      @__transform_rules ||= []
+      # Prepend new rules so they have higher precedence than older rules
+      @__transform_rules.unshift([Parslet::Pattern.new(expression), block])
+    end
+    
+    # Allows accessing the class' rules
+    #
+    def rules 
+      @__transform_rules ||= []
+    end
+
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@__transform_rules, rules.dup)
+    end
+  end
+  
+  def initialize(raise_on_unmatch=false, &block) 
+    @raise_on_unmatch = raise_on_unmatch
+    @rules = []
+    
+    if block
+      instance_eval(&block)
+    end
+  end
+  
+  # Defines a rule to be applied whenever apply is called on a tree. A rule
+  # is composed of two parts: 
+  # 
+  # * an *expression pattern*
+  # * a *transformation block*
+  #
+  def rule(expression, &block)
+    # Prepend new rules so they have higher precedence than older rules
+    @rules.unshift([Parslet::Pattern.new(expression), block])
+  end
+  
+  # Applies the transformation to a tree that is generated by Parslet::Parser
+  # or a simple parslet. Transformation will proceed down the tree, replacing
+  # parts/all of it with new objects. The resulting object will be returned. 
+  #
+  # Using the context parameter, you can inject bindings for the transformation.
+  # This can be used to allow access to the outside world from transform blocks,
+  # like so:
+  # 
+  #   document = # some class that you act on
+  #   transform.apply(tree, document: document)
+  #   
+  # The above will make document available to all your action blocks: 
+  #
+  #   # Variant A
+  #   rule(...) { document.foo(bar) }
+  #   # Variant B
+  #   rule(...) { |d| d[:document].foo(d[:bar]) }
+  #
+  # @param obj PORO ast to transform
+  # @param context start context to inject into the bindings. 
+  #
+  def apply(obj, context=nil)
+    transform_elt(
+      case obj
+        when Hash
+          recurse_hash(obj, context)
+        when Array
+          recurse_array(obj, context)
+      else
+        obj
+      end, 
+      context
+    )
+  end
+  
+  # Executes the block on the bindings obtained by Pattern#match, if such a match
+  # can be made. Depending on the arity of the given block, it is called in 
+  # one of two environments: the current one or a clean toplevel environment.
+  #
+  # If you would like the current environment preserved, please use the 
+  # arity 1 variant of the block. Alternatively, you can inject a context object
+  # and call methods on it (think :ctx => self).
+  #
+  #   # the local variable a is simulated
+  #   t.call_on_match(:a => :b) { a } 
+  #   # no change of environment here
+  #   t.call_on_match(:a => :b) { |d| d[:a] }
+  #
+  def call_on_match(bindings, block)
+    if block
+      if block.arity == 1
+        return block.call(bindings)
+      else
+        context = Context.new(bindings)
+        return context.instance_eval(&block)
+      end
+    end
+  end
+  
+  # Allow easy access to all rules, the ones defined in the instance and the 
+  # ones predefined in a subclass definition. 
+  #
+  def rules 
+    self.class.rules + @rules
+  end
+  
+  # @api private 
+  #
+  def transform_elt(elt, context) 
+    rules.each do |pattern, block|
+      if bindings=pattern.match(elt, context)
+        # Produces transformed value
+        return call_on_match(bindings, block)
+      end
+    end
+    
+    # No rule matched - element is not transformed
+    if @raise_on_unmatch && elt.is_a?(Hash)
+      elt_types = elt.map do |key, value|
+        [ key, value.class ]
+      end.to_h
+      raise NotImplementedError, "Failed to match `#{elt_types.inspect}`"
+    else
+      return elt
+    end
+  end
+
+  # @api private 
+  #
+  def recurse_hash(hsh, ctx) 
+    hsh.inject({}) do |new_hsh, (k,v)|
+      new_hsh[k] = apply(v, ctx)
+      new_hsh
+    end
+  end
+  # @api private 
+  #
+  def recurse_array(ary, ctx) 
+    ary.map { |elt| apply(elt, ctx) }
+  end
+end
+
+require 'parslet/context'

data/lib/parslet/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Parslet
+  VERSION = '3.0.0'
+end