plurimath-parslet 3.0.0

data/lib/parslet/export.rb

@@ -0,0 +1,163 @@
+# Allows exporting parslet grammars to other lingos. 
+
+require 'set'
+require 'parslet/atoms/visitor'
+
+class Parslet::Parser
+  module Visitors
+    class Citrus
+      attr_reader :context, :output
+      def initialize(context)
+        @context = context
+      end
+      
+      def visit_str(str)
+        "\"#{str.inspect[1..-2]}\""
+      end
+      def visit_re(match)
+        match.to_s
+      end
+
+      def visit_entity(name, block)
+        context.deferred(name, block)
+
+        "(#{context.mangle_name(name)})"
+      end
+      def visit_named(name, parslet)
+        parslet.accept(self)
+      end
+
+      def visit_sequence(parslets)
+        '(' +
+        parslets.
+          map { |el| el.accept(self) }.
+          join(' ') +
+        ')'
+      end
+      def visit_repetition(tag, min, max, parslet)
+        parslet.accept(self) + "#{min}*#{max}"
+      end
+      def visit_alternative(alternatives)
+        '(' +
+        alternatives.
+          map { |el| el.accept(self) }.
+          join(' | ') +
+        ')'
+      end
+
+      def visit_lookahead(positive, bound_parslet)
+        (positive ? '&' : '!') +
+        bound_parslet.accept(self)
+      end
+    end
+
+    class Treetop < Citrus
+      def visit_repetition(tag, min, max, parslet)
+        parslet.accept(self) + "#{min}..#{max}"
+      end
+
+      def visit_alternative(alternatives)
+        '(' +
+        alternatives.
+          map { |el| el.accept(self) }.
+          join(' / ') +
+        ')'
+      end
+    end
+  end
+
+  # A helper class that formats Citrus and Treetop grammars as a string. 
+  #
+  class PrettyPrinter
+    attr_reader :visitor
+    def initialize(visitor_klass)
+      @visitor = visitor_klass.new(self)
+    end
+
+    # Pretty prints the given parslet using the visitor that has been
+    # configured in initialize. Returns the string representation of the
+    # Citrus or Treetop grammar.
+    #
+    def pretty_print(name, parslet)
+      output = ["grammar #{name}\n"]
+      
+      output << rule('root', parslet)
+      
+      seen = Set.new
+      loop do
+        # @todo is constantly filled by the visitor (see #deferred). We 
+        # keep going until it is empty.
+        break if @todo.empty?
+        name, block = @todo.shift
+
+        # Track what rules we've already seen. This breaks loops.
+        next if seen.include?(name)
+        seen << name
+
+        output << rule(name, block.call)
+      end
+      
+      output << "end\n"
+      output.join
+    end
+    
+    # Formats a rule in either dialect. 
+    #
+    def rule(name, parslet)
+      "  rule #{mangle_name name}\n" +
+      "    " + parslet.accept(visitor) + "\n" +
+      "  end\n"
+    end
+    
+    # Whenever the visitor encounters an rule in a parslet, it defers the
+    # pretty printing of the rule by calling this method. 
+    #
+    def deferred(name, content)
+      @todo ||= []
+      @todo << [name, content]
+    end
+
+    # Mangles names so that Citrus and Treetop can live with it. This mostly
+    # transforms some of the things that Ruby allows into other patterns. If
+    # there is collision, we will not detect it for now. 
+    #
+    def mangle_name(str)
+      str.to_s.sub(/\?$/, '_p')
+    end
+  end
+
+  # Exports the current parser instance as a string in the Citrus dialect. 
+  #
+  # Example: 
+  #
+  #   require 'parslet/export'
+  #   class MyParser < Parslet::Parser
+  #     root(:expression)
+  #     rule(:expression) { str('foo') }
+  #   end
+  #   
+  #   MyParser.new.to_citrus # => a citrus grammar as a string
+  #
+  def to_citrus
+    PrettyPrinter.new(Visitors::Citrus).
+      pretty_print(self.class.name, root)
+  end
+
+  # Exports the current parser instance as a string in the Treetop dialect. 
+  #
+  # Example: 
+  #
+  #   require 'parslet/export'
+  #   class MyParser < Parslet::Parser
+  #     root(:expression)
+  #     rule(:expression) { str('foo') }
+  #   end
+  #   
+  #   MyParser.new.to_treetop # => a treetop grammar as a string
+  #
+  def to_treetop
+    PrettyPrinter.new(Visitors::Treetop).
+      pretty_print(self.class.name, root)
+  end
+end
+

data/lib/parslet/expression/treetop.rb

@@ -0,0 +1,92 @@
+class Parslet::Expression::Treetop
+  class Parser < Parslet::Parser
+    root(:expression)
+    
+    rule(:expression) { alternatives }
+    
+    # alternative 'a' / 'b'
+    rule(:alternatives) {
+      (simple >> (spaced('/') >> simple).repeat).as(:alt)
+    }
+    
+    # sequence by simple concatenation 'a' 'b'
+    rule(:simple) { occurrence.repeat(1).as(:seq) }
+    
+    # occurrence modifiers
+    rule(:occurrence) {
+      atom.as(:repetition) >> spaced('*').as(:sign) |
+      atom.as(:repetition) >> spaced('+').as(:sign) |
+      atom.as(:repetition) >> repetition_spec |
+      
+      atom.as(:maybe) >> spaced('?') | 
+      atom
+    }
+        
+    rule(:atom) { 
+      spaced('(') >> expression.as(:unwrap) >> spaced(')') |
+      dot |
+      string |
+      char_class
+    }
+    
+    # a character class
+    rule(:char_class) {
+      (str('[') >>
+        (str('\\') >> any |
+        str(']').absent? >> any).repeat(1) >>
+      str(']')).as(:match) >> space?
+    }
+    
+    # anything at all
+    rule(:dot) { spaced('.').as(:any) }
+    
+    # recognizing strings
+    rule(:string) {
+      str('\'') >> 
+      (
+        (str('\\') >> any) |
+        (str("'").absent? >> any)
+      ).repeat.as(:string) >> 
+      str('\'') >> space?
+    }
+    
+    # repetition specification like {1, 2}
+    rule(:repetition_spec) {
+      spaced('{') >> 
+        integer.maybe.as(:min) >> spaced(',') >> 
+        integer.maybe.as(:max) >> spaced('}')
+    }
+    rule(:integer) {
+      match['0-9'].repeat(1)
+    }
+    
+    # whitespace handling
+    rule(:space) { match("\s").repeat(1) }
+    rule(:space?) { space.maybe }
+    
+    def spaced(str)
+      str(str) >> space?
+    end
+  end
+  
+  class Transform < Parslet::Transform
+    
+    rule(:repetition => simple(:rep), :sign => simple(:sign)) { 
+      min = sign=='+' ? 1 : 0
+      Parslet::Atoms::Repetition.new(rep, min, nil) }
+    rule(:repetition => simple(:rep), :min => simple(:min), :max => simple(:max)) { 
+      Parslet::Atoms::Repetition.new(rep, 
+        Integer(min || 0), 
+        max && Integer(max) || nil) }
+      
+    rule(:alt => subtree(:alt))       { Parslet::Atoms::Alternative.new(*alt) }
+    rule(:seq => sequence(:s))        { Parslet::Atoms::Sequence.new(*s) }
+    rule(:unwrap => simple(:u))       { u }
+    rule(:maybe => simple(:m))        { |d| d[:m].maybe }
+    rule(:string => simple(:s))       { Parslet::Atoms::Str.new(s) }
+    rule(:match => simple(:m))        { Parslet::Atoms::Re.new(m) }
+    rule(:any => simple(:a))          { Parslet::Atoms::Re.new('.') }
+  end
+  
+end
+

data/lib/parslet/expression.rb

@@ -0,0 +1,51 @@
+
+# Allows specifying rules as strings using the exact same grammar that treetop
+# does, minus the actions. This is on one hand a good example of a fully
+# fledged parser and on the other hand might even turn out really useful. 
+#
+# This can be viewed as an extension to parslet and might even be hosted in
+# its own gem one fine day. 
+# 
+class Parslet::Expression
+  include Parslet
+  
+  autoload :Treetop, 'parslet/expression/treetop'
+  
+  # Creates a parslet from a foreign language expression. 
+  #
+  # Example: 
+  #   
+  #   Parslet::Expression.new("'a' 'b'")
+  #
+  def initialize(str, opts={}, context=self)
+    @type = opts[:type] || :treetop
+    @exp = str
+    @parslet = transform(
+      parse(str))
+  end
+  
+  # Transforms the parse tree into a parslet expression. 
+  #
+  def transform(tree)
+    transform = Treetop::Transform.new
+    
+    # pp tree
+    transform.apply(tree)
+  rescue 
+    warn "Could not transform: " + tree.inspect
+    raise
+  end
+  
+  # Parses the string and returns a parse tree.
+  #
+  def parse(str)
+    parser = Treetop::Parser.new
+    parser.parse(str)
+  end
+
+  # Turns this expression into a parslet.
+  #
+  def to_parslet
+    @parslet
+  end
+end

data/lib/parslet/graphviz.rb

@@ -0,0 +1,97 @@
+
+# Paints a graphviz graph of your parser.
+
+begin
+  require 'ruby-graphviz'
+rescue LoadError
+  puts "Please install the 'ruby-graphviz' gem first."
+  fail
+end
+
+require 'set'
+require 'parslet/atoms/visitor'
+
+module Parslet
+  class GraphvizVisitor
+    def initialize g
+      @graph = g
+      @known_links = Set.new
+      @visited = Set.new
+    end
+
+    attr_reader :parent
+
+    def visit_parser(root)
+      recurse root, node('parser')
+    end
+    def visit_entity(name, block)
+      s = node(name)
+
+      downwards s
+
+      return if @visited.include?(name)
+      @visited << name
+
+      recurse block.call, s
+    end
+    def visit_named(name, atom)
+      recurse atom, parent
+    end
+    def visit_repetition(tag, min, max, atom)
+      recurse atom, parent
+    end
+    def visit_alternative(alternatives)
+      p = parent
+      alternatives.each do |atom|
+        recurse atom, p
+      end
+    end
+    def visit_sequence(sequence)
+      p = parent
+      sequence.each do |atom|
+        recurse atom, p
+      end
+    end
+    def visit_lookahead(positive, atom)
+      recurse atom, parent
+    end
+    def visit_re(regexp)
+      # downwards node(regexp.object_id, label: escape("re(#{regexp.inspect})"))
+    end
+    def visit_str(str)
+      # downwards node(str.object_id, label: escape("#{str.inspect}"))
+    end
+
+    def escape str
+      str.gsub('"', "'")
+    end
+    def node name, opts={}
+      @graph.add_nodes name.to_s, opts
+    end
+    def downwards child
+      if @parent && !@known_links.include?([@parent, child])
+        @graph.add_edges(@parent, child)
+        @known_links << [@parent, child]
+      end
+    end
+    def recurse node, current
+      @parent = current
+      node.accept(self)
+    end
+  end
+
+  module Graphable
+    def graph opts
+      g = GraphViz.new(:G, type: :digraph)
+      visitor = GraphvizVisitor.new(g)
+
+      new.accept(visitor)
+
+      g.output opts
+    end
+  end
+
+  class Parser # reopen for introducing the .graph method
+    extend Graphable
+  end
+end

data/lib/parslet/parser.rb

@@ -0,0 +1,68 @@
+
+# The base class for all your parsers. Use as follows: 
+#
+#   require 'parslet'
+#        
+#   class MyParser < Parslet::Parser
+#     rule(:a) { str('a').repeat }
+#     root(:a)        
+#   end
+#        
+#   pp MyParser.new.parse('aaaa')   # => 'aaaa'
+#   pp MyParser.new.parse('bbbb')   # => Parslet::Atoms::ParseFailed: 
+#                                   #    Don't know what to do with bbbb at line 1 char 1.
+#
+# Parslet::Parser is also a grammar atom. This means that you can mix full 
+# fledged parsers freely with small parts of a different parser. 
+#
+# Example: 
+#   class ParserA < Parslet::Parser
+#     root :aaa
+#     rule(:aaa) { str('a').repeat(3,3) }
+#   end
+#   class ParserB < Parslet::Parser
+#     root :expression
+#     rule(:expression) { str('b') >> ParserA.new >> str('b') }
+#   end
+#
+# In the above example, ParserB would parse something like 'baaab'. 
+#
+class Parslet::Parser < Parslet::Atoms::Base
+  include Parslet
+
+  class << self # class methods
+    # Define the parsers #root function. This is the place where you start 
+    # parsing; if you have a rule for 'file' that describes what should be 
+    # in a file, this would be your root declaration: 
+    #
+    #   class Parser
+    #     root :file
+    #     rule(:file) { ... }
+    #   end
+    #
+    # #root declares a 'parse' function that works just like the parse 
+    # function that you can call on a simple parslet, taking a string as input
+    # and producing parse output. 
+    #
+    # In a way, #root is a shorthand for: 
+    #
+    #   def parse(str)
+    #     your_parser_root.parse(str)
+    #   end
+    #
+    def root(name)
+      undef_method :root if method_defined? :root
+      define_method(:root) do
+        self.send(name)
+      end
+    end
+  end
+  
+  def try(source, context, consume_all)
+    root.try(source, context, consume_all)
+  end
+  
+  def to_s_inner(prec)
+    root.to_s(prec)
+  end
+end

data/lib/parslet/pattern/binding.rb

@@ -0,0 +1,49 @@
+
+# Used internally for representing a bind placeholder in a Parslet::Transform
+# pattern. This is the superclass for all bindings. 
+#
+# It defines the most permissive kind of bind, the one that matches any subtree
+# whatever it looks like. 
+#
+class Parslet::Pattern::SubtreeBind < Struct.new(:symbol)
+  def variable_name
+    symbol
+  end
+  
+  def inspect
+    "#{bind_type_name}(#{symbol.inspect})"
+  end
+  
+  def can_bind?(subtree)
+    true
+  end
+
+private 
+  def bind_type_name 
+    if md=self.class.name.match(/(\w+)Bind/)
+      md.captures.first.downcase
+    else
+      # This path should never be used, but since this is for inspection only, 
+      # let's not raise.
+      'unknown_bind'
+    end
+  end
+end
+
+# Binds a symbol to a simple subtree, one that is not either a sequence of
+# elements or a collection of attributes. 
+#
+class Parslet::Pattern::SimpleBind < Parslet::Pattern::SubtreeBind
+  def can_bind?(subtree)
+    not [Hash, Array].include?(subtree.class)
+  end
+end
+
+# Binds a symbol to a sequence of simple leafs ([element1, element2, ...])
+#
+class Parslet::Pattern::SequenceBind < Parslet::Pattern::SubtreeBind
+  def can_bind?(subtree)
+    subtree.kind_of?(Array) &&
+      (not subtree.any? { |el| [Hash, Array].include?(el.class) })
+  end
+end

data/lib/parslet/pattern.rb

@@ -0,0 +1,113 @@
+# Matches trees against expressions. Trees are formed by arrays and hashes
+# for expressing membership and sequence. The leafs of the tree are other
+# classes. 
+#
+# A tree issued by the parslet library might look like this: 
+#
+#   { 
+#     :function_call => {
+#       :name => 'foobar', 
+#       :args => [1, 2, 3]
+#     }
+#   }
+#
+# A pattern that would match against this tree would be: 
+#
+#   { :function_call => { :name => simple(:name), :args => sequence(:args) }}
+#
+# Note that Parslet::Pattern only matches at a given subtree; it wont try 
+# to match recursively. To do that, please use Parslet::Transform. 
+#
+class Parslet::Pattern  
+  def initialize(pattern)
+    @pattern = pattern
+  end
+
+  # Decides if the given subtree matches this pattern. Returns the bindings
+  # made on a successful match or nil if the match fails. If you specify 
+  # bindings to be a hash, the mappings in it will be treated like bindings
+  # made during an attempted match. 
+  #
+  #   Pattern.new('a').match('a', :foo => 'bar') # => { :foo => 'bar' }
+  #
+  # @param subtree [String, Hash, Array] poro subtree returned by a parse
+  # @param bindings [Hash] variable bindings to be verified
+  # @return [Hash, nil] On success: variable bindings that allow a match. On 
+  #   failure: nil
+  #
+  def match(subtree, bindings=nil)
+    bindings = bindings && bindings.dup || Hash.new
+    return bindings if element_match(subtree, @pattern, bindings)
+  end
+  
+  # Returns true if the tree element given by +tree+ matches the expression
+  # given by +exp+. This match must respect bindings already made in
+  # +bindings+. Note that bindings is carried along and modified. 
+  #
+  # @api private
+  #
+  def element_match(tree, exp, bindings) 
+    # p [:elm, tree, exp]
+    if tree.is_a?(Hash) && exp.is_a?(Hash)
+      return element_match_hash(tree, exp, bindings)
+    elsif tree.is_a?(Array) && exp.is_a?(Array)
+      return element_match_ary_single(tree, exp, bindings)
+    else
+      # If elements match exactly, then that is good enough in all cases
+      return true if exp === tree
+      
+      # If exp is a bind variable: Check if the binding matches
+      if exp.respond_to?(:can_bind?) && exp.can_bind?(tree)
+        return element_match_binding(tree, exp, bindings)
+      end
+                  
+      # Otherwise: No match (we don't know anything about the element
+      # combination)
+      return false
+    end
+  end
+  
+  # @api private
+  #
+  def element_match_binding(tree, exp, bindings)
+    var_name = exp.variable_name
+
+    # TODO test for the hidden :_ feature.
+    if var_name && bound_value = bindings[var_name]
+      return bound_value == tree
+    end
+    
+    # New binding: 
+    bindings.store var_name, tree
+    
+    return true
+  end
+  
+  # @api private
+  #
+  def element_match_ary_single(sequence, exp, bindings)
+    return false if sequence.size != exp.size
+    
+    return sequence.zip(exp).all? { |elt, subexp|
+      element_match(elt, subexp, bindings) }
+  end
+  
+  # @api private
+  #
+  def element_match_hash(tree, exp, bindings)
+    # Early failure when one hash is bigger than the other
+    return false unless exp.size == tree.size
+    
+    # We iterate over expected pattern, since we demand that the keys that
+    # are there should be in tree as well.
+    exp.each do |expected_key, expected_value|
+      return false unless tree.has_key? expected_key
+      
+      # Recurse into the value and stop early on failure
+      value = tree[expected_key]
+      return false unless element_match(value, expected_value, bindings)
+    end
+    
+    return true
+  end  
+end

data/lib/parslet/position.rb

@@ -0,0 +1,21 @@
+
+# Encapsules the concept of a position inside a string. 
+#
+class Parslet::Position
+  attr_reader :bytepos
+
+  include Comparable
+
+  def initialize string, bytepos
+    @string = string
+    @bytepos = bytepos
+  end
+
+  def charpos
+    @string.byteslice(0, @bytepos).size
+  end
+
+  def <=> b
+    self.bytepos <=> b.bytepos
+  end
+end

data/lib/parslet/rig/rspec.rb

@@ -0,0 +1,52 @@
+RSpec::Matchers.define(:parse) do |input, opts|
+  as = block = nil
+  result = trace = nil
+
+  match do |parser|
+    begin
+      result = parser.parse(input)
+      block ? 
+        block.call(result) : 
+        (as == result || as.nil?)
+    rescue Parslet::ParseFailed => ex
+      trace = ex.parse_failure_cause.ascii_tree if opts && opts[:trace]
+      false
+    end
+  end
+
+  public_send(respond_to?(:failure_message) ? :failure_message : :failure_message_for_should) do |is|
+    if block
+      "expected output of parsing #{input.inspect}" <<
+      " with #{is.inspect} to meet block conditions, but it didn't"
+    else
+      "expected " << 
+        (as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} to equal #{as.inspect}, but was #{result.inspect}" : 
+          "#{is.inspect} to be able to parse #{input.inspect}") << 
+        (trace ? 
+          "\n"+trace : 
+          '')
+    end
+  end
+
+  public_send(respond_to?(:failure_message_when_negated) ? :failure_message_when_negated : :failure_message_for_should_not) do |is|
+    if block
+      "expected output of parsing #{input.inspect} with #{is.inspect} not to meet block conditions, but it did"
+    else
+      "expected " << 
+        (as ? 
+          "output of parsing #{input.inspect}"<<
+          " with #{is.inspect} not to equal #{as.inspect}" :
+          
+          "#{is.inspect} to not parse #{input.inspect}, but it did")
+    end
+  end
+
+  # NOTE: This has a nodoc tag since the rdoc parser puts this into 
+  # Object, a thing I would never allow. 
+  chain :as do |expected_output=nil, &my_block|
+    as = expected_output
+    block = my_block
+  end
+end