l43_peg 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fd34fe9a8f6cc7dbcd31983b498f89d08b5a8cbb2ead84f279bfa1fdc97af2e
-  data.tar.gz: 8ec2a0361e0a254e484648260d6835971a3c210b454bd30be5dc060e8a77518b
+  metadata.gz: e5b92019011d80442cfe66f4b3a841a31bba54547efd479a2d19b1f7e687adef
+  data.tar.gz: 75cb9467e13dc72e773bebe345b68b05d431bdbfc6671c7bc215bd063a86cd6c
 SHA512:
-  metadata.gz: dbe9a870df4681c29c1fc65b173e831a31efbf15af88ebd3fa2b6003c8c7ac4321eb509b2b737f58051919669465a063c044e5cde187fb18c0de8af506d4a048
-  data.tar.gz: 28f2eb73223629254c8329799d90abf012d18c67c1ab5ff9627a1b2cf55fd75a92e98b402ac6438ea398fc88f61f328429727066446ff239ffdd5ed7d92cc042
+  metadata.gz: ab3a4841408511554c96725a7659d7b5928336d195323e06dd8c707f247d48f5e2b7d1831768e018de7fdcfbd3d2dfba0aa791d10b1ab422fb08f8b225797066
+  data.tar.gz: be59e8841fcc4e9f22194555fa40c8573805a589f119a728a216e256d729fcdd4ce4abaac76df0547a109415b83208e333fc209ef00bb9e46fcd03ec3dafbd85

data/README.md

@@ -1,5 +1,7 @@
 # L43Peg
 
+[![Gem Version](https://badge.fury.io/rb/l43_peg.svg)](https://badge.fury.io/rb/l43_peg)
+
 ## 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.
@@ -68,11 +70,80 @@ When we map the parser
 Then we can convert the string valus
 
 ```ruby
-    assert_parse_success(parser, %w[--start=42 --end=44 --inc=2], ast: {start: 42, end: 44, inc: 2}, rest: [])
+    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)}
+```
+
+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`
+```ruby
+   let :parser do
+     L43Peg::Parsers.args_parser(
+       {
+          negative: "(-\\d+)",
+          positive: "\\+?(\\d+)"
+       },
+       &:to_i
+     )
+   end
+```
+
+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`
+
+```ruby
+   L43Peg.parse_tokens(parser, %w[43 -44 +45]) => :ok, result
+   expect(result).to eq(positive: [43, 45], negative: -44)
+```
+
+And if we get an error the result is as follows
+
+```ruby
+   parser = L43Peg::Parsers.char_parser('a') 
+   L43Peg.parse_string(parser, 'b') => :error, message
+   expect(message).to eq("char \"b\"")
 ```
 
 
-## Author
+# Author
 
 Copyright © 2024 Robert Dober
 robert.dober@gmail.com

data/lib/l43_peg/combinators/many.rb

@@ -24,9 +24,14 @@ module L43Peg
             count += 1
           in L43Peg::Failure
             if count < min
-              return fail_parser("many #{name} should match at least #{min} times but did only #{count} times")
+              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:)
+            end
+            return succeed_parser(ast, curr_input.drop, cache: curr_cache)
           end
         end
       end

data/lib/l43_peg/combinators.rb

@@ -13,8 +13,8 @@ module L43Peg
     include L43Peg::Mappers
     include L43Peg::Parsers
 
-    def args_parser(definitions, name: nil, &block)
-      parser = tokens_parser(definitions, &block)
+    def args_parser(definitions, name: nil, stop: nil, &block)
+      parser = tokens_parser(definitions, stop:, &block)
       name   = name || "args_parser(#{definitions.inspect})"
       inner  = many(parser)
       map(inner, name:, fn: join_maps)

data/lib/l43_peg/helper.rb

@@ -2,8 +2,8 @@
 
 module L43Peg
   module Helper
-    def fail_parser(reason)
-      L43Peg::Failure.new(reason:)
+    def fail_parser(reason, input: nil)
+      L43Peg::Failure.new(reason:, input:)
     end
     def succeed_parser(ast, input, cache: nil)
       L43Peg::Success.new(ast:, rest: input, cache: cache || input.cache)

data/lib/l43_peg/parsers/tokens_parser.rb

@@ -6,13 +6,13 @@ module L43Peg
 
       private
 
-      def initialize(map, name: nil, &blk)
+      def initialize(map, name: nil, stop: nil, &blk)
         map = _check_arg!(map)
         name = name || "tokens_parser(#{map.inspect})"
         super(name) do |tokens, cache, _name|
           case _find_matching(map, tokens)
           in [token, success]
-            _succeed(tokens:, token:, success:, &blk)
+            _succeed(tokens:, token:, stop:, success:, &blk)
           else
             reason = "no token matches (in #{name})"
             L43Peg::Failure.new(cache:, input: tokens, parsed_by: self, reason:)
@@ -47,7 +47,9 @@ module L43Peg
         end.to_h
       end
 
-      def _succeed(success:, token:, tokens:, &blk)
+      def _succeed(stop:, success:, token:, tokens:, &blk)
+        return L43Peg::Stop.new if token == stop
+
         result = if blk
                    blk.(success.ast)
                  else

data/lib/l43_peg/parsers.rb

@@ -5,14 +5,16 @@ require_subdir {}
 
 module L43Peg
   module Parsers extend self
-    def args_parser(args, name: nil)      = L43Peg::Parsers::ArgsParser.new(args, name:)
+    def args_parser(args, name: nil, stop: nil, &blk) =
+      L43Peg::Combinators.args_parser(args, name:, stop:, &blk)
     def char_parser(charset = nil)        = L43Peg::Parsers::CharParser.new(charset)
     def end_parser                        = L43Peg::Parsers::EndParser.instance
     def failure_parser                    = L43Peg::Parsers::FailureParser.instance
     def int_parser                        = L43Peg::Parsers::IntParser.instance
     def rgx_parser(rgx, name: nil, **o)   = L43Peg::Parsers::RgxParser.new(rgx, name:, **o)
     def token_parser(spc, name: nil, **o) = L43Peg::Parsers::TokenParser.new(spc, name:, **o)
-    def tokens_parser(map, name: nil, &b) = L43Peg::Parsers::TokensParser.new(map, name:, &b)
+    def tokens_parser(map, name: nil, stop: nil, &b) = 
+      L43Peg::Parsers::TokensParser.new(map, name:, stop:, &b)
     def verb_parser(verb, name: nil)      = L43Peg::Parsers::VerbParser.new(verb, name:)
   end
 end

data/lib/l43_peg/stop.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module L43Peg
+  class Stop
+    extend L43::OpenObject
+    attributes
+    # A placeholder to halt many
+  end
+end
+# SPDX-License-Identifier: Apache-2.0

data/lib/l43_peg.rb

@@ -4,7 +4,28 @@ require_relative 'l43/require_helper'
 require_relative 'l43/open_object'
 require_subdir {}
 
-module L43Peg
-  VERSION = "0.1.4"
+module L43Peg extend self
+  VERSION = "0.1.6"
+
+  def parse_string(parser, input, lnb: 1, col: 1, context: {})
+    input = Input.new(input:, col:, lnb:, context:)
+    _parse(parser, input)
+  end
+
+  def parse_tokens(parser, tokens, tnb: 1, context: {})
+    tokens = Tokens.new(tokens:, tnb:, context:)
+    _parse(parser, tokens)
+  end
+
+  private
+
+  def _parse(parser, input)
+    case parser.(input)
+    in Success => success
+      [:ok, success.ast]
+    in Failure => failure
+      [:error, failure.reason]
+    end
+  end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: l43_peg
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Robert Dober
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-22 00:00:00.000000000 Z
+date: 2024-04-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   A (still incomplete) PEG Library
@@ -43,9 +43,10 @@ files:
 - lib/l43_peg/parsers/token_parser.rb
 - lib/l43_peg/parsers/tokens_parser.rb
 - lib/l43_peg/parsers/verb_parser.rb
+- lib/l43_peg/stop.rb
 - lib/l43_peg/success.rb
 - lib/l43_peg/tokens.rb
-homepage: https://gitlab.com/l43-gems/l43_peg
+homepage: https://codeberg.org/lab419/l43_peg
 licenses:
 - AGPL-3.0-or-later
 metadata: {}