nestedtext 2.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830cd05483344cec4a5d4132a7b6a373c81e6e48494dbf22dd29ff5ff5985599
-  data.tar.gz: 8ff4109630f482c63ddc9aac99de1a34f3dc3977c12af5a94eae266ad8a8a7d0
+  metadata.gz: bfafdf3e9638459777da2f7209954955473758103c72533b58a66cc23f4020e3
+  data.tar.gz: 400fd879811f4d09c193da219ffa0ff61853ee0e51baac386c58b7016dfbe354
 SHA512:
-  metadata.gz: 2e10ec7ae7e7d48c5a708be79803e8048322e474301d3e499c4bdee33199e7e99c4b1d3c8de2fd9ad6055d12332745c93c108d178ff829bdf1ddee1fad243d2a
-  data.tar.gz: 247bd8a03e0c4433f10811523b1e7da9b2ac747f98c1d735a1a7efdeef23b6b8b38be360a88c82acdedba66c90f177102a04ecd85777c77cac9f9a092a3f86e2
+  metadata.gz: 708025814b4038b1b5c6eea70378762e1155ae73e933cc902a17d26d4ce3efbb2a5b52f7d535c385818e34484fe12278f981c253469d80a875e97aa8f25b20c1
+  data.tar.gz: fe87505719301bf79a71cdef1c9d89d71f9058318f5f59f1305ac79b0b69007b79976d6e288a4846824c6cc89323021b4b29df56b8f14f534cd59906d55b0843

data/CHANGELOG.md

@@ -6,7 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.1.0] - date
+## [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.
 

data/README.md

@@ -3,13 +3,13 @@
 [![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)](#)
+[![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)
 
@@ -56,7 +56,7 @@ vice president:
 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).
+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:
@@ -78,17 +78,6 @@ 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: true`, otherwise Ruby Symbols are encoded as Custom Class (see below).
-*empty*     |  `nil`    | when `strict: true`, otherwise as Custom Class. 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
@@ -119,7 +108,6 @@ 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:
 
@@ -142,9 +130,46 @@ k3:
     - 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. 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)
@@ -191,7 +216,6 @@ 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
@@ -204,13 +228,16 @@ 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.
+**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')
-```
+  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.
 

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/decode.rb

@@ -1,18 +1,38 @@
 # frozen_string_literal: true
 
 require "nestedtext/parser"
-require "nestedtext/errors"
+require "nestedtext/errors_internal"
 
 require "logger"
 require "stringio"
 
 module NestedText
+  # 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
 
+  # 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)
 

data/lib/nestedtext/dumper.rb

@@ -92,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,16 +1,22 @@
 # frozen_string_literal: true
 
-require "nestedtext/errors"
 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
+  # 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)
-    # io - additionaly write the out result to IO and still return result.
-
     raise Errors::DumpBadIOError, io unless io.nil? || io.respond_to?(:write) && io.respond_to?(:fsync)
 
     dumper = Dumper.new(indentation, strict)
@@ -22,6 +28,13 @@ module NestedText
     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::DumpFileBadPathError, filename unless filename.is_a? String
 

data/lib/nestedtext/encode_helpers.rb

@@ -1,16 +1,14 @@
 require "nestedtext/dumper"
 
 module NestedText
-  module NTEncodeStrictMixin
-    def to_nt(**kwargs)
-      NestedText.dump(self, strict: true, **kwargs)
-    end
-  end
-  private_constant :NTEncodeStrictMixin
-
+  # A mixin for Custom Classes to get the to_nt shortcut.
+  # TODO rename to: ToNTMixin
   module NTEncodeMixin
+    # Encode this object to a NestedText string.
+    #
+    # This method takes the same arguments as NestedText::dump.
     def to_nt(**kwargs)
-      NestedText.dump(self, **kwargs)
+      NestedText.dump(self, strict: false, **kwargs)
     end
   end
 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

data/lib/nestedtext/{errors.rb → errors_internal.rb}

@@ -4,13 +4,9 @@ require "word_wrap"
 require "word_wrap/core_ext"
 
 require "nestedtext/constants"
+require "nestedtext/error"
 
 module NestedText
-  # 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 users from instansiating.

data/lib/nestedtext/parser.rb

@@ -2,7 +2,7 @@
 
 require "stringio"
 
-require "nestedtext/errors"
+require "nestedtext/errors_internal"
 require "nestedtext/scanners"
 require "nestedtext/constants"
 
@@ -15,7 +15,6 @@ module NestedText
       end
     end
 
-    # TODO: document that caller is responsible for closing IO after done with Parser.
     def initialize(io, top_class, strict: false)
       assert_valid_input_type io
       Parser.assert_valid_top_level_type(top_class)

data/lib/nestedtext/scanners.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "nestedtext/errors"
+require "nestedtext/errors_internal"
 
 module NestedText
   class LineScanner

data/lib/nestedtext/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module NestedText
-  VERSION = "2.1.0"
+  # The version of this library.
+  VERSION = "3.0.0"
 end

data/lib/nestedtext.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
-require_relative "nestedtext/encode"
-require_relative "nestedtext/decode"
 require_relative "nestedtext/core_ext"
+require_relative "nestedtext/decode"
+require_relative "nestedtext/encode"
+require_relative "nestedtext/encode_helpers"
+require_relative "nestedtext/error"
 require_relative "nestedtext/version"
 
+##
+# = NestedText
+# The main module in this library to use.
+#
+# See README.md for documentation on Types, Strict Mode and Custom Classes.
 module NestedText
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nestedtext
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Erik Westrup
@@ -62,7 +62,8 @@ files:
 - lib/nestedtext/dumper.rb
 - lib/nestedtext/encode.rb
 - lib/nestedtext/encode_helpers.rb
-- lib/nestedtext/errors.rb
+- lib/nestedtext/error.rb
+- lib/nestedtext/errors_internal.rb
 - lib/nestedtext/parser.rb
 - lib/nestedtext/scanners.rb
 - lib/nestedtext/version.rb