proforma 1.0.0.pre.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 99a81eae5ad4326d4a525793b02615f3bcd5b7ac9bf3dd2e77d06b39f6fafe62
+  data.tar.gz: 4c3a71da8fa80f4a93117153ffb2a72ff35bbb624233f814d1669f821e3656d5
+SHA512:
+  metadata.gz: 1c77a46115ad3804aa9752ef9d118e2e068a7a4d446b59c93eb6184d8f6101dadedeae52e2764957443533549d275cdea8647c1c49cb5c5fc4dd802cba3b13c7
+  data.tar.gz: 3ef60250c4a60b014fe28ae9dc1917f01ef5cab6217ba1310c0662ac920172fa14c4599e9a502dcf6380b6aa70ed63d14e7f8cc38038417ba9aa15c4d5d0d9be

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=01997b4f8e96c9ea5d16ccfce52dad36705571483859d8f0e3cb8fdd8825a758
+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 (April 20th, 2019)
+
+Initial implementation.
+
+# 0.0.1 (March 14th, 2019)
+
+Library Shell.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,105 @@
+PATH
+  remote: .
+  specs:
+    proforma (1.0.0.pre.alpha)
+      acts_as_hashable (~> 1)
+
+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)
+    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)
+    thor (0.20.3)
+    unicode-display_width (1.4.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec (~> 4.7)
+  proforma!
+  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,328 @@
+# Proforma
+
+[![Gem Version](https://badge.fury.io/rb/proforma.svg)](https://badge.fury.io/rb/proforma) [![Build Status](https://travis-ci.org/bluemarblepayroll/proforma.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/proforma) [![Maintainability](https://api.codeclimate.com/v1/badges/71ab6d000e617989b3e1/maintainability)](https://codeclimate.com/github/bluemarblepayroll/proforma/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/71ab6d000e617989b3e1/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/proforma/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Proforma is a Ruby-based document rendering framework with a focus on being:
+
+1. Configurable: the virtual document model allows templates to be defined as configuration
+2. Simple: basic set of controls that limit flexibility but increase simplicity and standardization
+3. Extendable: different value resolvers and document rendering engines can be plugged in
+
+The basic premise is you input a dataset and a template and Proforma:
+
+1. Evaluate and data-bind each component
+2. Render as a file
+
+When a component is in the process of being data-bound it will be evaluated against the current data being read.  The evaluator serves two purposes:
+
+1. Given a record and an expression, find me a raw value (resolving)
+2. Given a record and an expression, return me a formatted string-based value (text templating)
+
+The basic evaluator that comes with this library is Proforma::HashEvaluator.  It is limited to:
+
+1. only resolving values for hash objects and cannot handle nesting / recursion / dot notation.
+2. only text templating simple expressions: if the expression starts with a ```$:``` then it is noted as being a data-bound value.  The value proceeding the ```$:``` will be resolved and returned.  If it does not begin with this special string then it is deemed just a basic string and it will be returned verbatim.
+
+Other libraries that can be plugged in, such as:
+
+1. [![proforma-extended-evaluator](https://github.com/bluemarblepayroll/proforma-extended-evaluator): adds nested dot-notation object value resolution and rich text templating.
+2. [![proforma-prawn-renderer](https://github.com/bluemarblepayroll/proforma-prawn-renderer)]: adds PDF rendering.
+
+See the libraries respective README files for more information.
+
+## Installation
+
+To install through Rubygems:
+
+````
+gem install install proforma
+````
+
+You can also add this to your Gemfile:
+
+````
+bundle add proforma
+````
+
+## Examples
+
+*The examples in this library will be based on the default plugins that are contained within package and thus will be as bare bones as they can be.  See other plugin library documentation to see how the input and output can be greatly enhanced.*
+
+## Virtual Document Object Model Introduction
+
+The following is a list of components that can be used for modeling:
+
+* Banner: define image, title, and details
+* DataTable: define columns with header, body, and footer contents
+* Grouping: one-to-many dataset traversal
+* Header: large, bold text
+* Pane: define columns and lines (akin to a details section)
+* Separator: draw a line
+* Spacer: blank space below component
+* Text: basic text
+
+Most aspects of the components will be data-bound.
+
+### Getting Started: Rendering a List
+
+Let's say we have a list of users:
+
+````ruby
+data = [
+  { id: 1, first: 'Matt', last: 'Smith' },
+  { id: 2, first: 'Katie', last: 'Rizzo' },
+  { id: 3, first: 'Nathan', last: 'Nathanson' }
+]
+
+template = {
+  title: 'User List',
+  children: [
+    {
+      type: 'DataTable',
+      columns: [
+        { header: 'ID Number', body: '$:id' },
+        { header: 'First Name', body: '$:first' },
+        { header: 'Last Name', body: '$:last' }
+      ]
+    }
+  ]
+}
+
+documents = Proforma.render(data, template)
+````
+
+The `documents` variable will now be an array with only one document object:
+
+````ruby
+documents = [
+  {
+    contents: "ID Number, First Name, Last Name\n1, Matt, Smith\n...", # condensed
+    extension: ".txt",
+    title: "User List"
+  )
+]
+````
+
+The `contents` attribute will be the rendered text-based table.
+
+### Rendering Records
+
+Let's now say instead of rendering a table we want to render one unique document per record:
+
+````ruby
+data = [
+  { id: 1, first: 'Matt', last: 'Smith' },
+  { id: 2, first: 'Katie', last: 'Rizzo' },
+  { id: 3, first: 'Nathan', last: 'Nathanson' }
+]
+
+template = {
+  title: 'User Details',
+  split: true, # notice the split directive here.
+  children: [
+    {
+      type: 'Pane',
+      columns: [
+        {
+          lines: [
+            { label: 'ID Number', value: '$:id' },
+            { label: 'First Name', value: '$:first' }
+          ]
+        },
+        {
+          lines: [
+            { label: 'Last Name', value: '$:last' }
+          ]
+        }
+      ]
+    }
+  ]
+}
+
+documents = Proforma.render(data, template)
+````
+
+The `documents` variable will now be an array with three document objects:
+
+````ruby
+documents = [
+  {
+    contents: "ID Number: 1\nFirst Name: Matt\nLast Name: Smith\n",
+    extension: ".txt",
+    title: "User Details"
+  },
+  {
+    contents: "ID Number: 2\nFirst Name: Katie\nLast Name: Rizzo\n",
+    extension: ".txt",
+    title: "User Details"
+  },
+  {
+    contents: "ID Number: 3\nFirst Name: Nathan\nLast Name: Nathanson\n",
+    extension: ".txt",
+    title: "User Details"
+  }
+]
+````
+
+Each document will have a `contents` attribute that contains its respective rendered text-based pane.
+
+### Bringing It All Together
+
+Let's build on our previous user list example and add more data.  With this additional data, we will add sub-data tables using grouping:
+
+````ruby
+data = [
+  {
+    id: 1,
+    first: 'Matt',
+    last: 'Smith',
+    phone_numbers: [
+      { type: 'Mobile', number: '444-333-2222' },
+      { type: 'Home', number: '444-333-2222' }
+    ]
+  },
+  {
+    id: 2,
+    first: 'Katie',
+    last: 'Rizzo',
+    phone_numbers: [
+      { type: 'Fax', number: '888-777-6666' }
+    ]
+  },
+  {
+    id: 3,
+    first: 'Nathan',
+    last: 'Nathanson',
+    phone_numbers: []
+  }
+]
+
+template = {
+  title: 'User Report',
+  children: [
+    {
+      type: 'Banner',
+      title: 'System A',
+      details: "555 N. Michigan Ave.\nChicago, IL 55555\n555-555-5555 ext. 5132"
+    },
+    { type: 'Header', value: 'User List' },
+    { type: 'Separator' },
+    { type: 'Spacer' },
+    {
+      type: 'DataTable',
+      columns: [
+        { header: 'ID Number', body: '$:id' },
+        { header: 'First Name', body: '$:first' },
+        { header: 'Last Name', body: '$:last' }
+      ]
+    },
+    { type: 'Spacer' },
+    {
+      type: 'Grouping',
+      children: [
+        { type: 'Header', value: 'User Details' },
+        { type: 'Separator' },
+        { type: 'Spacer' },
+        {
+          type: 'Pane',
+          columns: [
+            {
+              lines: [
+                { label: 'ID Number', value: '$:id' },
+                { label: 'First Name', value: '$:first' }
+              ]
+            },
+            {
+              lines: [
+                { label: 'Last Name', value: '$:last' }
+              ]
+            }
+          ]
+        },
+        {
+          type: 'DataTable',
+          property: 'phone_numbers',
+          columns: [
+            { header: 'Type', body: '$:type' },
+            { header: 'Number', body: '$:number' }
+          ]
+        },
+        { type: 'Spacer' }
+      ]
+    }
+  ]
+}
+
+documents = Proforma.render(data, template)
+````
+
+The `documents` variable will now be an array with only one document object:
+
+````ruby
+documents = [
+  {
+    contents: '========================================\nSystem A\n=======Nathan...', # ...
+    extension: '.txt',
+    title: 'User Report'
+  }
+]
+````
+
+The `contents` attribute will now contain:
+
+* banner
+* user summary table
+* user details pane (one per user)
+* user phone numbers table (one per user)
+
+## 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.gemspec for versions supported)
+2. Install bundler (gem install bundler)
+3. Clone the repository (git clone git@github.com:bluemarblepayroll/proforma.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/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`
+7. Publish package to RubyGems: `gem push proforma-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.