parse-framework 0.0.1

data/.yardopts

@@ -0,0 +1,3 @@
+--protected
+--hide-api private
+--files sample/*

data/README.md

@@ -0,0 +1,318 @@
+Parse
+=====
+
+The framework for building parsers.
+
+Features
+--------
+
+- **Position tracking**. You can always obtain the current position and the current rule's start position while parsing.
+- **Position remapping**. Ever wanted to implement something like C preprocessor's `#line` command? Now it is possible!
+- **Automatic error handling**. If the parsing fails, the raised error contains the failure position and what is expected at that position. No additional coding is required.
+- **Flexible and easy to use**. Parsers are written in plain Ruby. You may implement any parsing algorithms you wish! Also no clumsy DSLs or code generation are used - you may use your favorite IDE!
+
+Install
+-------
+
+Command line:
+
+    gem install parse-framework
+
+With [Bundler](http://bundler.io/):
+
+    echo 'gem "parse-framework"' >>Gemfile
+    bundle install
+
+Usage
+-----
+
+Write subclass of {Parse} class.
+
+Also you may find {Parse::MapPosition} and {Code} classes useful!
+
+Examples
+--------
+
+First parser:
+
+    require 'parse'
+    
+    class HelloWorldParser < Parse
+      
+      def start
+        scan("hello world")
+      end
+      
+    end
+
+Usage:
+
+    puts HelloWorldParser.new.("hello world")
+      #=> hello world
+
+Sequence:
+
+    class HelloWorldParser < Parse
+      
+      def start
+        scan("hello ") and scan("world")
+      end
+      
+    end
+    
+    puts HelloWorldParser.new.("hello world")
+      #=> world
+
+Analyze errors:
+
+    begin
+      HelloWorldParser.new.("Hello everyone")
+    rescue Parse::Error => e
+      puts "error at #{e.pos.line + 1}:#{e.pos.column + 1}: #{e.message}"
+    end
+    
+    #=> error at 1:7: "world" expected
+
+Regexps:
+
+    class HelloWorldParser < Parse
+      
+      def start
+        scan(/[Hh]ello/) and scan(/\s+/) and scan("world")
+      end
+      
+    end
+    
+    puts HelloWorldParser.new.("Hello world")
+      #=> "world"
+
+Alteration:
+
+    class HelloWorldParser < Parse
+      
+      def start
+        scan(/[Hh]ello/) and scan(/\s+/) and (
+          _{ scan("world") } or
+          _{ scan("everyone") }
+        )
+      end
+      
+    end
+    
+    puts HelloWorldParser.new.("Hello everyone")
+      #=> everyone
+
+Separate rules:
+
+    class HelloWorldParser < Parse
+      
+      def start
+        scan(/[Hh]ello/) and scan(/\s+/) and who
+      end
+      
+      def who
+        _{ scan("world") } or
+        _{ scan("everyone") }
+      end
+      
+    end
+    
+    puts HelloWorldParser.new.("Hello everyone")
+      #=> everyone
+
+Repetition:
+
+    class MillionThankYousParser < Parse
+      
+      def start
+        many { scan("thank you") and scan(/\s*/) }
+      end
+      
+    end
+    
+    MillionThankYousParser.new.("thank you thank you thank you")
+
+`many` is a Parser Combinator. There are many other Parser Combinators, see {Parse}'s doc.
+
+Counting:
+
+    class MillionThankYousParser < Parse
+      
+      def start
+        count = 0
+        many {
+          scan("thank you") and scan(/\s*/) and
+          act { count += 1 }  # `act` always returns true regardless of 
+                              # the block's result.
+        } and
+        count  # the last non-nil value in the sequence is the
+               # sequence's result.
+      end
+      
+    end
+    
+    puts MillionThankYousParser.new.("thank you thank you thank you")
+      #=> 3
+
+Capture variables:
+
+    class ChatBot < Parse
+      
+      def start
+        scan("My name is ") and n = scan(/\w+/) and scan(/[\!\.]/) and n
+      end
+      
+    end
+    
+    puts ChatBot.new.("My name is John!")
+      #=> John
+
+Parse LISP expressions (using AST nodes):
+
+    class ParseLISP < Parse
+      
+      # a shorthand for declaring a Struct with member "children" and a method
+      # "to_ruby_value" and including the module "ASTNode" into it.
+      Cons = ASTNode.new :children do
+        
+        def to_ruby_value
+          children.map(&:to_ruby_value)
+        end
+        
+      end
+      
+      Atom = ASTNode.new :val do
+        
+        def to_ruby_value
+          val
+        end
+        
+      end
+      
+      def start
+        skipped and
+        r = (_{ cons } or _{ atom }) and
+        r.to_ruby_value
+      end
+      
+      # "rule" is similar to "def" but it allows to use "_(node)" in its body.
+      # "_(node)" sets {ASTNode#pos} to the rule's start position.
+      rule :atom do
+        _{ n = scan(/\d+/) and skipped and act { n = n.to_i } and _(Atom[n]) } or
+        _{ s = scan(/"[^"]*"/) and skipped and act { s = s[1...-1] } and _(Atom[s]) } or
+        _{ s = scan(/[^\(\)\"\s\;]+/) and skipped and act { s = s.to_sym } and _(Atom[s]) }
+      end
+      
+      rule :cons do
+        scan("(") and skipped and
+        a = many { _{ atom } or _{ cons } } and  # "many" results in array of
+                                                 # successfully parsed values
+        scan(")") and skipped and
+        _(Cons[a])
+      end
+      
+      def skipped
+        opt {
+          _{ scan(/\s+/) } or
+          _{ scan(/;.*\n/) }
+        }
+      end
+      
+    end
+    
+    p ParseLISP.new.(' (a b (c d) (e 12 "s")) ')
+      #=> [:a, :b, [:c, :d], [:e, 12, "s"]]
+
+The same but using `token` macro:
+
+    class ParseLISP < Parse
+      
+      Cons = ASTNode.new :children do
+        
+        def to_ruby_value
+          children.map(&:to_ruby_value)
+        end
+        
+      end
+      
+      Atom = ASTNode.new :val do
+        
+        def to_ruby_value
+          val
+        end
+        
+      end
+      
+      def start
+        skipped and
+        r = (_{ cons } or _{ atom }) and
+        r.to_ruby_value
+      end
+      
+      rule :atom do
+        _{ n = number and _(Atom[n]) } or        # !!!
+        _{ s = string and _(Atom[s]) } or        # !!!
+        _{ s = symbol and _(Atom[s]) }                    # !!!
+      end
+      
+      rule :cons do
+        lbrace and                               # !!!
+        a = many { _{ atom } or _{ cons } } and
+        rbrace and                               # !!!
+        _(Cons[a])
+      end
+      
+      def skipped
+        opt {
+          _{ scan(/\s+/) } or
+          _{ scan(/;.*\n/) }
+        }
+      end
+      
+      # !!!
+      
+      # `token` is like `rule` but:
+      # 1) it handles errors slightly different, see doc.
+      # 2) it skips `whitespace_and_comments` after the token
+      token :number, "integer number" do
+        n = scan(/\d+/) and n.to_i
+      end
+      
+      # you may omit description.
+      token :string do
+        s = scan(/"[^"]*"/) and s[1...-1]
+      end
+      
+      token :symbol do
+        s = scan(/[^\(\)\"\s\;]+/) and s.to_sym
+      end
+      
+      # a shorthand for ``token :lbrace, "`('" do scan("(") end''
+      token :lbrace, "("
+      
+      token :rbrace, ")"
+      
+      # required by `token`.
+      alias whitespace_and_comments skipped
+      
+      # !!!
+      
+    end
+    
+    p ParseLISP.new.(' (a b (c d) (e 12 "s")) ')
+      #=> [:a, :b, [:c, :d], [:e, 12, "s"]]
+
+There are many other features, see {Parse}'s documentation, it is pretty detailed!
+
+License
+-------
+
+The MIT License (MIT)
+
+Copyright (c) 2016 Various Furriness
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/array/bsearch_index.rb

@@ -0,0 +1,33 @@
+unless Array.method_defined? :bsearch_index
+  class Array
+    def bsearch_index
+      return to_enum(__method__) unless block_given?
+      from = 0
+      to = size - 1
+      satisfied = nil
+      while from <= to do
+        midpoint = (from + to).div(2)
+        cur_index = midpoint
+        result = yield(cur = self[midpoint])
+        case result
+        when Numeric
+          return cur_index if result == 0
+          result = result < 0
+        when true
+          satisfied = cur
+          satisfied_index = cur_index
+        when nil, false
+          # nothing to do
+        else
+          raise TypeError, "wrong argument type #{result.class} (must be numeric, true, false or nil)"
+        end
+        if result
+          to = midpoint - 1
+        else
+          from = midpoint + 1
+        end
+      end
+      satisfied_index
+    end
+  end
+end

data/lib/code.rb

@@ -0,0 +1,179 @@
+
+# To disable YARD warnings:
+# 
+# @!parse
+#   class Object
+#   end
+
+# 
+# @example
+#   
+#   method_names = {
+#     :eat => "M1",
+#     :cut => "M2"
+#   }
+#   
+#   c = code <<
+#     "class Apple \n" <<
+#     "{ \n" <<
+#     "public: \n" <<
+#     "    void " << non_code(:eat) << "(); \n" <<
+#     "    void " << non_code(:cut) << "(int PiecesCount); \n" <<
+#     "}; \n"
+#   c.non_code_parts.each do |part|
+#     if part.is_a? Symbol then
+#       if not method_names.key? part then
+#         raise "method name not found!"
+#       end
+#     end
+#   end
+#   c = c.map_non_code_parts do |part|
+#     if part.is_a? Symbol then
+#       method_names[part]
+#     end
+#   end
+#   puts c
+#     # class Apple 
+#     # { 
+#     # public: 
+#     #     void M1(); 
+#     #     void M2(int PiecesCount); 
+#     # }; 
+# 
+class Code
+  
+  # @api private
+  # @note used by {Code}, {::code}, {::non_code} only.
+  # 
+  # @param [Array<String, NonCodePart>] parts
+  # @param [Object, nil] metadata
+  # 
+  def initialize(parts, metadata = nil)
+    @parts = parts
+    @metadata = metadata
+  end
+  
+  # @overload + str
+  #   @param [String] str
+  #   @return [Code]
+  # @overload + code
+  #   @param [Code] code
+  #   @return [Code]
+  def + arg
+    case arg
+    when String then self + Code.new([arg])
+    when Code then Code.new(self.parts + arg.parts)
+    end
+  end
+  
+  # @overload << str
+  #   Appends +str+ to self.
+  #   @param [String] str
+  #   @return [self]
+  # @overload << code
+  #   Appends +str+ to self.
+  #   @param [Code] code
+  #   @return [self]
+  def << arg
+    case arg
+    when String then self << Code.new([arg])
+    when Code then @parts.concat(arg.parts); self
+    end
+  end
+  
+  # @overload metadata(obj)
+  #   @param [Object] obj
+  #   @return [Code] a {Code} with +obj+ attached to it. The +obj+ can later
+  #     be retrieved with {#metadata}().
+  # @overload metadata
+  #   @return [Object, nil] an {Object} attached to this {Code} with
+  #     {#metadata}(obj) or nil if no {Object} was attached.
+  def metadata(*args)
+    if args.empty?
+    then @metadata
+    else Code.new(@parts, args.first)
+    end
+  end
+  
+  # @yieldparam [Object] part
+  # @yieldreturn [String]
+  # @return [Code] a {Code} with {#non_code_parts} mapped by the passed block.
+  def map_non_code_parts(&f)
+    Code.new(
+      @parts.map do |part|
+        case part
+        when String then part
+        when NonCodePart then f.(part.data)
+        end
+      end
+    )
+  end
+  
+  # @return [Enumerable<Object>] non-code parts of this {Code} introduced
+  #   with {::non_code}. See also {#map_non_code_parts}.
+  def non_code_parts
+    @parts.select { |part| part.is_a? NonCodePart }.map(&:data)
+  end
+  
+  # @return [String]
+  def to_s
+    if (x = @parts.find { |part| part.is_a? NonCodePart }) then
+      raise "non-code part: #{x.inspect}"
+    end
+    @parts.join
+  end
+  
+  # @return [String]
+  def inspect
+    Inspectable.new(@parts, @metadata).inspect
+  end
+  
+  # @api private
+  # @note used by {Code}, {::non_code} only.
+  NonCodePart = Struct.new :data
+  
+  protected
+  
+  # @!visibility private
+  attr_reader :parts
+  
+  private
+  
+  # @!visibility private
+  Inspectable = Struct.new :parts, :metadata
+  
+end
+
+class Array
+  
+  # @param [Code, String] delimiter
+  # @return [Code]
+  def join_code(delimiter = "")
+    self.reduce do |r, self_i|
+      code << r << delimiter << self_i
+    end or
+    code
+  end
+  
+end
+
+# @overload code
+#   @return [Code] an empty {Code}.
+# @overload code(str)
+#   @param [String] str
+#   @return [Code] +str+ converted to {Code}.
+def code(str = nil)
+  if str
+  then Code.new([str])
+  else Code.new([])
+  end
+end
+
+# @param [Object] data
+# @return [Code] a {Code} consisting of the single non-code part +data+.
+#   See also {Code#non_code_parts}.
+def non_code(data)
+  Code.new([Code::NonCodePart.new(data)])
+end
+
+alias __non_code__ non_code

data/lib/parse.rb

@@ -0,0 +1,614 @@
+require 'strscan'
+require 'strscan/substr'
+
+# To disable YARD warnings:
+# @!parse
+#   class Exception
+#     def message
+#     end
+#   end
+#   class Array
+#   end
+#   class String
+#   end
+#   class StringScanner
+#     attr_reader :pos
+#   end
+
+# 
+class Parse
+  
+  # 
+  # parses +text+.
+  # 
+  # If $DEBUG == true then it prints {Parse.rule} calls to stdout.
+  # 
+  # @param [String] text
+  # @param [String] file file the +text+ is taken from.
+  # @raise [Parse::Error, IOError]
+  # @return [Object] what {#start} returns (non-nil).
+  # 
+  def call(text, file = "-")
+    @text = StringScanner.new(text)
+    @file = file
+    @most_probable_error = nil
+    @allow_errors = true
+    @rule_start_pos = nil
+    r = start()
+    if r.nil? or not @text.eos? then
+      if @most_probable_error
+      then raise @most_probable_error
+      else raise Error.new(StringScannerPosition.new(@text.pos, @text, @file), "syntax error")
+      end
+    end
+    return r
+  end
+  
+  module Position
+    
+    include Comparable
+    
+    # @param [Integer] line
+    # @param [Integer] column
+    # @param [String] file
+    # @return [Position]
+    def self.new(line, column, file = "-")
+      Position2.new(line, column, file)
+    end
+    
+    # @!method file
+    #   @abstract
+    #   @return [String]
+    
+    # @!method line
+    #   @abstract
+    #   @return [Integer]
+    
+    # @!method column
+    #   @abstract
+    #   @return [Integer]
+    
+    # @return [-1, 0, 1, nil] nil if +other+.{#file} != self.{#file} or
+    #   +other+ is not a {Position}. Otherwise it compares {#line} and {#column}
+    #   and returns -1, 0 or 1. See also {Comparable#<=>}.
+    def <=> other
+      return nil unless other.is_a? Position
+      return nil unless self.file == other.file
+      x = self.line <=> other.line
+      return x if x != 0
+      return self.column <=> other.column
+    end
+    
+    # @return [Boolean]
+    def == other
+      return false unless other.is_a? Position
+      return (self <=> other) == 0
+    end
+    
+    # @return [String]
+    def to_s
+      "#{file}:#{line}:#{column}"
+    end
+    
+  end
+  
+  class Error < Exception
+    
+    # @param [Position] pos
+    # @param [String] message
+    def initialize(pos, message)
+      super(message)
+      @pos = pos
+    end
+    
+    # @return [Position]
+    attr_reader :pos
+    
+    # @param [Error] other +self+.{#pos} must be equal to +other+.{#pos}.
+    # @return [Error] an {Error} with {Exception#message} combined from
+    #   {Exception#message}s of +self+ and +other+ (using "or" word).
+    def or other
+      raise "#{self.pos} == #{other.pos} is false" unless self.pos == other.pos
+      Error.new(pos, "#{self.message} or #{other.message}")
+    end
+    
+  end
+  
+  class Expected < Error
+    
+    # @param [Position] pos
+    # @param [String] what_1
+    # @param [*String] what_2_n
+    def initialize(pos, what_1, *what_2_n)
+      @what = [what_1, *what_2_n]
+      super(pos, "#{@what.join(", ")} expected")
+    end
+    
+    # (see Error#or)
+    def or other
+      if other.is_a? Expected
+        raise "#{self.pos} == #{other.pos} is false" unless self.pos == other.pos
+        Expected.new(pos, *(self.what + other.what).uniq)
+      else
+        super(other)
+      end
+    end
+    
+    protected
+    
+    # @!visibility private
+    # @return [Array<String>]
+    attr_reader :what
+    
+  end
+  
+  protected
+  
+  # @!method start()
+  #   @abstract
+  #   
+  #   Implementation of {#call}. Or the starting rule.
+  #   
+  #   @return [Object, nil] a result of parsing or nil if the parsing failed.
+  #   @raise [Parse::Error] if the parsing failed.
+  #   @raise [IOError]
+  #   
+  
+  # 
+  # scans +arg+ in +text+ passed to {#call} starting from {#pos} and,
+  # if scanned successfully, advances {#pos} and returns the scanned
+  # sub-{String}. Otherwise it calls {#expected} and returns nil.
+  # 
+  # @param [String, Regexp] arg
+  # @return [String, nil]
+  # 
+  def scan(arg)
+    case arg
+    when Regexp then @text.scan(arg) or expected(pos, %(regexp "#{arg.source}"))
+    when String then @text.scan(Regexp.new(Regexp.escape(arg))) or expected(pos, %("#{arg}"))
+    end
+  end
+  
+  # alias for {#_1} and {#_2}
+  def _(arg = nil, &block)
+    if arg
+    then _1(arg)
+    else _2(&block)
+    end
+  end
+  
+  # -------------
+  # @!group Rules
+  # -------------
+  
+  # defines method +name+ with body +body+. Inside +body+ {#rule_start_pos}
+  # is the value of {#pos} right before the defined method's call.
+  # 
+  # @param [Symbol] name
+  # @return [void]
+  # 
+  def self.rule(name, &body)
+    define_method(name) do
+      old_rule_start_pos = @rule_start_pos
+      @rule_start_pos = pos
+      begin
+        if $DEBUG then STDERR.puts("#{pos.file}:#{pos.line+1}:#{pos.column+1}: entering rule :#{name}"); end
+        r = instance_eval(&body)
+        if $DEBUG then STDERR.puts("#{pos.file}:#{pos.line+1}:#{pos.column+1}: exiting rule :#{name} #{if r.nil? then "(with nil)" end}"); end
+        r
+      ensure
+        @rule_start_pos = old_rule_start_pos
+      end
+    end
+  end
+  
+  # See {Parse::rule}.
+  # 
+  # @return [Position]
+  # 
+  attr_reader :rule_start_pos
+  
+  # @param [ASTNode] node
+  # @return [ASTNode] +node+ which is
+  #   {ASTNode#initialize_pos}({#rule_start_pos})-ed.
+  def _1(node)
+    node.initialize_pos(rule_start_pos)
+  end
+  
+  # @overload token(name, [description], string | regexp | &body)
+  # 
+  # A shorthand for:
+  #   
+  #   rule name do
+  #     expect(description) {
+  #       no_errors {
+  #         r = (scan(string) | scan(regexp) | body) and
+  #         whitespace_and_comments and
+  #         r
+  #       }
+  #     }
+  #   end
+  # 
+  # Method +whitespace_and_comments+ must be defined!
+  # 
+  # +description+ defaults to <code>"`#{string}'"</code>,
+  # <code>%(regexp "#{regexp}")</code> or <code>"#{name}"</code> (in that
+  # order, depending on what is defined).
+  # 
+  # @return [void]
+  def self.token(name, *args, &body)
+    pattern, body =
+      if body.nil? then
+        pattern = args.pop
+        [pattern, proc { scan(pattern) }]
+      else
+        [nil, body]
+      end
+    description =
+      args.pop ||
+      case pattern
+      when nil then "#{name}"
+      when String then "`#{pattern}'"
+      when Regexp then %(regexp "#{pattern.source}")
+      end
+    raise ArgumentError, "wrong number of arguments" unless args.empty?
+    rule name do
+      expect(description) {
+        no_errors {
+          r = instance_eval(&body) and whitespace_and_comments and r
+        }
+      }
+    end
+  end
+  
+  # ----------
+  # @!endgroup
+  # ----------
+  
+  # ----------------
+  # @!group Position
+  # ----------------
+  
+  # @return [Position] current {Position} in +text+ passed to {#call}.
+  def pos
+    StringScannerPosition.new(@text.pos, @text, @file)
+  end
+  
+  # is {#pos} at the end of the text?
+  def end?
+    @text.eos?
+  end
+  
+  alias eos? end?
+  
+  # is {#pos} at the beginning of the text?
+  def begin?
+    @text.pos == 0
+  end
+  
+  # ----------
+  # @!endgroup
+  # ----------
+  
+  # --------------------------
+  # @!group Parser Combinators
+  # --------------------------
+  
+  # calls +f+ and returns true.
+  # 
+  # @return [true]
+  def act(&f)
+    f.()
+    true
+  end
+  
+  #   
+  # calls +f+. If +f+ results in nil then it restores {#pos} to the
+  # value before the call.
+  # 
+  # @return what +f+ returns.
+  # 
+  def _2(&f)
+    old_text_pos = @text.pos
+    f.() or begin
+      @text.pos = old_text_pos
+      nil
+    end
+  end
+  
+  # calls +f+ using {#_2} many times until it returns nil.
+  # 
+  # @return [Array] an {Array} of non-nil results of +f+.
+  # 
+  def many(&f)
+    r = []
+    while true
+      f0 = _(&f)
+      if f0
+      then r.push(f0)
+      else break
+      end
+    end
+    r
+  end
+  
+  # calls +f+ using {#_2}.
+  # 
+  # @return [Array] an empty {Array} if +f+ results in nil and an {Array}
+  #   containing the single result of +f+ otherwise.
+  # 
+  def opt(&f)
+    [_(&f)].compact
+  end
+  
+  # The same as <code>f.() and many(&f)</code>.
+  # 
+  # @return [Array, nil] an {Array} of results of +f+ or nil if the first call
+  #   to +f+ returned nil.
+  # 
+  def one_or_more(&f)
+    f1 = f.() and f2_n = many(&f) and [f1, *f2_n]
+  end
+  
+  alias many1 one_or_more
+  
+  # @overload not_follows(*method_ids)
+  #   
+  #   calls methods specified by +method_ids+. If any of them returns non-nil
+  #   then this method returns nil, otherwise it returns true. The methods
+  #   are called inside {#no_errors}. {#pos} is restored after each method's
+  #   call.
+  #   
+  #   @param [Array<Symbol>] method_ids
+  #   @return [true, nil]
+  #   
+  # @overload not_follows(&f)
+  # 
+  #   calls +f+. If +f+ returns non-nil then this method returns nil,
+  #   otherwise it returns true. +f+ is called inside {#no_errors}.
+  #   {#pos} is restored after +f+'s call.
+  #   
+  #   @return [true, nil]
+  # 
+  def not_follows(*method_ids, &f)
+    if f then
+      if no_errors { _{ f.() } }
+      then nil
+      else true
+      end
+    else # if not method_ids.empty? then
+      if no_errors { method_ids.any? { |method_id| _{ __send__(method_id) } } }
+      then nil
+      else true
+      end
+    end
+  end
+  
+  # ----------
+  # @!endgroup
+  # ----------
+  
+  # --------------
+  # @!group Errors
+  # --------------
+  
+  # 
+  # sets {#most_probable_error} to +error+ if it is more probable than
+  # {#most_probable_error} or if {#most_probable_error} is nil.
+  # 
+  # @param [Error] error
+  # @return [nil]
+  # 
+  def error(error)
+    if @allow_errors then
+      if @most_probable_error.nil? or @most_probable_error.pos < error.pos then
+        @most_probable_error = error
+      elsif @most_probable_error and @most_probable_error.pos == error.pos then
+        @most_probable_error = @most_probable_error.or error
+      else
+        # do nothing
+      end
+    end
+    return nil
+  end
+  
+  # macro
+  def expected(pos, what_1, *what_2_n)
+    error(Expected.new(pos, what_1, *what_2_n))
+  end
+  
+  # macro
+  def expect(what_1, *what_2_n, &body)
+    p = pos and body.() or expected(p, what_1, *what_2_n)
+  end
+  
+  # calls +block+. Inside the +block+ {#error} has no effect.
+  # 
+  # @return what +block+ returns.
+  # 
+  def no_errors(&block)
+    old_allow_errors = @allow_errors
+    begin
+      @allow_errors = false
+      block.()
+    ensure
+      @allow_errors = old_allow_errors
+    end
+  end
+  
+  # @return [Error, nil]
+  attr_reader :most_probable_error
+  
+  # ----------
+  # @!endgroup
+  # ----------
+  
+  private
+  
+  # @api private
+  # @note used by {Position#new} only.
+  class Position2
+    
+    include Position
+    
+    # @param [Integer] line
+    # @param [Integer] column
+    # @param [String] file
+    def initialize(line, column, file)
+      @line = line
+      @column = column
+      @file = file
+    end
+    
+    # (see Position#file)
+    attr_reader :file
+    
+    # (see Position#column)
+    attr_reader :column
+    
+    # (see Position#line)
+    attr_reader :line
+    
+  end
+  
+  # @!visibility private
+  # 
+  # A {Position} optimized for using with {StringScanner}.
+  # 
+  class StringScannerPosition
+    
+    include Position
+    
+    # @param [Integer] text_pos {StringScanner#pos} in +text+.
+    # @param [StringScanner] text
+    # @param [String] file see {Position#file}.
+    def initialize(text_pos, text, file)
+      @text = text
+      @text_pos = text_pos
+      @file = file
+    end
+    
+    # (see Position#file)
+    attr_reader :file
+    
+    # (see Position#line)
+    def line
+      line_and_column[0]
+    end
+    
+    # (see Position#column)
+    def column
+      line_and_column[1]
+    end
+    
+    # (see Position#<=>)
+    def <=> other
+      case other
+      when StringScannerPosition
+        return nil unless self.file == other.file
+        return self.text_pos <=> other.text_pos
+      else
+        super(other)
+      end
+    end
+    
+    # @!visibility private
+    attr_reader :text_pos
+    
+    # @!visibility private
+    attr_reader :text
+    
+    private
+    
+    def line_and_column
+      @line_and_column ||= begin
+        s = @text.substr(0, @text_pos)
+        lines = s.split("\n", -1).to_a
+        [
+          line = if lines.size == 0 then 0 else lines.size - 1 end,
+          column = (lines.last || "").size
+        ]
+      end
+    end
+    
+  end
+  
+end
+
+module ASTNode
+  
+  # macro
+  def self.new(*properties, &body)
+    (if properties.empty? then Class.new else Struct.new(*properties); end).tap do |c|
+      c.class_eval do
+        
+        include ASTNode
+        
+        # @return [Boolean]
+        def === other
+          self.class == other.class and
+          self.members.all? { |member| self.__send__(member) === other.__send__(member) }
+        end
+        
+        if properties.empty? then
+          # @return [Array<Symbol>]
+          def members
+            []
+          end
+        end
+        
+      end
+      c.class_eval(&body) if body
+    end
+  end
+  
+  # 
+  # Sets {#pos} to +pos+.
+  # 
+  # @param [Parse::Position] pos
+  # @return [self]
+  def initialize_pos(pos)
+    @pos = pos
+    self
+  end
+  
+  # @note {#initialize_pos} must be called before this method can be used.
+  # @return [Parse::Position]
+  def pos
+    raise "initialize_pos() must be called before this method can be used" unless @pos
+    @pos
+  end
+  
+end
+
+# Alias for {ASTNode.new}.
+def node(*properties, &body)
+  ASTNode.new(*properties, &body)
+end
+
+# class Calc < Parse
+#   
+#   Number = ASTNode.new :val
+#   
+#   rule :start do
+#     x1 = number and x2 = many { comma and number } and [x1, *x2]
+#   end
+#   
+#   rule :number do
+#     s = scan(/\d+/) and _(Number[s])
+#   end
+#   
+#   token :comma, ","
+#   
+#   def whitespace_and_comments
+#     scan(/\s+/)
+#   end
+#   
+# end
+# 
+# begin
+#   p Calc.new.("10a 20", __FILE__)
+# rescue Parse::Error => e
+#   puts "error: #{e.pos.file}:#{e.pos.line}:#{e.pos.column}: #{e.message}"
+# end
+

data/lib/parse/map_position.rb

@@ -0,0 +1,97 @@
+require 'parse'
+require 'array/bsearch_index'
+
+class Parse
+  
+  # 
+  # @example
+  #   
+  #   def pos(line, column, file)
+  #     Parse::Position.new(line, column, file)
+  #   end
+  #   
+  #   m = Parse::MapPosition.new
+  #   m.map_from(pos(5, 10, "src.c"), pos(3, 2, "src.y"))
+  #   m.map_from(pos(30, 5, "src.c"), pos(0, 0, "extra.y"))
+  #   p m[pos(1,12,"src.c")]  # src.c:1:12
+  #   p m[pos(5,12,"src.c")]  # src.y:3:4
+  #   p m[pos(6,10,"src.c")]  # src.y:4:10
+  #   p m[pos(30,5,"src.c")]  # extra.y:0:0
+  #   p m[pos(40,0,"src.c")]  # extra.y:10:0
+  # 
+  class MapPosition
+  
+    def initialize()
+      @mappings = []
+    end
+    
+    # 
+    # Before:
+    # 
+    # - <code>m[pos1] == pos2</code>
+    # 
+    # After:
+    # 
+    # - <code>m[pos1] == new_pos_b.advance(pos1 |-| pos_b)</code>
+    #   if <code>pos1 >= pos_b</code>
+    # - <code>m[pos1] == pos2</code> otherwise
+    # 
+    # Here <code>pos_m |-| pos_n</code> is the number of characters between
+    # +pos_m+ and +pos_n+; <code>p.advance(n)</code> is +p+ advanced by
+    # +n+ characters.
+    # 
+    # This method can not be called with +pos_b+ with different
+    # {Position#file}s!
+    # 
+    # @param [Position] pos_b
+    # @param [Position] new_pos_b
+    # @return [self]
+    # 
+    def map_from(pos_b, new_pos_b)
+      raise "can not call this method with different Position#file (was `#{@mappings.first.pos_b.file}' but `#{pos_b.file}' specified)" if not @mappings.empty? and @mappings.first.pos_b.file != pos_b.file
+      pos_b_idx = @mappings.bsearch_index { |mapping| mapping.pos_b >= pos_b } || @mappings.size
+      @mappings[pos_b_idx..-1] = [Mapping[pos_b, new_pos_b]]
+    end
+    
+    # 
+    # See also {#map_from}.
+    # 
+    # @param [Position] pos1
+    # @return [Position]
+    def [](pos1)
+      # 
+      return pos1 if @mappings.empty? or @mappings.first.pos_b.file != pos1.file
+      # 
+      mapping = find_mapping_for pos1
+      # 
+      return pos1 if mapping.nil?
+      # 
+      pos_b, new_pos_b = mapping.pos_b, mapping.new_pos_b
+      # new_pos_b.advance(pos1 |-| pos_b)
+      if pos1.line == pos_b.line
+      then Parse::Position.new(new_pos_b.line, new_pos_b.column + (pos1.column - pos_b.column), new_pos_b.file)
+      else Parse::Position.new(new_pos_b.line + (pos1.line - pos_b.line), pos1.column, new_pos_b.file)
+      end
+    end
+    
+    alias call []
+    
+    private
+    
+    # @return [Mapping, nil] a {Mapping} from +@mappings+ with
+    #   {Mapping#pos_b} == max and {Mapping#pos_b} <= pos1;
+    #   or nil if there is no such {Mapping}.
+    def find_mapping_for pos1
+      idx = @mappings.bsearch_index { |mapping| mapping.pos_b >= pos1 }
+      return @mappings.last if idx.nil?
+      return @mappings[idx] if pos1 == @mappings[idx].pos_b
+      return nil if idx == 0
+      return @mappings[idx - 1]
+    end
+    
+    # @!visibility private
+    Mapping = Struct.new :pos_b, :new_pos_b
+      
+  end
+  
+end

data/lib/strscan/substr.rb

@@ -0,0 +1,16 @@
+
+class StringScanner
+  
+  # @param [Integer] start some value of {StringScanner#pos}.
+  # @param [Integer] end_ some value of {StringScanner#pos}.
+  # @return [String]
+  def substr(start, end_)
+    old_pos = self.pos
+    self.pos = start
+    result = peek(end_ - start)
+    self.pos = old_pos
+    return result
+  end
+  
+end
+  

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: parse-framework
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Various Furriness
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-27 00:00:00.000000000 Z
+dependencies: []
+description: ! 'The framework for building parsers. It features position tracking
+  and automatic
+
+  error handling!
+
+'
+email: various.furriness@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/strscan/substr.rb
+- lib/parse/map_position.rb
+- lib/array/bsearch_index.rb
+- lib/parse.rb
+- lib/code.rb
+- README.md
+- .yardopts
+homepage: http://furronymous.bitbucket.org/parse
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Parser building framework
+test_files: []
+has_rdoc: