stringento 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a9c5bc1e6be2d2b938d8558ffed9dfbf772e6455e5d685d191a573b4ed2f39d0
+  data.tar.gz: 35a3d3762d62d34e7910d96f3572b0fb99188212baa931d0c6fbc7b2c4546302
+SHA512:
+  metadata.gz: b2a0ccd6b31c1fab010b8204e5be9786fe8df043dc4f198bc44a9dc52f1b72d1bc7bb5cb242c122cbd33b3263f9a6542fe6dc9f9e19c12996f65a688812ce3ef
+  data.tar.gz: ca6ba92b4db5ad88ec139f2352684f3b7534224bedc631546ac21f053354824f75dcddb15d6e27d5d130b2da600ad363ab13a1c5b3f9afd2eaa291f039493242

data/.editorconfig

@@ -0,0 +1,8 @@
+# See http://editorconfig.org/
+
+[*]
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+end_of_line = lf

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+*.gem
+/tmp
+/coverage

data/.rubocop.yml

@@ -0,0 +1,11 @@
+Metrics/LineLength:
+  Max: 100
+
+Metrics/BlockLength:
+  ExcludedMethods: ['let', 'it', 'describe', 'context', 'specify']
+
+Metrics/MethodLength:
+  Max: 25
+
+AllCops:
+  TargetRubyVersion: 2.3

data/.ruby-version

@@ -0,0 +1 @@
+2.6.0

data/.travis.yml

@@ -0,0 +1,20 @@
+env:
+  global:
+    - CC_TEST_REPORTER_ID=5d35e3d9b28655a2040bdc46f31576dc73c61c7bee8c7dd6ea9832b9aeb61833
+language: ruby
+rvm:
+  # Build on the latest stable of all supported Rubies (https://www.ruby-lang.org/en/downloads/):
+  - 2.3.8
+  - 2.4.5
+  - 2.5.3
+  - 2.6.0
+cache: bundler
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rubocop
+  - bundle exec rspec spec --format documentation
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.0.1 (April 4th, 2019)
+
+Library Shell.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,123 @@
+PATH
+  remote: .
+  specs:
+    stringento (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    Ascii85 (1.0.3)
+    afm (0.2.2)
+    ansi (1.5.0)
+    ast (2.4.0)
+    coderay (1.1.2)
+    concurrent-ruby (1.1.5)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    faker (1.9.3)
+      i18n (>= 0.7)
+    ffi (1.9.25)
+    formatador (0.2.5)
+    guard (2.15.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    hashery (2.1.2)
+    hirb (0.7.3)
+    i18n (1.6.0)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.2)
+    json (2.1.0)
+    listen (3.1.5)
+      rb-fsevent (~> 0.9, >= 0.9.4)
+      rb-inotify (~> 0.9, >= 0.9.7)
+      ruby_dep (~> 1.2)
+    lumberjack (1.0.13)
+    method_source (0.9.2)
+    nenv (0.3.0)
+    notiffany (0.1.1)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    parallel (1.13.0)
+    parser (2.6.0.0)
+      ast (~> 2.4.0)
+    pdf-inspector (1.3.0)
+      pdf-reader (>= 1.0, < 3.0.a)
+    pdf-reader (2.2.0)
+      Ascii85 (~> 1.0.0)
+      afm (~> 0.2.1)
+      hashery (~> 2.0)
+      ruby-rc4
+      ttfunk
+    powerpack (0.1.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rb-fsevent (0.10.3)
+    rb-inotify (0.9.10)
+      ffi (>= 0.5.0, < 2)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.63.1)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
+    ruby-rc4 (0.1.5)
+    ruby_dep (1.5.0)
+    shellany (0.0.1)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-console (0.4.2)
+      ansi
+      hirb
+      simplecov
+    simplecov-html (0.10.2)
+    thor (0.20.3)
+    ttfunk (1.5.1)
+    unicode-display_width (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  faker (~> 1)
+  guard-rspec (~> 4.7)
+  pdf-inspector (~> 1)
+  pry (~> 0)
+  rspec (~> 3.8)
+  rubocop (~> 0.63.1)
+  simplecov (~> 0.16.1)
+  simplecov-console (~> 0.4.2)
+  stringento!
+
+BUNDLED WITH
+   1.17.3

data/Guardfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2019 Blue Marble Payroll, LLC
+
+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/README.md

@@ -0,0 +1,162 @@
+*This is a Ruby implementation of [Stringent](https://github.com/bluemarblepayroll/stringent).  The name Stringent was already taken within RubyGems so this was named Stringento instead.*
+
+---
+
+# Stringento
+
+[![Gem Version](https://badge.fury.io/rb/stringento.svg)](https://badge.fury.io/rb/stringento) [![Build Status](https://travis-ci.org/bluemarblepayroll/stringento.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/stringento) [![Maintainability](https://api.codeclimate.com/v1/badges/22aabc80514fe3db20da/maintainability)](https://codeclimate.com/github/bluemarblepayroll/stringento/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/22aabc80514fe3db20da/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/stringento/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This library provides a pluggable string templating system.  At its core, it can take a templated string (such as: '{last_name}, {first_name} {middle_name}') and a input object (default is a plain old Ruby object) and it will dynamically resolve the string based on the input.  It also provides two optional arguments which help make this library 'pluggable':
+
+1. Custom Resolver: Instead of passing in a PORO as your input, you can pass in other object types and use a custom resolver for value getting.
+1. Custom Formatter: Customize the way each string token is rendered by extending the token syntax to: {token:formatter:argument}.  Formatter is the formatting method to call and argument will be passed in as meta-data/options.
+
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install stringento
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add stringento
+````
+
+## Examples
+
+### Getting Started
+
+Consider the following example:
+
+> 'The {fox_speed} brown fox jumps over the {dog_speed} dog'
+
+We can evaluate this by executing:
+
+```ruby
+example = 'The {fox_speed} brown fox jumps over the {dog_speed} dog'
+input = { 'fox_speed' => 'quick', 'dog_speed' => 'lazy' }
+
+result = Stringento.evaluate(example, input)
+```
+
+Result should now be: 'The quick brown fox jumps over the lazy dog'
+
+### Custom Resolution
+
+The above example works just fine using the default object value resolver, but you can also pass in a custom function that will serve as resolver.  That way you could use dot notation for value resolution.  For example:
+
+```ruby
+class NestedHashResolver
+  def resolve(value, input)
+    parts = value.to_s.split('.').map(&:to_sym)
+
+    input ? input.dig(*parts) : nil
+  end
+end
+
+example = 'The {fox.speed} brown fox jumps over the {dog.speed} dog'
+input = { fox: { speed: 'quick' }, dog: { speed: 'lazy' } }
+
+result = Stringento.evaluate(example, input, resolver: NestedHashResolver.new)
+```
+
+The ```result``` variable should now be: 'The quick brown fox jumps over the lazy dog'
+
+### Custom Formatting
+
+Another extendable aspect is formatting.  Consider a basic example where we want to show 'Yes' for a true value, 'No' for a false value, and an 'Unknown' for a null value:
+
+> 'The fox is quick: {fox.quick::yes_no_unknown}'
+
+In this case we can use a custom formatter called yes_no_unknown that understands how to do this for us.  The custom formatter is controlled externally from this library, which means you can use this for whatever purpose you see fit.  Here would be an example implementation of this custom formatter:
+
+```ruby
+class CustomFormatter < ::Stringento::Formatter
+  def yes_no_unknown_formatter(value, _arg)
+    if value.nil?
+      'Unknown'
+    elsif value
+      'Yes'
+    else
+      'No'
+    end
+  end
+end
+```
+
+Now, we can pass this in and consume it as follows:
+
+```ruby
+class NestedHashResolver
+  def resolve(value, input)
+    parts = value.to_s.split('.').map(&:to_sym)
+
+    input ? input.dig(*parts) : nil
+  end
+end
+
+example = 'The fox is quick: {fox.quick::yes_no_unknown}'
+input = { fox: { quick: true } }
+
+result = evaluate(example, input, resolver: NestedHashResolver.new, formatter: CustomFormatter.new)
+```
+
+The ```result``` variable should now be: 'The fox is quick: Yes'
+
+*Note: If we wanted to use the default resolver we could omit resolver instead of the custom resolver.*
+
+## Contributing
+
+### Development Environment Configuration
+
+Basic steps to take to get this repository compiling:
+
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check stringento.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/stringento.git)
+4. Navigate to the root folder (cd stringento)
+5. Install dependencies (bundle)
+
+### Running Tests
+
+To execute the test suite run:
+
+````
+bundle exec rspec spec --format documentation
+````
+
+Alternatively, you can have Guard watch for changes:
+
+````
+bundle exec guard
+````
+
+Also, do not forget to run Rubocop:
+
+````
+bundle exec rubocop
+````
+
+### 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:
+
+1. Merge Pull Request into master
+2. Update ```lib/stringento/version.rb``` using [semantic versioning](https://semver.org/)
+3. Install dependencies: ```bundle```
+4. Update ```CHANGELOG.md``` with release notes
+5. Commit & push master to remote and ensure CI builds master successfully
+6. Build the project locally: `gem build stringento`
+7. Publish package to RubyGems: `gem push stringento-X.gem` where X is the version to push
+8. Tag master with new version: `git tag <version>`
+9. Push tags remotely: `git push origin --tags`
+
+## License
+
+This project is MIT Licensed.

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'stringento'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'pry'
+Pry.start

data/lib/stringento/formatter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Stringento
+  # Base class / base implementation of a formatter.
+  # In order to customize formatting:
+  # - Derive subclass
+  # - Implement formatter methods ending in: _formatter.
+  # - Pass instance into into Stringento#evaluate
+  class Formatter
+    METHOD_SUFFIX = '_formatter'
+
+    private_constant :METHOD_SUFFIX
+
+    def format(value, formatter = '', arg = '')
+      method_name = "#{formatter}#{METHOD_SUFFIX}"
+
+      if respond_to?(method_name)
+        send(method_name, value, arg)
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/lib/stringento/placeholder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Stringento
+  # A placeholder is a to-be-resolved-and-formatted token within a string.
+  # A placeholder has a minimum one part and at maximum three parts (token::formatter:argument),
+  # for example:
+  # - first_name
+  # - first_name::capitalize
+  # - dob::date::mm-dd-yyyy
+  class Placeholder
+    SEPARATOR = '::'
+
+    attr_reader :arg, :formatter, :name, :value
+
+    def initialize(value)
+      @value = value.to_s
+
+      parts = @value.split(SEPARATOR)
+      count = parts.length
+
+      raise ArgumentError, "Cannot be split: #{value}" if count.negative? || count > 3
+
+      @name       = parts[0] || ''
+      @formatter  = parts[1] || ''
+      @arg        = parts[2] || ''
+
+      freeze
+    end
+  end
+end

data/lib/stringento/resolver.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Stringento
+  # This is the base class / implementation for how values are resolved.
+  # In order to change this:
+  # - Derive a subclass
+  # - Override the #resolve method
+  # - Pass instance into into Stringento#evaluate
+  class Resolver
+    def resolve(value, input)
+      if input&.respond_to?(:[])
+        input[value]
+      elsif input&.respond_to?(value)
+        input.send(value)
+      end
+    end
+  end
+end

data/lib/stringento/stringento.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'formatter'
+require_relative 'placeholder'
+require_relative 'resolver'
+require_relative 'template'
+
+# Top-level API for main external consumption.  It is better to use this than instantiating
+# your own Template objects because this top-level object will cache Template objects based
+# on the expression.  It also provides less default resolver and formatter instantiations.
+module Stringento
+  class << self
+    def evaluate(expression, input, resolver: nil, formatter: nil)
+      template(expression).evaluate(
+        input,
+        resolver: (resolver || default_resolver),
+        formatter: (formatter || default_formatter)
+      )
+    end
+
+    private
+
+    def templates
+      @templates ||= {}
+    end
+
+    def template(expression)
+      templates[expression.to_s] ||= Template.new(expression)
+    end
+
+    def default_resolver
+      @default_resolver ||= Resolver.new
+    end
+
+    def default_formatter
+      @default_formatter ||= Formatter.new
+    end
+  end
+end

data/lib/stringento/template.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Stringento
+  # This is the main rendering engine for the library.  It connects together the notions of:
+  # parsing, value resolution, and value formatting in a consumable way.
+  class Template
+    TOKEN_REGULAR_EXPRESSION = /{(.*?)}/.freeze
+
+    private_constant :TOKEN_REGULAR_EXPRESSION
+
+    attr_reader :value
+
+    def initialize(value)
+      @value = value.to_s
+    end
+
+    def placeholders
+      @placeholders ||= value.scan(TOKEN_REGULAR_EXPRESSION)
+                             .flatten
+                             .map { |str| Placeholder.new(str) }
+    end
+
+    def evaluate(input, resolver: Resolver.new, formatter: Formatter.new)
+      placeholders.inject(value) do |output, placeholder|
+        resolved_value = (resolver || default_resolver).resolve(placeholder.name, input)
+
+        formatted_value = (formatter || default_formatter).format(
+          resolved_value,
+          placeholder.formatter,
+          placeholder.arg
+        )
+
+        output.gsub("{#{placeholder.value}}", formatted_value)
+      end
+    end
+  end
+end

data/lib/stringento/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Stringento
+  VERSION = '1.0.0'
+end

data/lib/stringento.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'stringento/stringento'

data/spec/examples/custom_formatter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+class CustomFormatter < ::Stringento::Formatter
+  def yes_no_formatter(value, _arg)
+    value ? 'Yes' : 'No'
+  end
+
+  def yes_no_unknown_formatter(value, _arg)
+    if value.nil?
+      'Unknown'
+    elsif value
+      'Yes'
+    else
+      'No'
+    end
+  end
+end

data/spec/examples/indifferent_hash_resolver.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+class IndifferentHashResolver
+  def resolve(value = '', input = {})
+    input ? (input[value.to_s] || input[value.to_s.to_sym]) : nil
+  end
+end

data/spec/examples/nested_hash_resolver.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+class NestedHashResolver
+  def resolve(value, input)
+    parts = value.to_s.split('.').map(&:to_sym)
+
+    input ? input.dig(*parts) : nil
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'pry'
+require 'csv'
+
+require 'simplecov'
+require 'simplecov-console'
+SimpleCov.formatter = SimpleCov::Formatter::Console
+SimpleCov.start
+
+require './lib/stringento'