raabro 1.1.3 → 1.1.4

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+
+# raabro CHANGELOG.md
+
+
+## raabro 1.1.4  released 2017-08-17
+
+* fail with ArgumentError if Raabro.pp input is not a Raabro::Tree
+* parse(x, error: true) will produce an error message
+  `[ line, column, offset, err_message, err_visual ]`
+
+
+## raabro 1.1.3  released 2016-07-11
+
+* display `>nonstring(14)<` in Raabro.pp
+* add "tears" to Raabro.pp
+
+
+## raabro 1.1.2  released 2016-04-04
+
+* add Raabro.pp(tree)
+
+
+## raabro 1.1.1  released 2016-04-03
+
+* Tree#clast
+
+
+## raabro 1.1.0  released 2016-02-09
+
+* many improvements
+* unlock custom `rewrite(t)`
+
+
+## raabro 1.0.5  released 2015-09-25
+
+* allow for .parse(s, debug: 1 to 3)
+* drop complications in _narrow(parser)
+
+
+## raabro 1.0.4  released 2015-09-24
+
+* provide a default .rewrite implementation
+
+
+## raabro 1.0.3  released 2015-09-23
+
+* drop the shrink! concept
+
+
+## raabro 1.0.2  released 2015-09-23
+
+* don't let parse() shrink tree when prune: false
+* let parse() return tree anyway when prune: false
+* add parse(s, rewrite: false) option
+
+
+## raabro 1.0.1  released 2015-09-23
+
+* take last parser as default :root
+* provide default .parse for modules including Raabro
+
+
+## raabro 1.0.0  released 2015-09-23
+
+* first complete (hopefully) release
+
+
+## raabro 0.9.0
+
+* initial push to RubyGems
+

data/LICENSE.txt

@@ -1,5 +1,5 @@
 
-Copyright (c) 2015-2016, John Mettraux, jmettraux@gmail.com
+Copyright (c) 2015-2017, John Mettraux, jmettraux@gmail.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -125,10 +125,102 @@ def ren(name, input, parser)
   # renames the output of the wrapped parser
 
 def jseq(name, input, eltpa, seppa)
-  # seq(name, input, eltpa, seppa, eltpa, seppa, eltpaa, seppa, ...)
+  #
+  # seq(name, input, eltpa, seppa, eltpa, seppa, eltpa, seppa, ...)
+  #
+  # a sequence of `eltpa` parsers separated (joined) by `seppa` parsers
 
 def eseq(name, input, startpa, eltpa, seppa, endpa)
+  #
   # seq(name, input, startpa, eltpa, seppa, eltpa, seppa, ..., endpa)
+  #
+  # a sequence of `eltpa` parsers separated (joined) by `seppa` parsers
+  # preceded by a `startpa` parser and followed by a `endpa` parser
+```
+
+
+## the `seq` parser and its quantifiers
+
+`seq` is special, it understands "quantifiers": `'?'`, `'+'` or `'*'`. They make behave `seq` a bit like a classical regex.
+
+```ruby
+module CartParser include Raabro
+
+  def fruit(i)
+    rex(:fruit, i, /(tomato|apple|orange)/)
+  end
+  def vegetable(i)
+    rex(:vegetable, i, /(potato|cabbage|carrot)/)
+  end
+
+  def cart(i)
+    seq(:cart, i, :fruit, '*', :vegetable, '*')
+  end
+    # zero or more fruits followed by zero or more vegetables
+end
+```
+
+(Yes, this sample parser parses string like "appletomatocabbage", it's not very useful, but I hope you get the point about `.seq`)
+
+
+## errors
+
+By default, a parser will return nil when it cannot successfully parse the input.
+
+For example, given the above [`Fun` parser](#a-sample-parserrewriter), parsing some truncated input would yield `nil`:
+```ruby
+tree = Sample::Fun.parse('f(a, b')
+  # yields `nil`...
+```
+
+One can reparse with `error: true` and receive an error array with the parse error details:
+```ruby
+err = Sample::Fun.parse('f(a, b', error: true)
+  # yields:
+  # [ line, column, offest, error_message, error_visual ]
+[ 1, 4, 3, 'parsing failed .../:exp/:fun/:arg', "f(a, b\n   ^---" ]
+```
+
+The last string in the error array looks like when printed out:
+```
+f(a, b
+   ^---
+```
+
+### error when not all is consumed
+
+Consider the following toy parser:
+```ruby
+module ToPlus include Raabro
+
+  # parse
+
+  def to_plus(input); rep(:tos, input, :to, 1); end
+
+  # rewrite
+
+  def rewrite(t); [ :ok, t.string ]; end
+end
+```
+
+```ruby
+Sample::ToPlus.parse('totota')
+  # yields nil since all the input was not parsed, "ta" is remaining
+
+Sample::ToPlus.parse('totota', all: false)
+  # yields
+[ :ok, "toto" ]
+  # and doesn't care about the remaining input "ta"
+
+Sample::ToPlus.parse('totota', error: true)
+  # yields
+[ 1, 5, 4, "parsing failed, not all input was consumed", "totota\n    ^---" ]
+```
+
+The last string in the error array looks like when printed out:
+```
+totota
+    ^---
 ```
 
 

data/lib/raabro.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright (c) 2015-2016, John Mettraux, jmettraux@gmail.com
+# Copyright (c) 2015-2017, John Mettraux, jmettraux@gmail.com
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -25,7 +25,7 @@
 
 module Raabro
 
-  VERSION = '1.1.3'
+  VERSION = '1.1.4'
 
   class Input
 
@@ -55,6 +55,11 @@ module Raabro
 
       l < 0 ? @string[@offset..l] : @string[@offset, l]
     end
+
+    def at(i)
+
+      @string[i, 1]
+    end
   end
 
   class Tree
@@ -181,6 +186,74 @@ module Raabro
 
       cs = []; @children.each_with_index { |c, i| cs << c if i.even? }; cs
     end
+
+    def extract_error
+
+#Raabro.pp(self, colors: true)
+      err_tree, stack = lookup_error || lookup_all_error
+
+      line, column = line_and_column(err_tree.offset)
+
+      err_message =
+        if stack
+          path = stack
+           .compact.reverse.take(3).reverse
+           .collect(&:inspect).join('/')
+          "parsing failed .../#{path}"
+        else
+          "parsing failed, not all input was consumed"
+        end
+      visual =
+        visual(line, column)
+
+      [ line, column, err_tree.offset, err_message, visual ]
+    end
+
+    def lookup_error(stack=[])
+
+#print "le(): "; Raabro.pp(self, colors: true)
+      return nil if @result != 0
+      return [ self, stack ] if @children.empty?
+      @children.each { |c|
+        es = c.lookup_error(stack.dup.push(self.name))
+        return es if es }
+      nil
+    end
+
+    # Not "lookup all errors" but "lookup all error", in other
+    # words lookup the point up until which the parser stopped (not
+    # consuming all the input)
+    #
+    def lookup_all_error
+
+#print "lae(): "; Raabro.pp(self, colors: true)
+      @children.each { |c| return [ c, nil ] if c.result == 0 }
+      @children.reverse.each { |c| es = c.lookup_all_error; return es if es }
+      nil
+    end
+
+    def line_and_column(offset)
+
+      line = 1
+      column = 0
+
+      (0..offset).each do |off|
+
+        column += 1
+        next unless @input.at(off) == "\n"
+
+        line += 1
+        column = 0
+      end
+
+      [ line, column ]
+    end
+
+    def visual(line, column)
+
+      @input.string.split("\n")[line - 1] + "\n" +
+      ' ' * (column - 1) + '^---'
+    end
   end
 
   module ModuleMethods
@@ -472,6 +545,7 @@ module Raabro
           all(nil, Raabro::Input.new(input, opts), root)
         end
 
+      return reparse_for_error(input, opts, t) if opts[:error] && t.result != 1
       return nil if opts[:prune] != false && t.result != 1
 
       t = t.children.first if t.parter == :all
@@ -481,6 +555,17 @@ module Raabro
       t
     end
 
+    def reparse_for_error(input, opts, t)
+
+      t =
+        opts[:prune] == false ?
+        t :
+        parse(input, opts.merge(error: false, rewrite: false, prune: false))
+#Raabro.pp(t, colours: true)
+
+      t.extract_error
+    end
+
     def rewrite_(tree)
 
       t = tree.lookup(nil)
@@ -520,10 +605,16 @@ module Raabro
     # Brown       0;33     Yellow        1;33
     # Light Gray  0;37     White         1;37
 
-  def self.pp(tree, depth=0)
+  def self.pp(tree, depth=0, opts={})
+
+    fail ArgumentError.new(
+      'tree is not an instance of Raabro::Tree'
+    ) unless tree.is_a?(Raabro::Tree)
+
+    depth, opts = 0, depth if depth.is_a?(Hash)
 
     _rs, _dg, _gn, _yl, _bl, _lg =
-      $stdout.tty? ?
+      (opts[:colors] || opts[:colours] || $stdout.tty?) ?
       [ "", "", "", "", "", "" ] :
       [ '', '', '', '', '', '' ]
 
@@ -554,7 +645,7 @@ module Raabro
     print str
     print "#{_rs}\n"
 
-    tree.children.each { |c| self.pp(c, depth + 1) }
+    tree.children.each { |c| self.pp(c, depth + 1, opts) }
 
     if depth == 0
       print _dg

data/raabro.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.authors = [ 'John Mettraux' ]
   s.email = [ 'jmettraux@gmail.com' ]
   s.homepage = 'http://github.com/jmettraux/raabro'
-  s.rubyforge_project = 'rufus'
+  #s.rubyforge_project = 'rufus'
   s.license = 'MIT'
   s.summary = 'a very dumb PEG parser library'
 
@@ -21,14 +21,16 @@ A very dumb PEG parser library, with a horrible interface.
 
   #s.files = `git ls-files`.split("\n")
   s.files = Dir[
+    'README.{md,txt}',
+    'CHANGELOG.{md,txt}', 'CREDITS.{md,txt}', 'LICENSE.{md,txt}',
     'Makefile',
-    'lib/**/*.rb',# 'spec/**/*.rb', 'test/**/*.rb',
-    '*.gemspec', '*.txt', '*.rdoc', '*.md'
+    'lib/**/*.rb', #'spec/**/*.rb', 'test/**/*.rb',
+    "#{s.name}.gemspec",
   ]
 
   #s.add_runtime_dependency 'tzinfo'
 
-  s.add_development_dependency 'rspec', '>= 2.13.0'
+  s.add_development_dependency 'rspec', '~> 3.4.0'
 
   s.require_path = 'lib'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raabro
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,24 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-11 00:00:00.000000000 Z
+date: 2017-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 2.13.0
+        version: 3.4.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: 2.13.0
+        version: 3.4.0
 description: A very dumb PEG parser library, with a horrible interface.
 email:
 - jmettraux@gmail.com
@@ -34,12 +34,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- CHANGELOG.md
+- LICENSE.txt
 - Makefile
 - lib/raabro.rb
 - raabro.gemspec
-- CHANGELOG.txt
-- LICENSE.txt
-- README.md
 homepage: http://github.com/jmettraux/raabro
 licenses:
 - MIT
@@ -60,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: rufus
+rubyforge_project: 
 rubygems_version: 1.8.23.2
 signing_key: 
 specification_version: 3

data/CHANGELOG.txt

@@ -1,64 +0,0 @@
-
-= raabro CHANGELOG.txt
-
-
-== raabro 1.1.3  released 2016-07-11
-
-- display >nonstring(14)< in Raabro.pp
-- add "tears" to Raabro.pp
-
-
-== raabro 1.1.2  released 2016-04-04
-
-- add Raabro.pp(tree)
-
-
-== raabro 1.1.1  released 2016-04-03
-
-- Tree#clast
-
-
-== raabro 1.1.0  released 2016-02-09
-
-- many improvements
-- unlock custom `rewrite(t)`
-
-
-== raabro 1.0.5  released 2015-09-25
-
-- allow for .parse(s, debug: 1 to 3)
-- drop complications in _narrow(parser)
-
-
-== raabro 1.0.4  released 2015-09-24
-
-- provide a default .rewrite implementation
-
-
-== raabro 1.0.3  released 2015-09-23
-
-- drop the shrink! concept
-
-
-== raabro 1.0.2  released 2015-09-23
-
-- don't let parse() shrink tree when prune: false
-- let parse() return tree anyway when prune: false
-- add parse(s, rewrite: false) option
-
-
-== raabro 1.0.1  released 2015-09-23
-
-- take last parser as default :root
-- provide default .parse for modules including Raabro
-
-
-== raabro 1.0.0  released 2015-09-23
-
-- first complete (hopefully) release
-
-
-== raabro 0.9.0
-
-- initial push to RubyGems
-