l43_peg 0.1.9 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e988304f4b2f29b9d0fdc15008e8cc0bdf1b9bd2407d5563a7a8d0f88ff805e
-  data.tar.gz: 6d8c8edca204793d062ce30dc2ee22f8f3a95faee74779e62beb4a9d90ef4234
+  metadata.gz: 12367798c13e0e131a3d2b0acd28db7c272fd9c25f46715e0ec1a6eb415e0eb5
+  data.tar.gz: e57b47017a6af939d130f6178326e3fe90965c7ccd3dadc0308b0f54fba9abe5
 SHA512:
-  metadata.gz: 5884815166a138bf01163af5b0782d83cac9ac97571cbcb9cc35a92dcc54dacef96fa5f5b97049c0d39b0585fa71e6c50a04d91459889c64a17a7858ac9bc199
-  data.tar.gz: 0c709f631fba65dcf86e172aba3b4fc3743d8d0a246089a361a0954a1abaaad69b24fa3de78e73ae62cb7ed3c150f950b7925cdafea2a8157c80d7b8720090a1
+  metadata.gz: e28f4a426cf654af9376932587cbb4252f4279392d09d0cc3e94f5d197e1cffc1eaa5134243ade86a3ae3632ced45aa453afccbffc57eca6eb23cda38dc88bb6
+  data.tar.gz: 94d10a4621e0ab446b338d15b1a694c045b77728673a1c503aa7627c6b4069d5d62eeb61992023e28bd7c098ca3e9b718e88dc65f7c942bddf1e454bb2b2fd3f

data/README.md

@@ -4,311 +4,66 @@
 
 ## A Parse Expression Grammar library for Ruby
 
-### This Version (v0.1.x) is Alpha Quality (many PEG features are missing, like recursion and even alternatives.
+## Table Of Contents
+- [Quick Start:](#quick-start-table-of-contents)
+- [Built In Parsers...](#built-in-parsers-table-of-contents)
+- [Concepts...](#concepts-table-of-contents)
+- [Combinators...](#combinators-table-of-contents)
+- [Author](#author-table-of-contents)
+- [LICENSE](#license-table-of-contents)
+<!-- END TOC -->
 
-    It is however released because it offers quite some nice parsing of ARGV which shall be demonstrated by the following
-    [speculations](https://rubygems.org/gems/speculate_about)
-
-    See [README_spec.rb](spec/speculations/README_spec.rb) for the generated code for details
-
-### Context: `arg_parser`
-
-Given the following argument specification
-
-```ruby 
-    include L43Peg::Combinators
-    let :args_spec do
-    {
-      start: "--start=(.*)",
-      end: "(?:--end|-e)=(.*)",
-      kwd: "--(alpha|beta|gamma)"
-    }
-    end
-```
-
-And the assoicated parser
+# Quick Start: [^](#table-of-contents)
 
+Given we import everyting into our namespace
 ```ruby
-  let(:parser) { args_parser(args_spec) } 
+    require 'l43_peg'
+    Kernel.include L43Peg # not the same as RSpec's include
 ```
 
-Then we can parse some input
-
-```ruby
-assert_parse_success(parser, %w[--start=42 --beta -e=44], ast: {start: "42", kwd: "beta", end: "44"}, rest: [])
-```
-
-And we can get the rest in a list of tokens
-
+Then we can use the parse function to parse a string or an instance of `Input`
 ```ruby
-assert_parse_success(parser, %w[--start=42 --beta -e=44 -s=not_an_arg --end=too_late], ast: {start: "42", kwd: "beta", end: "44"}, rest: %w[-s=not_an_arg --end=too_late])
-```
-
-Also note that multiple values are passed into an array
-
-```ruby
-input = %w[--end=42 --beta -e=44 --beta --end=not_too_late --gamma]
-ast   = {end: %w[42 44 not_too_late], kwd: %w[beta beta gamma]}
-assert_parse_success(parser, input, ast:, rest: [])
-  ```
-
-#### Context: Postprocessing
-
-  When we map the parser
-
-  ```ruby
-  let :int_args do
-{
-start: "--start=(.*)",
-         end: "--end=(.*)",
-         inc: "--inc=(.*)"
-}
-end
-let(:int_arg_parser) {args_parser(int_args, name: "int parser", &:to_i)}
-```
-
-Then we can convert the string valus
-
-  ```ruby
-assert_parse_success(int_arg_parser, %w[--start=42 --end=44 --inc=2], ast: {start: 42, end: 44, inc: 2}, rest: [])
-  ```
-
-#### Context: Knowing When To Stop
-
-  An argument parser that respects itself provides a means to _end_ argument parsing even if more matches follow.
-  An exmaple for that is the posix argument `--`
-
-  We can use whatever we want in `args_parser`, here is a variation:
-
-  Given the specification
-
-  ```ruby
-  let :args do
-    {
-      width: "w:(\\d+)",
-      height: "h:(\\d+)",
-       __stop: "(::)"
-    }
-  end
-  let(:wh_parser) {args_parser(args, stop: :__stop, &:to_i)}
+    parse("a", with: char_parser) => Success
+    parse("a", with: char_parser("b")) => Failure
 ```
 
-Then parsing the following input
-
-```ruby
-    input = %w[h:42 w:73 :: w:74]
-    ast   = {height: 42, width: 73}
-    assert_parse_success(wh_parser, input, ast:, rest: %w[w:74])
-  ```
-
-### Context: User Interface
-
-#### Context: Exposing the args_parser
-
-Above we have seen that we had to include an internal module so to get access to the `args_parser`.
-Client code might not want to use these intrusive methods and therefore the parsers are also exposed
-as module methods
-
-Given an _exposed_ `args_parser`
+And parsers that do not need any arguments can be passed in as symbols
 ```ruby
-let :parser do
-L43Peg::Parsers.args_parser(
-  {
-    negative: "(-\\d+)",
-    positive: "\\+?(\\d+)"
-},
-&:to_i
-)
-end
+    parse("a", with: :char_parser) => :ok, "a", _
 ```
 
-But we are also not interested in the internal representation of success and failure of parsing which was
-used in the speculations above. Nor do we want to transform our input into the internal representations
-as was done above by the helpers. (If you need to see the details of this you can inspect the
-  file [`parser_test.rb` in `spec/support`](spec/support/parser_test.rb))
-
-Then we can uses the interface of `L43Peg`
-
+And we can deconstruct the result into a status, ast and the rest `Input` instance.
 ```ruby
-  L43Peg.parse_tokens(parser, %w[43 -44 +45]) => :ok, result
-    expect(result).to eq(positive: [43, 45], negative: -44)
+    parse("a", with: char_parser) => :ok, "a", {src: ""}
+    parse("ab", with: char_parser) => :ok, "a", {src: "b"}
+    parse(Input.new(src: "ab"), with: char_parser) => :ok, "a", {src: "b"}
 ```
-
-And if we get an error the result is as follows
-
+And we can also deconstruct it into a `Hash` which provides even more information
 ```ruby
-parser = L43Peg::Parsers.char_parser('a') 
-L43Peg.parse_string(parser, 'b') => :error, message
-expect(message).to eq("char \"b\"")
+    parse("+42", with: int_parser) => {ok: true, ast: 42, parsed: "+42"}
 ```
 
-## Context: Regexp Parser
-
-The basic concept is the `rgx_parser`
+## Complete Documentation
 
-Given a `rgx_parser` for an identifier
-```ruby
-include L43Peg::Parsers
-let(:id_parser) { rgx_parser("[[:alpha:]][_[:alnum:]]*") } 
-```
+### Built In Parsers... [^](#table-of-contents)
 
-Then we can parse strings that start as such
-```ruby
-assert_parse_success(id_parser, "l43_peg", ast: "l43_peg")
-```
+...are described [here](speculations/built_in.md)
 
-And we can discard some input from the ast with the aid of captures
-```ruby
-sym_parser = rgx_parser(":([[:alpha:]][_[:alnum:]]*)")
-assert_parse_success(sym_parser, ":no_colon", ast: "no_colon")
-```
-
-But it can also fail
-```ruby
-reason = "input does not match /\\A[[:alpha:]][_[:alnum:]]*/ (in rgx_parser(\"[[:alpha:]][_[:alnum:]]*\"))"
-assert_parse_failure(id_parser, "42", reason:)
-```
+### Concepts... [^](#table-of-contents)
 
-#### Context: Warnings on empty matches
+...are described [here](speculations/concepts.md)
 
-Oftentimes bugs in PEG parsing are caused by zero width matches, while this is quite obvious with the `many` and
-`opt` or `maybe` combinators (**N.B.** they are not yet implemented, use `many(max: 1)` instead)
-and they common use patterns with these combinators are safe.
-
-However regular expression parsing might hide zero width matches, and that's whey they will trigger a warning by default
-
-Given an empty match rgex parser
-```ruby
-    let(:empty_parser) { rgx_parser("a*") }
-```
-
-Then we get a warning when matching an empty string
-```ruby
-    expect { assert_parse_success(empty_parser, "", ast: "") }
-      .to output("Warning, parser rgx_parser(\"a*\") succeeds with empty match\n").to_stderr
-```
-
-However this behavior can also be disabled
-
-And therefore
-```ruby
-    parser = rgx_parser("a*", warn_on_empty: false)
-    expect { assert_parse_success(parser, "", ast: "") }
-      .not_to output.to_stderr
-```
-
-
-### Context: Tokenize Strings with Regexen
-
-Now we can use a list of `rgx_parsers` to _tokenize_ a string (in the same way can use `tokens_parser` to
-  quantify elements of an array, but with dynamic bounds)
-
-Given some regexen
-```ruby
-let :regexen do
-[
-[:verb, "<<", nil, ->(*){ [:verb, "<"] }],
-[:verb, "\\$(\\$)"],
-[:color_and_style, "<(.+?),(.+?)>", :all],
-[:color, "<(.+?)>", 1],
-[:reset, "\\$"],
-[:verb, "[^<$]+"],
-]
-end
-let(:tokenizer) { L43Peg::Combinators.rgx_tokenize(regexen) }
-```
-
-Then we can tokenize some inputs
-```ruby
-input = "<red,bold>HELLO$and<<<green>$$<reset>"
-ast = [ 
-[:color_and_style, ["<red,bold>", "red", "bold"]],
-[:verb, "HELLO"],
-[:reset, "$"],
-[:verb, "and"],
-[:verb, "<"],
-[:color, "green"],
-[:verb, "$"],
-[:color, "reset"]
-]
-assert_parse_success(tokenizer, input, ast:)
-```
-
-### Context: Debugging
-
-As parsers are by design imbricated functions debugging is not always simple.
-Enter the `debug_parser`, a parser that _debugs_  parsers by not changing their behavior
-by displaying more or less detailed information
-
-Given a parser
-```ruby
-  include L43Peg::Combinators
-  let :args do
-    {
-      lat: "lat:(\\d+)",
-      long: "long:(\\d+)",
-    }
-  end
-  let(:geo_parser) {args_parser(args, &:to_i)}
-```
-
-#### Context: Minimum level of information
-
-Given a minum debug parser
-```ruby
-  let(:debugger) {debug_parser(geo_parser, level: :min)}
-```
-
-Then we will get some output
-```ruby
-    expected =
-        "Tokens<[\"lat:43\", \"long:2\"]>\nSuccess: @1\n"
-    expect { parsed_success(debugger, ["lat:43", "long:2"]) }
-        .to output(expected).to_stderr
-```
-
-#### Context: Default level of information
-Given a default debug parser
-```ruby
-    let(:debugger) {debug_parser(char_parser("a"))}
-```
-
-Then we will get some output on errors
-```ruby
-    expected ="Input<\"b\"@1:1>\nFailure: char \"b\" @[1, 1]\n"
-    expect { parsed_failure(debugger, "b") }
-        .to output(expected).to_stderr
-```
-
-#### Context: Maximum level of information
-Given a maxium level parser
-```ruby
-    let(:max_debugger) { debug_parser(char_parser("b"), level: :max) }
-```
-
-Then we will get this output on errors
-```ruby
-expected = 
-    [ 
-      "================================================================================",
-      'Input<col:1 input:"bc" lnb:1 context:{}>',
-      "================================================================================",
-      'Success<ast:"b" cache:{} rest:"c">',
-      "================================================================================",
-      ""
-    ].join("\n")
-
-    expect { parsed_success(max_debugger,"bc") }
-      .to output(expected).to_stderr
-```
+### Combinators... [^](#table-of-contents)
 
+... which are the working horses of any PEG library
+are described [here](speculations/combinators.md)
 
-# Author
+# Author [^](#table-of-contents)
 
-  Copyright © 2024 Robert Dober
+  Copyright © 202[4,5,6] Robert Dober
   robert.dober@gmail.com
 
-# LICENSE
+# LICENSE [^](#table-of-contents)
 
   GNU AFFERO GENERAL PUBLIC LICENSE, Version 3, 19 November 2007. Please refer to [LICENSE](LICENSE) for details.
 

data/lib/l43_peg/box.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module L43Peg
+
+  module Box
+    attr_reader :value
+
+    def self.make(class_name)
+      klass = Object.const_get(class_name) if Object.const_defined?(class_name)
+      raise NotABox, "#{class_name} is already defined but not a Box!" if klass && !(klass < self)
+      klass = Object.const_set(class_name, Class.new.include(self)) unless klass
+      klass
+    end
+
+    def deconstruct_keys(*) = {class: self, value:}
+
+    private
+    def initialize(value, &blk) 
+      @value = blk ? blk.(value) : value
+    end
+  end
+
+
+  module BoxFactory extend self
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/boxed.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Boxed extend self
+      def boxed(parser, box, name: nil, &mapper)
+        name ||= "boxed(#parser.name})"
+        Combinators.map(parser, name:) { |ast|
+          ast = mapper.(ast) if mapper
+          Mappers.box(box, ast)
+        }
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/choice.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Choice extend self
+      def choice(*parsers, name:)
+        name ||= "option(#{parsers.flatten.map(&:name).join(", ")})"
+        parser = Parser.new(name) {|input, _name=nil| _choice(input:, name:, parsers: parsers.flatten)}
+      end
+
+      private
+      def _choice(input:, name:, parsers:)
+        # **N.B.** Cache lookup would be great here to see if some
+        #          parsers have already failed on this input
+        parsers.each do |parser|
+          result = parser.(input)
+          case result
+          in L43Peg::Success => success
+            return success
+          else
+          end
+        end
+        
+        L43Peg::Failure.new(parsed_by: name, reason: "no choice matched", name:)
+      end
+      
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/debug_parser.rb

@@ -7,11 +7,11 @@ module L43Peg
       DEFAULT_LEVEL = 5
       MAX_LEVEL = 10
 
-      def parse_with_debug(parser:, name:, level:)
+      def debug_parser(parser:, name:, level:)
         level = _normalize_level(level)
-        -> (input, cache, name1=nil) do
-          _report_input(input, cache:, level:, name: name1||name)
-          case parser.(input, cache:)
+        Parser.new(name:) do |input, name1=nil|
+          _report_input(input, level:, name: name1||name)
+          case parser.(input)
           in Success => success
             _report_success(success, name: name1||name, level:)
           in Failure => failure
@@ -49,7 +49,7 @@ module L43Peg
         failure
       end
 
-      def _report_input(input, cache:, name:, level:)
+      def _report_input(input, name:, level:)
         _hl(level:)
         _prt(input.debug, level:, needed: MAX_LEVEL) ||
           _prt(input.head_hr(20, position: true), level:, needed: DEFAULT_LEVEL) ||

data/lib/l43_peg/combinators/ignore.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Ignore extend self
+      def ignore(parser, name: nil)
+        Combinators.map(parser, name: name || "ignore(#{parser.name})") { nil }
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/lazy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Lazy extend self
+      def lazy(name: nil, &parser)
+        name ||= "lazy()"
+          Parser.new(name, &lazy_parse_fn(parser))
+      end
+
+      private
+      def lazy_parse_fn(parser)
+        -> input do
+          parser.().(input)
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/many.rb

@@ -1,43 +1,48 @@
 # frozen_string_literal: true
 
-require_relative "../helper"
 module L43Peg
   module Combinators
     module Many extend self
+      def many(parser, name: nil, min: 0, max: nil)
+        name ||= "many(#{parser.name}, min: #{min}, max: #{max})"
+          Parser.new(name) { many_parse_fn(input: it, parser:, name:, min:, max:) }
+      end
 
-      include L43Peg::Helper
-      def many(input:, cache:, name:, parser:, min:, max:)
+      private
+      def many_parse_fn(input:, name:, parser:, min:, max:)
         curr_input = input
-        curr_cache = cache
         count = 0
         ast   = []
+        parsed = String.new
 
         loop do
           if max && count == max
-            return succeed_parser(ast, curr_input, cache: curr_cache)
+            return L43Peg::Success.new(ast:, rest: curr_input, parsed:)
           end
-          case parser.(curr_input, cache: curr_cache)
-          in L43Peg::Success => success
-            ast.push(success.ast)
-            curr_input = success.rest
-            curr_cache = success.cache
-            count += 1
+
+          case parser.(curr_input)
           in L43Peg::Failure
-            if count < min
-              return fail_parser("many #{name} should match at least #{min} times but did only #{count} times", input:)
-            end
-            return succeed_parser(ast, curr_input, cache: curr_cache)
-          in L43Peg::Stop
-            if count < min
-              return fail_parser("many #{name} should match at least #{min} times but did only #{count} times", input:)
+            if count <  min
+              return L43Peg::Failure.new(
+                reason: "many #{name} should match at least #{min} times but did only #{count} times", name:)
+            else
+              return L43Peg::Success.new(ast:, rest: curr_input, parsed:)
             end
-            return succeed_parser(ast, curr_input.drop, cache: curr_cache)
+          in {ast: new_ast, parsed: new_parsed, rest: curr_input}
+            ast.push(new_ast)
+            parsed << new_parsed
+            count += 1
+            # in L43Peg::Stop
+            #   if count < min
+            #     return fail_parser("many #{name} should match at least #{min} times but did only #{count} times", input:)
+            #   end
+            #   return succeed_parser(ast:, rest: curr_input.drop, parsed:) 
+          in bad_result
+            Errors.bad_result(bad_result.inspect)
           end
         end
       end
-
     end
   end
 end
-
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/map.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Map extend self
+      def map(parser, name: nil, fn: nil, box: nil, &mapper)
+        raise ArgumentError, "must not provide keyword parameter fn and a block" if fn && mapper
+        mapper = fn || mapper
+        raise ArgumentError, "must provide one of the keyword parameters [fn:, box:] or a block" unless mapper || box
+        mapper ||= :itself
+        Parser.new(name || "map(#{parser.name})") {|input, name=nil| _map(input:, name:, parser:, box:, mapper:)}
+      end
+
+      private
+      def _map(box:, input:, name:, parser:, mapper:)
+        case parser.(input)
+        in L43Peg::Failure => failure
+          failure.update(name:)
+        in L43Peg::Success => success
+          success.map(box:, &mapper)
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/map_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module MapError extend self
+      def map_error(parser, name: nil, reason: nil)
+        name ||= "map_error(#{parser.name}"
+                            Parser.new(name) { _map_error(input: it, parser:, name:, reason:) }
+      end
+
+      private
+      def _map_error(input:, parser:, name:, reason:)
+        case parser.(input)
+        in Failure => failure
+          failure.map(name:, reason:)
+        in success
+          success
+        end
+      end
+
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/l43_peg/combinators/satisfy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module L43Peg
+  module Combinators
+    module Satisfy extend self
+      def satisfy(parser, name: nil, fn: nil, &satisfier)
+        raise ArgumentError, "must not provide keyword parameter fn and a block" if fn && satisfier
+        satisfier = fn || satisfier
+        raise ArgumentError, "must provide one the keyword parameter fn: or a block" unless satisfier
+        name ||= "satisfy(#{parser.name})"
+
+        Parser.new(name) {|input, name=nil| _satisfy(input:, name:, parser:, satisfier:)}
+      end
+
+      private
+
+      def _satisfy(input:, name:, parser:, satisfier:)
+        case parser.(input)
+        in Success => success
+          if satisfier.(success.ast)
+            success
+          else
+            L43Peg::Failure.new(
+              parsed_by: self, 
+              reason: "satisfier failed on ast: #{success.ast.inspect}",
+              name:)
+          end
+        in failure
+          failure
+        end
+      end
+
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later