nestedtext 3.2.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dde068cab1260c8f534bdce49b3efea6fe1db7d30a73b180eff12d931d5a8f4
-  data.tar.gz: 325515db0115690e4aa62892e43445cc550d96346840f6404356214667b04de0
+  metadata.gz: 195cf273687c9cf4af35eaea661eef6086bdb8b1f47578092e7473a4cb56a418
+  data.tar.gz: 32ca43c2433eea7065cd56e2809c85accd1165a3bf734e5ba0525fe3a256f56a
 SHA512:
-  metadata.gz: 1eab50ba68842d4c00011f18c3ef84d89ac848e9d7a63a821153690ba750b3f6ae707c0ef71dc211dd5c4c76b6272d1e670c0a9698db3d31fe80066500916f6f
-  data.tar.gz: efaafb7e53f31a6d9db3178befd6a9471a3677ff23122fbf1975018338c3ec35a04f12d61f4af05b9b2fd805bedf0b23f6c8fb2fa3dc12a59a5d3391ecdb1e33
+  metadata.gz: 8869b326141ccf9e56653bade9795f5a110f45d628df8eb1c372763a7cf5bfe7cb8a1077ff0fb36e5b0ec466f5f9f286fe877e1aaf1a4af3271c4ce5f8f718ed
+  data.tar.gz: ac63098b99b0d5d4f2060ecae53d8f325ca64af240e7250e07f3757088d7aee9ef81f495f8b4969b7a139f373b2c77d8c0711d947421ef41075f6671b2d9c453

data/CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.0] - 2022-01-28
+### Changed
+- **Breaking change**: Renamed `NTEncodeMixin` to `ToNTMixin`.
+- All code linted with RuboCop
+
 ## [3.2.1] - 2022-01-27
 ### Fixed
 - Fix logo at rubydoc.info
@@ -26,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
+- **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 Custom Objects and calling the method on the array.
 - Internal clean-up and simplifications on helper classes and methods.
 
 ## [2.1.0] - 2022-01-27
@@ -49,7 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.1.1] - 2022-01-25
 ### Fixed
-- Renamed `NTEncodeMixing` to `NTEncodeMixin` .
+- Renamed `ToNTMixing` to `ToNTMixin` .
 
 ## [1.1.0] - 2022-01-25
 ### Added
@@ -70,13 +75,13 @@ The library is now useful for users!
 - Publish Gem to GitHub Packages
 
 ## [0.4.0] - 2022-01-24
-- Iteration on CD GitHub Actins workflow.
+- Iteration on CD GitHub Actions workflow.
 
 ## [0.3.0] - 2022-01-24
-- Iteration on CD GitHub Actins workflow.
+- Iteration on CD GitHub Actions workflow.
 
 ## [0.2.0] - 2022-01-24
-- Iteration on CD GitHub Actins workflow.
+- Iteration on CD GitHub Actions workflow.
 
 ## [0.1.0] - 2022-01-24
 ### Added

data/README.md

@@ -1,7 +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/)
+[![Documentation](https://img.shields.io/badge/docs-API-informational?logo=readthedocs&logoColor=violet)](https://www.rubydoc.info/gems/nestedtext/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/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)
@@ -16,8 +16,8 @@
 
 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>
+<!-- Use URL to hosted 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="nestedtext-ruby 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).
 
@@ -57,7 +57,7 @@ vice president:
 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).
+The **full API documentation** can be found at [rubydocs.info](https://www.rubydoc.info/gems/nestedtext/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:
@@ -172,7 +172,7 @@ Other Class | String | `#to_s` will be called if there is no `#encode_nt_with`
 ## 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.
+A class implementing `#encode_nt_with` is referred to as `Custom Class` in this document.
 
 ```ruby
 class Apple
@@ -221,10 +221,10 @@ data:
     - 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`:
+If you want to add some more super powers to your custom class, you can add the `#to_nt` shortcut by including the `ToNTMixin`:
 ```ruby
 class Apple
-  include NestedText::NTEncodeMixin
+  include NestedText::ToNTMixin
   ...
 end
 
@@ -278,12 +278,15 @@ See [encode_custom_classes_test.rb](test/nestedtext/encode_custom_classes_test.r
 1. For local testing, install the gem on local machine with: `$ bundle exec rake install`.
    * or manually with `$ gem build *.gemscpec && gem install *.gem`
 
-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)
-```
+
+Extra:
+* 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)
+   ```
+* To see undocumented methods with [YARD](https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md): `$ yard stats --list-undoc`
 
 # 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.

data/lib/nestedtext/constants.rb

@@ -1,7 +1,10 @@
-require "stringio"
+# frozen_string_literal: true
+
+require 'stringio'
+
 module NestedText
-  TOP_LEVEL_TYPES = [Object, Hash, Array, String]
-  CUSTOM_CLASS_KEY = "__nestedtext_class__"
+  TOP_LEVEL_TYPES = [Object, Hash, Array, String].freeze
+  CUSTOM_CLASS_KEY = '__nestedtext_class__'
 
   private_constant :TOP_LEVEL_TYPES, :CUSTOM_CLASS_KEY
 end

data/lib/nestedtext/core_ext.rb

@@ -1,28 +1,23 @@
-require "nestedtext/encode_helpers"
+# frozen_string_literal: true
 
-# 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?
+require 'nestedtext/encode_helpers'
 
 # Extended with the `#to_nt` method.
-class String include NestedText::NTEncodeMixin; end
+class String include NestedText::ToNTMixin; end
 
 # Extended with the `#to_nt` method.
-class Array include NestedText::NTEncodeMixin; end
+class Array include NestedText::ToNTMixin; end
 
 # Extended with the `#to_nt` method.
-class Hash include NestedText::NTEncodeMixin; end
+class Hash include NestedText::ToNTMixin; end
 
 # Extended with NestedText support.
 class NilClass
-  include NestedText::NTEncodeMixin
+  include NestedText::ToNTMixin
 
   # Adds support for encoding and decoding nil.
   def self.nt_create(_data) = nil
 
   # Adds support for encoding and decoding nil.
-  def encode_nt_with() = ""
+  def encode_nt_with() = ''
 end

data/lib/nestedtext/core_ext_internal.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 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
+        # Windows/Mac -> Unix
         gsub(/\r\n?/, "\n")
       end
     end

data/lib/nestedtext/decode.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require "nestedtext/parser"
-require "nestedtext/errors_internal"
+require 'nestedtext/parser'
+require 'nestedtext/errors_internal'
 
-require "logger"
-require "stringio"
+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 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.
@@ -19,13 +20,14 @@ module NestedText
   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
+    Parser.new(StringIO.new(ntstring), top_class, 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 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.
@@ -36,8 +38,8 @@ module NestedText
     raise Errors::WrongInputTypeError.new([String], filename) unless !filename.nil? && filename.is_a?(String)
 
     # Open explicitly in text mode to detect \r as line ending.
-    File.open(filename, mode = "rt") do |file|
-      Parser.new(file, top_class, strict: strict).parse
+    File.open(filename, 'rt') do |file|
+      Parser.new(file, top_class, strict:).parse
     end
   end
 end

data/lib/nestedtext/dumper.rb

@@ -1,10 +1,12 @@
-require "nestedtext/core_ext_internal"
+# frozen_string_literal: true
+
+require 'nestedtext/core_ext_internal'
 
 module NestedText
   using NestedText.const_get(:CoreExtInternal)
 
   # Dumping with recursive DFS traversal of the object references.
-  class Dumper
+  class Dumper # rubocop:disable Metrics/ClassLength
     def initialize(indentation, strict)
       @indentation = indentation
       @strict = strict
@@ -18,31 +20,31 @@ module NestedText
       dump_any obj
     end
 
-    private
-
     def self.add_prefix(prefix, target)
       if target.empty? || target[0] == "\n"
-        target.prepend(prefix)
+        "#{prefix}#{target}"
       else
-        target.prepend(prefix, " ")
+        "#{prefix} #{target}"
       end
     end
 
     def self.multiline_key?(key)
-      syntax1 = "{[#"
-      syntax2 = ":->"
+      syntax1 = '{[#'
+      syntax2 = ':->'
 
       key.empty? ||
         key != key.strip ||
         key.include?("\n") ||
-        key.include?(": ") ||
+        key.include?(': ') ||
         syntax1.include?(key.lstrip[0]) ||
-        syntax2.include?(key.lstrip[0]) && key.lstrip[1] == " "
+        (syntax2.include?(key.lstrip[0]) && key.lstrip[1] == ' ')
     end
 
+    private
+
     def convert_key(key)
       if key.nil?
-        ""
+        ''
       elsif key.is_a? String
         key.normalize_line_endings
       elsif !@strict
@@ -52,10 +54,11 @@ module NestedText
       end
     end
 
-    def indent(target)
-      indentstr = " " * @indentation
-      indented = "\n" + target.lines.map { |line| indentstr + line }.join
-      target.replace indented
+    def indent(target, depth)
+      return target unless depth.positive?
+
+      indentstr = ' ' * @indentation
+      "\n#{target.lines.map { |line| indentstr + line }.join}"
     end
 
     def trace_cycles(obj)
@@ -81,77 +84,79 @@ module NestedText
     def dump_any(obj, depth: 0, **kwargs)
       trace_cycles(obj) do
         case obj
-        when Hash then dump_hash(obj, depth: depth, **kwargs)
-        when Array then dump_array(obj, depth: depth, **kwargs)
-        when String then dump_string(obj, depth: depth, **kwargs)
+        when Hash then dump_hash(obj, depth:, **kwargs)
+        when Array then dump_array(obj, depth:, **kwargs)
+        when String then dump_string(obj, depth:, **kwargs)
         when nil
-          @strict ? "" : dump_custom_class(nil, depth: depth, **kwargs)
+          @strict ? '' : dump_custom_class(nil, depth:, **kwargs)
         else
-          dump_custom_class(obj, depth: depth, **kwargs)
+          dump_custom_class(obj, depth:, **kwargs)
         end
       end
     end
 
-    def dump_hash(obj, depth: 0, **kwargs)
-      rep = if obj.empty?
-              "{}"
-            else
-              obj.map do |key, value|
-                trace_keys(key) do
-                  key = convert_key(key)
-
-                  if Dumper.multiline_key?(key)
-                    key_lines = key.empty? ? [""] : key.lines
-                    key_lines << "" if key_lines[-1][-1] =~ /\n|\r/
-                    rep_key = key_lines.map { |line| Dumper.add_prefix(":", line) }.join
-                    force_multiline = value.is_a? String
-                    rep_value = dump_any(value, depth: depth + 1, force_multiline: force_multiline, **kwargs)
-                  else
-                    rep_key = "#{key}:"
-                    rep_value = dump_any(value, depth: depth + 1, **kwargs)
-                    rep_key += " " unless rep_value.empty? || rep_value.include?("\n")
-                  end
-                  "#{rep_key}#{rep_value}"
-                end
-              end.join("\n")
-            end
-      indent(rep) if depth > 0
-      rep
+    def dump_hash_key_multiline(key, value, depth, **kwargs)
+      key_lines = key.empty? ? [''] : key.lines
+      key_lines << '' if key_lines[-1][-1] =~ /\n|\r/
+      rep_key = key_lines.map { |line| Dumper.add_prefix(':', line) }.join
+      rep_value = dump_any(value, depth: depth + 1, force_multiline: value.is_a?(String), **kwargs)
+      [rep_key, rep_value].join
     end
 
-    def dump_array(obj, depth: 0, **kwargs)
-      rep = if obj.empty?
-              # TODO: replace this special case with simply general inline rendering detection.
-              "[]"
+    def dump_hash_key(key, value, depth, **kwargs)
+      rep_key = "#{key}:"
+      rep_value = dump_any(value, depth: depth + 1, **kwargs)
+      rep_key += ' ' unless rep_value.empty? || rep_value.include?("\n")
+      [rep_key, rep_value].join
+    end
+
+    def dump_hash_items(hash, depth, **kwargs)
+      hash.map do |key, value|
+        trace_keys(key) do
+          key = convert_key(key)
+          if Dumper.multiline_key?(key)
+            dump_hash_key_multiline(key, value, depth, **kwargs)
+          else
+            dump_hash_key(key, value, depth, **kwargs)
+          end
+        end
+      end.join("\n")
+    end
+
+    def dump_hash(hash, depth: 0, **kwargs)
+      rep = hash.empty? ? '{}' : dump_hash_items(hash, depth, **kwargs)
+      indent(rep, depth)
+    end
+
+    def dump_array(array, depth: 0, **kwargs)
+      rep = if array.empty?
+              '[]'
             else
-              obj.each_with_index.map do |e, i|
+              array.each_with_index.map do |e, i|
                 trace_keys(i) do
-                  e_rep = dump_any(e, depth: depth + 1, **kwargs)
-                  Dumper.add_prefix("-", e_rep)
+                  Dumper.add_prefix('-', dump_any(e, depth: depth + 1, **kwargs))
                 end
               end.join("\n")
             end
 
-      indent(rep) if depth > 0
-      rep
+      indent(rep, depth)
     end
 
-    def dump_string(obj, depth: 0, force_multiline: false)
-      obj = obj.normalize_line_endings
-      lines = obj.lines
-      lines << "\n" if !lines.empty? && lines[-1][-1] == "\n"
-      if lines.length > 1 || depth == 0 || force_multiline
-        lines.each do |line|
-          Dumper.add_prefix(">", line)
-        end
-      end
+    def prefix_lines(lines, depth, multiline)
+      lines = lines.map { |line| Dumper.add_prefix('>', line) } if multiline || depth.zero?
+      lines << '>' if lines.empty? && (depth.zero? || multiline)
+      lines
+    end
+
+    def dump_string(string, depth: 0, force_multiline: false)
+      lines = string.normalize_line_endings.lines
+      lines << '' if !lines.empty? && lines.last[-1] == "\n"
+      multiline = lines.length > 1 || force_multiline
 
-      # Case of empty input string. No space after '>'
-      lines << ">" if lines.empty? && (depth == 0 || force_multiline)
+      lines = prefix_lines(lines, depth, multiline)
 
       rep = lines.join.chomp
-      indent(rep) if !rep.empty? && depth > 0 && (rep.include?("\n") || force_multiline)
-      rep
+      multiline ? indent(rep, depth) : rep
     end
 
     def dump_custom_class(obj, **kwargs)
@@ -160,8 +165,8 @@ module NestedText
       if obj.is_a? Symbol
         dump_string(obj.id2name, **kwargs)
       elsif obj.respond_to? :encode_nt_with
-        class_name = obj.nil? ? "nil" : obj.class.name
-        enc = { CUSTOM_CLASS_KEY => class_name, "data" => obj.encode_nt_with }
+        class_name = obj.nil? ? 'nil' : obj.class.name
+        enc = { CUSTOM_CLASS_KEY => class_name, 'data' => obj.encode_nt_with }
         dump_any(enc, **kwargs)
       else
         dump_string(obj.to_s, **kwargs)

data/lib/nestedtext/encode.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
-require "nestedtext/dumper"
-require "nestedtext/errors_internal"
+require 'nestedtext/dumper'
+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 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.
+  # @return [String, nil] A String containing NestedText data, or nil when obj is represented as empty.
   # @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)
-    raise Errors::DumpBadIOError, 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))
 
     dumper = Dumper.new(indentation, strict)
     result = dumper.dump obj
@@ -41,7 +42,7 @@ module NestedText
   def self.dump_file(obj, filename, **kwargs)
     raise Errors::DumpFileBadPathError, filename unless filename.is_a? String
 
-    File.open(filename, mode = "wt") do |file|
+    File.open(filename, 'wt') do |file|
       dump(obj, io: file, **kwargs)
     end
   end

data/lib/nestedtext/encode_helpers.rb

@@ -1,9 +1,10 @@
-require "nestedtext/dumper"
+# frozen_string_literal: true
+
+require 'nestedtext/dumper'
 
 module NestedText
   # A mixin for Custom Classes to get the to_nt shortcut.
-  # TODO rename to: ToNTMixin
-  module NTEncodeMixin
+  module ToNTMixin
     # Encode this object to a NestedText string.
     #
     # This method takes the same named arguments as {NestedText.dump}.

data/lib/nestedtext/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module NestedText
   # Top level error to rescue on.
   #