proforma 1.0.0.pre.alpha

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'proforma'
+
+# 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/bin/render

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'proforma'
+require 'fileutils'
+require 'yaml'
+require 'pry'
+
+def read_yaml(filename)
+  # rubocop:disable Security/YAMLLoad
+  YAML.load(read(filename))
+  # rubocop:enable Security/YAMLLoad
+end
+
+def read(filename)
+  File.open(filename, 'r:bom|utf-8').read
+end
+
+jobs_dir = File.join('tmp', 'jobs')
+output_dir = File.join('tmp', 'jobs_output')
+
+jobs = Dir[File.join(jobs_dir, '*.yml')]
+
+if jobs.empty?
+  puts "No jobs detected in the path: #{jobs_dir}"
+  puts '--------------------------------------------------------------'
+  puts "To use, place YAML files into #{jobs_dir} directory."
+  puts 'You can find example YAML files in: spec/fixtures/snapshots'
+  puts '--------------------------------------------------------------'
+
+  exit
+end
+
+jobs.each do |job|
+  job_name = File.basename(job, File.extname(job))
+
+  puts "Rendering: #{job_name} (#{job})"
+
+  contents        = read_yaml(job)
+  data            = contents['data']
+  template        = contents['template']
+  evaluator       = contents['evaluator'] || Proforma::HashEvaluator.new
+  renderer        = contents['renderer'] || Proforma::PlainTextRenderer.new
+  job_output_dir  = File.join(output_dir, job_name)
+
+  FileUtils.mkdir_p(job_output_dir)
+
+  outputs = Proforma.render(
+    data,
+    template,
+    evaluator: evaluator,
+    renderer: renderer
+  )
+
+  outputs.each_with_index do |output, index|
+    name_without_extension = [
+      index.to_s,
+      output.title.to_s
+    ].reject(&:empty?).join('.')
+
+    filename = "#{name_without_extension}#{output.extension}"
+
+    IO.write(File.join(job_output_dir, filename), output.contents)
+  end
+
+  puts "Done Rendering: #{job} (output can be found in: #{job_output_dir})"
+end

data/lib/proforma.rb

@@ -0,0 +1,38 @@
+# 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 'acts_as_hashable'
+require 'bigdecimal'
+require 'forwardable'
+require 'stringio'
+
+# Monkey-patching core libaries
+require_relative 'proforma/core_ext/hash'
+Hash.include ::Proforma::CoreExt::Hash
+
+require_relative 'proforma/compiling'
+require_relative 'proforma/document'
+require_relative 'proforma/hash_evaluator'
+require_relative 'proforma/modeling'
+require_relative 'proforma/plain_text_renderer'
+require_relative 'proforma/prototype'
+require_relative 'proforma/template'
+require_relative 'proforma/type_factory'
+require_relative 'proforma/model_factory'
+
+# The top-level API that should be seen as the main entry point into this library.
+module Proforma
+  class << self
+    def render(data, template, evaluator: HashEvaluator.new, renderer: PlainTextRenderer.new)
+      Template.make(template)
+              .compile(data, evaluator)
+              .map { |prototype| renderer.render(prototype) }
+    end
+  end
+end

data/lib/proforma/compiling.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.
+#
+
+require_relative 'compiling/aggregation'
+require_relative 'compiling/compilable'
+require_relative 'compiling/counter'

data/lib/proforma/compiling/aggregation.rb

@@ -0,0 +1,62 @@
+# 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
+  module Compiling
+    # This class is a group of aggregators that knows how to process records.
+    class Aggregation
+      attr_reader :aggregators, :evaluator
+
+      def initialize(aggregators, evaluator)
+        raise ArgumentError, 'evaluator is required' unless evaluator
+
+        @aggregators  = Array(aggregators)
+        @counters     = {}
+        @evaluator    = evaluator
+      end
+
+      def add(records)
+        records.each do |record|
+          aggregators.each do |aggregator|
+            property  = aggregator.property
+            value     = evaluator.value(record, property)
+            name      = aggregator.name
+
+            entry(name).add(value)
+          end
+        end
+
+        self
+      end
+
+      def to_hash
+        aggregators.map { |aggregator| execute(aggregator) }.to_h
+      end
+
+      private
+
+      attr_reader :counters
+
+      def entry(name)
+        counters[name.to_s] ||= Counter.new
+      end
+
+      def execute(aggregator)
+        name      = aggregator.name
+        function  = aggregator.function
+
+        raise ArgumentError, "bad func: #{function}" unless entry(name).respond_to?(function)
+
+        value = entry(name).send(function)
+
+        [name, value.to_s('f')]
+      end
+    end
+  end
+end

data/lib/proforma/compiling/compilable.rb

@@ -0,0 +1,21 @@
+# 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
+  module Compiling
+    # This mix-in provides common methods for model compilation.
+    module Compilable
+      private
+
+      def array(data)
+        data.is_a?(Hash) ? [data] : Array(data)
+      end
+    end
+  end
+end

data/lib/proforma/compiling/counter.rb

@@ -0,0 +1,35 @@
+# 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
+  module Compiling
+    # A counter is the actual underlying data structure for aggregation.
+    class Counter
+      attr_reader :count, :sum
+
+      def initialize
+        @count = 0
+        @sum   = BigDecimal(0)
+      end
+
+      def add(value)
+        parsed_value = value.to_s.empty? ? 0 : BigDecimal(value.to_s)
+
+        @count += 1
+        @sum   += parsed_value
+
+        self
+      end
+
+      def ave
+        sum / count
+      end
+    end
+  end
+end

data/lib/proforma/core_ext/hash.rb

@@ -0,0 +1,21 @@
+# 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
+  module CoreExt
+    # Monkey-patches for the core Hash class.  These will be manually mixed in separately.
+    module Hash
+      unless method_defined?(:symbolize_keys)
+        def symbolize_keys
+          map { |k, v| [k.to_sym, v] }.to_h
+        end
+      end
+    end
+  end
+end

data/lib/proforma/document.rb

@@ -0,0 +1,38 @@
+# 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
+  # A rendering engine will output one or more of these objects. It is the final realization
+  # of the compilation + rendering process.
+  class Document
+    acts_as_hashable
+
+    attr_reader :contents, :extension, :title
+
+    def initialize(contents: nil, extension: '', title: '')
+      @contents   = contents
+      @extension  = extension
+      @title      = title
+
+      freeze
+    end
+
+    def eql?(other)
+      return false unless other.is_a?(self.class)
+
+      contents == other.contents &&
+        extension == other.extension &&
+        title == other.title
+    end
+
+    def ==(other)
+      eql?(other)
+    end
+  end
+end

data/lib/proforma/hash_evaluator.rb

@@ -0,0 +1,40 @@
+# 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
+  # This class will serve as the evaluator that gets shipped with the base framework.
+  # Other packages can extend or create their own and plug them into the rendering
+  # pipeline.
+  # This, being a prototype for customizable evaluators, just provides basic evaluation:
+  # - it can only handle hashes for value extraction
+  # - if text is prefixed with a dollar sign and colon then it means it will be dynamically
+  #   evaluated against the record.  For example: $:id
+  class HashEvaluator
+    PROPERTY_PREFIX = '$:'
+
+    def value(object, expression)
+      return object if expression.to_s.empty?
+      return nil    unless object.is_a?(Hash)
+
+      if object.key?(expression.to_s)
+        object[expression.to_s]
+      elsif object.key?(expression.to_s.to_sym)
+        object[expression.to_s.to_sym]
+      end
+    end
+
+    def text(object, expression)
+      if expression.to_s.start_with?(PROPERTY_PREFIX)
+        value(object, expression.to_s[2..-1])
+      else
+        expression
+      end
+    end
+  end
+end

data/lib/proforma/model_factory.rb

@@ -0,0 +1,38 @@
+# 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
+  # This class serves as a singleton that can make Proforma::Modeling components.
+  class ModelFactory
+    REGISTRY = {
+      'Banner': Modeling::Banner,
+      'Collection': Modeling::Collection,
+      'DataTable': Modeling::DataTable,
+      'Grouping': Modeling::Grouping,
+      'Header': Modeling::Header,
+      'Pane': Modeling::Pane,
+      'Separator': Modeling::Separator,
+      'Spacer': Modeling::Spacer,
+      'Table': Modeling::Table,
+      'Text': Modeling::Text
+    }.freeze
+
+    class << self
+      extend Forwardable
+
+      def_delegators :factory, :array, :make
+
+      private
+
+      def factory
+        @factory ||= TypeFactory.new(REGISTRY)
+      end
+    end
+  end
+end

data/lib/proforma/modeling.rb

@@ -0,0 +1,21 @@
+# 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 'modeling/generic_container'
+require_relative 'modeling/types'
+require_relative 'modeling/banner'
+require_relative 'modeling/collection'
+require_relative 'modeling/data_table'
+require_relative 'modeling/grouping'
+require_relative 'modeling/header'
+require_relative 'modeling/pane'
+require_relative 'modeling/separator'
+require_relative 'modeling/spacer'
+require_relative 'modeling/table'
+require_relative 'modeling/text'

data/lib/proforma/modeling/banner.rb

@@ -0,0 +1,64 @@
+# 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
+  module Modeling
+    # A Banner is a specific type of header that is comprised of an image and some text.
+    # Both the image and text could be optional and, like all modeling components,
+    # it is up to the rendering engine how to render it.
+    class Banner
+      include Compiling::Compilable
+      acts_as_hashable
+
+      attr_writer :details, :image_height, :image_width, :title
+
+      attr_accessor :image
+
+      def initialize(
+        details: '',
+        image: nil,
+        image_height: nil,
+        image_width: nil,
+        title: ''
+      )
+        @details      = details
+        @image        = image
+        @image_height = image_height
+        @image_width  = image_width
+        @title        = title
+      end
+
+      def details
+        @details.to_s
+      end
+
+      def title
+        @title.to_s
+      end
+
+      def image_height
+        @image_height ? @image_height.to_f : nil
+      end
+
+      def image_width
+        @image_width ? @image_width.to_f : nil
+      end
+
+      def compile(data, evaluator)
+        self.class.new(
+          details: evaluator.text(data, details),
+          image: evaluator.value(data, image),
+          image_height: image_height,
+          image_width: image_width,
+          title: evaluator.text(data, title)
+        )
+      end
+    end
+  end
+end