proforma-extended-evaluator 1.0.0.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 39f0512316231d5d6072f4a26afa88b956d2ae6f1a4b8cf2aa9d45fed2beaba0
+  data.tar.gz: f960a2c8956402fd065466c06468d8e8a3b8103a2f5274c72d35c7f8cbf62eec
+SHA512:
+  metadata.gz: 7de610f73e925ab605818eb5db4472d2aa5c93f95772c8a4f90040301c6ba80929734a5196d19a6766991c3fdf42e78d0e991d4304fccb3d9f19705f5c820f9b
+  data.tar.gz: 98ad38935c497f6c3742d944a5084c6161ea8033a52095ea68d45a491553da3deba260da85b8b306fc8856fe085734c4c60b4b9ae27acf66b01c0fbbbab754d7

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=404bf43b14c0d46bf70b7ccfe096d5ad43d9278d965e4a740c0220ce5a2daa00
+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,7 @@
+# 1.0.0-alpha (April 19th, 2019)
+
+Publishing first candidate of initial release.
+
+# 0.0.1 (April 17th, 2019)
+
+Library Shell.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,109 @@
+PATH
+  remote: .
+  specs:
+    proforma-extended-evaluator (1.0.0.pre.alpha)
+      stringento (~> 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    acts_as_hashable (1.0.5)
+    ansi (1.5.0)
+    ast (2.4.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    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)
+    hirb (0.7.3)
+    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)
+    powerpack (0.1.2)
+    proforma (1.0.0.pre.alpha)
+      acts_as_hashable (~> 1)
+    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_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)
+    stringento (2.0.0)
+    thor (0.20.3)
+    unicode-display_width (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.7)
+  proforma (>= 1.0.0.pre.alpha)
+  proforma-extended-evaluator!
+  pry (~> 0)
+  rspec (~> 3.8)
+  rubocop (~> 0.63.1)
+  simplecov (~> 0.16.1)
+  simplecov-console (~> 0.4.2)
+
+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,180 @@
+# Proforma Extended Evaluator
+
+[![Gem Version](https://badge.fury.io/rb/proforma-extended-evaluator.svg)](https://badge.fury.io/rb/proforma-extended-evaluator) [![Build Status](https://travis-ci.org/bluemarblepayroll/proforma-extended-evaluator.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/proforma-extended-evaluator) [![Maintainability](https://api.codeclimate.com/v1/badges/79e66b596906f633bc95/maintainability)](https://codeclimate.com/github/bluemarblepayroll/proforma-extended-evaluator/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/79e66b596906f633bc95/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/proforma-extended-evaluator/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The core Proforma library intentionally ships with a very weak evaluator.  Custom text templating and value resolution is not part of the core library's domain.  This library fills that void.  The goals of this library are to provide:
+
+1. Nested value resolution using dot-notation: `demographics.contact.first_name`
+2. Indifferent object types for value resolution: Hash, OpenStruct, any Object subclass, etc.
+3. Rich text templating: `{demo.last}, {demo.first} {demo.middle}`
+4. Customizable formatting:
+  * `{amount::currency}` -> `$12,345.67 USD`
+  * `{dob::date}` -> `2/4/1976`
+  * `{user_count::number::0}` -> `12,400,569`
+  * `{logins_per_day::number::2}` -> `76,004.45`
+  * `{smoker::boolean}` -> `Yes` or `No`
+  * `{smoker::boolean::nullable}` -> `Yes` or `No` or `Unknown`
+  * `{social_security_number::left_mask}` -> `XXXXXXX1234`
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install proforma-extended-evaluator
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add proforma-extended-evaluator
+````
+
+## Examples
+
+### Connecting to Proforma Rendering Pipeline
+
+To use this plugin within Proforma:
+
+1. Install Proforma
+2. Install this library
+3. Require both libraries
+4. Pass in an instance of Proforma::ExtendedEvaluator into the Proforma#render method
+
+````ruby
+require 'proforma'
+require 'proforma/extended_evaluator'
+
+data = [
+  {
+    id: 1,
+    person: {
+      first: 'James',
+      last: 'Bond',
+      dob: '1960-05-14',
+      smoker: false,
+      ssn: '123-45-6789'
+    },
+    balance: '123.445388'
+  }
+]
+
+template = {
+  children: [
+    {
+      type: 'Grouping',
+      children: [
+        {
+          type: 'Header',
+          value: 'Details For: {person.last}, {person.first} ({id})'
+        },
+        {
+          type: 'Pane',
+          columns: [
+            {
+              lines: [
+                { label: 'ID #', value: '{id::number::0}' },
+                { label: 'First Name', value: '{person.first}' },
+                { label: 'Last Name', value: '{person.last}' },
+                { label: 'Social Security #', value: '{person.ssn::left_mask}' }
+              ]
+            },
+            {
+              lines: [
+                { label: 'Birthdate', value: '{person.dob::date}' },
+                { label: 'Smoker', value: '{person.smoker::boolean}' },
+                { label: 'Balance', value: '{balance::currency}' }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+documents = Proforma.render(data, template, evaluator: Proforma::ExtendedEvaluator.new)
+````
+
+The `documents` attribute will now be an array with one object:
+
+```ruby
+expected_documents = [
+  {
+    contents: "DETAILS FOR: BOND, JAMES (1)\nID #: 1\nFirst Name: James\nLast Name:"\
+              " Bond\nSocial Security #: XXXXXXX6789\nBirthdate: 05/14/1960\nSmoker:"\
+              " No\nBalance: $123.45 USD\n",
+    extension: '.txt',
+    title: ''
+  }
+]
+```
+
+Notice how all strings are properly formatted as prescribed in the template.
+
+### Advanced Formatting (Customization/Options)
+
+Formatter options are biased towards USA localization.  You can override any of the options of the Formatter class, here are the options and their defaults:
+
+Option           | Default
+---------------- | -------
+currency_code    | 'USD'
+currency_round   | 2
+currency_symbol  | '$'
+date_format      | '%m/%d/%Y'
+mask_char        | 'X'
+false_value      | 'No'
+null_value       | 'Unknown'
+true_value       | 'Yes'
+
+## 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 proforma-extended-evaluator.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/proforma-extended-evaluator.git)
+4. Navigate to the root folder (cd proforma)
+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/proforma/extended_evaluator/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 proforma-extended-evaluator`
+7. Publish package to RubyGems: `gem push proforma-extended-evaluator-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 'proforma/extended_evaluator'
+
+# 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/proforma/extended_evaluator/formatter.rb

@@ -0,0 +1,129 @@
+# 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 Proforma
+  class ExtendedEvaluator
+    # This library uses Stringento for its string-based formatting.  This class is meant to be
+    # plugged into Stringento to provide formatting for data types, such as: strings, dates,
+    # currency, numbers, etc.
+    class Formatter < Stringento::Formatter
+      DEFAULTS = {
+        currency_code: 'USD',
+        currency_round: 2,
+        currency_symbol: '$',
+        date_format: '%m/%d/%Y',
+        mask_char: 'X',
+        false_value: 'No',
+        null_value: 'Unknown',
+        true_value: 'Yes'
+      }.freeze
+
+      ISO_DATE_FORMAT           = '%Y-%m-%d'
+      NULLISH                   = /(nil|null)$/i.freeze
+      THOUSANDS_WITH_DECIMAL    = /(\d)(?=\d{3}+\.)/.freeze
+      THOUSANDS_WITHOUT_DECIMAL = /(\d)(?=\d{3}+$)/.freeze
+      TRUTHY                    = /(true|t|yes|y|1)$/i.freeze
+
+      attr_reader :currency_code,
+                  :currency_round,
+                  :currency_symbol,
+                  :date_format,
+                  :false_value,
+                  :mask_char,
+                  :null_value,
+                  :true_value
+
+      def initialize(opts = {})
+        opts = DEFAULTS.merge(opts)
+
+        @currency_code   = opts[:currency_code]
+        @currency_round  = opts[:currency_round]
+        @currency_symbol = opts[:currency_symbol]
+        @date_format     = opts[:date_format]
+        @false_value     = opts[:false_value]
+        @mask_char       = opts[:mask_char]
+        @null_value      = opts[:null_value]
+        @true_value      = opts[:true_value]
+      end
+
+      def left_mask_formatter(value, arg)
+        keep_last = arg.to_s.empty? ? 4 : arg.to_s.to_i
+
+        string_value = value.to_s
+
+        return ''     if null_or_empty?(string_value)
+        return value  if string_value.length <= keep_last
+
+        mask(string_value, keep_last)
+      end
+
+      def date_formatter(value, _arg)
+        return '' if null_or_empty?(value)
+
+        date = Date.strptime(value.to_s, ISO_DATE_FORMAT)
+
+        date.strftime(date_format)
+      end
+
+      def currency_formatter(value, _arg)
+        return '' if null_or_empty?(value)
+
+        prefix = null_or_empty?(currency_symbol) ? '' : currency_symbol
+        suffix = null_or_empty?(currency_code) ? '' : " #{currency_code}"
+
+        formatted_value = number_formatter(value, currency_round)
+
+        "#{prefix}#{formatted_value}#{suffix}"
+      end
+
+      def number_formatter(value, arg)
+        decimal_places = arg.to_s.empty? ? 6 : arg.to_s.to_i
+
+        regex = decimal_places.positive? ? THOUSANDS_WITH_DECIMAL : THOUSANDS_WITHOUT_DECIMAL
+
+        format("%0.#{decimal_places}f", value || 0).gsub(regex, '\1,')
+      end
+
+      def boolean_formatter(value, arg)
+        nullable = arg.to_s == 'nullable'
+
+        if nullable && nully?(value)
+          null_value
+        elsif truthy?(value)
+          true_value
+        else
+          false_value
+        end
+      end
+
+      private
+
+      def mask(string, keep_last)
+        unmasked_part     = string[-keep_last..-1]
+        masked_char_count = string.size - keep_last
+
+        (mask_char * masked_char_count) + unmasked_part
+      end
+
+      def null_or_empty?(val)
+        val.nil? || val.to_s.empty?
+      end
+
+      # rubocop:disable Style/DoubleNegation
+      def nully?(val)
+        null_or_empty?(val) || !!(val.to_s =~ NULLISH)
+      end
+
+      def truthy?(val)
+        !!(val.to_s =~ TRUTHY)
+      end
+      # rubocop:enable Style/DoubleNegation
+    end
+  end
+end

data/lib/proforma/extended_evaluator/resolver.rb

@@ -0,0 +1,51 @@
+# 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 Proforma
+  class ExtendedEvaluator
+    # This class is also meant to be plugged into Stringento to provide value resolution.
+    class Resolver
+      DOT_NOTATION_SEPARATOR = '.'
+
+      def resolve(value, input)
+        traverse(input, value.to_s.split(DOT_NOTATION_SEPARATOR))
+      end
+
+      private
+
+      def traverse(object, through)
+        pointer = object
+
+        through.each do |t|
+          next unless pointer
+
+          pointer = get(pointer, t)
+        end
+
+        pointer
+      end
+
+      def get(object, key)
+        if object.is_a?(Hash)
+          indifferent_hash_get(object, key)
+        elsif object.respond_to?(key)
+          object.send(key)
+        end
+      end
+
+      def indifferent_hash_get(hash, key)
+        if hash.key?(key.to_s)
+          hash[key.to_s]
+        elsif hash.key?(key.to_s.to_sym)
+          hash[key.to_s.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/proforma/extended_evaluator/version.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.
+#
+
+module Proforma
+  class ExtendedEvaluator
+    VERSION = '1.0.0-alpha'
+  end
+end

data/lib/proforma/extended_evaluator.rb

@@ -0,0 +1,49 @@
+# 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 'bigdecimal'
+require 'stringento'
+
+require_relative 'extended_evaluator/formatter'
+require_relative 'extended_evaluator/resolver'
+
+module Proforma
+  # This class provides robust functionality for value resolution and text templating.
+  # For value resolution it uses its own dot-notation and
+  # message-based object traversal algorithm.
+  # For text templating it uses the Stringento library.
+  class ExtendedEvaluator
+    attr_reader :formatter, :resolver
+
+    def initialize(formatter: Formatter.new, resolver: Resolver.new)
+      raise ArgumentError, 'formatter is required'  unless formatter
+      raise ArgumentError, 'resolver is required'   unless resolver
+
+      @formatter  = formatter
+      @resolver   = resolver
+
+      freeze
+    end
+
+    def value(object, expression)
+      resolver.resolve(expression, object)
+    end
+
+    def text(object, expression)
+      record = object.is_a?(Array) || object.nil? ? {} : object
+
+      Stringento.evaluate(
+        expression.to_s,
+        record,
+        resolver: resolver,
+        formatter: formatter
+      )
+    end
+  end
+end

data/proforma-extended-evaluator.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require './lib/proforma/extended_evaluator/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'proforma-extended-evaluator'
+  s.version     = Proforma::ExtendedEvaluator::VERSION
+  s.summary     = 'Proforma evaluator plugin for nested object value resolution and text templating'
+
+  s.description = <<-DESCRIPTION
+    Proforma comes with basic object value resolution and no text templating.
+    This library fills these necessities that any reasonably robust document rendering framework should have.
+  DESCRIPTION
+
+  s.authors     = ['Matthew Ruggio']
+  s.email       = ['mruggio@bluemarblepayroll.com']
+  s.files       = `git ls-files`.split("\n")
+  s.test_files  = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.homepage    = 'https://github.com/bluemarblepayroll/proforma-extended-evaluator'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 2.3.8'
+
+  s.add_dependency('stringento', '~>2')
+
+  s.add_development_dependency('guard-rspec', '~>4.7')
+  s.add_development_dependency('proforma', '>=1.0.0-alpha')
+  s.add_development_dependency('pry', '~>0')
+  s.add_development_dependency('rspec', '~> 3.8')
+  s.add_development_dependency('rubocop', '~>0.63.1')
+  s.add_development_dependency('simplecov', '~>0.16.1')
+  s.add_development_dependency('simplecov-console', '~>0.4.2')
+end

data/spec/proforma/extended_evaluator/formatter_spec.rb

@@ -0,0 +1,157 @@
+# 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 'spec_helper'
+
+describe Proforma::ExtendedEvaluator::Formatter do
+  describe '#left_mask_formatter' do
+    specify 'returns empty string if value is null' do
+      expect(subject.left_mask_formatter(nil, '')).to eq('')
+    end
+
+    specify 'returns empty string if value is empty string' do
+      expect(subject.left_mask_formatter('', '')).to eq('')
+    end
+
+    context 'when arg is blank' do
+      let(:arg) { '' }
+
+      specify 'returns value if length is less than or equal to mask length' do
+        expect(subject.left_mask_formatter('a',       arg)).to eq('a')
+        expect(subject.left_mask_formatter('ab',      arg)).to eq('ab')
+        expect(subject.left_mask_formatter('abc',     arg)).to eq('abc')
+        expect(subject.left_mask_formatter('abcd',    arg)).to eq('abcd')
+        expect(subject.left_mask_formatter('abcde',   arg)).to eq('Xbcde')
+        expect(subject.left_mask_formatter('abcdef',  arg)).to eq('XXcdef')
+      end
+    end
+
+    context 'when arg is populated' do
+      let(:arg) { '2' }
+
+      specify 'returns value if length is less than or equal to mask length (arg)' do
+        expect(subject.left_mask_formatter('a',       arg)).to eq('a')
+        expect(subject.left_mask_formatter('ab',      arg)).to eq('ab')
+        expect(subject.left_mask_formatter('abc',     arg)).to eq('Xbc')
+        expect(subject.left_mask_formatter('abcd',    arg)).to eq('XXcd')
+        expect(subject.left_mask_formatter('abcde',   arg)).to eq('XXXde')
+        expect(subject.left_mask_formatter('abcdef',  arg)).to eq('XXXXef')
+      end
+    end
+  end
+
+  describe '#date_formatter' do
+    subject do
+      described_class.new(
+        date_format: '%m/%d/%Y'
+      )
+    end
+
+    let(:arg) { '' }
+
+    specify 'returns empty string if value is null' do
+      expect(subject.date_formatter(nil, '')).to eq('')
+    end
+
+    specify 'returns empty string if value is empty string' do
+      expect(subject.date_formatter('', '')).to eq('')
+    end
+
+    specify 'returns formatted date' do
+      expect(subject.date_formatter('2018-01-02', arg)).to eq('01/02/2018')
+    end
+  end
+
+  describe '#currency_formatter' do
+    subject do
+      described_class.new(
+        currency_code: 'USD',
+        currency_round: 2,
+        currency_symbol: '$'
+      )
+    end
+
+    let(:arg) { '' }
+
+    specify 'returns empty string if value is null' do
+      expect(subject.currency_formatter(nil, '')).to eq('')
+    end
+
+    specify 'returns empty string if value is empty string' do
+      expect(subject.currency_formatter('', '')).to eq('')
+    end
+
+    specify 'returns formatted currency' do
+      expect(subject.currency_formatter('12345.67', arg)).to eq('$12,345.67 USD')
+    end
+  end
+
+  describe '#number_formatter' do
+    subject do
+      described_class.new(
+        currency_code: 'USD',
+        currency_round: 2,
+        currency_symbol: '$'
+      )
+    end
+
+    let(:arg) { '3' }
+
+    specify 'returns empty string if value is null' do
+      expect(subject.currency_formatter(nil, '')).to eq('')
+    end
+
+    specify 'returns empty string if value is empty string' do
+      expect(subject.currency_formatter('', '')).to eq('')
+    end
+
+    specify 'returns formatted number' do
+      expect(subject.number_formatter('12345.67899', arg)).to eq('12,345.679')
+    end
+  end
+
+  describe '#boolean_formatter' do
+    context 'non-nullable' do
+      let(:arg) { '' }
+
+      it 'should format truthy' do
+        expect(subject.boolean_formatter(true,    arg)).to eq('Yes')
+        expect(subject.boolean_formatter('true',  arg)).to eq('Yes')
+        expect(subject.boolean_formatter('True',  arg)).to eq('Yes')
+        expect(subject.boolean_formatter('t',     arg)).to eq('Yes')
+        expect(subject.boolean_formatter('1',     arg)).to eq('Yes')
+        expect(subject.boolean_formatter(1,       arg)).to eq('Yes')
+      end
+
+      it 'should format falsy' do
+        expect(subject.boolean_formatter(false,   arg)).to eq('No')
+        expect(subject.boolean_formatter('false', arg)).to eq('No')
+        expect(subject.boolean_formatter('False', arg)).to eq('No')
+        expect(subject.boolean_formatter(0,       arg)).to eq('No')
+        expect(subject.boolean_formatter('f',     arg)).to eq('No')
+      end
+
+      it 'should format nully' do
+        expect(subject.boolean_formatter(nil,     arg)).to eq('No')
+        expect(subject.boolean_formatter('nil',   arg)).to eq('No')
+        expect(subject.boolean_formatter('null',  arg)).to eq('No')
+      end
+    end
+
+    context 'nullable' do
+      let(:arg) { 'nullable' }
+
+      it 'should format nully' do
+        expect(subject.boolean_formatter(nil,     arg)).to eq('Unknown')
+        expect(subject.boolean_formatter('nil',   arg)).to eq('Unknown')
+        expect(subject.boolean_formatter('null',  arg)).to eq('Unknown')
+      end
+    end
+  end
+end

data/spec/proforma/extended_evaluator/resolver_spec.rb

@@ -0,0 +1,43 @@
+# 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 'spec_helper'
+
+describe Proforma::ExtendedEvaluator::Resolver do
+  subject { described_class.new }
+
+  context 'when input is a hash' do
+    let(:input) { { 'id' => 1, demographics: { 'first' => 'Matt' } } }
+
+    specify '#resolve gets correct value' do
+      expect(subject.resolve(:id, input)).to  eq(input['id'])
+      expect(subject.resolve('id', input)).to eq(input['id'])
+
+      expect(subject.resolve('demographics.first', input)).to eq(input.dig(:demographics, 'first'))
+    end
+  end
+
+  context 'when input is an OpenStruct' do
+    let(:input) do
+      OpenStruct.new(
+        id: 1,
+        demographics: OpenStruct.new(
+          first: 'Matt'
+        )
+      )
+    end
+
+    specify '#resolve gets correct value' do
+      expect(subject.resolve(:id, input)).to  eq(input.id)
+      expect(subject.resolve('id', input)).to eq(input.id)
+
+      expect(subject.resolve('demographics.first', input)).to eq(input.demographics.first)
+    end
+  end
+end

data/spec/proforma/extended_evaluator_spec.rb

@@ -0,0 +1,130 @@
+# 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 'spec_helper'
+
+describe Proforma::ExtendedEvaluator do
+  describe '#initialize' do
+    it 'should raise ArgumentError if formatter is null' do
+      expect { described_class.new(formatter: nil) }.to raise_error(ArgumentError)
+    end
+
+    it 'should raise ArgumentError if resolver is null' do
+      expect { described_class.new(resolver: nil) }.to raise_error(ArgumentError)
+    end
+
+    it 'should assign formatter and resolver' do
+      formatter = Proforma::ExtendedEvaluator::Formatter.new
+      resolver = Proforma::ExtendedEvaluator::Resolver.new
+
+      instance = described_class.new(formatter: formatter, resolver: resolver)
+
+      expect(instance.formatter).to equal(formatter)
+      expect(instance.resolver).to equal(resolver)
+    end
+  end
+
+  specify '#value is delegated to resolver#resolve' do
+    resolver    = Proforma::ExtendedEvaluator::Resolver.new
+    object      = { id: 1 }
+    expression  = 'id'
+
+    instance = described_class.new(resolver: resolver)
+
+    expect(resolver).to receive(:resolve).with(expression, object)
+
+    instance.value(object, expression)
+  end
+
+  specify '#text will use blank object if an array is passed in' do
+    object      = [{ id: 1 }]
+    expression  = '{id}'
+
+    instance = described_class.new
+
+    actual_text = instance.text(object, expression)
+
+    expect(actual_text).to eq('')
+  end
+
+  specify '#text will use object if an object is passed in' do
+    object      = { id: 1 }
+    expression  = '{id}'
+
+    instance = described_class.new
+
+    actual_text = instance.text(object, expression)
+
+    expect(actual_text).to eq('1')
+  end
+
+  specify 'Proforma Rendering Example' do
+    data = [
+      {
+        id: 1,
+        person: {
+          first: 'James',
+          last: 'Bond',
+          dob: '1960-05-14',
+          smoker: false,
+          ssn: '123-45-6789'
+        },
+        balance: '123.445388'
+      }
+    ]
+
+    template = {
+      children: [
+        {
+          type: 'Grouping',
+          children: [
+            {
+              type: 'Header',
+              value: 'Details For: {person.last}, {person.first} ({id})'
+            },
+            {
+              type: 'Pane',
+              columns: [
+                {
+                  lines: [
+                    { label: 'ID #', value: '{id::number::0}' },
+                    { label: 'First Name', value: '{person.first}' },
+                    { label: 'Last Name', value: '{person.last}' },
+                    { label: 'Social Security #', value: '{person.ssn::left_mask}' }
+                  ]
+                },
+                {
+                  lines: [
+                    { label: 'Birthdate', value: '{person.dob::date}' },
+                    { label: 'Smoker', value: '{person.smoker::boolean}' },
+                    { label: 'Balance', value: '{balance::currency}' }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+
+    actual_documents = Proforma.render(data, template, evaluator: Proforma::ExtendedEvaluator.new)
+
+    expected_documents = [
+      Proforma::Document.new(
+        contents: "DETAILS FOR: BOND, JAMES (1)\nID #: 1\nFirst Name: James\nLast Name:"\
+                  " Bond\nSocial Security #: XXXXXXX6789\nBirthdate: 05/14/1960\nSmoker:"\
+                  " No\nBalance: $123.45 USD\n",
+        extension: '.txt',
+        title: ''
+      )
+    ]
+
+    expect(actual_documents).to eq(expected_documents)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+# 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 'yaml'
+require 'pry'
+require 'proforma'
+
+require 'simplecov'
+require 'simplecov-console'
+SimpleCov.formatter = SimpleCov::Formatter::Console
+SimpleCov.start
+
+require './lib/proforma/extended_evaluator'

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: proforma-extended-evaluator
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre.alpha
+platform: ruby
+authors:
+- Matthew Ruggio
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-04-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: stringento
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.7'
+- !ruby/object:Gem::Dependency
+  name: proforma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0.pre.alpha
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0.pre.alpha
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.63.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.63.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+description: |2
+      Proforma comes with basic object value resolution and no text templating.
+      This library fills these necessities that any reasonably robust document rendering framework should have.
+email:
+- mruggio@bluemarblepayroll.com
+executables:
+- console
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE
+- README.md
+- bin/console
+- lib/proforma/extended_evaluator.rb
+- lib/proforma/extended_evaluator/formatter.rb
+- lib/proforma/extended_evaluator/resolver.rb
+- lib/proforma/extended_evaluator/version.rb
+- proforma-extended-evaluator.gemspec
+- spec/proforma/extended_evaluator/formatter_spec.rb
+- spec/proforma/extended_evaluator/resolver_spec.rb
+- spec/proforma/extended_evaluator_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/bluemarblepayroll/proforma-extended-evaluator
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.8
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Proforma evaluator plugin for nested object value resolution and text templating
+test_files:
+- spec/proforma/extended_evaluator/formatter_spec.rb
+- spec/proforma/extended_evaluator/resolver_spec.rb
+- spec/proforma/extended_evaluator_spec.rb
+- spec/spec_helper.rb