dolos 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfeffbbe4108e43ba81ccd210f2689910d310fc3947fe05ed22a9972e581e96a
-  data.tar.gz: e181ccca4725008464fc92670b8120cf55262ba469d6ec494270081eb902c241
+  metadata.gz: f8e2e4aa7f86848de041ffcdb29a21c552608d6e7e48617763102cbd6fe29319
+  data.tar.gz: d94587b9583bf071deddf3cdc04bf3b2f91cfbab8ab81d15da82c4b59351f72a
 SHA512:
-  metadata.gz: 27fe73f34d41692d31c00d30bc03869cdefcef4ee785acbb72da12c9bceb85b78357da7c3d6d1435598b40fb635fb5e71d56254c18597c8d7d424748afc7c098
-  data.tar.gz: 9dd78f5e313830742505bbeb1488ed643a700facc2193ed3e996eef795913a50bb660a2af2dcd7c9a73e6e5f84befa7e461b2cf10d4bd11f22d68901ecc59e9b
+  metadata.gz: e5676cdf9a97bbcd49fb2e52d68ee935093e30b0dd78431ae83442cc3a8b522e57db4c90610500407e114ad88a517151f0ddb1e84f5c2897f009946064317e01
+  data.tar.gz: 7231d5bb051cb2edab89bdea12630c7a6bac4fd6fb2477524c04906acc90a81c3af82ed123bd8d08b5f3910ca65e6c985189256534222ad201f910312c7099b2

data/.rubocop.yml

@@ -0,0 +1,2 @@
+AllCops:
+  DisabledByDefault: true

data/README.md

@@ -1,6 +1,9 @@
 # Dolos
+[![Gem version](https://badge.fury.io/rb/dolos.svg)](https://rubygems.org/gems/dolos)
+[![Build status](https://github.com/benetis/dolos/actions/workflows/ruby.yml/badge.svg)](https://github.com/benetis/dolos/actions)
 
-<img height="256" src="docs/dolos_stable_diff.png" width="256"/>
+
+<img height="256" src="docs/images/dolos_stable_diff.png" width="256"/>
 
 
 ### Disclaimer
@@ -35,18 +38,12 @@ greet_and_speak.run("Hello, Parsers are great!") # <Result::Success>
 
 ```ruby
 require 'dolos'
-require 'dolos_common_parsers/common_parsers'
-
-include Dolos
-# frozen_string_literal: true
-require_relative 'dolos'
-require_relative 'dolos_common_parsers/common_parsers'
 
 include Dolos
 
 # Include common parsers
 # In future this can be more structured, moved them to separate module to prevent breaking changes
-include Dolos::CommonParsers
+include Dolos::Common
 
 # Library usage example
 # Parse out a name and address from a letter

data/docs/README.md

@@ -0,0 +1,22 @@
+# Dolos
+
+## What is Dolos?
+Dolos is parser combinator library for Ruby. It is inspired by FastParse and Scala Parser Combinators.
+
+## What are parser combinators?
+Parser combinators are a way to build parsers from smaller parsers. For example, you can build a parser for a number from a parser for a digit.
+This is a very simple example, but it can be used to build more complex parsers.
+Parsers are lazy and only run when needed. This allows to build complex parsers before passing input to them.
+```ruby
+hello = string("Hello")
+greeting = hello >> c(" ") >> string("Ruby developer!")
+greeting.run("Hello Ruby developer!") # => Success
+```
+
+## What's different from alternatives?
+This library focuses on two things:
+- Parsers integrate well into Ruby code. There is no need to keep them in separate classes.
+- Fine grained control over parsers. You can `map` and adjust each parser separately
+- Two ways of capturing values: traditional `>>`, other product operators to construct value and `capture!`
+  - For simple parsers `capture!` can be used to very quickly capture values into flat arrays 
+- Running parsers will not throw exceptions and instead return a result object. Exceptions don't play well with parsing.

data/docs/_sidebar.md

@@ -0,0 +1,4 @@
+* [Home](/)
+* [Getting started](getting_started.md)
+  * [Installation](getting_started.md#installation)
+  * [Usage](getting_started.md#usage)

data/docs/getting_started.md

@@ -0,0 +1,52 @@
+# Getting started 
+
+## Installation
+
+Install the gem and add it to your Gemfile:
+```shell
+$ bundle add dolos
+```
+Or manually:
+```ruby
+gem 'dolos'
+```
+
+## Usage
+
+Two things to do:
+- require library
+- include module `Dolos` and `Dolos::Common`
+
+```ruby
+require 'dolos'
+
+include Dolos
+include Dolos::Common # Common parsers
+```
+
+### Basic parsers
+
+A simple parser which matches one word.
+
+```ruby
+require 'dolos'
+include Dolos
+
+hello = c("Hello") # c("") is an alias for string(""). Can be read as: case-sensitive string match
+
+hello.run("Hello").success? # => true
+
+hello.run("hello").success? # => failure
+```
+
+After defining parser, it can be ran with `run('my-input')` method. It returns a `Result` object.
+
+### Result
+
+Result can be either `Success` or `Failure`. It can be checked with `success?` or `failure?` methods.
+
+Success will also have `value` property which will contain the result of the parser. There is also `captures`, but 
+that's for later.
+
+
+Failure will have `inspect` method which will return a string with the error message. It will show error position as well.

data/docs/index.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: '',
+      repo: ''
+    }
+    window.$docsify = {
+      loadSidebar: true
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-ruby.min.js"></script>
+</body>
+</html>

data/examples/letter.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 require 'dolos'
-require 'dolos_common_parsers/common_parsers'
 
 include Dolos
 
 # Include common parsers
 # In future this can be more structured, moved them to separate module to prevent breaking changes
-include Dolos::CommonParsers
+include Dolos::Common
 
 # Library usage example
 # Parse out a name and address from a letter

data/lib/dolos/parsers.rb

@@ -2,6 +2,11 @@
 
 module Dolos
   module Parsers
+
+    # String parser
+    # Matches exactly the given string
+    # string('hello').run('hello') => Success.new('hello', 5)
+    # Alias: c, for case-sensitive. Ex: c('hello').run('hello') => Success.new('hello', 5)
     def string(str)
       utf8_str = str.encode('UTF-8')
 
@@ -21,9 +26,12 @@ module Dolos
         end
       end
     end
-
     alias_method :c, :string
 
+    # Regex parser
+    # Accepts a regex, matches the regex against the input
+    # parser = regex(/\d+/)
+    # result = parser.run('123') # => Success.new('123', 3)
     def regex(pattern)
       Parser.new do |state|
         state.input.mark_offset
@@ -41,6 +49,8 @@ module Dolos
       end
     end
 
+    # Matches any character
+    # any_char.run('a') # => Success.new('a', 1)
     def any_char
       Parser.new do |state|
         state.input.mark_offset
@@ -62,6 +72,7 @@ module Dolos
     end
 
     # Matches any character in a string
+    # Passed string can be imagined as a set of characters
     # Example:
     #  char_in('abc').run('b') # => Success.new('b', 1)
     def char_in(characters_string)

data/lib/dolos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dolos
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 end

data/lib/dolos.rb

@@ -5,6 +5,7 @@ require_relative "dolos/parser_state"
 require_relative "dolos/result"
 require_relative "dolos/string_io_wrapper"
 require_relative "dolos/parsers"
+require_relative 'parsers/common'
 
 module Dolos
   include Parsers
@@ -15,16 +16,24 @@ module Dolos
       @parser_proc = block
     end
 
+    # Run the parser with the given input
+    # Returns a Result<Success|Failure>
+    # string("hello").run("hello") => Success.new("hello", 5)
     def run(input)
       run_with_state(ParserState.new(input))
     end
 
+
     def run_with_state(state)
       result = @parser_proc.call(state)
       state.last_success_position = state.input.offset if result.success?
       result
     end
 
+    # Capture the result of the parser
+    # p = string("hello").capture!
+    # p.run("hello").captures => ["hello"]
+    # Captures is a flat array of all captured values
     def capture!(wrap_in = nil)
       Parser.new do |state|
         result = run_with_state(state)
@@ -32,7 +41,10 @@ module Dolos
       end
     end
 
-    # Will call `map` on captures
+    # Map the captures of the parser
+    # p = string("hello").map_captures { |captures| captures.map(&:upcase) }
+    # p.run("hello") => Success.new("hello", 5, ["HELLO"])
+    # This only maps over captures, not the value
     def map_captures(&block)
       Parser.new do |state|
         result = run_with_state(state)
@@ -40,7 +52,9 @@ module Dolos
       end
     end
 
-    # Will call block on tuple of value
+    # Map the result of the parser
+    # p = string("hello").map { |s| s.upcase }
+    # p.run("hello") => Success.new("HELLO", 5)
     def map(&block)
       Parser.new do |state|
         result = run_with_state(state)
@@ -48,6 +62,7 @@ module Dolos
       end
     end
 
+    # Combine the result of the parser with another parser
     def combine(&block)
       Parser.new do |state|
         result = run_with_state(state)
@@ -62,12 +77,10 @@ module Dolos
       end
     end
 
-    def flatten
-      map_captures do |captures|
-        captures.flatten
-      end
-    end
-
+    # Combine the result of the parser with another parser
+    # Has an alias of `&`
+    # p = string("hello") & string("world")
+    # p.run("helloworld") => Success.new(["hello", "world"], 10)
     def product(other_parser)
       combine do |value1, capture1|
         other_parser.map do |value2|
@@ -79,6 +92,10 @@ module Dolos
     end
     alias_method :&, :product
 
+
+    # Combine the result of the parser with another parser
+    # Discards the result of the second parser
+    # p = string("hello") << string("world")
     def product_l(other_parser)
       combine do |value1, capture1|
         other_parser.map do |_|
@@ -89,6 +106,9 @@ module Dolos
       end
     end
 
+    # Combine the result of the parser with another parser
+    # Discards the result of the first parser
+    # p = string("hello") >> string("world")
     def product_r(other_parser)
       combine do |_, capture1|
         other_parser.map do |value2|
@@ -102,6 +122,10 @@ module Dolos
     alias_method :<<, :product_l
     alias_method :>>, :product_r
 
+    # Combine the result of the parser with another parser
+    # If the first parser fails, it will try the second parser
+    # p = string("hello") | string("world") | string("!")
+    # p.run("hello") => Success.new("hello", 5)
     def choice(other_parser)
       Parser.new do |state|
         result = run_with_state(state)
@@ -114,6 +138,9 @@ module Dolos
     end
     alias_method :|, :choice
 
+
+    # Repeat the parser n times
+    # Separator is optional, its another parser that will be run between each repetition
     # rep0         # 0 or more
     # rep          # 1 or more
     # rep(n = 2)   # exactly 2
@@ -156,11 +183,17 @@ module Dolos
         end
       end
     end
+
+    # Repeat the parser zero or more times
+    # c(" ").rep0.run("   ") => Success.new([" ", " ", " "], 3)
     def zero_or_more
       repeat(n_min: 0, n_max: Float::INFINITY)
     end
     alias_method :rep0, :zero_or_more
 
+    # Repeat the parser one or more times
+    # Same as rep0, but must match at least once
+    # c(" ").rep.run("A") => Failure.new("...")
     def one_or_more(exactly = nil)
       if exactly.nil?
         repeat(n_min: 1, n_max: Float::INFINITY)
@@ -170,6 +203,8 @@ module Dolos
     end
     alias_method :rep, :one_or_more
 
+    # Make parser optional
+    # c(" ").opt.run("A") => Success.new([], 0)
     def optional
       Parser.new do |state|
         result = run_with_state(state.dup)

data/lib/{dolos_common_parsers/common_parsers.rb → parsers/common.rb}

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module Dolos
-  module CommonParsers
+  # Common parsers
+  # Separated from the main library to improve them later on
+  # These will change, new ones will be added. Once API stabilises, we will see what to do
+  # We have to be careful what is in the scope when we include this main module
+  # Probably a package of parsers following some RFC will be added as well.
+  # Keeping them separate for now
+  module Common
     def ws
       regex(/\s/)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dolos
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - benetis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-22 00:00:00.000000000 Z
+date: 2023-08-23 00:00:00.000000000 Z
 dependencies: []
 description: Parser combinators library for Ruby. In active development, not stable
   yet.
@@ -19,6 +19,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -27,7 +28,12 @@ files:
 - benchmarks/json/nested_json_166.json
 - benchmarks/json/nested_json_1m.json
 - benchmarks/letter.rb
-- docs/dolos_stable_diff.png
+- docs/.nojekyll
+- docs/README.md
+- docs/_sidebar.md
+- docs/getting_started.md
+- docs/images/dolos_stable_diff.png
+- docs/index.html
 - examples/letter.rb
 - lib/dolos.rb
 - lib/dolos/parser_state.rb
@@ -35,7 +41,7 @@ files:
 - lib/dolos/result.rb
 - lib/dolos/string_io_wrapper.rb
 - lib/dolos/version.rb
-- lib/dolos_common_parsers/common_parsers.rb
+- lib/parsers/common.rb
 - sig/dolos.rbs
 - sig/dolos/common_parsers.rbs
 - sig/dolos/parser.rbs