paco 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 874b690b05bae4b9627aab0da0d248b020de705fbbbc88be1dc6e08afdeb8bc5
-  data.tar.gz: 4d69df9a10c651470acc62b297c0c628ab80afa2f508c3f0588c24e811b14000
+  metadata.gz: ae17ec48820da8d99722dd87e2f834cc238497c948dff292490665cdeb16fbc1
+  data.tar.gz: 30046ad4c3203dcf35430c9512df303f008fe513c11f92e06137a7131ee586fe
 SHA512:
-  metadata.gz: 6c5ed079f9a70a4eb11dc754ed24b59d1b50ee9e5a29baf36ab9f61cb040c6609284f8d4b9d6f3044d1ab26e8617a349b4b3811026c97b87c731d423422576d5
-  data.tar.gz: b1afa018f1646c3421e21d01be36cd052468cb824843dc66dd38cabd92a92aee734470a08fd5b169c5bbdadab196440543e1e14419322079e50cb0b31b82fd49
+  metadata.gz: bf9fb9a162ab9c8292047942ebf8cc57e6a0382fa680beed1802129f6abd07d2483a24ba734f260c0fef9ba948e54ac9cf9635bc49abbbc457d2d91c6c5a9fb7
+  data.tar.gz: 0d4ef03c2022c26ae813d1d3f925b539c6cb7e2e715f27f965a80f9b8809e7a4c6d6d78bb6c5086603f3585aaf44e6035b5f72892078d44d63f4cfd5ca83509b

data/CHANGELOG.md

@@ -5,9 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog],
 and this project adheres to [Semantic Versioning].
 
-## [Unreleased]
+## [0.2.0] - 2021-12-28
 
-## [0.1.0]
+### Added
+
+- Callstack collection for debugging. ([@skryukov])
+
+Pass `with_callstack: true` to the `Paco::Parser#parse` method to collect a callstack while parsing. To examine the callstack catch the `ParseError` exception:
+
+```ruby
+begin
+  string("Paco").parse("Paco!", with_callstack: true)
+rescue Paco::ParseError => e
+  pp e.callstack.stack # You will probably want to use `binding.irb` or `binding.pry`
+end
+```
+
+- `Paco::Combinators.index` method. ([@skryukov])
+
+Call `Paco::Combinators.index` to get `Paco::Index` representing the current offset into the parse without consuming the input.
+`Paco::Index` has a 0-based character offset attribute `:pos` and 1-based `:line` and `:column` attributes.
+
+```ruby
+index.parse("Paco") #=> #<struct Paco::Index pos=0, line=1, column=1> 
+```
+
+- RSpec matcher `#parse`. ([@skryukov])
+
+Add `require "paco/rspec"` to `spec_helper.rb` to enable a special RSpec matcher `#parse`:
+
+```ruby
+subject { string("Paco") }
+
+it { is_expected.to parse("Paco") } # just checks if parser succeeds
+it { is_expected.to parse("Paco").as("Paco") } # checks if parser result is eq to value passed to `#as`
+it { is_expected.to parse("Paco").fully } # checks if parser result is the same as value passed to `#parse`
+```
+
+### Changed
+
+- `Paco::Combinators.seq_map` merged into `Paco::Combinators.seq`. ([@skryukov])
+- `Paco::Combinators.sep_by_1` renamed to `Paco::Combinators.sep_by!`. ([@skryukov])
+
+### Fixed
+
+- `Paco::Combinators::Char#regexp` now uses `\A` instead of `^`. ([@skryukov])
+- `include Paco` now works inside `irb`. ([@skryukov])
+- `Paco::Combinators#not_followed_by` and `Paco::Combinators#seq` now don't consume input on error. ([@skryukov])
+
+## [0.1.0] - 2021-12-12
 
 ### Added
 
@@ -15,7 +61,8 @@ and this project adheres to [Semantic Versioning].
 
 [@skryukov]: https://github.com/skryukov
 
-[Unreleased]: https://github.com/skryukov/paco/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/skryukov/paco/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/skryukov/paco/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/skryukov/paco/commits/v0.1.0
 
 [Keep a Changelog]: https://keepachangelog.com/en/1.0.0/

data/README.md

@@ -1,26 +1,83 @@
 # Paco
 
+[![Gem Version](https://badge.fury.io/rb/paco.svg)](https://rubygems.org/gems/paco)
+[![Build](https://github.com/skryukov/paco/workflows/Build/badge.svg)](https://github.com/skryukov/paco/actions)
+
 Paco is a parser combinator library inspired by Haskell's [Parsec] and [Parsimmon].
 
-## Installation
+"But I don't need to write another JSON parser or a new language, why do I need your library then?"
 
-Add this line to your application's Gemfile:
+Well, most probably you don't. But I can think of rare cases when you do. Say, you need to write a validation for [git branch names].
+
+You can go with easy-peasy regex:
 
 ```ruby
-gem "paco"
+branch_name_regex = /^(?!\/|.*(?:[\/.]\.|\/\/|@{|\\|\.lock$|[\/.]$))[^\040\177 ~^:?*\[]+$/
+
+branch_name_regex.match?("feature/branch-validation")
+```
+
+With Paco, you can go with a little more verbose version of that rule:
+
+```ruby
+module BranchNameParser
+  extend Paco
+
+  class << self
+    def parse(input)
+      parser.parse(input)
+    end
+
+    def parser
+      lookahead(none_of("/")).next(valid_chars.join)
+    end
+
+    def valid_chars
+      any_char.not_followed_by(invalid_sequences).at_least(1)
+    end
+    
+    def invalid_sequences
+      alt(invalid_chars, invalid_endings)
+    end
+
+    def invalid_chars
+      alt(
+        string("/."),
+        string(".."),
+        string("//"),
+        string("@{"),
+        string("\\\\"),
+        one_of("\040\177 ~^:?*\\[")
+      )
+    end
+
+    def invalid_endings
+      seq(
+        alt(string(".lock"), one_of("/.")),
+        eof
+      )
+    end
+  end
+end
+
+BranchNameParser.parse("feature/branch-validation")
 ```
 
-And then execute:
+Easy? Not really, but there is a chance you can read it. 😅
+
+See [API documentation](docs/paco.md), [examples](examples) and [specs](spec) for more info on usage.
 
-    $ bundle install
+<a href="https://evilmartians.com/"><img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
-Or install it yourself as:
+## Installation
 
-    $ gem install paco
+Add to your `Gemfile`:
 
-## Usage
+```ruby
+gem "paco"
+```
 
-See [API documentation](docs/paco.md), [examples](examples) and [specs](spec).
+And then run `bundle install`.
 
 ## Development
 
@@ -32,6 +89,11 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/skryukov/paco.
 
+## Alternatives
+
+- [parslet] - A small (but featureful) PEG based parser library.
+- [parsby] — Parser combinator library for Ruby inspired by Haskell's Parsec.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License].
@@ -39,4 +101,6 @@ The gem is available as open source under the terms of the [MIT License].
 [MIT License]: https://opensource.org/licenses/MIT
 [Parsec]: https://github.com/haskell/parsec
 [Parsimmon]: https://github.com/jneen/parsimmon
+[parslet]: https://github.com/kschiess/parslet
 [parsby]: https://github.com/jolmg/parsby
+[git branch names]: https://git-scm.com/docs/git-check-ref-format#_description

data/lib/paco/callstack.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Paco
+  class Callstack
+    attr_reader :stack
+
+    def initialize
+      @stack = []
+      @depth = 0
+    end
+
+    def failure(**params)
+      @depth -= 1
+      @stack << params.merge(status: :failure, depth: @depth)
+    end
+
+    def start(**params)
+      @depth += 1
+      @stack << params.merge(status: :start, depth: @depth)
+    end
+
+    def success(**params)
+      @depth -= 1
+      @stack << params.merge(status: :success, depth: @depth)
+    end
+  end
+end

data/lib/paco/combinators/char.rb

@@ -32,7 +32,7 @@ module Paco
       # @param [String] matcher
       # @return [Paco::Parser]
       def string(matcher)
-        Parser.new(matcher) do |ctx, parser|
+        Parser.new("string(#{matcher.inspect})") do |ctx, parser|
           src = ctx.read(matcher.length)
           parser.failure(ctx) if src != matcher
 
@@ -46,9 +46,10 @@ module Paco
       # When `group` is specified, it returns only the text in the specific regexp match group.
       # @param [Regexp] regexp
       # @return [Paco::Parser]
+      # @param [Integer] group
       def regexp(regexp, group: 0)
-        anchored_regexp = Regexp.new("^(?:#{regexp.source})", regexp.options)
-        Parser.new(regexp.inspect) do |ctx, parser|
+        anchored_regexp = Regexp.new("\\A(?:#{regexp.source})", regexp.options)
+        Parser.new("regexp(#{regexp.inspect})") do |ctx, parser|
           match = anchored_regexp.match(ctx.read_all)
           parser.failure(ctx) if match.nil?
 
@@ -61,7 +62,7 @@ module Paco
       # @param [Regexp] regexp
       # @return [Paco::Parser]
       def regexp_char(regexp)
-        satisfy(regexp.inspect) { |char| regexp.match?(char) }
+        satisfy("regexp_char(#{regexp.inspect})") { |char| regexp.match?(char) }
       end
 
       # Returns a parser that looks for exactly one character from passed
@@ -69,7 +70,7 @@ module Paco
       # @param [String, Array<String>] matcher
       # @return [Paco::Parser]
       def one_of(matcher)
-        satisfy(matcher.to_s) { |char| matcher.include?(char) }
+        satisfy("one_of(#{matcher})") { |char| matcher.include?(char) }
       end
 
       # Returns a parser that looks for exactly one character _NOT_ from passed
@@ -77,7 +78,7 @@ module Paco
       # @param [String, Array<String>] matcher
       # @return [Paco::Parser]
       def none_of(matcher)
-        satisfy("not #{matcher}") { |char| !matcher.include?(char) }
+        satisfy("none_of(#{matcher})") { |char| !matcher.include?(char) }
       end
 
       # Returns a parser that consumes and returns the next character of the input.
@@ -90,7 +91,7 @@ module Paco
       # @return [Paco::Parser]
       def remainder
         memoize do
-          Parser.new("remainder of the input") do |ctx, parser|
+          Parser.new("remainder") do |ctx, parser|
             result = ctx.read_all
             ctx.pos += result.length
             result
@@ -147,7 +148,7 @@ module Paco
         memoize { alt(newline, eof) }
       end
 
-      # Alias for `Paco::Combinators.regexp(/[a-z]/i)`.
+      # Alias for `Paco::Combinators.regexp_char(/[a-z]/i)`.
       # @return [Paco::Parser]
       def letter
         memoize { regexp_char(/[a-z]/i) }
@@ -156,16 +157,16 @@ module Paco
       # Alias for `Paco::Combinators.regexp(/[a-z]+/i)`.
       # @return [Paco::Parser]
       def letters
-        memoize { seq(letter, letter.many).fmap { |x| x.flatten.join } }
+        memoize { regexp(/[a-z]+/i) }
       end
 
       # Alias for `Paco::Combinators.regexp(/[a-z]*/i)`.
       # @return [Paco::Parser]
       def opt_letters
-        memoize { letters | succeed("") }
+        memoize { regexp(/[a-z]*/i) }
       end
 
-      # Alias for `Paco::Combinators.regexp(/[0-9]/)`.
+      # Alias for `Paco::Combinators.regexp_char(/[0-9]/)`.
       # @return [Paco::Parser]
       def digit
         memoize { regexp_char(/[0-9]/) }
@@ -174,13 +175,13 @@ module Paco
       # Alias for `Paco::Combinators.regexp(/[0-9]+/)`.
       # @return [Paco::Parser]
       def digits
-        memoize { seq(digit, digit.many).fmap { |x| x.flatten.join } }
+        memoize { regexp(/[0-9]+/) }
       end
 
       # Alias for `Paco::Combinators.regexp(/[0-9]*/)`.
       # @return [Paco::Parser]
       def opt_digits
-        memoize { digits | succeed("") }
+        memoize { regexp(/[0-9]*/) }
       end
 
       # Alias for `Paco::Combinators.regexp(/\s+/)`.

data/lib/paco/combinators.rb

@@ -1,22 +1,14 @@
 # frozen_string_literal: true
 
-require "monitor"
-
 require "paco/combinators/char"
+require "paco/memoizer"
 
 module Paco
   module Combinators
-    def self.extended(base)
-      base.extend MonitorMixin
-      base.extend Char
-    end
-
-    def self.included(base)
-      base.include MonitorMixin
-      base.include Char
-    end
+    include Char
+    extend Char
 
-    extend self
+    module_function
 
     # Returns a parser that runs the passed `parser` without consuming the input, and
     # returns `null` if the passed `parser` _does not match_ the input. Fails otherwise.
@@ -28,10 +20,11 @@ module Paco
         begin
           parser._parse(ctx)
         rescue ParseError
-          ctx.pos = start_pos
           nil
         else
           pars.failure(ctx)
+        ensure
+          ctx.pos = start_pos
         end
       end
     end
@@ -39,7 +32,7 @@ module Paco
     # Returns a parser that doesn't consume any input and always returns `result`.
     # @return [Paco::Parser]
     def succeed(result)
-      Parser.new { result }
+      Parser.new("succeed(#{result})") { result }
     end
 
     # Returns a parser that doesn't consume any input and always fails with passed `message`.
@@ -54,7 +47,7 @@ module Paco
     # @param [Paco::Parser] parser
     # @return [Paco::Parser]
     def lookahead(parser)
-      Parser.new do |ctx|
+      Parser.new("lookahead(#{parser.desc})") do |ctx|
         start_pos = ctx.pos
         parser._parse(ctx)
         ctx.pos = start_pos
@@ -68,7 +61,7 @@ module Paco
     def alt(*parsers)
       raise ArgumentError, "no parsers specified" if parsers.empty?
 
-      Parser.new do |ctx|
+      Parser.new("alt(#{parsers.map(&:desc).join(", ")})") do |ctx|
         result = nil
         last_error = nil
         start_pos = ctx.pos
@@ -86,26 +79,25 @@ module Paco
 
     # Accepts one or more parsers, and returns a parser that expects them
     # to match in order, returns an array of all their results.
+    # If `block` specified, passes results of the `parses` as an arguments
+    # to a `block`, and at the end returns its result.
     # @param [Array<Paco::Parser>] parsers
     # @return [Paco::Parser]
     def seq(*parsers)
       raise ArgumentError, "no parsers specified" if parsers.empty?
 
-      Parser.new do |ctx|
-        parsers.map { |parser| parser._parse(ctx) }
+      result = Parser.new("seq(#{parsers.map(&:desc).join(", ")})") do |ctx|
+        start_pos = ctx.pos
+        begin
+          parsers.map { |parser| parser._parse(ctx) }
+        rescue ParseError => e
+          ctx.pos = start_pos
+          raise e
+        end
       end
-    end
+      return result unless block_given?
 
-    # Returns a parser that matches all `parsers` sequentially, and passes
-    # their results as an arguments to a `block`, and at the end returns its result.
-    # @param [Array<Paco::Parser>] parsers
-    # @return [Paco::Parser]
-    def seq_map(*parsers, &block)
-      raise ArgumentError, "no parsers specified" if parsers.empty?
-
-      seq(*parsers).fmap do |results|
-        block.call(*results)
-      end
+      result.fmap { |results| yield(*results) }
     end
 
     # Accepts a block that returns a parser, which is evaluated the first time the parser is used.
@@ -121,7 +113,8 @@ module Paco
     # @param [Paco::Parser] separator
     # @return [Paco::Parser]
     def sep_by(parser, separator)
-      alt(sep_by_1(parser, separator), succeed([]))
+      alt(sep_by!(parser, separator), succeed([]))
+        .with_desc("sep_by(#{parser.desc}, #{separator.desc})")
     end
 
     # Returns a parser that expects one or more matches for `parser`,
@@ -129,11 +122,11 @@ module Paco
     # @param [Paco::Parser] parser
     # @param [Paco::Parser] separator
     # @return [Paco::Parser]
-    def sep_by_1(parser, separator)
-      seq_map(parser, many(separator.next(parser))) do |first, arr|
-        [first] + arr
-      end
+    def sep_by!(parser, separator)
+      seq(parser, many(separator.next(parser))) { |first, arr| [first] + arr }
+        .with_desc("sep_by!(#{parser.desc}, #{separator.desc})")
     end
+    alias_method :sep_by_1, :sep_by!
 
     # Expects the parser `before` before `parser` and `after` after `parser. Returns the result of the parser.
     # @param [Paco::Parser] before
@@ -148,13 +141,10 @@ module Paco
     # @param [Paco::Parser] parser
     # @return [Paco::Parser]
     def many(parser)
-      Parser.new do |ctx|
+      Parser.new("many(#{parser.desc})") do |ctx|
         results = []
-        # last_pos = ctx.pos
         loop do
           results << parser._parse(ctx)
-          # raise ArgumentError, "smth wrong" if last_pos == ctx.pos
-          # last_pos = ctx.pos
         rescue ParseError
           break
         end
@@ -169,15 +159,16 @@ module Paco
       alt(parser, succeed(nil))
     end
 
+    # Returns parser that returns `Paco::Index` representing
+    # the current offset into the parse without consuming the input.
+    # @return [Paco::Parser]
+    def index
+      Parser.new { |ctx| ctx.index }
+    end
+
     # Helper used for memoization
     def memoize(&block)
-      key = block.source_location
-      synchronize do
-        @_paco_memoized ||= {}
-        return @_paco_memoized[key] if @_paco_memoized.key?(key)
-
-        @_paco_memoized[key] = block.call
-      end
+      Memoizer.memoize(block.source_location, &block)
     end
   end
 end

data/lib/paco/context.rb

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
+
+require "paco/callstack"
+require "paco/index"
+
 module Paco
   class Context
-    attr_reader :input, :last_pos, :pos
+    attr_reader :input, :last_pos, :callstack
+    attr_accessor :pos
 
-    def pos=(np)
-      # TODO: is that needed?
-      @last_pos = @pos
-      @pos = np
-    end
-
-    def initialize(input, pos = 0)
+    def initialize(input, pos: 0, with_callstack: false)
       @input = input
       @pos = pos
+      @callstack = Callstack.new if with_callstack
     end
 
     def read(n)
@@ -19,22 +19,33 @@ module Paco
     end
 
     def read_all
-      input[pos..-1]
+      input[pos..]
     end
 
     def eof?
       pos >= input.length
     end
 
+    # @param [Integer] from
+    # @return [Paco::Index]
     def index(from = nil)
-      from ||= pos
-      lines = input[0..from].lines
-
-      {
-        line: lines.length,
-        column: lines[-1]&.length || 0,
-        pos: from
-      }
+      Index.calculate(input: input, pos: from || pos)
+    end
+
+    # @param [Paco::Parser] parser
+    def failure_parse(parser)
+      @callstack&.failure(pos: pos, parser: parser.desc)
+    end
+
+    # @param [Paco::Parser] parser
+    def start_parse(parser)
+      @callstack&.start(pos: pos, parser: parser.desc)
+    end
+
+    # @param [Object] result
+    # @param [Paco::Parser] parser
+    def success_parse(result, parser)
+      @callstack&.success(pos: pos, result: result, parser: parser.desc)
     end
   end
 end

data/lib/paco/index.rb

@@ -0,0 +1,15 @@
+module Paco
+  Index = Struct.new(:pos, :line, :column) do
+    # @param [String] input
+    # @param [Integer] pos
+    def self.calculate(input:, pos:)
+      raise ArgumentError, "`pos` must be a non-negative integer" if pos < 0
+      raise ArgumentError, "`pos` is grater then input length" if pos > input.length
+
+      lines = input[0..pos].lines
+      line = lines.empty? ? 1 : lines.length
+      column = lines.last&.length || 1
+      new(pos, line, column)
+    end
+  end
+end

data/lib/paco/memoizer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Paco
+  module Memoizer
+    extend MonitorMixin
+
+    class << self
+      def memoize(key, &block)
+        synchronize do
+          @paco_memoized ||= {}
+          return @paco_memoized[key] if @paco_memoized.key?(key)
+
+          @paco_memoized[key] = block.call
+        end
+      end
+    end
+  end
+end

data/lib/paco/parse_error.rb

@@ -1,28 +1,29 @@
 # frozen_string_literal: true
+
 module Paco
   class Error < StandardError; end
 
   class ParseError < Error
+    attr_reader :ctx, :pos, :expected
+
     # @param [Paco::Context] ctx
     def initialize(ctx, expected)
       @ctx = ctx
       @pos = ctx.pos
       @expected = expected
+    end
 
-      # TODO: make this possible to show every parsing message? or last n?
-      # puts ""
-      # puts "#{ctx.pos}/#{ctx.input.length}: #{ctx.input[ctx.last_pos..ctx.pos]}"
-      # puts "expected: #{expected}"
-      # puts ""
+    def callstack
+      ctx.callstack
     end
 
     def message
-      index = @ctx.index(@pos)
+      index = ctx.index(pos)
       <<~MSG
-        Parsing error
-        line #{index[:line]}, column #{index[:column]}:
-        unexpected #{@ctx.input[@pos] || "end of file"}
-        expecting #{@expected}
+        \nParsing error
+        line #{index.line}, column #{index.column}:
+        unexpected #{ctx.eof? ? "end of file" : ctx.input[pos].inspect}
+        expecting #{expected}
       MSG
     end
   end

data/lib/paco/parser.rb

@@ -6,36 +6,47 @@ module Paco
   class Parser
     attr_reader :desc
 
+    # @param [String] desc
     def initialize(desc = "", &block)
       @desc = desc
       @block = block
     end
 
-    def parse(input)
-      ctx = input.is_a?(Context) ? input : Context.new(input)
+    # @param [String] desc
+    # @return [Paco::Parser]
+    def with_desc(desc)
+      @desc = desc
+      self
+    end
+
+    # @param [String, Paco::Context] input
+    # @param [true, false] with_callstack
+    def parse(input, with_callstack: false)
+      ctx = input.is_a?(Context) ? input : Context.new(input, with_callstack: with_callstack)
       skip(Paco::Combinators.eof)._parse(ctx)
     end
 
+    # @param [Paco::Context] ctx
     def _parse(ctx)
-      @block.call(ctx, self)
-      # TODO: add ability for debugging
-      # puts ""
-      # puts "#{@block.source_location} succeed."
-      # puts "#{ctx.input.length}/#{ctx.pos}: " + ctx.input[ctx.last_pos..ctx.pos].inspect
-      # puts ""
-      # res
+      ctx.start_parse(self)
+      res = @block.call(ctx, self)
+      ctx.success_parse(res, self)
+      res
     end
 
     # Raises ParseError
     # @param [Paco::Context] ctx
     # @raise [Paco::ParseError]
     def failure(ctx)
+      ctx.failure_parse(self)
       raise ParseError.new(ctx, desc), "", []
     end
 
     # Returns a new parser which tries `parser`, and if it fails uses `other`.
+    # @param [Paco::Parser] other
+    # @return [Paco::Parser]
     def or(other)
-      Parser.new do |ctx|
+      Parser.new("or(#{desc}, #{other.desc})") do |ctx|
         _parse(ctx)
       rescue ParseError
         other._parse(ctx)
@@ -47,7 +58,7 @@ module Paco
     # @param [Poco::Parser] other
     # @return [Paco::Parser]
     def skip(other)
-      Paco::Combinators.seq(self, other).fmap { |results| results[0] }
+      Paco::Combinators.seq(self, other).fmap { |results| results[0] }.with_desc("#{desc}.skip(#{other.desc})")
     end
     alias_method :<, :skip
 
@@ -55,14 +66,15 @@ module Paco
     # @param [Poco::Parser] other
     # @return [Paco::Parser]
     def next(other)
-      bind { other }
+      Paco::Combinators.seq(self, other).fmap { |results| results[1] }
+        .with_desc("#{desc}.next(#{other.desc})")
     end
     alias_method :>, :next
 
     # Transforms the output of `parser` with the given block.
     # @return [Paco::Parser]
     def fmap(&block)
-      Parser.new do |ctx|
+      Parser.new("#{desc}.fmap") do |ctx|
         block.call(_parse(ctx))
       end
     end
@@ -74,7 +86,7 @@ module Paco
     # with the other Paco::Combinators.
     # @return [Paco::Parser]
     def bind(&block)
-      Parser.new do |ctx|
+      Parser.new("#{desc}.bind") do |ctx|
         block.call(_parse(ctx))._parse(ctx)
       end
     end
@@ -139,7 +151,7 @@ module Paco
         raise ArgumentError, "invalid attributes: min `#{min}`, max `#{max}`"
       end
 
-      Parser.new do |ctx|
+      Parser.new("#{desc}.times(#{min}, #{max})") do |ctx|
         results = min.times.map { _parse(ctx) }
         (max - min).times.each do
           results << _parse(ctx)
@@ -154,7 +166,7 @@ module Paco
     # Returns a parser that runs `parser` at least `num` times,
     # and returns an array of the results.
     def at_least(num)
-      Paco::Combinators.seq_map(times(num), many) do |head, rest|
+      Paco::Combinators.seq(times(num), many) do |head, rest|
         head + rest
       end
     end

data/lib/paco/rspec/parse_matcher.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define(:parse) do |input|
+  chain :as do |expected_output = nil, &block|
+    @expected = expected_output
+    @block = block
+  end
+
+  chain :fully do
+    @expected = input
+  end
+
+  match do |parser|
+    @result = parser.parse(input)
+    return @block.call(@result) if @block
+    return @expected == @result if defined?(@expected)
+
+    true
+  rescue Paco::ParseError => e
+    @error_message = e.message
+    false
+  end
+
+  failure_message do |subject|
+    msg = "expected output of parsing #{input.inspect} with #{subject.inspect} to"
+    was = (@result ? "was #{@result.inspect}" : "raised an error #{@error_message}")
+    return "#{msg} meet block conditions, but it didn't. It #{was}" if @block
+    return "#{msg} equal #{@expected.inspect}, but it #{was}" if defined?(@expected)
+
+    "expected #{subject.inspect} to successfully parse #{input.inspect}, but it #{was}"
+  end
+
+  failure_message_when_negated do |subject|
+    msg = "expected output of parsing #{input.inspect} with #{subject.inspect} not to"
+    return "#{msg} meet block conditions, but it did" if @block
+    return "#{msg} equal #{@expected.inspect}" if defined?(@expected)
+
+    "expected #{subject.inspect} to not parse #{input.inspect}, but it did"
+  end
+
+  description do
+    return "parse #{input.inspect} with block conditions" if @block
+    return "parse #{input.inspect} as #{@expected.inspect}" if defined?(@expected)
+
+    "parse #{input.inspect}"
+  end
+end

data/lib/paco/rspec.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Utils for testing Paco
+require "paco/rspec/parse_matcher"

data/lib/paco/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Paco
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/paco.rb

@@ -4,7 +4,6 @@ require "paco/version"
 require "paco/parse_error"
 require "paco/context"
 require "paco/parser"
-require "paco/combinators"
 
 module Paco
   def self.extended(base)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paco
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-12 00:00:00.000000000 Z
+date: 2021-12-28 00:00:00.000000000 Z
 dependencies: []
 description: Paco is a parser combinator library.
 email:
@@ -20,14 +20,17 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- bin/console
-- bin/setup
 - lib/paco.rb
+- lib/paco/callstack.rb
 - lib/paco/combinators.rb
 - lib/paco/combinators/char.rb
 - lib/paco/context.rb
+- lib/paco/index.rb
+- lib/paco/memoizer.rb
 - lib/paco/parse_error.rb
 - lib/paco/parser.rb
+- lib/paco/rspec.rb
+- lib/paco/rspec/parse_matcher.rb
 - lib/paco/version.rb
 homepage: https://github.com/skryukov/paco
 licenses:

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require "bundler/setup"
-require "paco"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here