portable 1.0.0.pre.alpha → 1.0.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06ca8f7296a55a271a94e228c6e47f7c8d572e42ed43ea7f03b3dc9547b05fc1
-  data.tar.gz: ebc9dc0c2f3867c468e27e4976a9f8a9304f739449b228b520a97cd14ec23b2f
+  metadata.gz: 112f223aca7d26dda5b4e9c93b1e83174885e941806de503c2d15be37047cdc1
+  data.tar.gz: 7d9764151388559dd0ac999b69fa4bed16ff9d02fdb796944ff4d22b30b5056d
 SHA512:
-  metadata.gz: 1497db394e1dab96acbe34327a683e5e3390f0912461c8ae2e312def8996b7add5f025012e9871ccb3193014d123e23ba2993625af9a462e86756f00d00b1550
-  data.tar.gz: 5e0ea223a2d1894075e6fcf07b0eecd6a7242e37263ba7bea4e01ffefe22f95c7bcaad18fef35e74ae4b7435efc8012636dcb1e0d10a349c802327726a65dcf1
+  metadata.gz: 0bb98a4e53e669c13fbf361d2b3e5be4572ce2b42ab99e43b555ecc8db7c89c25cd28b653b61bc1b3ab2ace6688886ba0f1d45f04d4d1bcb3b178d7183adad6a
+  data.tar.gz: 14ac7eebf7b0af0b6553317e1d9f1f51757554ad43b9f0827a036ed12ff9ff9b67c5e2feb5db03566cce6ce43783ad8a24e0aed42a2a5367e306283531cb0214

data/README.md

@@ -31,7 +31,7 @@ bundle add portable
 
 ## Examples
 
-### Getting Started with Exports
+### Getting Started Writing CSV Files
 
 Consider the following data set as an array of hashes:
 
@@ -45,26 +45,24 @@ patients = [
 We could configure an export like so:
 
 ````ruby
-export = {
-  columns: [
-    { header: :first },
-    { header: :last },
-    { header: :dob }
-  ]
+document = {
+  data_table: {
+    columns: [
+      { header: :first },
+      { header: :last },
+      { header: :dob }
+    ]
+  }
 }
 ````
 
 And execute the export against the example dataset in order to generate a CSV file:
 
 ````ruby
-writer   = Portable::Writer.new(export)
+writer   = Portable::Csv::Writer.new(export)
 filename = File.join('tmp', 'patients.csv')
 
-writer.open(filename) do |writer|
-  patients.each do |patient|
-    writer.write(object: patient)
-  end
-end
+writer.open(filename) { |writer| writer.write_all(patients) }
 ````
 
 We should now have a CSV file at tmp/patients.csv that looks like this:
@@ -78,31 +76,33 @@ Frank | Rizzo | 1930-09-22
 
 This library uses Realize under the hood, so you have the option of configuring any transformation pipeline for each column.  Reviewing [Realize's list of transformers](https://github.com/bluemarblepayroll/realize#transformer-gallery) is recommended to see what is available.
 
-Let's expand our example above with different headers and date formatting:
+Let's expand our CSV example above with different headers and date formatting:
 
 ````ruby
-export = {
-  columns: [
-    {
-      header: 'First Name',
-      transformers: [
-        { type: 'r/value/resolve', key: :first }
-      ]
-    },
-    {
-      header: 'Last Name',
-      transformers: [
-        { type: 'r/value/resolve', key: :last }
-      ]
-    },
-    {
-      header: 'Date of Birth',
-      transformers: [
-        { type: 'r/value/resolve', key: :dob },
-        { type: 'r/format/date', output_format: '%m/%d/%Y' },
-      ]
-    }
-  ]
+document = {
+  data_table: {
+    columns: [
+      {
+        header: 'First Name',
+        transformers: [
+          { type: 'r/value/resolve', key: :first }
+        ]
+      },
+      {
+        header: 'Last Name',
+        transformers: [
+          { type: 'r/value/resolve', key: :last }
+        ]
+      },
+      {
+        header: 'Date of Birth',
+        transformers: [
+          { type: 'r/value/resolve', key: :dob },
+          { type: 'r/format/date', output_format: '%m/%d/%Y' },
+        ]
+      }
+    ]
+  }
 }
 ````
 
@@ -115,6 +115,71 @@ Frank      | Rizzo     | 09/22/1930
 
 Realize is also [pluggable](https://github.com/bluemarblepayroll/realize#plugging-in-transformers), so you are able to create your own and plug them directly into Realize.
 
+### Options
+
+Each writer can have its own set of options.
+
+#### CSV Options
+
+The following options are available for customizing CSV documents:
+
+* byte_order_mark: (optional, default is nothing): This option will write out a byte order mark identifying the encoding for the file.  This is useful for ensuring applications like Microsoft Excel open CSV files properly.  See Portable::Csv::ByteOrderMark constants for acceptable values.
+
+### Custom Header/Footer Rows
+
+The main document model can also include statically defined rows to place either at the header (above data table) or footer (below data table) locations.  For example:
+
+````ruby
+document = {
+  data_table: {
+    columns: [
+      {
+        header: 'First Name',
+        transformers: [
+          { type: 'r/value/resolve', key: :first }
+        ]
+      },
+      {
+        header: 'Last Name',
+        transformers: [
+          { type: 'r/value/resolve', key: :last }
+        ]
+      },
+      {
+        header: 'Date of Birth',
+        transformers: [
+          { type: 'r/value/resolve', key: :dob },
+          { type: 'r/format/date', output_format: '%m/%d/%Y' },
+        ]
+      }
+    ]
+  },
+  header_rows: [
+    [ 'Run Date', '04/05/2000' ],
+    [ 'Run By', 'Hops the Bunny' ],
+    [],
+    [ 'BEGIN' ]
+  ],
+  header_rows: [
+    [ 'END' ]
+  ],
+}
+````
+
+Using this document configuration would yield a CSV with four "header rows" at the top, one "data table header row", two data rows, and one "footer row".  This is not easily illustrated in Markdown, but this would be the result:
+
+````
+Run Date   | 04/05/2000
+Run By     | Hops the Bunny
+
+BEGIN
+First Name | Last Name | Date of Birth
+---------- | --------- | -------------
+Marky      | Mark      | 04/05/2000
+Frank      | Rizzo     | 09/22/1930
+END
+````
+
 ## Contributing
 
 ### Development Environment Configuration

data/lib/portable.rb

@@ -10,8 +10,12 @@
 require 'acts_as_hashable'
 require 'csv'
 require 'fileutils'
+require 'forwardable'
 require 'objectable'
 require 'realize'
 require 'time'
 
-require_relative 'portable/writer'
+require_relative 'portable/data_table'
+require_relative 'portable/document'
+require_relative 'portable/transformer'
+require_relative 'portable/writers'

data/lib/portable/csv/byte_order_mark.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 Portable
+  module Csv
+    # Define all acceptable byte order mark values.
+    module ByteOrderMark
+      UTF_8    = "\xEF\xBB\xBF"
+      UTF_16BE = "\xFE\xFF"
+      UTF_16LE = "\xFF\xFE"
+      UTF_32BE = "\x00\x00\xFE\xFF"
+      UTF_32LE = "\xFE\xFF\x00\x00"
+
+      class << self
+        def resolve(value)
+          value ? const_get(value.to_s.upcase.to_sym) : nil
+        end
+      end
+    end
+  end
+end

data/lib/portable/csv/document.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 'options'
+
+module Portable
+  module Csv
+    # Defines all the options for an export including static header rows, footer rows, and how
+    # to draw the data table.
+    class Document < Portable::Document
+      attr_reader :options
+
+      def_delegators :options,
+                     :byte_order_mark,
+                     :byte_order_mark?
+
+      def initialize(data_table: {}, footer_rows: [], header_rows: [], options: {})
+        @options = Options.make(options)
+
+        super(
+          data_table: data_table,
+          footer_rows: footer_rows,
+          header_rows: header_rows
+        )
+      end
+    end
+  end
+end

data/lib/portable/csv/options.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 'byte_order_mark'
+
+module Portable
+  module Csv
+    # Defines all the options for an export including static header rows, footer rows, and how
+    # to draw the data table.
+    class Options
+      acts_as_hashable
+
+      attr_reader :byte_order_mark
+
+      def initialize(byte_order_mark: nil)
+        @byte_order_mark = ByteOrderMark.resolve(byte_order_mark)
+
+        freeze
+      end
+
+      def byte_order_mark?
+        !byte_order_mark.nil?
+      end
+    end
+  end
+end

data/lib/portable/csv/writer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 'document'
+
+module Portable
+  module Csv
+    # Main API for writing files.  There are two main patterns to choose from:
+    #   1. calling #open, #write, and #close manually.
+    #   2. calling #open and passing a block and having #close automatically called.
+    class Writer
+      class AlreadyOpenError < StandardError; end
+      class NotOpenError < StandardError; end
+
+      attr_reader :csv, :document, :time, :transformer
+
+      def initialize(document, resolver: Objectable.resolver, time: Time.now.utc)
+        @document    = Document.make(document, nullable: false)
+        @time        = time || Time.now.utc
+        @transformer = Transformer.new(@document.columns, resolver: resolver)
+      end
+
+      def open?
+        !csv.nil?
+      end
+
+      # Will raise a AlreadyOpenError exception if a writer has already been opened but
+      # not yet closed.
+      def open(filename)
+        raise AlreadyOpenError, 'writer is already open' if open?
+
+        initialize_csv(filename)
+        write_head
+
+        if block_given?
+          yield self
+          close
+        end
+
+        self
+      end
+
+      # Will raise a NotOpenError exception if a writer has not yet been opened.
+      def write_all(objects = [])
+        raise NotOpenError, 'writer is not open' unless open?
+
+        objects.each { |o| write(o) }
+
+        self
+      end
+
+      # Will raise a NotOpenError exception if a writer has not yet been opened.
+      def write(object = {})
+        raise NotOpenError, 'writer is not open' unless open?
+
+        csv << transformer.transform(object, time).values
+
+        self
+      end
+
+      # Will raise a NotOpenError exception if a writer has not yet been opened.
+      def close
+        raise NotOpenError, 'writer is not open' unless open?
+
+        write_foot
+
+        @csv.close
+        @csv = nil
+        self
+      end
+
+      private
+
+      def ensure_directory_exists(filename)
+        path = File.dirname(filename)
+
+        FileUtils.mkdir_p(path) unless File.exist?(path)
+      end
+
+      def initialize_csv(filename)
+        ensure_directory_exists(filename)
+
+        @csv = CSV.open(filename, 'w')
+
+        csv.to_io.write(document.byte_order_mark) if document.byte_order_mark?
+      end
+
+      def write_head
+        raw_write(document.header_rows)
+
+        csv << document.headers if document.include_headers?
+      end
+
+      def write_foot
+        raw_write(document.footer_rows)
+      end
+
+      def raw_write(rows)
+        rows.each { |row| csv << row }
+      end
+    end
+  end
+end

data/lib/portable/{export.rb → data_table.rb}

@@ -10,30 +10,30 @@
 require_relative 'column'
 
 module Portable
-  # Defines all the options for an export like columns, whether or not you want to include
-  # headers, and more.
-  class Export
+  # Defines all the options for the data grid within an export like columns, whether or not
+  # you want to include headers, and more.
+  class Datagrid
     acts_as_hashable
 
-    module Bom
-      UTF8 = "\uFEFF"
-    end
-    include Bom
-
-    attr_reader :bom, :columns, :include_headers
+    attr_reader :columns
 
-    alias include_headers? include_headers
-
-    def initialize(bom: nil, columns: [], include_headers: true)
-      @bom             = bom ? Bom.const_get(bom.to_s.upcase.to_sym) : nil
+    def initialize(columns: [], include_headers: true)
       @columns         = Column.array(columns)
       @include_headers = include_headers || false
 
       freeze
     end
 
+    def include_headers?
+      include_headers
+    end
+
     def headers
       columns.map(&:header)
     end
+
+    private
+
+    attr_reader :include_headers
   end
 end

data/lib/portable/document.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 Portable
+  # Base document object model defining what all documents should include.
+  class Document
+    acts_as_hashable
+    extend Forwardable
+
+    attr_reader :data_table,
+                :footer_rows,
+                :header_rows
+
+    def_delegators :data_table,
+                   :columns,
+                   :headers,
+                   :include_headers?,
+                   :headers,
+                   :transform
+
+    def initialize(data_table: {}, footer_rows: [], header_rows: [])
+      @data_table  = Datagrid.make(data_table)
+      @footer_rows = footer_rows || []
+      @header_rows = header_rows || []
+
+      freeze
+    end
+  end
+end

data/lib/portable/transformer.rb

@@ -7,8 +7,6 @@
 # LICENSE file in the root directory of this source tree.
 #
 
-require_relative 'export'
-
 module Portable
   # Internal intermediary class that knows how to combine columns specification instances with their
   # respective Realize pipelines.

data/lib/portable/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Portable
-  VERSION = '1.0.0-alpha'
+  VERSION = '1.0.0-alpha.1'
 end

data/lib/portable/writers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2020-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 'csv/writer'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portable
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha
+  version: 1.0.0.pre.alpha.1
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2020-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -174,10 +174,15 @@ files:
 - exe/.gitkeep
 - lib/portable.rb
 - lib/portable/column.rb
-- lib/portable/export.rb
+- lib/portable/csv/byte_order_mark.rb
+- lib/portable/csv/document.rb
+- lib/portable/csv/options.rb
+- lib/portable/csv/writer.rb
+- lib/portable/data_table.rb
+- lib/portable/document.rb
 - lib/portable/transformer.rb
 - lib/portable/version.rb
-- lib/portable/writer.rb
+- lib/portable/writers.rb
 - portable.gemspec
 homepage: https://github.com/bluemarblepayroll/portable
 licenses:

data/lib/portable/writer.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Copyright (c) 2020-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 'export'
-require_relative 'transformer'
-
-module Portable
-  # Main API for writing files.  There are two main patterns to choose from:
-  #   1. calling #open, #write, and #close manually.
-  #   2. calling #open and passing a block and having #close automatically called.
-  class Writer
-    class AlreadyOpenError < StandardError; end
-    class NotOpenError < StandardError; end
-
-    attr_reader :csv, :export, :transformer
-
-    def initialize(export, resolver: Objectable.resolver)
-      @export      = Export.make(export, nullable: false)
-      @transformer = Transformer.new(@export.columns, resolver: resolver)
-    end
-
-    def open?
-      !csv.nil?
-    end
-
-    # Will raise a AlreadyOpenError exception if a writer has already been opened but
-    # not yet closed.
-    def open(filename)
-      raise AlreadyOpenError, 'writer is already open' if open?
-
-      initialize_csv(filename)
-
-      if block_given?
-        yield self
-        close
-      end
-
-      self
-    end
-
-    # Will raise a NotOpenError exception if a writer has not yet been opened.
-    def write(object: {}, time: Time.now.utc)
-      raise NotOpenError, 'writer is not open' unless open?
-
-      csv << transformer.transform(object, time).values
-
-      self
-    end
-
-    # Will raise a NotOpenError exception if a writer has not yet been opened.
-    def close
-      raise NotOpenError, 'writer is not open' unless open?
-
-      @csv.close
-      @csv = nil
-      self
-    end
-
-    private
-
-    def ensure_directory_exists(filename)
-      path = File.dirname(filename)
-
-      FileUtils.mkdir_p(path) unless File.exist?(path)
-    end
-
-    def initialize_csv(filename)
-      ensure_directory_exists(filename)
-
-      @csv = CSV.open(filename, 'w')
-
-      csv.to_io.write(export.bom) if export.bom
-      csv << export.headers       if export.include_headers?
-    end
-  end
-end