Nay

Lightweight and simple string templating library

Supplies a simple interface for evaluating string templates with objects.

Installation

To install through Rubygems:

gem install nay

You can also add this to your Gemfile using:

bundle add nay

Examples

Simple String-based Expression

animal = {
  'animal' => {
    'speed' => 'quick',
    'type' => 'fox'
  }
}

string   = 'A << animal.speed >> << animal.type >> jumps over the fence!'
compiled = Nay.evaluate(string, animal)

This would set compiled to: 'A quick fox jumps over the fence!'`

Notes:

Tokens are passed through #[] method for the passed in object. Any object providing a brackets interface will work.
A valid token only contains the following characters: [a-zA-Z0-9_-]. If a token needs to contain something not in that list then qualify it with double quotes (i.e. hello, << person."first name" >>)

More Complex Expressions

Expressions are not limited to just being a string. Here are the basic heuristics:

hash: then each key and value are recursively traversed
array: then each entry is recursively traversed
string: evaluated with parameters
anything not a hash, array, or string: do nothing

An example of this would be a somewhat complicated object:

object = {
  '<< id_key >>' => '<< id >>',
  'pets' => [
    '<< pets."pet 1" >>',
    '<< pets."pet 2" >>'
  ],
  zyx: :vut
}

parameters = {
  'id_key' => 'id',
  'id' => 123,
  'pets' => {
    'pet 1' => 'dog',
    'pet 2' => 'cat'
  },
  zyx: :vut
}

evaluated_object = Nay.evaluate(object, parameters)

In the above example evaluated_object would be equivalent to:

{
  'id' => '123',
  'pets' => [
    'dog',
    'cat'
  ],
  zyx: :vut
}

Notes:

A hash, hash key, and hash value are represented here
An array with entries are represented here
A non-string is represented here (as the zyx/vut key/value)

Contributing

Development Environment Configuration

Basic steps to take to get this repository compiling:

Install Ruby (check nay.gemspec for versions supported)
Install bundler (gem install bundler)
Clone the repository (git clone git@github.com:mattruggio/nay.git)
Navigate to the root folder (cd nay)
Install dependencies (bundle)

Running Tests

To execute the test suite run:

bin/rspec spec --format documentation

Alternatively, you can have Guard watch for changes:

bin/guard

Also, do not forget to run Rubocop:

bin/rubocop

And auditing the dependencies:

bin/bundler-audit check --update

Publishing

Note: ensure you have proper authorization before trying to publish new versions.

After code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:

Merge Pull Request into main
Update version.rb using semantic versioning
Install dependencies: bundle
Update CHANGELOG.md with release notes
Commit & push main to remote and ensure CI builds main successfully
Run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Code of Conduct

Everyone interacting in this codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

License

This project is MIT Licensed.

mattruggio/nay

Nay