nestedtext 1.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f5f6f0ac6182999d4036976103b740552796029ffe77749a8cdf5d0d8d0167
-  data.tar.gz: c06dd5613b6c5296398a838e2419dd2addaf34b9712a1baec36ecd23e5d4c6f9
+  metadata.gz: bfafdf3e9638459777da2f7209954955473758103c72533b58a66cc23f4020e3
+  data.tar.gz: 400fd879811f4d09c193da219ffa0ff61853ee0e51baac386c58b7016dfbe354
 SHA512:
-  metadata.gz: 0dc821033f7813441756fcfb04e9b6a442993130462ff2572c7401b634149b538be4a831a7deb5fdb91a432be5f795d37b473fc6ac4dad5eb1e8b9c88762a5f9
-  data.tar.gz: ba7d69e4bfb3929c5dd5e0f037e88b7b13fac466aa011bccacf8095812f990c1e32b8c449df721514414cc8ce0b1c6f11723644cce13a5ee4330f549c793ee56
+  metadata.gz: 708025814b4038b1b5c6eea70378762e1155ae73e933cc902a17d26d4ce3efbb2a5b52f7d535c385818e34484fe12278f981c253469d80a875e97aa8f25b20c1
+  data.tar.gz: fe87505719301bf79a71cdef1c9d89d71f9058318f5f59f1305ac79b0b69007b79976d6e288a4846824c6cc89323021b4b29df56b8f14f534cd59906d55b0843

data/CHANGELOG.md

@@ -6,6 +6,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2022-01-27
+### Added
+- API documentation generated with rdoc.
+
+### Fixed
+- Removed leaked `NT_MIXIN` constant in core extensions.
+
+### Changed
+- **Breaking change**: `#to_nt` on `String`, `Array` and `Hash` is no longer strict by default for consistency an unexpected surprises e.g. when having an array of CustomObjects and calling the method on the array.
+- Internal clean-up and simplifications on helper classes and methods.
+
+## [2.1.0] - 2022-01-27
+### Changed
+- Slim down Gem by using include instead of block list.
+
+## [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.

data/CONTRIBUTING.md

@@ -1,4 +1,4 @@
 # How to contribute
 Please use GitHub tooling (issues, PRs) to disucssion and code contributions!
 
-When you open an PR, Travis will build your code, run tests, liters and so on.
+When you open an PR, GitHub Actions will build your code, run tests, liters and so on.

data/README.md

@@ -1,43 +1,116 @@
 # 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)
+[![Official Tests](https://img.shields.io/badge/Official%20Tests-Passing-success?logo=cachet)](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)
 [![GitHub Actions: Continuous Deployment](https://github.com/erikw/nestedtext-ruby/actions/workflows/cd.yml/badge.svg)](https://github.com/erikw/nestedtext-ruby/actions/workflows/cd.yml)
 [![GitHub Actions: CodeQL Analysis](https://github.com/erikw/nestedtext-ruby/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/erikw/nestedtext-ruby/actions/workflows/codeql-analysis.yml)
 [![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)
+[![SLOC](https://img.shields.io/tokei/lines/github/erikw/nestedtext-ruby?logo=codefactor&logoColor=lightgrey)](#)
+[![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 API documentation can be found at [**rubydocs.info**](https://www.rubydoc.info/gems/nestedtext/). 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
+```
+
+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 +120,136 @@ 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
 ```
+
+## Types
+Ruby classes maps like this to NestedText types:
+Ruby | [NestedText](https://nestedtext.org/en/latest/basic_syntax.html)
+---|---
+`String`  |`String`
+`Array`   |`List`
+`Hash`    |`Dictionary`
+
+
+### Strict Mode
+The strict mode determines how classes other than the basic types `String`, `Array` and `Hash` are handled during encoding and decoding. By **default** strict mode is turned **off**.
+
+With `strict: true`
+Ruby | NestedText | Comment
+---|---|---
+`nil`        |*empty*  | (1.)
+`Symbol`     |`String` | Raises `NestedText::Error`
+Other Class | --      | Raises `NestedText::Error`
+
+
+With `strict: false`
+Ruby | NestedText | Comment
+---|---|---
+`nil`        | *Custom Class Encoding* | (1.)
+`Symbol`     | `String` |
+Custom Class | *Custom Class Encoding* | If the [Custom Class](#custom-classes-serialization) implements `#encode_nt_with` (2.)
+Other Class | String | `#to_s` will be called if there is no `#encode_nt_with`
+
+
+* (1.) How empty strings and nil are handled depends on where it is used. This library follows how the official implementation does it.
+
+
+
+
+
 ## 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.
+
+A class implementing `#encode_nt_with` is refered to as `Custom Class` in this document.
+
+```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
+```
+
+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
+```
+
+
+**Important notes**:
+* The special key to denote the class name is subject to change in future versions and you **must not** rely on it.
+* Custom Classes **can not be a key** in a Hash. Trying to do this will raise an Error.
+* 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 +268,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 +310,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 +319,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.1.1 | :x:                |
+| 2.x.x   | :white_check_mark: |
+| < 2.0.0 | :x:                |
 
 
 ## Reporting a Vulnerability

data/lib/nestedtext/core_ext.rb

@@ -1,17 +1,18 @@
 require "nestedtext/encode_helpers"
 
+# Extension of Ruby core types with the NestedText::NTEncodeMixin.
+#
 # TODO: add encoding of more Ruby native classes like Integer, Float etc plus commons like Set,....? Not covered in NestedText language.
 # Or leave this to a schema validator 3rd party plugin maybe? And replace my custom class decoding (and also encoding?)?
 # 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(:NTEncodeStrictMixin)
-class String include NT_MIXIN end
-class Array include NT_MIXIN end
-class Hash include NT_MIXIN end
+class String include NestedText::NTEncodeMixin; end
+class Array include NestedText::NTEncodeMixin; end
+class Hash include NestedText::NTEncodeMixin; end
 
 class NilClass
-  include NT_MIXIN
+  include NestedText::NTEncodeMixin
 
   def self.nt_create(_data) = nil
 

data/lib/nestedtext/core_ext_internal.rb

@@ -1,5 +1,5 @@
 module NestedText
-  # Hiding extensions for Kernel here away from clients.
+  # 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

data/lib/nestedtext/decode.rb

@@ -1,19 +1,39 @@
 # frozen_string_literal: true
 
 require "nestedtext/parser"
-require "nestedtext/errors"
+require "nestedtext/errors_internal"
 
 require "logger"
 require "stringio"
 
 module NestedText
-  def self.load(ntstring, top_class: Object, strict: true)
+  # Decode a NestedText string to Ruby objects.
+  #
+  # [ntstring] The string containing NestedText to be decoded.
+  # [top_class] Force the top level returned object to be of this type. Supported values are +Object+, +Array+, +Hash+ and +String+. Default is +Object+.
+  # [strict] If strict mode should be used. +true+ or +false+. Default is +false+
+  #
+  # Returns the parsed object.
+  #
+  # Raises NestedText::Error if anything went wrong.
+  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)
+  # Decode a NestedText stored in a given file.
+
+  # [filename] The file path to read NestedText to decode from.
+  # [top_class] Force the top level returned object to be of this type. Supported values are +Object+, +Array+, +Hash+ and +String+. Default is +Object+.
+  # [strict] If strict mode should be used. +true+ or +false+. Default is +false+
+  #
+  # Returns the parsed object.
+  #
+  # Raises NestedText::Error if anything went wrong.
+  #
+  # Raises +IOError+ on issue opening +filename+ for reading in text mode.
+  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

@@ -3,17 +3,18 @@ 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
 
@@ -47,7 +48,7 @@ module NestedText
       elsif !@strict
         key.to_s
       else
-        raise Errors::DumpHashKeyStrictString, key
+        raise Errors::DumpHashKeyStrictStringError, key
       end
     end
 
@@ -57,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)
@@ -93,7 +92,6 @@ module NestedText
       end
     end
 
-    # 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,32 +1,42 @@
 # frozen_string_literal: true
 
-require "nestedtext/errors"
-require "nestedtext/encode_helpers"
 require "nestedtext/dumper"
-
-# Model after JSON
-# NestedText.dump(obj, io=nil) => dumps to string, or to IO if given
-# NestedText.dump_file(obj, filename)
+require "nestedtext/errors_internal"
 
 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)
-    # 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)
+  # Encode a Ruby object to a NestedText string.
+  #
+  # [obj] The object to encode to NestedText.
+  # [io] Additionally write the output to this IO object. The caller is responsible for that the IO is closed after the call to this method.
+  # [indentation] The indentation of nested levels to use.
+  # [strict] If strict mode should be used. +true+ or +false+. Default is +false+
+  #
+  # Returns a String containing NestedText data.
+  #
+  # Raises NestedText::Error if anything went wrong.
+  #
+  # Raises whatever the passed +io+ can raise.
+  def self.dump(obj, io: nil, indentation: 4, strict: false)
+    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
 
+  # Encode a Ruby object to a NestedText file.
+  #
+  # [filename] The file path to write the NestedText result to. The conventional file extension is +.nt+.
+  #
+  # Raises +IOError+ on issues opening the +filename+ for writing in text mode.
+  #
+  # Apart from +filename+, this method behaves exactly like dump (taking same arguments, returning and raising the same values).
   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,26 +1,14 @@
 require "nestedtext/dumper"
 
 module NestedText
-  module NTEncodeStrictMixin
-    def to_nt(indentation: 4, strict: true)
-      Dumper.new(EncodeOptions.new(indentation, strict)).dump self
-    end
-  end
-  private_constant :NTEncodeStrictMixin
-
+  # A mixin for Custom Classes to get the to_nt shortcut.
+  # TODO rename to: ToNTMixin
   module NTEncodeMixin
-    def to_nt(indentation: 4)
-      Dumper.new(EncodeOptions.new(indentation, false)).dump self
-    end
-  end
-
-  class EncodeOptions
-    attr_reader :indentation, :strict
-
-    def initialize(indentation = 4, strict = true)
-      @indentation = indentation
-      @strict = strict
+    # Encode this object to a NestedText string.
+    #
+    # This method takes the same arguments as NestedText::dump.
+    def to_nt(**kwargs)
+      NestedText.dump(self, strict: false, **kwargs)
     end
   end
-  private_constant :EncodeOptions
 end

data/lib/nestedtext/error.rb

@@ -0,0 +1,8 @@
+module NestedText
+  # Top level error to rescue on.
+  #
+  # +Error+ is a subclass of +StandardError+ and behaves as expected e.g. +#message+.
+  class Error < StandardError
+    private_class_method :new
+  end
+end