nestedtext 2.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830cd05483344cec4a5d4132a7b6a373c81e6e48494dbf22dd29ff5ff5985599
-  data.tar.gz: 8ff4109630f482c63ddc9aac99de1a34f3dc3977c12af5a94eae266ad8a8a7d0
+  metadata.gz: 8dde068cab1260c8f534bdce49b3efea6fe1db7d30a73b180eff12d931d5a8f4
+  data.tar.gz: 325515db0115690e4aa62892e43445cc550d96346840f6404356214667b04de0
 SHA512:
-  metadata.gz: 2e10ec7ae7e7d48c5a708be79803e8048322e474301d3e499c4bdee33199e7e99c4b1d3c8de2fd9ad6055d12332745c93c108d178ff829bdf1ddee1fad243d2a
-  data.tar.gz: 247bd8a03e0c4433f10811523b1e7da9b2ac747f98c1d735a1a7efdeef23b6b8b38be360a88c82acdedba66c90f177102a04ecd85777c77cac9f9a092a3f86e2
+  metadata.gz: 1eab50ba68842d4c00011f18c3ef84d89ac848e9d7a63a821153690ba750b3f6ae707c0ef71dc211dd5c4c76b6272d1e670c0a9698db3d31fe80066500916f6f
+  data.tar.gz: efaafb7e53f31a6d9db3178befd6a9471a3677ff23122fbf1975018338c3ec35a04f12d61f4af05b9b2fd805bedf0b23f6c8fb2fa3dc12a59a5d3391ecdb1e33

data/CHANGELOG.md

@@ -6,7 +6,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.1.0] - date
+## [3.2.1] - 2022-01-27
+### Fixed
+- Fix logo at rubydoc.info
+
+## [3.2.0] - 2022-01-27
+### Changed
+- Switch from rdoc formatting syntax to Markdown with Redcarpet to be able to render README.md properly.
+
+## [3.1.0] - 2022-01-27
+### Changed
+- Switch from rdoc to YARD to match rubydoc.info that is used automatically for Gems uploaded to rubygems.org.
+
+## [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,19 +3,20 @@
 [![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)
 
 
 A ruby library for the human friendly data format [NestedText](https://nestedtext.org/).
 
+<!-- Use URL to hosetd image, so that it shows up at rubydocs.info as well. Using relative image and yardoc option "--asset img:img" did not work. -->
 <a href="#" ><img src="https://raw.githubusercontent.com/erikw/nestedtext-ruby/main/img/logo.webp" align="right" width="420px" alt="Project logo" /></a>
 
 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).
@@ -56,7 +57,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 +79,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,11 +109,10 @@ 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:
 
-```irb
+```ruby
 irb> require 'nestedtext'
 irb> puts "a\nstring".to_nt
 > a
@@ -132,7 +121,10 @@ irb> puts ["i1", "i2", "i3"].to_nt
 - i1
 - i2
 - i3
-irb> puts({"k1" => "v1", "multiline\nkey" => "v2", "k3" => ["a", "list"]}.to_nt)
+irb> hash = {"k1" => "v1",
+            "multiline\nkey" => "v2",
+            "k3" => ["a", "list"]}
+irb> puts hash.to_nt
 k1: v1
 : multiline
 : key
@@ -142,9 +134,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 +220,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 +232,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,19 +1,28 @@
 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
+# Extended with the `#to_nt` method.
+class String include NestedText::NTEncodeMixin; end
 
+# Extended with the `#to_nt` method.
+class Array include NestedText::NTEncodeMixin; end
+
+# Extended with the `#to_nt` method.
+class Hash include NestedText::NTEncodeMixin; end
+
+# Extended with NestedText support.
 class NilClass
-  include NT_MIXIN
+  include NestedText::NTEncodeMixin
 
+  # Adds support for encoding and decoding nil.
   def self.nt_create(_data) = nil
 
+  # Adds support for encoding and decoding nil.
   def encode_nt_with() = ""
 end

data/lib/nestedtext/decode.rb

@@ -1,18 +1,37 @@
 # 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.
+  #
+  # @param ntstring [String] The string containing NestedText to be decoded.
+  # @param top_class [String] Force the top level returned object to be of this type. Supported values are `Object`, `Array`, `Hash` and `String`.
+  # @param strict [Boolean] If strict mode should be used.
+  #
+  # @return [Object, nil] The parsed object.
+  #
+  # @raise [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.
+  #
+  # @param filename [String] The file path to read NestedText to decode from.
+  # @param top_class [String] Force the top level returned object to be of this type. Supported values are `Object`, `Array`, `Hash` and `String`.
+  # @param strict [Boolean] If strict mode should be used.
+  #
+  # @return [Object, nil] The parsed object.
+  #
+  # @raise [NestedText::Error] if anything went wrong.
+  # @raise [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,20 @@
 # 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.
+  #
+  # @param obj [Object] The object to encode to NestedText.
+  # @param io [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.
+  # @param indentation [Integer] The indentation of nested levels to use.
+  # @param strict [Boolean] If strict mode should be used.
+  #
+  # @return A String containing NestedText data.
+  # @raise [NestedText::Error] if anything went wrong.
+  # @raise Whatever the `io` can raise, if supplied.
   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 +26,18 @@ module NestedText
     dumper.dump obj
   end
 
+  # Encode a Ruby object to a NestedText file.
+
+  # Apart from `filename`, this method behaves exactly like dump.
+  #
+  # @param (see dump)
+  # @param filename [String] The file path to write the NestedText result to. The conventional file extension is `.nt`.
+  #
+  #
+  # @return (see dump)
+  # @raise (see dump)
+  # @raise [IOError] on issues opening the `filename` for writing in text mode.
+  #
   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 named 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.2.1"
 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 {file: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.2.1
 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