oo_peg 0.1.0

data/lib/oo_peg/result.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module OOPeg
+  class Result
+    class IllegalState < RuntimeError
+    end
+
+    attr_reader :ast, :error, :input, :ok, :parser_name 
+
+    def self.ok(ast:, input:, parser_name: nil) = new(ok: true, ast:, input:, parser_name:) 
+
+    def self.nok(input:, error:, parser_name: nil) 
+      new(ok: false, input:, error:, parser_name:)
+    end
+
+    def deconstruct_keys(*, **) = to_h
+
+    def map(&blk)
+      return self unless ok
+      self.class.ok(ast: blk.(ast), input:)
+    end
+
+    def merge(ast: nil, error: nil, input: nil, parser_name: nil)
+      _check_valid_merge_params!(ast:, error:, input:)
+      @ast = ast if ast
+      @error = error if error
+      @input = input if input
+      @parser_name = parser_name if parser_name
+      self
+    end
+
+    def or(input:, error:, parser_name: nil) = self.class.nok(input:, error:, parser_name:)
+
+    # def reduce(values, &blk)
+    #   result = self
+    #   values.each do |ele|
+    #     result = blk.(result, ele)
+    #     break result unless result.ok
+    #   end
+    #   result
+    # end
+
+    def to_h =  {ast:, error:, input:, ok:, parser_name:}  
+
+    def to_s = inspect
+
+    # def update(&updater)
+    #   raise IllegalState, "must not update an error result" unless ok
+    #   map(&updater)
+    # end
+
+    # def update_or(input:, error:, parser_name: nil, &updater)
+    #   return map(&updater) if ok
+
+    #   self.class.nok(input:, error:, parser_name:)
+    # end
+
+    # def while(input: nil, error: nil, name: nil, &blk)
+    #   result = self
+    #   count = 0
+    #   loop do
+    #     return input ? self.class.nok(input:, error:, name:) : result unless result.ok
+    #     result = blk.(self, count)
+    #     count += 1
+    #   end
+    #   result
+    # end
+
+    private
+    def initialize(ok:, input:, ast: nil, error: nil, parser_name: nil)
+      @ast = ast
+      @error = error
+      @input = input
+      @ok = ok
+      @parser_name = parser_name
+    end
+
+    def _check_valid_merge_params!(ast:, error:, input:)
+      if ok
+        raise ArgumentError, "must not merge error upon ok result" if error
+      else
+        raise ArgumentError, "must not merge ast or input upon nok result" if ast || input
+      end
+      
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OOPeg
+  module Version
+    VERSION = "0.1.0"
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/oo_peg.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require_relative 'oo_peg/ostruct'
+require_relative 'oo_peg/parser'
+##
+# == OOPeg
+# A peg parser not using custom sytnax but exposing an OO based API
+#
+# === Usage
+#
+#     require 'oo_peg'
+#
+# Will be enough unless you need some advanced parsers which are provided by
+# this gem too.
+#
+# Than you can combine the available parsers and combinators which should be
+# enough to parse about any Context Free Language. However, later on we will
+# show how to enhance your base parsers if needed.
+#
+# All available _parsers_ are defined in +OOPeg::Parsers+ a module that you
+# can either include into your class/main or mixin.
+#
+# All available _combinators_ are class or instance methods of the +OOPeg::Parser+
+# class.
+#
+# As a matter of fact, to achieve the same behavior in your code as in these
+# +doc_rspecs+ (c.f. https://rubygems.org/gems/doc_rspec) you can use
+#
+#        include OOPeg::Parsers
+#        include OOPeg # for the main parse method
+#
+# === Quick Start Examples
+#
+# An integer parser is already provided, so let us show how to parse a list 
+# of integers
+#
+#     # example: Parsing A List Of Integers
+#
+#      input = "42, 43, 44"
+#      head_parser = int_parser
+#      tail_parser = char_parser(",").and(ws_parser, int_parser)
+#        .map(&:last).many
+#      parser = head_parser.and(tail_parser).and(end_parser).map(&:flatten)
+#
+#      result = parse(parser, input)
+#      result.ast => [42, 43, 44]
+#      result is! ok
+#
+# Now there is a lot going on here, so let us break down things a little bit
+#
+# ==== The Int Parser
+#
+#     # example: The Int Parser
+#
+#     parse(int_parser, "+0").ast => 0
+#     parse(int_parser, "-42").ast => -42
+#
+# ==== The Char And Whitespace parsers
+#
+#     # example: White Space
+#
+#     parse(ws_parser, " ").ast => nil
+#     parse(ws_parser, "   ").ast => nil
+#     parse(ws_parser, " ") is! ok
+#     expect(parse(ws_parser, "")).not_to be_ok
+#
+#     parse(char_parser(","), ",").ast => ","
+#     parse(char_parser(","), " ").ast => nil
+#     expect(parse(char_parser(",")," ")).not_to be_ok
+#
+# ==== The End Parser
+#
+#     # example: The End Parser
+#
+#     parse(end_parser, "") is! ok
+#     expect(parse(end_parser, " ")).not_to be_ok
+#     expect(parse(end_parser, "alpha")).not_to be_ok
+#     expect(parse(end_parser, "42")).not_to be_ok
+#
+# ==== Making Sequences with +.and+
+#
+#     # example: A sequence of two parsers
+#
+#     parser = char_parser(",").and(ws_parser)
+#
+#     # N.B.: nil results are not included into the result list
+#     parse(parser, ",  ").ast => [","]
+#
+#     # example: Assuring a sequence parses all input with the end_parser
+#
+#     parser = char_parser(",").and(ws_parser, end_parser)
+#
+#     parse(parser, ",  ").ast => [","]
+#     expect(parse(parser, ",  hello")).not_to be_ok
+#
+# ==== Combining the sequence with many
+#
+#     # example: many lets us parse lists
+#
+#     parser = char_parser(",").and(ws_parser).many
+#     
+#     parse(parser, "").ast => []
+#     parse(parser, ", ").ast => [[","]]
+#     parse(parser, ", , ").ast => [[","], [","]]
+#
+#     # example: use map and flatten to get simpler results
+#
+#     parser = char_parser(",").and(ws_parser).many.map(&:flatten)
+#     
+#     parse(parser, "").ast => []
+#     parse(parser, ", ").ast => [","]
+#     parse(parser, ", , ").ast => [",", ","]
+#
+#     # example: many takes a min: length constraint
+#
+#     parser = char_parser(",").and(ws_parser).many(min: 2).map(&:flatten)
+#     
+#     parse(parser, "").ast => nil # A synonym for not_ok in this case
+#     parse(parser, ", ").ast => nil
+#     parse(parser, ", , ").ast => [",", ","]
+#
+# Now we have explained all the elements of the first usage by means of some examples.
+#
+# We will continue to use this approach to document all available parsers and combinators
+# in the
+#
+# OOPeg@Detailed+API+Documentation
+#
+#
+# === Basic Concepts
+#
+# - What Is A Parser?
+#
+#   In the context of this gem, a +Parser+ is an instance of the class +OOPeg::Parser+.
+#
+# - How can we write parsers?
+#
+#   Mostly we do not need as we have predefined parsers which we can parmetrize and
+#   combine with combinators to create new parsers.
+#
+# - So What Is A Combinator?
+#
+#   Combinators are methods on parsers, oftentimes accepting more parsers as arguments
+#   which return parsers.
+#
+# - How does a parser parse?
+#
+#   It will take some input and return a result.
+#
+# - When does a parser succeed?
+#
+#   If its result is +ok+ IOW <tt>result.ok?</tt> or <tt>result => {ok: true}</tt>
+#
+# - When does a parser fail?
+#
+#   Why don't you take a wild guess here?
+#
+# - But what is an input?
+#
+#   - Short answer: A string
+#   - Correct answer: An object of class +OOPeg::Input+ that contains the graphemes of an input string
+#     and its character position
+#
+# - So, when I call <tt>parse(some_parser, "some string")</tt>, does the +parse+
+#   method convert the string?
+#   
+#   Indeed!
+#
+# - And a result?
+#
+#   An instance of the class +OOPeg::Result+
+#
+# - Wait a minute, I have seen an +OpenStruct+
+#
+#   Well +OOPeg#parse+ converts an +OOPeg::Result+ to an +OpenStruct+ after
+#   calling the _real_ parse method +OOPeg::Parser#parse+
+# 
+# - So can I write my own parser?
+#
+#   Again, indeed!
+#
+#   Here is an example:
+#
+#     # example: look Ma, my own parser
+#
+#     R = OOPeg::Result
+#     my_parser = OOPeg::Parser.new("my parser") do |input| 
+#       case input.content
+#       in [a, b, *]
+#         if a.to_i < b.to_i
+#           # it is important to advance the input
+#           R.ok(ast: "#{a.to_i} < #{b.to_i}", input: input.advance(2))
+#         else
+#           R.nok(input:, error: "not rising", parser_name: "my parser")
+#         end
+#       else
+#         R.nok(input:, error: "need two digits", parser_name: "my parser")
+#       end
+#     end
+#
+#     parse(my_parser, "").error => "need two digits"
+#     parse(my_parser, "a").error => "need two digits"
+#     parse(my_parser, "42").error => "not rising"
+#     parse(my_parser, "02").ast => "0 < 2"
+#
+# === Detailed API Documentation
+#
+# ==== Basic Parsers
+#
+# The Basic Parsers are parsers that do not depend on other parsers or combinators.
+# They are documented in detail in
+# OOPeg::Parsers::BaseParsers
+#
+#
+# ==== Common Parsers
+#
+# These are <em>convenience</em> parsers that rely on the basic parsers and combinators,
+# they are documented in detail in
+# OOPeg::Parsers::CommonParsers
+#
+# ==== Combinators
+#
+# A _combinator_ is a method that takes one or more parsers and returns another parser.
+#
+# They are exposed as methods on the +OOPeg::Parser+ class and implemented in
+# OOPeg::Parser::Combinators
+#
+# ==== Advanced Parsers
+#
+# These are parsers that parse commonly used grammars, like +Symbols+, +Strings+ and
+# complete +S-Expressions+.
+#
+# They are not automatically required and must be used as follows
+#
+#     require 'oo_peg/parsers/advanced'
+#     extend OOPeg::Parsers::Advanced
+#
+#
+# Here is their detailed documentation
+# OOPeg::Parsers::Advanced
+#
+# Each parser, exposed in the +OOPeg::Parsers::Advanced+ module
+# can also be required individually like so <tt>require 'oo_peg/parsers/advanced/string_parser'.
+#
+# This will expose the +OOPeg::Parsers::Advanced::StringParser+ class.
+#
+module OOPeg
+
+  def self.parse(parser, input) = OpenStruct.new(OOPeg::Parser.parse(parser, input).to_h)
+  def parse(parser, input) = OpenStruct.new(OOPeg::Parser.parse(parser, input).to_h)
+  # def parse(parser, input)
+  #   result = OOPeg::Parser.parse(parser, input)
+  #   OpenStruct.new(result.to_h)
+  # end
+  
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: oo_peg
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Dober
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.13.0
+description: A peg parser not using custom sytnax but exposing an OO based API
+email: robert.dober@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/enumerable.rb
+- lib/oo_peg.rb
+- lib/oo_peg/input.rb
+- lib/oo_peg/ostruct.rb
+- lib/oo_peg/parser.rb
+- lib/oo_peg/parser/class_methods.rb
+- lib/oo_peg/parser/combinators.rb
+- lib/oo_peg/parser/combinators/lazy.rb
+- lib/oo_peg/parsers.rb
+- lib/oo_peg/parsers/advanced.rb
+- lib/oo_peg/parsers/advanced/operator_parser.rb
+- lib/oo_peg/parsers/advanced/sexp_parser.rb
+- lib/oo_peg/parsers/advanced/string_parser.rb
+- lib/oo_peg/parsers/advanced/symbol_parser.rb
+- lib/oo_peg/parsers/base_parsers.rb
+- lib/oo_peg/parsers/common_parsers.rb
+- lib/oo_peg/parsers/lispy_parser.rb
+- lib/oo_peg/parsers/pseudo_parsers.rb
+- lib/oo_peg/parsers/true_set.rb
+- lib/oo_peg/result.rb
+- lib/oo_peg/version.rb
+homepage: https://codeberg.org/lab419/oo_peg
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://codeberg.org/lab419/oo_peg
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: '["A peg parser not using custom sytnax but exposing an OO based API"]'
+test_files: []