nestedtext 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ffd37e7360f79d6b9bd1dec3ca7687ea16d5e44f3a8ff0286af9df02307b04b
-  data.tar.gz: 6bd6979a011e1072cc9fea0e23b429792576b728b011d58efeb397d66dac809f
+  metadata.gz: 74caf2136f95b24dc7b72d92e869c59992e7a573258d50c33762ade211f289fc
+  data.tar.gz: 9a185f16e4ecf87166fd90e47487a1bbff690713479049503b8b63594889c296
 SHA512:
-  metadata.gz: 951bb426600944496e51b96ce51b7315baec4c54e55bf78c67cc72db222a18a70a1a328e5c29d0a48764bdc3413fe0fd674f2f23e58e04a909a057ac3d8a5165
-  data.tar.gz: b1cdc7c5f13b2e7846918e20707969e8cc636d4b3390622ce6914b6d785888b4319627af040a7bda95a4883c3818ae9bb83852b86d23262f325d5588bbe56191
+  metadata.gz: 49da0bd5404cc394f0ab0bf746da45fad947502bdb7c9a5017df44c5a7fff0bfc25a3b3baa3142574185fe8da727ddee388903f2cb0a3efbe683f952bdfd7a59
+  data.tar.gz: 66e5f06985d49b05702d6a569c1ac44f875726bd01ba7021b9e8ede0fb39e83aae9141e3c9e5e06c720e7dde207ac5b334c217473b0e36c390d3914c27eb5d83

data/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2022-01-25
+The library is now useful for clients!
+
+### Changed
+- Hide all internals in the module from clients.
+
 ## [0.6.0] - 2022-01-24
 ### Fixed
 - Move runtime dependencies from Gemfile to .gemspec.

data/README.md

@@ -1,9 +1,9 @@
-# NestedText Ruby Library [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Get%20a%20nifty%20tooltip%20for%20term%20definitions%20in%20your%20Jekyll%20blog%20with%20this%20plugin&url=https://github.com/erikw/nestedtext-ruby&via=erik_westrup&hashtags=jekyll,plugin)
+# 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)
 [![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/)
-[![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)
 [![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)
 [![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)
@@ -37,6 +37,25 @@ TODO link to my test repo showin live usage. https://github.com/erikw/nestedtext
 
 ## Encoding (writing NT)
 
+`#to_nt` method:
+```irb
+irb> require 'nestedtext'
+irb> puts "a\nstring".to_nt
+> a
+> string
+irb> puts ["i1", "i2", "i3"].to_nt
+- i1
+- i2
+- i3
+irb> puts({"k1" => "v1", "multiline\nkey" => "v2", "k3" => "multiline\nvalue"}.to_nt)
+k1: v1
+: multiline
+: key
+    > v2
+k3:
+    > multiline
+    > value
+```
 ## Custom Classes Serialization
 This library has support for serialization/deserialization of custom classes as well.
 `strict: false` flag needed
@@ -72,9 +91,16 @@ See [encode_custom_classes_test.rb](test/nestedtext/encode_custom_classes_test.r
 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.  You can also run `$ script/console` for an interactive prompt that will allow you to experiment.
+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`
 
-To install this gem onto your local machine, run `$ bundle exec rake install`.
+Make sure that only intended constants and methods are exposed from the module `NestedText`. Check with
+```
+irb> require 'nestedtext'
+irb> NestedText.constants
+irb> NestedText.methods(false)
+```
 
 ## 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

@@ -2,4 +2,6 @@ require "stringio"
 module NestedText
   TOP_LEVEL_TYPES = [Object, Hash, Array, String]
   CUSTOM_CLASS_KEY = "__nestedtext_class__"
+
+  private_constant :TOP_LEVEL_TYPES, :CUSTOM_CLASS_KEY
 end

data/lib/nestedtext/core_ext.rb

@@ -5,12 +5,14 @@ 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?
 
-class String include NestedText::NTEncodeStrictMixing end
-class Array include NestedText::NTEncodeStrictMixing end
-class Hash include NestedText::NTEncodeStrictMixing end
+NT_MIXIN = NestedText.const_get(:NTEncodeStrictMixing)
+
+class String include NT_MIXIN end
+class Array include NT_MIXIN end
+class Hash include NT_MIXIN end
 
 class NilClass
-  include NestedText::NTEncodeStrictMixing
+  include NT_MIXIN
 
   def self.nt_create(_data) = nil
 

data/lib/nestedtext/decode.rb

@@ -2,7 +2,6 @@
 
 require "nestedtext/parser"
 require "nestedtext/errors"
-require "nestedtext/helpers"
 
 require "logger"
 require "stringio"
@@ -15,16 +14,12 @@ module NestedText
 
     raise Errors::WrongInputTypeError.new([String], ntstring) unless ntstring.nil? || ntstring.is_a?(String)
 
-    assert_valid_top_level_type top_class
-
     Parser.new(StringIO.new(ntstring), top_class, strict: strict).parse
   end
 
   def self.load_file(filename, top_class: Object, strict: true)
     raise Errors::WrongInputTypeError.new([String], filename) unless !filename.nil? && filename.is_a?(String)
 
-    assert_valid_top_level_type top_class
-
     # 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

data/lib/nestedtext/dumper.rb

@@ -174,4 +174,5 @@ module NestedText
       end
     end
   end
+  private_constant :Dumper
 end

data/lib/nestedtext/encode_helpers.rb

@@ -1,11 +1,13 @@
 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
     end
   end
+  private_constant :NTEncodeStrictMixing
 
   module NTEncodeMixing
     def to_nt(indentation: 4)
@@ -21,4 +23,5 @@ module NestedText
       @strict = strict
     end
   end
+  private_constant :EncodeOptions
 end

data/lib/nestedtext/errors.rb

@@ -6,12 +6,19 @@ require "word_wrap/core_ext"
 require "nestedtext/constants"
 
 module NestedText
-  # Top level ParseError for clients to rescue.
-  class Error < StandardError; end
+  # 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
+  class Error < StandardError
+    private_class_method :new
+  end
 
   module Errors
+    class InternalError < Error
+      public_class_method :new # Prevent clients from instansiating.
+    end
+
     # TODO: rename all Subclasses to ParseXError, just like for Dump
-    class ParseError < Error
+    class ParseError < InternalError
       attr_reader :lineno, :colno, :message_raw
 
       def initialize(line, colno, message)
@@ -177,25 +184,7 @@ module NestedText
       end
     end
 
-    class UnsupportedTopLevelTypeError < Error
-      def initialize(type_class)
-        super("The given top level type #{type_class&.name} is unsupported. Chose between #{TOP_LEVEL_TYPES.join(", ")}.")
-      end
-    end
-
-    class WrongInputTypeError < Error
-      def initialize(class_exps, class_act)
-        super("The given input type #{class_act.class.name} is unsupported. Expected to be of types #{class_exps.map(&:name).join(", ")}")
-      end
-    end
-
-    class TopLevelTypeMismatchParsedType < Error
-      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 AssertionError < Error; end
+    class AssertionError < InternalError; end
 
     class LineScannerIsEmpty < AssertionError
       def initialize
@@ -209,19 +198,7 @@ module NestedText
       end
     end
 
-    class DumpBadIO < Error
-      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 < Error
-      def initialize(path)
-        super("Must supply a string to a file path that can be written to. Given: #{path}")
-      end
-    end
-
-    class DumpError < Error
+    class DumpError < InternalError
       attr_reader :culprit
 
       def initialize(culprit, message)
@@ -258,5 +235,36 @@ module NestedText
 
       raise LineTagNotDetected, line
     end
+
+    class UnsupportedTopLevelTypeError < InternalError
+      def initialize(type_class)
+        super("The given top level type #{type_class&.name} is unsupported. Chose between #{TOP_LEVEL_TYPES.join(", ")}.")
+      end
+    end
+
+    class WrongInputTypeError < InternalError
+      def initialize(class_exps, class_act)
+        super("The given input type #{class_act.class.name} is unsupported. Expected to be of types #{class_exps.map(&:name).join(", ")}")
+      end
+    end
+
+    class TopLevelTypeMismatchParsedType < 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
+      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
+      def initialize(path)
+        super("Must supply a string to a file path that can be written to. Given: #{path}")
+      end
+    end
   end
+  private_constant :Errors
 end

data/lib/nestedtext/parser.rb

@@ -4,14 +4,20 @@ require "stringio"
 
 require "nestedtext/errors"
 require "nestedtext/scanners"
-require "nestedtext/helpers"
+require "nestedtext/constants"
 
 module NestedText
   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)
+        raise Errors::UnsupportedTopLevelTypeError, top_class
+      end
+    end
+
     # TODO: document that caller is responsible for closing IO after done with Parser.
     def initialize(io, top_class, strict: true)
       assert_valid_input_type io
-      NestedText.assert_valid_top_level_type(top_class)
+      Parser.assert_valid_top_level_type(top_class)
       @top_class = top_class
       @strict = strict
       @line_scanner = LineScanner.new(io)
@@ -284,4 +290,5 @@ module NestedText
       result
     end
   end
+  private_constant :Parser
 end

data/lib/nestedtext/scanners.rb

@@ -40,6 +40,7 @@ module NestedText
       @next_line = line
     end
   end
+  private_constant :LineScanner
 
   class InlineScanner
     attr_reader :line, :pos
@@ -68,6 +69,7 @@ module NestedText
       empty? ? nil : @line.content[@pos]
     end
   end
+  private_constant :InlineScanner
 
   class Line
     # Reference: https://nestedtext.org/en/latest/file_format.html
@@ -158,4 +160,5 @@ module NestedText
       end
     end
   end
+  private_constant :Line
 end

data/lib/nestedtext/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nestedtext
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Erik Westrup
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-24 00:00:00.000000000 Z
+date: 2022-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: warning
@@ -68,7 +68,6 @@ files:
 - lib/nestedtext/encode.rb
 - lib/nestedtext/encode_helpers.rb
 - lib/nestedtext/errors.rb
-- lib/nestedtext/helpers.rb
 - lib/nestedtext/parser.rb
 - lib/nestedtext/scanners.rb
 - lib/nestedtext/version.rb

data/lib/nestedtext/helpers.rb

@@ -1,7 +0,0 @@
-module NestedText
-  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)
-      raise Errors::UnsupportedTopLevelTypeError, top_class
-    end
-  end
-end