nestedtext 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ab788532b6de8dfb6b589b789afe4d04a6bc7ef9403aaf69f02306680ff4955
+  data.tar.gz: 994fe9aae478fb40d191ea96452a0c247b3385dd4e8fe28a323d271feb3e0f11
+SHA512:
+  metadata.gz: f6ce566b64bd8874c8b3fae58ab772177249103bf65176cc2ee02e8c74993fa47bd1ed269a9b69c0e6f7a8fecc667fee0e76ec509ef1f1e5608ce8b4d97859ae
+  data.tar.gz: 22dab61d1a2cad3eafa3f097c03bbf802747bbe363269161292a663d06d80e61152025de4d6facafba31006f07fb1a5d847775ca483b809b418536d60ce14ecc

data/.editorconfig

@@ -0,0 +1,24 @@
+# Modified version of https://github.com/ruby/ruby/blob/master/.editorconfig
+
+root = true
+
+[*]
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+tab_width = 4
+trim_trailing_whitespace = true
+
+[*.rb]
+indent_size = 2
+
+[*.gemspec]
+indent_size = 2
+
+[*.yml]
+indent_size = 2
+
+[test/nestedtext/encode_test.rb]
+# So we can test trailing whitespace strings.
+trim_trailing_whitespace = unset

data/.gitignore

@@ -0,0 +1,19 @@
+# Contrary to ruby apps, ruby gems should not check in Gemfile.lock.
+# Reference: https://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/
+Gemfile.lock
+
+# Bundle local config
+.bundle/
+
+# Package gem from $(rake install)
+pkg/
+
+# minitest
+/test/html_reports/
+/test/reports/
+
+# simplecov
+/coverage/
+
+# byebug
+/.byebug_history

data/.rubocop.yml

@@ -0,0 +1,143 @@
+# See pages relaed at https://docs.rubocop.org/rubocop/1.12/cops_layout.html
+
+
+# TODO  clean this upand remove Excludes not needed.
+
+# Rubocop extensions
+require:
+  - rubocop-rake
+
+inherit_mode:
+  merge:
+    - Exclude  # Merge my AllCops.Excllude with default exludes from https://github.com/rubocop/rubocop/blob/master/config/default.yml
+
+AllCops:
+  TargetRubyVersion: 3.0
+  Include:
+  - lib/**/*.rb
+  - spec/**/*.rb
+  Exclude:
+  # Travis: during build there will be a lot of rubocop config files in this pat which will cause build failure as the refer to gems which are not installed by this project.
+  # See https://github.com/rubocop/rubocop/issues/9832
+  - gemfiles/vendor/bundle/**/*
+
+Gemspec/DateAssignment:
+  Enabled: true
+
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: true
+
+Lint/AmbiguousAssignment:
+  Enabled: true
+Lint/DeprecatedConstants:
+  Enabled: true
+Lint/DuplicateBranch:
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement:
+  Enabled: true
+Lint/EmptyBlock:
+  Enabled: true
+Lint/EmptyClass:
+  Enabled: true
+Layout/EmptyLineBetweenDefs:
+  Enabled: true
+  Exclude:
+  - lib/nestedtext-ruby/errors.rb
+Lint/EmptyInPattern:
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock:
+  Enabled: true
+Layout/LineLength:
+  Max: 120
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: true
+Lint/NumberedParameterAssignment:
+  Enabled: true
+Lint/OrAssignmentToConstant:
+  Enabled: true
+Lint/RedundantDirGlobSort:
+  Enabled: true
+Layout/SpaceBeforeBrackets:
+  Enabled: true
+Lint/SymbolConversion:
+  Enabled: true
+Lint/ToEnumArguments:
+  Enabled: true
+Lint/TripleQuotes:
+  Enabled: true
+Lint/UnexpectedBlockArity:
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator:
+  Enabled: true
+Lint/UnreachableCode:
+  Severity: error
+Lint/UselessAccessModifier:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: true
+Metrics/BlockLength:
+  Enabled: true
+  Max: 100
+Metrics/MethodLength:
+  Enabled: true
+  Max: 25
+
+Naming/FileName:
+  Enabled: false
+  Exclude:
+  - lib/nestedtext-ruby.rb
+Naming/InclusiveLanguage:
+  Enabled: true
+
+Style/ArgumentsForwarding:
+  Enabled: true
+Style/CollectionCompact:
+  Enabled: true
+Style/Documentation:
+  Enabled: true
+  Exclude:
+  - lib/nestedtext-ruby/errors.rb
+Style/DocumentDynamicEvalDefinition:
+  Enabled: true
+Style/EndlessMethod:
+  Enabled: true
+Style/HashConversion:
+  Enabled: true
+Style/HashExcept:
+  Enabled: true
+Style/IfWithBooleanLiteralBranches:
+  Enabled: true
+Style/InPatternThen:
+  Enabled: true
+Style/MultilineInPatternThen:
+  Enabled: true
+Style/NegatedIfElseCondition:
+  Enabled: true
+Style/NilLambda:
+  Enabled: true
+Style/QuotedSymbols:
+  Enabled: true
+Style/RedundantArgument:
+  Enabled: true
+Style/RegexpLiteral:
+  Enabled: false
+Style/SingleLineMethods:
+  Enabled: true
+  Exclude:
+  - lib/nestedtext-ruby/errors.rb
+Style/StringChars:
+  Enabled: true
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+Style/SwapValues:
+  Enabled: true
+
+
+# Reference: https://github.com/rubocop/rubocop-rake/blob/master/config/default.yml
+Rake:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.1.0

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+## [0.1.0] - 2022-01-24
+### Added
+- Initial release. If this release works, an 1.0.0 will soon follow.

data/CONTRIBUTING.md

@@ -0,0 +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.

data/Gemfile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Put require=false on gem's that we don't need to import in code (cli exec only)
+
+source "https://rubygems.org"
+
+# Include dependencies from the .gemspec
+gemspec
+
+# Development dependencies
+# Should rather be here than in the .gemspec
+# Reference: https://github.com/rubygems/bundler/pull/7222
+# However there's an argument for using gemspec too: https://bundler.io/guides/creating_gem.html#testing-our-gem
+group :development, :test do
+  gem "appraisal", "~> 2.4", require: false
+  gem "gem-release", "~> 2.0", require: false
+  gem "pry-byebug", "~> 3.9"
+  gem "rake", "~> 13.0", require: false
+  gem "solargraph", require: false
+end
+
+group :test do
+  gem "minitest-byebug", "~> 0.0.3"
+  gem "minitest-reporters", "~> 1.4", require: false
+  gem "rubocop", "~> 1.18", require: false
+  gem "rubocop-rake", "~> 0.6", require: false
+  gem "simplecov", "~> 0.21", require: false
+end
+
+gem "warning", "~> 1.2"
+gem "word_wrap", "~> 1.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Erik Westrup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/OSSMETADATA

@@ -0,0 +1 @@
+osslifecycle=active

data/README.md

@@ -0,0 +1,113 @@
+# 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)
+[![Gem Version](https://badge.fury.io/rb/nestedtext-ruby.svg)](https://badge.fury.io/rb/nestedtext-ruby)
+[![Gem Downloads](https://ruby-gem-downloads-badge.herokuapp.com/nestedtext-ruby?color=brightgreen&type=total&label=gem%20downloads)](https://rubygems.org/gems/nestedtext-ruby)
+[![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/)
+[![Tests](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)
+[![CodeQL](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/7ffb648ec4b77f3f9eb8/maintainability)](https://codeclimate.com/github/erikw/nestedtext-ruby/maintainability)
+[![Code Climate Test Coverage](https://api.codeclimate.com/v1/badges/7ffb648ec4b77f3f9eb8/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)
+[![OSS Lifecycle](https://img.shields.io/osslifecycle/erikw/nestedtext-ruby)](https://github.com/Netflix/osstracker)
+
+
+Inspired by the `JSON` and `YAML` modules.
+
+This project will soon be released! :tada:
+
+On-going development is at branch [**dev**](https://github.com/erikw/nestedtext-ruby/tree/dev).
+
+# What is NestedText?
+TODO
+
+## Examples
+TODO NT examples
+
+# Usage
+TODO Link to lib docs
+TODO link to my test repo showin live usage.
+
+
+# Usage
+## Decoding (reading NT)
+
+## Encoding (writing NT)
+
+## Custom Classes Serialization
+This library has support for serialization/deserialization of custom classes as well.
+`strict: false` flag needed
+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
+   - 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'
+
+     NestedText::load(...)
+     NestedText::dump(...)
+     obj.to_nt
+   ```
+
+
+
+# Development
+
+1. Clone the repo
+   ```console
+   $ 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.  You can also run `$ script/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `$ bundle exec rake install`.
+
+## 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
+Following instructions from [bundler.io](https://bundler.io/guides/creating_gem.html#releasing-the-gem):
+```console
+$ vi -p lib/nestedtext/version.rb CHANGELOG.md
+$ bundle exec rake build
+$ ver=$(ruby -r ./lib/nestedtext/version.rb -e 'puts NestedText::VERSION')
+$ bundle exec rake release
+```
+
+## (semi-manually) Using gem-release gem extension
+Using [gem-release](https://github.com/svenfuchs/gem-release):
+```console
+$ vi CHANGELOG.md && git add CHANGELOG.md && git commit -m "Update CHANGELOG.md" && git push
+$ gem bump --version minor --tag --sign --push --release
+```
+For `--version`, use `major|minor|patch` as needed.
+
+## (semi-automatic) Using GitHub Actions CD
+Just push a new semver tag and the workflow [cd.yml](.github/workflows/cd.yml) will publish a new release at rubygems.org.
+
+```console
+$ vi -p lib/nestedtext/version.rb CHANGELOG.md
+$ git commit -am "Prepare vX.Y.Z" && git push
+$ git tag x.y.z && git push --tags
+```
+
+
+# Contributing
+Bug reports and pull requests are welcome on GitHub at [https://github.com/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).

data/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+
+## Reporting a Vulnerability
+Please open a GitHub Issue in this repository for any potential issues!

data/lib/nestedtext/constants.rb

@@ -0,0 +1,5 @@
+require "stringio"
+module NestedText
+  TOP_LEVEL_TYPES = [Object, Hash, Array, String]
+  CUSTOM_CLASS_KEY = "__nestedtext_class__"
+end

data/lib/nestedtext/core_ext.rb

@@ -0,0 +1,18 @@
+require "nestedtext/encode_helpers"
+
+# 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?
+
+class String include NestedText::NTEncodeStrictMixing end
+class Array include NestedText::NTEncodeStrictMixing end
+class Hash include NestedText::NTEncodeStrictMixing end
+
+class NilClass
+  include NestedText::NTEncodeStrictMixing
+
+  def self.nt_create(_data) = nil
+
+  def encode_nt_with() = ""
+end

data/lib/nestedtext/decode.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "nestedtext/parser"
+require "nestedtext/errors"
+require "nestedtext/helpers"
+
+require "logger"
+require "stringio"
+
+module NestedText
+  def self.load(ntstring, top_class: Object, strict: true)
+    # logger = Logger.new(STDOUT) # TODO: make this available to other classes in module. How avoid singleton?
+    # logger.info "input=#{raw_input_string}"
+    # logger.info "top=#{top}"
+
+    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
+    end
+  end
+end

data/lib/nestedtext/dumper.rb

@@ -0,0 +1,177 @@
+# TODO: is this exposed to client who import this file? If so, hide it!
+class String
+  def normalize_line_endings
+    # windows/mac -> unix
+    gsub(/\r\n?/, "\n")
+  end
+end
+
+module NestedText
+  class Dumper
+    def initialize(opts = EncodeOptions.new)
+      @indentation = opts.indentation
+      @strict = opts.strict
+      @trace_cycles = nil
+      @trace_keys = nil
+    end
+
+    def dump(obj)
+      @trace_cycles = []
+      @trace_keys = []
+      dump_any obj
+    end
+
+    private
+
+    def self.add_prefix(prefix, target)
+      if target.empty? || target[0] == "\n"
+        target.prepend(prefix)
+      else
+        target.prepend(prefix, " ")
+      end
+    end
+
+    def self.multiline_key?(key)
+      syntax1 = "{[#"
+      syntax2 = ":->"
+
+      key.empty? ||
+        key != key.strip ||
+        key.include?("\n") ||
+        key.include?(": ") ||
+        syntax1.include?(key.lstrip[0]) ||
+        syntax2.include?(key.lstrip[0]) && key.lstrip[1] == " "
+    end
+
+    def convert_key(key)
+      if key.nil?
+        ""
+      elsif key.is_a? String
+        key.normalize_line_endings
+      elsif !@strict
+        key.to_s
+      else
+        raise Errors::DumpHashKeyStrictString, key
+      end
+    end
+
+    def indent(target)
+      indentstr = " " * @indentation
+      indented = "\n" + target.lines.map { |line| indentstr + line }.join
+      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)
+
+      @trace_cycles << obj
+      yield
+    ensure
+      @trace_cycles.pop
+    end
+
+    # TODO: different name on method and instance var...
+    def trace_keys(key)
+      @trace_keys << key
+      yield
+    ensure
+      @trace_keys.pop
+    end
+
+    def traced_key
+      @trace_keys.last
+    end
+
+    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 nil
+          @strict ? "" : dump_custom_class(nil, depth: depth, **kwargs)
+        else
+          dump_custom_class(obj, depth: depth, **kwargs)
+        end
+      end
+    end
+
+    # TODO: document that @strict: false allows to_s on key object
+    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
+    end
+
+    def dump_array(obj, depth: 0, **kwargs)
+      rep = if obj.empty?
+              # TODO: replace this special case with simply general inline rendering detection.
+              "[]"
+            else
+              obj.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)
+                end
+              end.join("\n")
+            end
+
+      indent(rep) if depth > 0
+      rep
+    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
+
+      # Case of empty input string. No space after '>'
+      lines << ">" if lines.empty? && (depth == 0 || force_multiline)
+
+      rep = lines.join.chomp
+      indent(rep) if !rep.empty? && depth > 0 && (rep.include?("\n") || force_multiline)
+      rep
+    end
+
+    def dump_custom_class(obj, **kwargs)
+      raise Errors::DumpUnsupportedTypeError.new(obj, traced_key) if @strict
+
+      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 }
+        dump_any(enc, **kwargs)
+      else
+        dump_string(obj.to_s, **kwargs)
+      end
+    end
+  end
+end

data/lib/nestedtext/encode.rb

@@ -0,0 +1,35 @@
+# 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)
+
+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)
+
+    opts = EncodeOptions.new(indentation, strict)
+    dumper = Dumper.new(opts)
+    result = dumper.dump obj
+    unless io.nil?
+      io.write(result)
+      io.fsync
+    end
+    result
+  end
+
+  def self.dump_file(obj, filename, **kwargs)
+    raise Errors::DumpFileBadPath, filename unless filename.is_a? String
+
+    File.open(filename, mode = "wt") do |file|
+      dump(obj, io: file, **kwargs)
+    end
+  end
+end