oo_peg 0.1.0

data/lib/oo_peg/parser/combinators.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+require_relative '../../enumerable'
+require_relative 'combinators/lazy'
+module OOPeg
+  class Parser
+    class InfiniteLoop < Exception; end
+
+    ##
+    #
+    # === The raison d'être of a PEG Parser are in fact the combinators
+    #
+    # So, without further ado...
+    #
+    # ==== +many+
+    #
+    # If a parser +p+ parses a string, the parser +p.many+ parses, well
+    # many occurrences of such strings concatenated.
+    #
+    # *N.B.* By default +many+ parses the empty input (0 occurrences)
+    # and can therefore _never_ _fail_!
+    # but we can force a minimum of occurrences.
+    #
+    # As indicated below, +many+ returns a list of all  parsed occurrences.
+    #
+    #     # example: many, the combinator for lists
+    #
+    #     vowel_parser = char_parser('aeiouy').many
+    #
+    #     parse(vowel_parser, "").ast => []
+    #     parse(vowel_parser, "ae").ast => %w[a e]
+    #
+    # And we can force a minimum of occurrences
+    #
+    #     # example: manyer, more than many
+    #
+    #     two_chars = char_parser.many(min: 2)
+    #
+    #     parse(two_chars, 'ab').ast => %w[a b]
+    #     parse(two_chars, 'a').error => '"many(char_parser(TrueSet))" did not succeed the required 2 times, but only 1'
+    #
+    #     # We can see that the error message lacks some context, let's try again
+    #
+    #     named = char_parser.many(min: 2, name: '2 chars')
+    #     parse(named, '').error => '"2 chars" did not succeed the required 2 times, but only 0'
+    #
+    # It is very frequently not an array of parsed strings, that we want, but the whole string, enter the
+    #
+    # ==== +joined+ combinator
+    #
+    #     # example: joining together
+    #
+    #     all_parser = char_parser.many.joined
+    #
+    #     parse(all_parser, "some text").ast => "some text"
+    #
+    # ==== +map+ modify the result's ast
+    #
+    # In the above example we have seen, that the +map+ combinator returns a list, oftentimes we want the
+    # parsed string to be returned...
+    #
+    # Enter +map+
+    #
+    #     # example: mapping a list back to a string
+    #
+    #     vowel_string_parser = char_parser('aeiouy').many.map(&:join)
+    #     parse(vowel_string_parser, "yo").ast => "yo"
+    #
+    # ===== Tagging, a special form of map
+    #
+    # +tagged(tag)+ is a short, convenience method for <tt>map { [tag, it] }</tt>
+    #
+    #     # example: tagging a result
+    #
+    #     tagged_char_parser = char_parser.tagged(:char)
+    #
+    #     parse(tagged_char_parser, 'q').ast => [:char, 'q']
+    #
+    #
+    # ==== +maybe+ (oftentimes called +option+ in other PEG Parsers)
+    #
+    # If a parser +p+ parses a string, the parser +p.maybe+ parses, well
+    # 0 or 1 occurrences of such a string.
+    #
+    # *N.B.* +maybe+ parses the empty input (0 occurrences)
+    # and can therefore _never_ _fail_!
+    # 
+    # We could also implement maybe with map as follows, but there
+    # is a subtle difference between <tt>[], "", nil</tt> to be observed.
+    #
+    #     # example: map and maybe
+    #
+    #     optional_char = char_parser.many(max: 1).map(&:join)
+    #     maybe_char   = char_parser.maybe
+    #
+    #     parse(optional_char, "abc").ast => "a"
+    #     parse(optional_char, "").ast => ""
+    #
+    #     parse(maybe_char, "abc").ast => "a"
+    #     parse(maybe_char, "").ast => nil 
+    #
+    # ==== +or+ (oftentimes called +select+ in other PEG Parsers)
+    #
+    # Can be an instance method
+    #
+    #     # example: or as an instance method
+    #
+    #     # yet another implementation of maybe :P
+    #
+    #     maybe_parser = char_parser('a').or(char_parser('b'), true_parser)
+    #
+    #     parse(maybe_parser, 'a').ast => 'a'
+    #     parse(maybe_parser, 'b').ast => 'b'
+    #     parse(maybe_parser, 'c').ast => nil 
+    #     parse(maybe_parser, 'c') is! ok
+    #
+    # Can be a class method
+    #
+    #     # example: or as a class method
+    #
+    #     int_or_number_parser = OOPeg::Parser.or(int_parser, set_parser('one', 'two'))
+    #
+    #     parse(int_or_number_parser, '12').ast => 12
+    #     parse(int_or_number_parser, 'one').ast => 'one'
+    #     parse(int_or_number_parser, 'two').ast => 'two'
+    #
+    #     parse(int_or_number_parser, 'three') not! ok
+    #
+    # ==== +and+ (oftentimes called +sequence+ in other PEG Parsers)
+    #
+    # Can be an instance method
+    #
+    #     # example: and as an instance method
+    #
+    #     # yet another implementation of set_parser("abc")
+    #
+    #     abc_parser = char_parser('a').and(char_parser('b'), char_parser('c'))
+    #
+    #     parse(abc_parser, 'abc').ast => %w[a b c] 
+    #     parse(abc_parser, 'bca') not! ok
+    #
+    # Can be a class method
+    #
+    #     # example: and as a class method
+    #
+    #     abc_parser = OOPeg::Parser.and(char_parser('a'), char_parser('b'), char_parser('c'))
+    #
+    #     parse(abc_parser, 'abc').ast => %w[a b c] 
+    #     parse(abc_parser, 'bca') not! ok
+    #
+    # Sometimes we do not want some parsed text in our AST, therefore the +.and+ combinator
+    # _ignores_ +nil+ ASTs.
+    #
+    #     # example: ignore a sign (at your own peril of course)
+    #
+    #     parser = OOPeg::Parser.and( char_parser('+').map {nil}, char_class_parser(:digit).many.joined )
+    #
+    #     parse(parser, "+42").ast => ['42'] 
+    #
+    # As it is a little bit cumbersome to write <tt>map { nil }</tt> we made a more idiomatic way to
+    # express this behavior:
+    #
+    # ==== +ignore+
+    #
+    #     # example: a better way of ignorance
+    #
+    #     parser = OOPeg::Parser.and( char_parser('+').ignore, char_class_parser(:digit).many.joined )
+    #
+    #     parse(parser, "+42").ast => ['42'] 
+    #
+    #
+    # ==== +satifsfy+ can fail a successful result does not touch failing results
+    #
+    # This, e.g. is used in the +kwd_parser+ or +set_parser+
+    #
+    #     # example: an odd parser
+    #
+    #     odd_parser = int_parser.satisfy(name: "oddy", &:odd?)
+    #
+    #     parse(odd_parser, '11').ast => 11
+    #     parse(odd_parser, '10') not! ok
+    #
+    #     parse(odd_parser, '10').error => 'oddy failed'
+    #
+    # **N.B.** it can also modify the result
+    #
+    #     even_parser = int_parser.satisfy { |n|
+    #       n.even? ? [:ok, n/2] : [:error, "#{n}'s odd"]
+    #     }
+    #
+    #     parse(even_parser, '84').ast => 42
+    #
+    #     parse(even_parser, '73').error => "73's odd"
+    #
+    # ==== Change result for succeeding *and* failing parsers: +map_or_rename+
+    #
+    # This allows us to modify the name or error message in case of failure *and* still
+    # transforming the ast if a block is given.
+    #
+    #     # example: A better odd parser?
+    #
+    #     better = int_parser.satisfy(&:odd?).map_or_rename(error: "Oh no", &:succ)
+    #
+    #     parse(better, '11').ast => 12
+    #     parse(better, '12').error => "Oh no"
+    #
+    #     # example: No need to provide a block
+    #
+    #     parse(char_parser.map_or_rename(name: "My Parser"), '') not! ok
+    #
+    # ==== Lookahead, an important concept...
+    #
+    # We can just check on the future \\o/
+    #
+    #     # example: Look ahead, do not advance
+    #
+    #     result = parse(int_parser.lookahead, '42')
+    #
+    #     result.ast is! nil
+    #     result is! ok
+    #     result.input.pos => 1
+    #     result.input.content => %w[4 2] 
+    #
+    #     # example: Look ahead, be disappointed
+    #
+    #     parse(int_parser.lookahead, 'alpha') not! ok
+    #
+    # === What About Recursive Parsers?
+    #
+    # Let us assume that we want to parse a language that is recursive, how can we create
+    # a recursive parser that does not loop up to a stack overflow?
+    #
+    # Here is a toy example to introduce the concept (but it will come in very handy later
+    # in our advanced OOPeg::Parsers::Advanced::SexpParser .
+    #
+    # ==== A parser for the language <tt>a^n • b^n</tt>, the naïve way.
+    #
+    #
+    #     # example: Look Ma' a stack overflow
+    #
+    #     $ab_count = 0
+    #     def ab_parser
+    #       $ab_count += 1
+    #       return true_parser if $ab_count == 1_000
+    #       char_parser('a').and(ab_parser, char_parser('b')).or(true_parser)
+    #     end
+    #
+    #     parse(ab_parser, 'aabb')
+    #
+    #     $ab_count => 1_000
+    #
+    # This problem can be solved by delaying the recursively called parser, which is done,
+    # with the aptly named:
+    #
+    # ==== +delay+ combinator
+    #
+    #     # example: Look Ma' it's working now
+    #
+    #     $ab_count = 0
+    #     def ab_parser
+    #       $ab_count += 1
+    #       return true_parser if $ab_count == 1_000
+    #       char_parser('a').and(delay {ab_parser}, char_parser('b')).joined.or(true_parser)
+    #     end
+    #
+    #     parse(ab_parser, 'aabb').ast => "aabb" 
+    #
+    #     $ab_count => 3 
+    #
+    module Combinators
+
+      private
+      def _debug(parser, name: nil)
+        Parser.new(parser.name) do |input|
+          puts "debugging #{name || parser.name}: #{input.inspect}"
+          result = Parser.parse(parser, input)
+          puts "debugging #{name || parser.name}: #{result}"
+          result
+        end
+      end
+
+      def _lookahead(parsers, name:)
+        parser = _select(parsers)
+        Parser.new(name || "lookahead(#{parser.name})") do |input, name|
+          case Parser.parse(parser, input)
+          in {ok: true}
+            {ok: true, ast: nil, input:}
+          in error
+            error
+          end
+        end
+      end
+
+      def _map(parser:, name:, &mapper)
+        raise ArgumentError, "missing mapper function" unless mapper
+
+        name ||= "map(#{parser.name})"
+        Parser.new(name) do |input|
+          result = Parser.parse(parser, input)
+          # require "debug"; binding.break
+          result.map(&mapper)
+          # require "debug"; binding.break
+          # case result
+          # in {ok: true, input: rest, ast:}
+          #   Result.ok(ast: mapper.(ast), input: rest)
+          # in {error:}
+          #   Result.nok(error:, input:, parser_name: name)
+          # end
+        end
+      end
+
+      def _many(parser, max:, min:, name:)
+        name ||= "many(#{parser.name})"
+        Parser.new(name) do |input|
+          total_ast = []
+          original_input = input
+          current_input = input
+          match_count = 0
+          loop do
+            if current_input.empty?
+              break Result.ok(ast: total_ast, input:) if match_count >= min
+              break Result.nok(
+                error: "#{name.inspect} did not succeed the required #{min} times, but only #{match_count}",
+                input: original_input,
+                parser_name: name)
+            end
+
+            case Parser.parse(parser, current_input)
+            in {ok: true, ast:, input:}
+              raise InfiniteLoop, "must not parse zero width inside many in parser: #{parser.name}" if input.pos == current_input.pos
+              current_input = input
+              total_ast = [*total_ast, ast]
+              match_count += 1
+              break Result.ok(ast: total_ast, input:) if max && match_count >= max
+            in _
+              break Result.ok(ast: total_ast, input:) if match_count >= min
+              break Result.nok(
+                error: "many #{name} did not succeed the required #{min} times, but only #{match_count}",
+                input: original_input,
+                parser_name: name)
+            end
+          end
+        end
+      end
+
+      def _map_or_rename(parser:, name: nil, error: nil, &mapper)
+        parser_name = name || parser.name
+        Parser.new(name) do |input|
+          result = Parser.parse(parser, input)
+          case result
+          in {ok: true, ast:}
+            mapper ? result.merge(ast: mapper.(ast)) : result
+          in _
+            result.merge(parser_name:, error:)
+          end
+        end
+      end
+
+      def _map_result(parser, name, mapper)
+        Parser.new(name) do |input, name|
+          result = Parser.parse(parser, input)
+          # require "debug"; binding.break
+          mapper.(result)
+        end
+      end
+
+      def _maybe(parser:, name: nil, replace_with: nil)
+        Parser.new(name || "maybe(#{parser.name})") do |input, name|
+          case Parser.parse(parser, input)
+          in {ok: false}
+            Result.ok(ast: replace_with, input:)
+          in success
+            success
+          end
+        end
+      end
+
+      def _satisfy(parser, name:, &satisfier)
+        name ||= "satisfy(#{parser.name})"
+
+        Parser.new(name) do |input|
+          original_input = input
+          case Parser.parse(parser, input)
+          in {ok: false} => error
+            error
+          in {ok: true, ast:, input:} => result
+            case satisfier.(ast)
+            in true
+              result
+            in [:ok, ast]
+              Result.ok(ast:, input:)
+            in [:error, error]
+              Result.nok(input: original_input, error:, parser_name: name)
+            in _
+              Result.nok(input: original_input, error: "#{name} failed", parser_name: name)
+            end
+          end
+        end
+      end
+
+      def _select(*parsers, name: nil)
+        parsers = parsers.flatten
+        name ||= "select(#{parsers.map(&:name).join(",")})"
+        raise ArgumentError, "all parsers must be instances of Parser" unless parsers.all? { Parser === it }
+        Parser.new(name || "select #{parsers.map(&:name).join(", ")}") do |input, name|
+          result = Result.nok(error: "No parser matched in select named #{name}", input:, parser_name: name)
+          parsers.each do |parser|
+            # case p(Parser.parse(parser, input))
+            this_result = Parser.parse(parser, input)
+            # require "debug"; binding.break
+            case this_result
+            in {ok: true} => result
+              break result
+            in _
+              nil
+            end
+          end
+          result
+        end
+      end
+
+      def _sequence(*parsers, name:)
+        parsers = parsers.flatten
+        raise ArgumentError, "all parsers must be instances of Parser" unless parsers.all? { Parser === it }
+        name ||= "seq(#{parsers.map(&:name).join(", ")})"
+        Parser.new(name) do |input|
+          original_input = input
+          result = parsers.reduce_while [input, []] do |(input, ast), parser|
+            # require "debug"; binding.break
+            parsed = Parser.parse(parser, input)
+            # p parsed
+            case parsed
+            in {ok: true, ast: nil, input:}
+              cont_reduce([input, ast])
+            in {ok: true, ast: ast_node, input:}
+              cont_reduce([input, [*ast, ast_node]])
+            in {ok: false, error:}
+              halt_reduce(Result.nok(input: original_input, error:, parser_name: name))
+            end
+          end
+
+          case result
+          in {ok: false} => error
+            result
+          in [input, ast]
+            Result.ok(ast:, input:)
+          end
+        end
+      end
+
+      def _tagged(tag, parser:, name:)
+        name ||= "tagged(#{parser.name} with #{tag.inspect})"
+        _map(parser:, name:) { [tag, it] }
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/parser.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'parser/class_methods'
+require_relative 'parser/combinators'
+require_relative 'input'
+require_relative 'parsers'
+require_relative 'result'
+
+module OOPeg
+  ##
+  # 
+  # This class represents a, well, parser
+  #
+  # It exposes a class method +parse+ which takes an input or a string (making it to
+  # an instance of +OOPeg::Input+ if necessary) and returns a +OOPeg::Result+
+  #
+  # It also exposes an homonymous instance method which *must* be called with an
+  # instance of +OOPeg::Input+
+  #
+  #     # example: the parse methods
+  #     
+  #     expect(OOPeg::Parser.parse(end_parser, "")).to be_a OOPeg::Result
+  #
+  #     # but for efficeny there is no check or conversion in the instance
+  #     # method
+  #
+  #     expect { end_parser.parse("") }
+  #       .to raise_error(NoMethodError, "undefined method 'content' for an instance of String")
+  #
+  class Parser
+    include Combinators
+    extend Combinators::Lazy
+    extend ClassMethods
+
+    attr_reader :name
+
+
+    def parse(input) = @parse_fn.(input)
+
+    # Combinators
+    #
+    def and(*parsers, name: nil) = _sequence([self, *parsers], name:)
+
+    def debug(name: nil) = _debug(self, name:)
+
+    def ignore = self.map { nil }
+
+    def joined(joiner: "") = self.map { |ast| ast.join(joiner) }
+
+    def lookahead(name: nil) = _lookahead(self, name:)
+
+    def many(name: nil, max: nil, min: 0) = _many(self, name:, max:, min:)
+    def map(name: nil, &blk) = _map(parser: self, name:, &blk)
+    def map_or_rename(name: nil, error: nil, &blk) = _map_or_rename(parser: self, name:, error:, &blk)
+    def maybe(name: nil, replace_with: nil) = _maybe(parser: self, name:, replace_with:)
+
+    def or(*parsers, name: nil) = _select(self, *parsers, name:)
+
+    def satisfy(name: nil, &satisfier) = _satisfy(self, name:, &satisfier)
+
+    def tagged(tag, name: nil) = _tagged(tag, parser: self, name:)
+
+    private
+    def initialize(name, &blk)
+      raise ArgumentError, "blk must be provided as a parse function" unless blk
+      @name = name
+      @parse_fn = blk
+    end
+    
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/parsers/advanced/operator_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OOPeg
+  module Parsers
+    module Advanced
+      module OperatorParser extend self
+        include OOPeg::Parsers
+
+        DEFAULT_OP_CHARS = "><+-*/=:.&|^~!"
+
+        def make(allowed: nil, min: 1, max: 3, name: nil)
+          allowed ||= DEFAULT_OP_CHARS
+          name ||= "OperatorParser"
+          char_parser(allowed)
+            .many(min:, max:, name:)
+            .joined(&:to_sym)
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/parsers/advanced/sexp_parser.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module OOPeg
+  module Parsers
+    module Advanced
+      module SexpParser extend self
+        include OOPeg::Parsers
+        include Advanced
+
+        def make(
+          parens: [:sexp, %w[( )], :map, %w[{ }], :arr, %w[[ ]]],
+          head_parser: nil,
+          tail_parser: nil,
+          sep_parser: ws_parser,
+          name: nil)
+
+          name ||= "SexpParser"
+          tail_parser ||= _default_tail_parser
+          head_parser ||= tail_parser
+
+          ws_parser(min: 0)
+            .and(
+          Parser.or(
+            parens
+            .each_slice(2)
+            .map(&_sexp_parser(head_parser:, tail_parser:, sep_parser:))
+          )).map(&:first)
+        end
+
+        private
+        def _default_tail_parser
+          Parser.or(
+            id_parser.tagged(:id),
+            int_parser.tagged(:int),
+            string_parser.tagged(:str),
+            symbol_parser.tagged(:sym),
+            operator_parser.tagged(:op),
+            delay {sexp_parser}
+          )
+        end
+
+        def _head_and_tail
+          -> ast do
+            ast => [h, t]
+            [h, *t]
+          end
+        end
+
+        def _inner_parser(head_parser:, tail_parser:, sep_parser:)
+          Parser.and(
+            head_parser,
+            sep_parser.and(tail_parser).many.map { it.map(&:first) },
+            name: 'inner s-exp parser'
+          )
+            .map(&_head_and_tail)
+            .maybe(replace_with: [])
+        end
+
+        def _sexp_parser(head_parser:, tail_parser:, sep_parser:)
+          -> parens do
+            parens => [tag, parsers]
+            parsers.map { char_parser(it).ignore } => [open, close]
+
+            Parser.and(
+              open.and(ws_parser(min: 0)).ignore,
+              _inner_parser(head_parser:, tail_parser:, sep_parser:)
+              .tagged(tag),
+            ws_parser(min: 0).and(close).ignore
+            ) 
+            # .debug
+          end
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/parsers/advanced/string_parser.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OOPeg
+  module Parsers
+    module Advanced
+      module StringParser extend self
+        include OOPeg::Parsers
+
+        def make(delim: %{'"}, doubled_escape: nil, extra_parser: nil, escape_with: "\\", name: "StringParser")
+          parser =
+          Parser.or(
+            delim.grapheme_clusters.map { |quote| make_delim_parser(quote, doubled_escape:, extra_parser:, escape_with:) }
+          )
+          parser.map_or_rename(error: "Missing closing delimiter", name:) { |ast| ast[1].join }
+        end
+
+        private
+
+        def make_delim_parser(delim, doubled_escape:, extra_parser:, escape_with:)
+              char_parser(delim)
+                .and(
+                  inner_parser(delim, doubled_escape:, extra_parser:, escape_with:),
+                  char_parser(delim)
+                )
+        end
+
+        def inner_parser(delim, doubled_escape:, extra_parser:, escape_with:)
+          parsers = [
+            (doubled_escape && word_parser(delim + delim).map { delim }),
+            word_parser(escape_with + delim).map { delim },
+            word_parser(escape_with + escape_with).map { escape_with },
+            char_parser(delim, negate: true)
+          ].compact
+          Parser.or(parsers).many
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/parsers/advanced/symbol_parser.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OOPeg
+  module Parsers
+    module Advanced
+      module SymbolParser extend self
+        include OOPeg::Parsers
+
+        def make(prefix: %{:}, inner_class: [:alnum, '_'], lead_class: :alpha, name: nil)
+          name ||= "SymbolParser"
+          Parser
+            .and(
+              char_parser(prefix).ignore,
+              id_parser(inner_class:, lead_class:, name:)
+            )
+            .map { it.first.to_sym }
+        end
+      end
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later