NestedText Ruby Library

Inspired by the JSON and YAML modules.

This project will soon be released! :tada:

On-going development is at branch dev.

What is NestedText?

TODO

https://nestedtext.org/en/latest/alternatives.html

Examples

TODO NT examples

Usage

TODO Link to lib docs TODO link to my test repo showin live usage. https://github.com/erikw/nestedtext-ruby-test

Usage

Decoding (reading NT)

Encoding (writing NT)

#to_nt method:

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 See 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

   </code>

Development

1. Clone the repo console $ git clone https://github.com/erikw/nestedtext-ruby.git && cd $(basename "$_" .git)
2. Install a supported ruby version (see .gemspec) with a ruby version manager e.g. rbenv, asdf or RVM
3. run $ script/setup to install dependencies
4. run $ script/test to run the tests
5. You can also run $ script/console for an interactive prompt that will allow you to experiment.
6. For local testing, install the gem on local machine with: $ bundle exec rake install.
   • or manuall with $ gem build *.gemscpec && gem install *.gem

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 after this for the pushed git tag.

(manually) Using bundler/gem_tasks rake tasks

Following instructions from bundler.io:

$ 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:

$ vi CHANGELOG.md && git commit -am "Update CHANGELOG.md" && git push
$ gem bump --version minor --tag --sign --push --release

For --version, use major|minor|patch as needed.

(semi-automatic, preferred) Using GitHub Actions CD

Just push a new semver tag and the workflow cd.yml will publish a new release at rubygems.org.

$ 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

or combined with gem-release

$ vi CHANGELOG.md
$ git commit -am "Update CHANGELOG.md" && git push
$ gem bump --version minor --tag --sign --push

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/erikw/nestedtext-ruby.

License

The gem is available as open source with the License.

Acknowledgement & Thanks

Thanks to the data format authors making it easier making new implementations by providing an official test suite.