nestedtext 1.1.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f906cf4ad95eb7c5db10e4aac5c9a8ef3fed91405dbad16572ed9a7c38fa7d05
-  data.tar.gz: c1189a45c17049006e0c81e589298ad9659e1bb42ce3889e31a863b279753663
+  metadata.gz: 309ec763445bda579aa39d3b82dec3bac8c7d2d2a76ef6b1c8e540452fa02150
+  data.tar.gz: d8fe34b30c1d1ce10206fa4b290339fb069b8cb66ce3d3e8ea58e6050271622f
 SHA512:
-  metadata.gz: 4dac3b9cc46cc628bcb5d804c13a986f3c9a5b7b207f02a84ac60caeff211cf416346e27af21b67485e41092e63b0c58de6f012a3a05b0a279a1f11edcdd3474
-  data.tar.gz: 13bc5644759667435b7c7da7ac60aaea5ab2236f9c4bd7a57856140967e9a2d9fc2ce60733df4076e500dcfc031a6954ccdc07a7c2d1fd1df60c280cf73cb13b
+  metadata.gz: 49b45ea8ab5f15704c7cd3322a40278f885b552377c978f661215dbdf727e29ac514c035bd6462ad7601e23dfcaebe159a5fbac13816eca6cc0e4fc6f25c7265
+  data.tar.gz: ff062a01cb069d1cd8b685b434fe8554966f52aadb946f8339eee8f6efda531575f988a49ef5ac3c7c232268e0bc007dac84aa00cb03cc434e0597a61a57ed88

data/.gitignore

@@ -10,6 +10,9 @@
 # When built from $(gem build *.gemspec)
 /*.gem
 
+# rdoc
+/doc
+
 # minitest
 /test/html_reports/
 /test/reports/

data/CHANGELOG.md

@@ -6,15 +6,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.1] - 2022-01-26
+### Fixed
+- README issue with logo showing up on Rdoc (out-commented HTML).
+
+## [2.0.0] - 2022-01-26
+### Changed
+- **Breaking change**: strict mode now defaults to false for both the `load` and `dump` methods.
+- Internal rename of error classes to be more consistent.
+- Internal simplification of argument passing.
+
+## [1.2.0] - 2022-01-25
+### Changed
+- Hide core extension `String.normalize_line_endings` from users.
+
+## [1.1.1] - 2022-01-25
+### Fixed
+- Renamed `NTEncodeMixing` to `NTEncodeMixin` .
+
 ## [1.1.0] - 2022-01-25
 ### Added
-- Expose `NestedText::VERSION` for convenience to the clients.
+- Expose `NestedText::VERSION` for convenience to the users.
 
 ## [1.0.0] - 2022-01-25
-The library is now useful for clients!
+The library is now useful for users!
 
 ### Changed
-- Hide all internals in the module from clients.
+- Hide all internals in the module from users.
 
 ## [0.6.0] - 2022-01-24
 ### Fixed

data/README.md

@@ -1,6 +1,7 @@
 # NestedText Ruby Library [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=NestedText,%20the%20human%20friendly%20data%20format,%20has%20a%20now%20a%20ruby%20library%20for%20easy%20encoding%20and%20decoding&url=https://github.com/erikw/nestedtext-ruby&via=erik_westrup&hashtags=nestedtext,ruby,gem)
 [![Gem Version](https://badge.fury.io/rb/nestedtext.svg)](https://badge.fury.io/rb/nestedtext)
 [![Gem Downloads](https://ruby-gem-downloads-badge.herokuapp.com/nestedtext?color=brightgreen&type=total&label=gem%20downloads)](https://rubygems.org/gems/nestedtext)
+[![Documentation](https://img.shields.io/badge/docs-API-informational?logo=readthedocs&logoColor=violet)](https://www.rubydoc.info/gems/nestedtext/)
 [![Data Format Version Supported](https://img.shields.io/badge/%F0%9F%84%BD%F0%9F%85%83%20Version%20Supported-3.2.1-blueviolet)](https://nestedtext.org/en/v3.2/)
 [![Official Tests](https://img.shields.io/badge/%F0%9F%8F%81%20Official%20Tests-Passing-success)](https://github.com/KenKundert/nestedtext_tests/tree/585e95a73d94ac1f48e71a154e2db0ab67cf30fa)
 [![GitHub Actions: Continuous Integration](https://github.com/erikw/nestedtext-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/erikw/nestedtext-ruby/actions/workflows/ci.yml)
@@ -9,35 +10,119 @@
 [![Code Climate Maintainability](https://api.codeclimate.com/v1/badges/8409b6cdc3dc62a33f6f/maintainability)](https://codeclimate.com/github/erikw/nestedtext-ruby/maintainability)
 [![Code Climate Test Coverage](https://api.codeclimate.com/v1/badges/8409b6cdc3dc62a33f6f/test_coverage)](https://codeclimate.com/github/erikw/nestedtext-ruby/test_coverage)
 [![SLOC](https://img.shields.io/tokei/lines/github/erikw/nestedtext-ruby)](#)
-[![License](https://img.shields.io/github/license/erikw/nestedtext-ruby)](LICENSE.txt)
+[![License](https://img.shields.io/github/license/erikw/nestedtext-ruby?color=informational)](LICENSE.txt)
 [![OSS Lifecycle](https://img.shields.io/osslifecycle/erikw/nestedtext-ruby)](https://github.com/Netflix/osstracker)
 
 
-Inspired by the `JSON` and `YAML` modules.
+A ruby library for the human friendly data format [NestedText](https://nestedtext.org/).
 
-This project will soon be released! :tada:
+<a href="#" ><img src="https://raw.githubusercontent.com/erikw/nestedtext-ruby/main/img/logo.webp" align="right" width="420px" alt="Project logo" /></a>
 
-On-going development is at branch [**dev**](https://github.com/erikw/nestedtext-ruby/tree/dev).
+Provided is support for decoding a NestedText file or string to Ruby data structures, as well as encoding Ruby objects to a NestedText file or string. Furthermore there is support for serialization and deserialization of custom classes. The supported language version of the data format can be see in the badge above. This implementation pass all the [official tests](https://github.com/KenKundert/nestedtext_tests).
+
+This library is inspired Ruby stdlib modules `JSON` and `YAML` as well as the Python [reference implementation](https://github.com/KenKundert/nestedtext) of NestedText. Parsing is done with a LL(1) recursive descent parser and dumping with a recursive DFS traversal of the object references.
 
 # What is NestedText?
-TODO
+Citing from the official [introduction](https://nestedtext.org/en/latest/index.html) page:
+> NestedText is a file format for holding structured data to be entered, edited, or viewed by people. It organizes the data into a nested collection of dictionaries, lists, and strings without the need for quoting or escaping. A unique feature of this file format is that it only supports one scalar type: strings.  While the decision to eschew integer, real, date, etc. types may seem counter intuitive, it leads to simpler data files and applications that are more robust.
+>
+> NestedText is convenient for configuration files, address books, account information, and the like. Because there is no need for quoting or escaping, it is particularly nice for holding code fragments.
 
-https://nestedtext.org/en/latest/alternatives.html
+*"Why do we need another data format?"* is the right question to ask. The answer is that the current popular formats (JSON, YAML, TOML, INI etc.) all have shortcomings which NestedText [addresses](https://nestedtext.org/en/latest/alternatives.html).
 
-## Examples
-TODO NT examples
+## Example
+Here's a full-fledged example of an address book (from the official docs):
+```nestedtext
+# Contact information for our officers
 
-# Usage
-TODO Link to lib docs
-TODO link to my test repo showin live usage. https://github.com/erikw/nestedtext-ruby-test
+president:
+    name: Katheryn McDaniel
+    address:
+        > 138 Almond Street
+        > Topeka, Kansas 20697
+    phone:
+        cell: 1-210-555-5297
+        home: 1-210-555-8470
+            # Katheryn prefers that we always call her on her cell phone.
+    email: KateMcD@aol.com
+    additional roles:
+        - board member
+
+vice president:
+    name: Margaret Hodge
+    ...
+```
 
+See the [language introduction](https://nestedtext.org/en/latest/basic_syntax.html) for more details.
 
 # Usage
+The full documentation can be found at [TODO](TODO). A minimal & fully working example of a project using this library can be found at [erikw/nestedtext-ruby-test](https://github.com/erikw/nestedtext-ruby-test).
+
 ## Decoding (reading NT)
+This is how you can decode NestedText from a string or directly from a file (`*.nt`) to Ruby object instances:
+
+### Any Top Level Type
+```ruby
+require 'nestedtext'
+
+ntstr = "- objitem1\n- list item 2"
+obj1 = NestedText::load(ntstr)
+
+obj2 = NestedText::load_file("path/to/data.nt")
+```
+
+The type of the returned object depends on the top level type in the NestedText data and will be of corresponding native Ruby type. In the example above, `obj1` will be an `Array` and obj2 will be `Hash` if `data.nt` looks like e.g.
+
+```
+key1: value1
+key2: value2
+```
+
+The NestedText types maps like this to Ruby:
+
+[NestedText](https://nestedtext.org/en/latest/basic_syntax.html) | Ruby | Comment
+---|---|---
+`String`    | `String`  |
+`List`      | `Array`   |
+`Dictionary`| `Hash`    |
+`String`    | `Symbol`  | when `strict: false`, otherwise Ruby Symbols are encoded as Custom Class (see below).
+*empty*     |  `nil`    | How empty strings and nil are handled depends on where it is used. This library follows how the official implementation does it.
+
+
+Thus you must know what you're parsing, or test what you decoded.
+
+### Explicit Top Level Type
+If you already know what you expect to have, you can guarantee that this is what you will get by telling either function what the expected top type is. If not, an error will be raised.
+
+```ruby
+require 'nestedtext'
+
+ntstr = "- objitem1\n- list item 2"
+array = NestedText::load(ntstr, top_class: Array)
+
+hash = NestedText::load_file("path/to/data.nt", top_class: Hash)
+
+# will raise NestedText::Error as we specify top level String but it will be Array.
+NestedText::load(ntstr, top_class: String)
+```
 
 ## Encoding (writing NT)
+This is how you can decode Ruby objects to a NestedText string or file:
+
+```ruby
+require 'nestedtext'
+
+data = ["i1", "i2"]
+
+ntstr = NestedText::dump(data)
+
+NestedText::dump_file(data, "path/to/data.nt")
+```
+
+
+### `#to_nt` Convenience
+To make it more convenient, the Ruby Core is extended with a `#to_nt` method on the supported types that will dump a String of the data structure. Here's an IRB session showing how it works:
 
-`#to_nt` method:
 ```irb
 irb> require 'nestedtext'
 irb> puts "a\nstring".to_nt
@@ -47,30 +132,97 @@ irb> puts ["i1", "i2", "i3"].to_nt
 - i1
 - i2
 - i3
-irb> puts({"k1" => "v1", "multiline\nkey" => "v2", "k3" => "multiline\nvalue"}.to_nt)
+irb> puts({"k1" => "v1", "multiline\nkey" => "v2", "k3" => ["a", "list"]}.to_nt)
 k1: v1
 : multiline
 : key
     > v2
 k3:
-    > multiline
-    > value
+    - a
+    - list
 ```
+
 ## Custom Classes Serialization
-This library has support for serialization/deserialization of custom classes as well.
-`strict: false` flag needed
+This library has support for serialization/deserialization of custom classes as well. This is done by letting the objects tell NestedText what data should be used to represent the object instance with the `#encode_nt_with` method (inspired by `YAML`'s `#encode_with` method). All objects being recursively referenced from a root object being serialized must either implement this method or be one of the core supported NestedText data types from the table above.
+
+```ruby
+class Apple
+  def initialize(type, weight)
+    @type = type
+    @weight = weight
+  end
+
+  def encode_nt_with
+    [@type, @weight]
+  end
+end
+```
+
+When an apple instance will be serialized e.g. by `apple.to_nt`, NestedText will call `Apple.encode_nt_with` if it exist and let the returned data be encoded to represent the instance.
+
+
+To be able to get this instance back when deserializing the NestedText there must be a class method `Class.nt_create(data)`. When deserializing NestedText and the class `Apple` is detected, and the method `#nt_create` exist on the class, it will be called with the decoded data belonging to it. This method should create and return a new instance of the class. In the most simple case it's just translating this to a call to `#new`.
+
+In full, the `Apple` class should look like:
+
+```ruby
+class Apple
+  def self.nt_create(data)
+    new(*data)
+  end
+
+  def initialize(type, weight)
+    @type = type
+    @weight = weight
+  end
+
+  def encode_nt_with
+    [@type, @weight]
+  end
+end
+```
+
+An instance of this class would be encoded like this:
+
+```ruby
+irb> puts NestedText::dump(Apple.new("granny smith", 12))
+__nestedtext_class__: Apple
+data:
+    - granny smith
+    - 12
+```
+Note that the special key to denote the class name is subject to change in future versions and you **must not** rely on it.
+
+If you want to add some more super powers to your custom class, you can add the `#to_nt` shortcut by including the `NTEncodeMixin`:
+```ruby
+class Apple
+  include NestedText::NTEncodeMixin
+  ...
+end
+
+Apple.new("granny smith", 12).to_nt
+```
+
+
+**NOTE** that when deserializing a custom class, this custom class must be available when calling the `#dump*` methods e.g.
+```ruby
+require 'nestedtext'
+require_relative 'apple'  # This is needed if Apple is defined in apple.rb and not in this scope already.
+
+NestedText::load_file('path/to/apple_dump.nt')
+```
+
 See [encode_custom_classes_test.rb](test/nestedtext/encode_custom_classes_test.rb) for more real working examples.
 
 
 # Installation
 1. Add this gem to your ruby project's Gemfile
-   - Simply with `$ bundle add nestedtext` when standing in the project root
+   - Simply with `$ bundle add nestedtext` when standing inside your project
    - Or manually by adding to `Gemfile`
    ```ruby
      gem 'nestedtext'
    ```
    and then running `$ bundle install`.
-   ```
 1. Require the library and start using it!
    ```ruby
      require 'nestedtext'
@@ -89,20 +241,20 @@ See [encode_custom_classes_test.rb](test/nestedtext/encode_custom_classes_test.r
    $ git clone https://github.com/erikw/nestedtext-ruby.git && cd $(basename "$_" .git)
    ```
 1. Install a supported ruby version (see .gemspec) with a ruby version manager e.g. [rbenv](https://github.com/rbenv/rbenv), [asdf](http://asdf-vm.com/) or [RVM](https://rvm.io/rvm/install)
-1. run `$ script/setup` to install dependencies
-1. run `$ script/test` to run the tests
+1. run `$ script/setup` or `$ bundle install` to install dependencies
+1. run `$ script/test` or `bundle exec rake test` to run the tests
 1. You can also run `$ script/console` for an interactive prompt that will allow you to experiment.
 1. For local testing, install the gem on local machine with: `$ bundle exec rake install`.
-   * or manuall with `$ gem build *.gemscpec && gem install *.gem`
+   * or manually with `$ gem build *.gemscpec && gem install *.gem`
 
-Make sure that only intended constants and methods are exposed from the module `NestedText`. Check with
+Make sure that only intended constants and methods are exposed publicly from the module `NestedText`. Check with
 ```
 irb> require 'nestedtext'
 irb> NestedText.constants
 irb> NestedText.methods(false)
 ```
 
-## Releasing
+# Releasing
 Instructions for releasing on rubygems.org below. Optionally make a GitHub [release](https://github.com/erikw/nestedtext-ruby/releases) after this for the pushed git tag.
 
 ## (manually) Using bundler/gem_tasks rake tasks
@@ -131,7 +283,7 @@ $ git commit -am "Prepare vX.Y.Z" && git push
 $ git tag x.y.z && git push --tags
 ```
 
-or combined with gem-release
+or combined with gem-release:
 ```console
 $ vi CHANGELOG.md
 $ git commit -am "Update CHANGELOG.md" && git push
@@ -140,10 +292,11 @@ $ gem bump --version minor --tag --sign --push
 
 
 # Contributing
-Bug reports and pull requests are welcome on GitHub at [https://github.com/erikw/nestedtext-ruby](https://github.com/erikw/nestedtext-ruby).
+Bug reports and pull requests are welcome on GitHub at [erikw/nestedtext-ruby](https://github.com/erikw/nestedtext-ruby).
 
 # License
 The gem is available as open source with the [License](./LICENSE.txt).
 
-# Acknowledgement & Thanks
-Thanks to the data format authors making it easier making new implementations by providing an [official test suite](https://github.com/KenKundert/nestedtext_tests).
+# Acknowledgments
+* Thanks to the data format authors making it easier making new implementations by providing an [official test suite](https://github.com/KenKundert/nestedtext_tests).
+* Thanks to [pixteller](https://pixteller.com/) & [mp4.to](https://mp4.to/webp/) for offering the tools needed for creating an animated logo.

data/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 1.x.x   | :white_check_mark: |
-| < 1.0   | :x:                |
+| 2.x.x   | :white_check_mark: |
+| < 2.0.0 | :x:                |
 
 
 ## Reporting a Vulnerability

data/lib/nestedtext/core_ext.rb

@@ -5,8 +5,7 @@ require "nestedtext/encode_helpers"
 # Or both: add encoding/decoding of more native classes, and allow decoding + applying a schema with 3rd party.
 # Or encourage using Marshal from core?
 
-NT_MIXIN = NestedText.const_get(:NTEncodeStrictMixing)
-
+NT_MIXIN = NestedText.const_get(:NTEncodeStrictMixin)
 class String include NT_MIXIN end
 class Array include NT_MIXIN end
 class Hash include NT_MIXIN end

data/lib/nestedtext/core_ext_internal.rb

@@ -0,0 +1,13 @@
+module NestedText
+  # Hiding extensions for Kernel here away from users.
+  # Reference: https://ruby-doc.org/core-3.1.0/doc/syntax/refinements_rdoc.html
+  module CoreExtInternal
+    refine String do
+      def normalize_line_endings
+        # windows/mac -> unix
+        gsub(/\r\n?/, "\n")
+      end
+    end
+  end
+  private_constant :CoreExtInternal
+end

data/lib/nestedtext/decode.rb

@@ -7,17 +7,13 @@ require "logger"
 require "stringio"
 
 module NestedText
-  def self.load(ntstring, top_class: Object, strict: true)
-    # logger = Logger.new(STDOUT) # TODO: make this available to other classes in module. How avoid singleton?
-    # logger.info "input=#{raw_input_string}"
-    # logger.info "top=#{top}"
-
+  def self.load(ntstring, top_class: Object, strict: false)
     raise Errors::WrongInputTypeError.new([String], ntstring) unless ntstring.nil? || ntstring.is_a?(String)
 
     Parser.new(StringIO.new(ntstring), top_class, strict: strict).parse
   end
 
-  def self.load_file(filename, top_class: Object, strict: true)
+  def self.load_file(filename, top_class: Object, strict: false)
     raise Errors::WrongInputTypeError.new([String], filename) unless !filename.nil? && filename.is_a?(String)
 
     # Open explicitly in text mode to detect \r as line ending.

data/lib/nestedtext/dumper.rb

@@ -1,23 +1,20 @@
-# TODO: is this exposed to client who import this file? If so, hide it!
-class String
-  def normalize_line_endings
-    # windows/mac -> unix
-    gsub(/\r\n?/, "\n")
-  end
-end
+require "nestedtext/core_ext_internal"
 
 module NestedText
+  using NestedText.const_get(:CoreExtInternal)
+
+  # Dumping with recursive DFS traversal of the object references.
   class Dumper
-    def initialize(opts = EncodeOptions.new)
-      @indentation = opts.indentation
-      @strict = opts.strict
-      @trace_cycles = nil
-      @trace_keys = nil
+    def initialize(indentation, strict)
+      @indentation = indentation
+      @strict = strict
+      @traced_cycles = nil
+      @traced_keys = nil
     end
 
     def dump(obj)
-      @trace_cycles = []
-      @trace_keys = []
+      @traced_cycles = []
+      @traced_keys = []
       dump_any obj
     end
 
@@ -51,7 +48,7 @@ module NestedText
       elsif !@strict
         key.to_s
       else
-        raise Errors::DumpHashKeyStrictString, key
+        raise Errors::DumpHashKeyStrictStringError, key
       end
     end
 
@@ -61,26 +58,24 @@ module NestedText
       target.replace indented
     end
 
-    # TODO: different name on method and instance var...
     def trace_cycles(obj)
-      raise Errors::DumpCyclicReferencesDetected, traced_key if @trace_cycles.include?(obj)
+      raise Errors::DumpCyclicReferencesDetectedError, traced_key if @traced_cycles.include?(obj)
 
-      @trace_cycles << obj
+      @traced_cycles << obj
       yield
     ensure
-      @trace_cycles.pop
+      @traced_cycles.pop
     end
 
-    # TODO: different name on method and instance var...
     def trace_keys(key)
-      @trace_keys << key
+      @traced_keys << key
       yield
     ensure
-      @trace_keys.pop
+      @traced_keys.pop
     end
 
     def traced_key
-      @trace_keys.last
+      @traced_keys.last
     end
 
     def dump_any(obj, depth: 0, **kwargs)
@@ -97,7 +92,7 @@ module NestedText
       end
     end
 
-    # TODO: document that @strict: false allows to_s on key object
+    # TODO: document that @strict==false allows to_s on key object
     def dump_hash(obj, depth: 0, **kwargs)
       rep = if obj.empty?
               "{}"

data/lib/nestedtext/encode.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "nestedtext/errors"
-require "nestedtext/encode_helpers"
 require "nestedtext/dumper"
 
 # Model after JSON
@@ -9,24 +8,22 @@ require "nestedtext/dumper"
 # NestedText.dump_file(obj, filename)
 
 module NestedText
-  # TODO: strict should maybe be false by default, as this is what ntpy does. If so, make the same for the load functions.
-  def self.dump(obj, io: nil, indentation: 4, strict: true)
+  def self.dump(obj, io: nil, indentation: 4, strict: false)
     # io - additionaly write the out result to IO and still return result.
 
-    raise Errors::DumpBadIO, io unless io.nil? || io.respond_to?(:write) && io.respond_to?(:fsync)
+    raise Errors::DumpBadIOError, io unless io.nil? || io.respond_to?(:write) && io.respond_to?(:fsync)
 
-    opts = EncodeOptions.new(indentation, strict)
-    dumper = Dumper.new(opts)
+    dumper = Dumper.new(indentation, strict)
     result = dumper.dump obj
     unless io.nil?
       io.write(result)
       io.fsync
     end
-    result
+    dumper.dump obj
   end
 
   def self.dump_file(obj, filename, **kwargs)
-    raise Errors::DumpFileBadPath, filename unless filename.is_a? String
+    raise Errors::DumpFileBadPathError, filename unless filename.is_a? String
 
     File.open(filename, mode = "wt") do |file|
       dump(obj, io: file, **kwargs)

data/lib/nestedtext/encode_helpers.rb

@@ -1,27 +1,16 @@
 require "nestedtext/dumper"
 
-# TODO: s/Mixing/Mixin/g
 module NestedText
-  module NTEncodeStrictMixing
-    def to_nt(indentation: 4, strict: true)
-      Dumper.new(EncodeOptions.new(indentation, strict)).dump self
+  module NTEncodeStrictMixin
+    def to_nt(**kwargs)
+      NestedText.dump(self, strict: true, **kwargs)
     end
   end
-  private_constant :NTEncodeStrictMixing
+  private_constant :NTEncodeStrictMixin
 
-  module NTEncodeMixing
-    def to_nt(indentation: 4)
-      Dumper.new(EncodeOptions.new(indentation, false)).dump self
+  module NTEncodeMixin
+    def to_nt(**kwargs)
+      NestedText.dump(self, **kwargs)
     end
   end
-
-  class EncodeOptions
-    attr_reader :indentation, :strict
-
-    def initialize(indentation = 4, strict = true)
-      @indentation = indentation
-      @strict = strict
-    end
-  end
-  private_constant :EncodeOptions
 end

data/lib/nestedtext/errors.rb

@@ -6,18 +6,16 @@ require "word_wrap/core_ext"
 require "nestedtext/constants"
 
 module NestedText
-  # Top level error for clients to rescue on.
-  # TODO hide #new so that client's cant create instance of it. Unit test this. https://ruby-doc.org/core-3.1.0/Module.html#private_class_method-method
+  # Top level error for users to rescue on.
   class Error < StandardError
     private_class_method :new
   end
 
   module Errors
     class InternalError < Error
-      public_class_method :new # Prevent clients from instansiating.
+      public_class_method :new # Prevent users from instansiating.
     end
 
-    # TODO: rename all Subclasses to ParseXError, just like for Dump
     class ParseError < InternalError
       attr_reader :lineno, :colno, :message_raw
 
@@ -55,68 +53,68 @@ module NestedText
       end
     end
 
-    class LineTagUnknown < ParseError
+    class ParseLineTagUnknownError < ParseError
       def initialize(line, tag)
         super(line, line.indentation, "The Line tag #{tag} is not among the allowed ones #{Line::ALLOWED_LINE_TAGS}")
       end
     end
 
-    class LineTagNotDetected < ParseError
+    class ParseLineTagNotDetectedError < ParseError
       def initialize(line)
         super(line, line.indentation, "unrecognized line.")
       end
     end
 
-    class LineTypeExpectedListItem < ParseError
+    class ParseLineTypeExpectedListItemError < ParseError
       def initialize(line)
         super(line, line.indentation, "expected list item.")
       end
     end
 
-    class MultilineKeyNoValue < ParseError
+    class ParseMultilineKeyNoValueError < ParseError
       def initialize(line)
         super(line, line.indentation, "multiline key requires a value.")
       end
     end
 
-    class InlineDictSyntaxError < ParseError
+    class ParseInlineDictSyntaxError < ParseError
       def initialize(line, colno, wrong_char)
         super(line, line.indentation + colno, "expected ‘,’ or ‘}’, found ‘#{wrong_char}’.")
       end
     end
 
-    class InlineDictKeySyntaxError < ParseError
+    class ParseInlineDictKeySyntaxError < ParseError
       def initialize(line, colno, wrong_char)
         super(line, line.indentation + colno, "expected ‘:’, found ‘#{wrong_char}’.")
       end
     end
 
-    class InlineMissingValue < ParseError
+    class ParseInlineMissingValueError < ParseError
       def initialize(line, colno)
         super(line, line.indentation + colno, "expected value.")
       end
     end
 
-    class InlineListSyntaxError < ParseError
+    class ParseInlineListSyntaxError < ParseError
       def initialize(line, colno, wrong_char)
         super(line, line.indentation + colno, "expected ‘,’ or ‘]’, found ‘#{wrong_char}’.")
       end
     end
 
-    class InlineNoClosingDelimiter < ParseError
+    class ParseInlineNoClosingDelimiterError < ParseError
       def initialize(line, colno)
         super(line, line.indentation + colno, "line ended without closing delimiter.")
       end
     end
 
-    class InlineExtraCharactersAfterDelimiter < ParseError
+    class ParseInlineExtraCharactersAfterDelimiterError < ParseError
       def initialize(line, colno, extra_chars)
         character_str = extra_chars.length > 1 ? "characters" : "character"
         super(line, line.indentation + colno, "extra #{character_str} after closing delimiter: ‘#{extra_chars}’.")
       end
     end
 
-    class InvalidIndentation < ParseError
+    class ParseInvalidIndentationError < ParseError
       def initialize(line, ind_exp)
         prev_line = line.prev
         if prev_line.nil? && ind_exp == 0
@@ -138,19 +136,19 @@ module NestedText
       end
     end
 
-    class LineTypeNotExpected < ParseError
+    class ParseLineTypeNotExpectedError < ParseError
       def initialize(line, type_exps, type_act)
         super(line, line.indentation, "The current line was detected to be #{type_act}, but we expected to see any of [#{type_exps.join(", ")}] here.")
       end
     end
 
-    class LineTypeExpectedDictItem < ParseError
+    class ParseLineTypeExpectedDictItemError < ParseError
       def initialize(line)
         super(line, line.indentation, "expected dictionary item.")
       end
     end
 
-    class InvalidIndentationChar < ParseError
+    class ParseInvalidIndentationCharError < ParseError
       def initialize(line)
         printable_char = line.content[0].dump.gsub(/"/, "")
 
@@ -166,19 +164,19 @@ module NestedText
       end
     end
 
-    class DictDuplicateKey < ParseError
+    class ParseDictDuplicateKeyError < ParseError
       def initialize(line)
         super(line, line.indentation, "duplicate key: #{line.attribs["key"]}.")
       end
     end
 
-    class ParseCustomClassNotFound < ParseError
+    class ParseCustomClassNotFoundError < ParseError
       def initialize(line, class_name)
         super(line, line.indentation, "Detected an encode custom class #{class_name} however we can't find it, so it can't be deserialzied.")
       end
     end
 
-    class ParseCustomClassNoCreateMethod < ParseError
+    class ParseCustomClassNoCreateMethodError < ParseError
       def initialize(line, class_name)
         super(line, line.indentation, "Detected an encode custom class #{class_name} but it does not have a #nt_create method, so it can't be deserialzied.")
       end
@@ -186,13 +184,13 @@ module NestedText
 
     class AssertionError < InternalError; end
 
-    class LineScannerIsEmpty < AssertionError
+    class AssertionLineScannerIsEmptyError < AssertionError
       def initialize
         super("There is no more input to consume. You should have checked this with #empty? before calling.")
       end
     end
 
-    class InlineScannerIsEmpty < AssertionError
+    class AssertionInlineScannerIsEmptyError < AssertionError
       def initialize
         super("There is no more input to consume. You should have checked this with #empty? before calling.")
       end
@@ -217,13 +215,13 @@ module NestedText
       end
     end
 
-    class DumpCyclicReferencesDetected < DumpError
+    class DumpCyclicReferencesDetectedError < DumpError
       def initialize(culprit)
         super(culprit, "cyclic reference found: cannot be dumped.")
       end
     end
 
-    class DumpHashKeyStrictString < DumpError
+    class DumpHashKeyStrictStringError < DumpError
       def initialize(obj)
         super(obj, "keys must be strings.")
       end
@@ -231,9 +229,9 @@ module NestedText
 
     def self.raise_unrecognized_line(line)
       # [[:space:]] include all Unicode spaces e.g. non-breakable space which \s does not.
-      raise InvalidIndentationChar, line if line.content.chr =~ /[[:space:]]/
+      raise ParseInvalidIndentationCharError, line if line.content.chr =~ /[[:space:]]/
 
-      raise LineTagNotDetected, line
+      raise ParseLineTagNotDetectedError, line
     end
 
     class UnsupportedTopLevelTypeError < InternalError
@@ -248,19 +246,19 @@ module NestedText
       end
     end
 
-    class TopLevelTypeMismatchParsedType < InternalError
+    class TopLevelTypeMismatchParsedTypeError < InternalError
       def initialize(class_exp, class_act)
         super("The requested top level class #{class_exp.name} is not the same as the actual parsed top level class #{class_act}.")
       end
     end
 
-    class DumpBadIO < InternalError
+    class DumpBadIOError < InternalError
       def initialize(io)
         super("When giving the io argument, it must be of type IO (respond to #write, #fsync). Given: #{io.class.name}")
       end
     end
 
-    class DumpFileBadPath < InternalError
+    class DumpFileBadPathError < InternalError
       def initialize(path)
         super("Must supply a string to a file path that can be written to. Given: #{path}")
       end

data/lib/nestedtext/parser.rb

@@ -7,6 +7,7 @@ require "nestedtext/scanners"
 require "nestedtext/constants"
 
 module NestedText
+  # A LL(1) recursive descent parser for NT.
   class Parser
     def self.assert_valid_top_level_type(top_class)
       unless !top_class.nil? && top_class.is_a?(Class) && TOP_LEVEL_TYPES.map(&:object_id).include?(top_class.object_id)
@@ -15,7 +16,7 @@ module NestedText
     end
 
     # TODO: document that caller is responsible for closing IO after done with Parser.
-    def initialize(io, top_class, strict: true)
+    def initialize(io, top_class, strict: false)
       assert_valid_input_type io
       Parser.assert_valid_top_level_type(top_class)
       @top_class = top_class
@@ -32,13 +33,13 @@ module NestedText
         !result.nil? && ![Hash, Array, String].include?(result.class) && @strict
       when Hash.object_id
         result = {} if result.nil?
-        raise Errors::TopLevelTypeMismatchParsedType.new(@top_class, result) unless result.instance_of?(Hash)
+        raise Errors::TopLevelTypeMismatchParsedTypeError.new(@top_class, result) unless result.instance_of?(Hash)
       when Array.object_id
         result = [] if result.nil?
-        raise Errors::TopLevelTypeMismatchParsedType.new(@top_class, result) unless result.instance_of?(Array)
+        raise Errors::TopLevelTypeMismatchParsedTypeError.new(@top_class, result) unless result.instance_of?(Array)
       when String.object_id
         result = "" if result.nil?
-        raise Errors::TopLevelTypeMismatchParsedType.new(@top_class, result) unless result.instance_of?(String)
+        raise Errors::TopLevelTypeMismatchParsedTypeError.new(@top_class, result) unless result.instance_of?(String)
       else
         raise Errors::UnsupportedTopLevelTypeError, @top_class
       end
@@ -80,8 +81,8 @@ module NestedText
         line = @line_scanner.read_next
 
         Errors.raise_unrecognized_line(line) if line.tag == :unrecognized
-        raise Errors::LineTypeExpectedListItem, line unless line.tag == :list_item
-        raise Errors::InvalidIndentation.new(line, indentation) if line.indentation != indentation
+        raise Errors::ParseLineTypeExpectedListItemError, line unless line.tag == :list_item
+        raise Errors::ParseInvalidIndentationError.new(line, indentation) if line.indentation != indentation
 
         value = line.attribs["value"]
         if value.nil?
@@ -104,8 +105,8 @@ module NestedText
         line = @line_scanner.read_next
         first_line = line if first_line.nil?
         Errors.raise_unrecognized_line(line) if line.tag == :unrecognized
-        raise Errors::InvalidIndentation.new(line, indentation) if line.indentation != indentation
-        raise Errors::LineTypeExpectedDictItem, line unless %i[dict_item key_item].include? line.tag
+        raise Errors::ParseInvalidIndentationError.new(line, indentation) if line.indentation != indentation
+        raise Errors::ParseLineTypeExpectedDictItemError, line unless %i[dict_item key_item].include? line.tag
 
         value = nil
         key = nil
@@ -129,14 +130,14 @@ module NestedText
             value = ""
           else
             unless exp_types.member?(@line_scanner.peek.tag)
-              raise Errors::LineTypeNotExpected.new(line, exp_types, line.tag)
+              raise Errors::ParseLineTypeNotExpectedError.new(line, exp_types, line.tag)
             end
-            raise Errors::MultilineKeyNoValue, line unless @line_scanner.peek.indentation > indentation
+            raise Errors::ParseMultilineKeyNoValueError, line unless @line_scanner.peek.indentation > indentation
 
             value = parse_any(@line_scanner.peek.indentation)
           end
         end
-        raise Errors::DictDuplicateKey, line if result.key? key
+        raise Errors::ParseDictDuplicateKeyError, line if result.key? key
 
         result[key] = value
       end
@@ -147,12 +148,12 @@ module NestedText
         begin
           clazz = class_name == "nil" ? NilClass : Object.const_get(class_name, false)
         rescue NameError
-          raise Errors::ParseCustomClassNotFound.new(first_line, class_name)
+          raise Errors::ParseCustomClassNotFoundError.new(first_line, class_name)
         end
         if clazz.respond_to? :nt_create
           result = clazz.nt_create(result["data"])
         else
-          raise Errors::ParseCustomClassNoCreateMethod.new(first_line, class_name)
+          raise Errors::ParseCustomClassNoCreateMethodError.new(first_line, class_name)
         end
       end
 
@@ -163,8 +164,8 @@ module NestedText
       result = []
       while !@line_scanner.peek.nil? && @line_scanner.peek.indentation >= indentation
         line = @line_scanner.read_next
-        raise Errors::InvalidIndentation.new(line, indentation) if line.indentation != indentation
-        raise Errors::LineTypeNotExpected.new(line, %i[string_item], line.tag) unless line.tag == :string_item
+        raise Errors::ParseInvalidIndentationError.new(line, indentation) if line.indentation != indentation
+        raise Errors::ParseLineTypeNotExpectedError.new(line, %i[string_item], line.tag) unless line.tag == :string_item
 
         value = line.attribs["value"]
         result << value
@@ -178,16 +179,16 @@ module NestedText
         key << @inline_scanner.read_next
       end
       if @inline_scanner.empty?
-        raise Errors::InlineNoClosingDelimiter.new(@inline_scanner.line,
-                                                   @inline_scanner.pos)
+        raise Errors::ParseInlineNoClosingDelimiterError.new(@inline_scanner.line,
+                                                             @inline_scanner.pos)
       end
 
       last_char = @inline_scanner.read_next
       if last_char == "}" && key.empty?
-        raise Errors::InlineMissingValue.new(@inline_scanner.line, @inline_scanner.pos - 1)
+        raise Errors::ParseInlineMissingValueError.new(@inline_scanner.line, @inline_scanner.pos - 1)
       end
       unless last_char == ":"
-        raise Errors::InlineDictKeySyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1, last_char)
+        raise Errors::ParseInlineDictKeySyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1, last_char)
       end
 
       key.join.strip
@@ -214,13 +215,13 @@ module NestedText
           break unless @inline_scanner.peek == ","
         end
         if @inline_scanner.empty?
-          raise Errors::InlineNoClosingDelimiter.new(@inline_scanner.line,
-                                                     @inline_scanner.pos)
+          raise Errors::ParseInlineNoClosingDelimiterError.new(@inline_scanner.line,
+                                                               @inline_scanner.pos)
         end
         last_char = @inline_scanner.read_next
         unless last_char == "}"
-          raise Errors::InlineDictSyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1,
-                                                  last_char)
+          raise Errors::ParseInlineDictSyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1,
+                                                       last_char)
         end
 
       when "["
@@ -235,17 +236,17 @@ module NestedText
           break unless @inline_scanner.peek == ","
         end
         if @inline_scanner.empty?
-          raise Errors::InlineNoClosingDelimiter.new(@inline_scanner.line,
-                                                     @inline_scanner.pos)
+          raise Errors::ParseInlineNoClosingDelimiterError.new(@inline_scanner.line,
+                                                               @inline_scanner.pos)
         end
         last_char = @inline_scanner.read_next
 
         if last_char != "]"
           if result[-1] == ""
-            raise Errors::InlineMissingValue.new(@inline_scanner.line, @inline_scanner.pos - 1)
+            raise Errors::ParseInlineMissingValueError.new(@inline_scanner.line, @inline_scanner.pos - 1)
           else
-            raise Errors::InlineListSyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1,
-                                                    last_char)
+            raise Errors::ParseInlineListSyntaxError.new(@inline_scanner.line, @inline_scanner.pos - 1,
+                                                         last_char)
           end
         end
       else # Inline string
@@ -264,8 +265,8 @@ module NestedText
       @inline_scanner = InlineScanner.new(@line_scanner.read_next)
       result = parse_inline
       unless @inline_scanner.empty?
-        raise Errors::InlineExtraCharactersAfterDelimiter.new(@inline_scanner.line, @inline_scanner.pos,
-                                                              @inline_scanner.remaining)
+        raise Errors::ParseInlineExtraCharactersAfterDelimiterError.new(@inline_scanner.line, @inline_scanner.pos,
+                                                                        @inline_scanner.remaining)
       end
       unless result.is_a? Hash
         raise Errors::AssertionError,
@@ -279,8 +280,8 @@ module NestedText
       @inline_scanner = InlineScanner.new(@line_scanner.read_next)
       result = parse_inline
       unless @inline_scanner.empty?
-        raise Errors::InlineExtraCharactersAfterDelimiter.new(@inline_scanner.line, @inline_scanner.pos,
-                                                              @inline_scanner.remaining)
+        raise Errors::ParseInlineExtraCharactersAfterDelimiterError.new(@inline_scanner.line, @inline_scanner.pos,
+                                                                        @inline_scanner.remaining)
       end
       unless result.is_a? Array
         raise Errors::AssertionError,

data/lib/nestedtext/scanners.rb

@@ -15,7 +15,7 @@ module NestedText
     end
 
     def read_next
-      raise Errors::LineScannerIsEmpty if empty?
+      raise Errors::AssertionLineScannerIsEmptyError if empty?
 
       line = @next_line
       prepare_next_line
@@ -59,7 +59,7 @@ module NestedText
     end
 
     def read_next
-      raise Errors::InlineScannerIsEmpty if empty?
+      raise Errors::AssertionInlineScannerIsEmptyError if empty?
 
       @pos += 1
       @line.content[@pos - 1]
@@ -108,7 +108,7 @@ module NestedText
 
     def tag=(tag)
       @tag = tag
-      raise Errors::LineTagUnknown.new(self, tag) unless ALLOWED_LINE_TAGS.include?(@tag)
+      raise Errors::ParseLineTagUnknownError.new(self, tag) unless ALLOWED_LINE_TAGS.include?(@tag)
     end
 
     def to_s
@@ -147,7 +147,6 @@ module NestedText
       elsif @content[0] == "{"
         self.tag = :inline_dict
       elsif @content[0] == "["
-        # TODO: merge path of inline dict and list and just set :inline?
         self.tag = :inline_list
       elsif @content =~ PATTERN_DICT_ITEM
         self.tag = :dict_item

data/lib/nestedtext/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NestedText
-  VERSION = "1.1.0"
+  VERSION = "2.0.1"
 end

data/nestedtext.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Erik Westrup"]
   spec.email         = ["erik.westrup@gmail.com"]
 
-  spec.summary       = "A ruby library implementation for the human friendly data format NestedText (https://nestedtext.org/)"
-  spec.description   = "A ruby library implementation for the human friendly data format NestedText (https://nestedtext.org/). There is support for decoding a NestedText file or string to Ruby data structures, as well as encoding Ruby objects to a NestedText file or string. Furthermore there is support for serialization and deserialization of custom classes. Support for v3.2.1 of the data format will all official tests passing."
+  spec.summary       = "A ruby library for the human friendly data format NestedText (https://nestedtext.org/)"
+  spec.description   = "A ruby library for the human friendly data format NestedText (https://nestedtext.org/). There is support for decoding a NestedText file or string to Ruby data structures, as well as encoding Ruby objects to a NestedText file or string. Furthermore there is support for serialization and deserialization of custom classes. Support for v3.2.1 of the data format will all official tests passing."
   spec.homepage      = "https://github.com/erikw/nestedtext-ruby/"
   spec.license       = "MIT"
   spec.required_ruby_version = [">= 3.0", "< 4"]
@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{\A(?:test/|script/|\.github/|\.gitmodules|Rakefile|TODO\.txt|\.codeclimate\.yml|\.vimlocal|\.simplecov)})
+      f.match(%r{\A(?:img/|test/|script/|\.github/|\.gitmodules|Rakefile|TODO\.md|\.codeclimate\.yml|\.vimlocal|\.simplecov)})
     end
   end
   spec.require_paths = ["lib"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nestedtext
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Erik Westrup
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-25 00:00:00.000000000 Z
+date: 2022-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: warning
@@ -38,11 +38,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: A ruby library implementation for the human friendly data format NestedText
-  (https://nestedtext.org/). There is support for decoding a NestedText file or string
-  to Ruby data structures, as well as encoding Ruby objects to a NestedText file or
-  string. Furthermore there is support for serialization and deserialization of custom
-  classes. Support for v3.2.1 of the data format will all official tests passing.
+description: A ruby library for the human friendly data format NestedText (https://nestedtext.org/).
+  There is support for decoding a NestedText file or string to Ruby data structures,
+  as well as encoding Ruby objects to a NestedText file or string. Furthermore there
+  is support for serialization and deserialization of custom classes. Support for
+  v3.2.1 of the data format will all official tests passing.
 email:
 - erik.westrup@gmail.com
 executables: []
@@ -63,6 +63,7 @@ files:
 - lib/nestedtext.rb
 - lib/nestedtext/constants.rb
 - lib/nestedtext/core_ext.rb
+- lib/nestedtext/core_ext_internal.rb
 - lib/nestedtext/decode.rb
 - lib/nestedtext/dumper.rb
 - lib/nestedtext/encode.rb
@@ -98,6 +99,5 @@ requirements: []
 rubygems_version: 3.3.3
 signing_key: 
 specification_version: 4
-summary: A ruby library implementation for the human friendly data format NestedText
-  (https://nestedtext.org/)
+summary: A ruby library for the human friendly data format NestedText (https://nestedtext.org/)
 test_files: []