file_composer 1.0.0.pre.alpha → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b20f3a6535e696278e0963870386a581303c62d227ad900dc434d6b5c48ba628
-  data.tar.gz: 39ed8e5cc2a575991931bbe525955af31081e82db860dc2b0e69b14d162c5d8c
+  metadata.gz: ad520dd24873c117d6f7e9ab5ef900ed90b01b3292cb196ce844f06d2902dae2
+  data.tar.gz: fde077efef63fd9b162015a9c1d8283aac7658a7d38b53a43cc0a64d5fa6498c
 SHA512:
-  metadata.gz: 66ef27c3b5f2c608d1ba988e095287caae3c1b3ef563d7129088bddeb01d00010943d5ed59708b2f20572fc2cc1c8b1e1a84fea11040b4573cdb73f56868ada5
-  data.tar.gz: ee35c5159e6020032754a4cd7067a930da1d2c7a4aa59e806c4837ffa0847206e904fa5e18b91af39027fc42f924ebdb05d989cd63e0dce245d90440323782d7
+  metadata.gz: bfa28568e0235ca9b78000c1ee8ebb300242bf490d57ae437360c9aecba8a4671588fe3e86938e675cd1940cb09084adea6fc80a6d5e4b895eece6f755cc24b1
+  data.tar.gz: fdcf7bacac07f821b2f62709551ea205680d1e59e8284e0c8431f69ef688659356a69975a5c0ce608081fb2e1438b80c0bf4362b57b71de095d694e2631eecc7

data/CHANGELOG.md

@@ -1,3 +1,3 @@
-# 1.0.0 (TBD)
+# 1.0.0 (September 16th, 2020)
 
 Initial Release

data/README.md

@@ -2,25 +2,142 @@
 
 [![Gem Version](https://badge.fury.io/rb/file_composer.svg)](https://badge.fury.io/rb/file_composer) [![Build Status](https://travis-ci.org/bluemarblepayroll/file_composer.svg?branch=master)](https://travis-ci.org/bluemarblepayroll/file_composer) [![Maintainability](https://api.codeclimate.com/v1/badges/5360d687b0e93a4c7cf5/maintainability)](https://codeclimate.com/github/bluemarblepayroll/file_composer/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/5360d687b0e93a4c7cf5/test_coverage)](https://codeclimate.com/github/bluemarblepayroll/file_composer/test_coverage) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-TBD
+The library can serve as a foundation for creating a composable and declarative file creation API.  Out of the box, it only provides for the creation of text files and zip archives.  Within zip archives you can compose N number of nested zip archives and text files.  It is designed to first write to disk, then move the written files elsewhere, give then store passed in.  This library is intended to be extended by registering your own document types and then using File Composer as a higher-order configuration layer.
 
 ## Installation
 
 To install through Rubygems:
 
-````
-gem install install file_composer
+````bash
+gem install file_composer
 ````
 
 You can also add this to your Gemfile:
 
-````
+````bash
 bundle add file_composer
 ````
 
 ## Examples
 
-TBD
+### Writing Text Files
+
+The simplest way to start would be to write a couple text files.  We declare this as:
+
+````ruby
+config = {
+  documents: [
+    {
+      type: :text,
+      filename: 'hello.txt',
+      data: 'hello world!'
+    },
+    {
+      type: :text,
+      filename: 'hello2.txt',
+      data: 'hello world again!'
+    }
+  ]
+}
+````
+
+And then execute it:
+
+````ruby
+blueprint = FileComposer::Blueprint.make(config)
+
+results = blueprint.write!
+````
+
+This would generate two files within the current relative path.
+
+### Configuring the Temporary Store
+
+In the example above, we did not specify a temporary directory to write the file to.  We can do this simply by passing in a path as the first argument to `Blueprint#write!`:
+
+````ruby
+temp_path = File.join('tmp', 'file_composer')
+blueprint = FileComposer::Blueprint.make(config)
+
+results = blueprint.write!(temp_path)
+````
+
+The two files should now be located in `tmp/file_composer` within the relative path.
+
+### Writing to Permanent Storage
+
+The second argument for `Blueprint#write!` can be a Ruby object instance that responds to `move!(local_filename)` and returns the permanent location.  By default this library only ships with two stores:
+
+* **FileComposer::Stores::Null**: perform no move and return the temporary file path.
+* **FileComposer::Stores::Local**: perform a file move and return the new file path.  The file path will also be sharded using the inputted date (defaults to the current date UTC).  The sharding helps ensure a more even distribution of files so one directory does not end up with all the files.
+
+An example using a local store would be:
+
+````ruby
+root      = 'storage'
+store     = FileComposer::Stores::Local.new(root: root)
+temp_path = File.join('tmp', 'file_composer')
+blueprint = FileComposer::Blueprint.make(config)
+
+results = blueprint.write!(temp_path, store)
+````
+
+This will now produce two files within a `storage/YYYY/MM/DD` directory in the relative path.  These files were initially written within the temporary store, but then moved after completion.
+
+### Custom Stores
+
+A store can be any Ruby object instance that responds to `move!(local_filename)` and returns the permanent location.  For example, you may choose to implement a custom one that moves files to cloud-based storage (i.e. Amazon S3).
+
+### Writing Zip Archives
+
+Say we wanted to also include a zip archive of some other files, we could update our configuration from above to:
+
+````ruby
+config = {
+  documents: [
+    {
+      type: :text,
+      filename: 'hello.txt',
+      data: 'hello world!'
+    },
+    {
+      type: :text,
+      filename: 'hello2.txt',
+      data: 'hello world again!'
+    },
+    {
+      type: :zip,
+      filename: 'hello3.zip',
+      blueprint: {
+        documents: [
+          {
+            type: :text,
+            filename: 'hello4.txt',
+            data: 'hello world again... again!'
+          }
+        ]
+      }
+    }
+  ]
+}
+````
+
+And then execute it:
+
+````ruby
+blueprint = FileComposer::Blueprint.make(config)
+
+results = blueprint.write!
+````
+
+This would now generate three files within the current relative path.  Some notes:
+
+* The zip archive document type allows for a fully nested hierarchy, where you can have zip archives within zip archives.
+* Files within the same level need to have unique, case-insensitive filenames or else an error will be raised.
+
+### Plugging in Custom Documents
+
+The documents, text files and zip archives, are meant to serve as 'core' documents.  Consumer applications will not find much value in these types by themselves.  The class `FileComposer::Documents` is a factory that is able to have document types plugged in using the [acts_as_hashable_factory](https://github.com/bluemarblepayroll/acts_as_hashable) API.
 
 ## Contributing
 

data/file_composer.gemspec

@@ -5,10 +5,10 @@ require './lib/file_composer/version'
 Gem::Specification.new do |s|
   s.name        = 'file_composer'
   s.version     = FileComposer::VERSION
-  s.summary     = 'High-level, pluggable and YAML-based API for creating files'
+  s.summary     = 'High-level, pluggable, and declarative API for creating files'
 
   s.description = <<-DESCRIPTION
-    This library provides a YAML-based configuration, called a Blueprint, that allows you to specify text files and zip files and it will create them.  It is pluggable so other document types and storage mediums can be added.
+    This library provides a declarative API, called a Blueprint, that allows you to specify text files and zip files and it will create them.  It is pluggable so other document types and storage mediums can be added.
   DESCRIPTION
 
   s.authors     = ['Matthew Ruggio']
@@ -35,7 +35,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('pry', '~>0')
   s.add_development_dependency('rake', '~> 13')
   s.add_development_dependency('rspec', '~> 3.8')
-  s.add_development_dependency('rubocop', '~>0.88.0')
+  s.add_development_dependency('rubocop', '~>0.90.0')
   s.add_development_dependency('simplecov', '~>0.18.5')
   s.add_development_dependency('simplecov-console', '~>0.7.0')
 end

data/lib/file_composer/blueprint.rb

@@ -19,10 +19,10 @@ module FileComposer
 
     def initialize(documents: [])
       @documents = Documents.array(documents)
+      filenames  = @documents.map { |a| a.filename.downcase }
+      not_unique = filenames.uniq.length != @documents.length
 
-      filenames = @documents.map { |a| a.filename.downcase }
-
-      raise ArgumentError, "not unique: #{filenames}" if filenames.uniq.length != @documents.length
+      raise ArgumentError, "filenames not unique: #{filenames}" if not_unique
     end
 
     def write!(temp_root = '', store = Stores::Null.new)

data/lib/file_composer/documents.rb

@@ -11,7 +11,11 @@ require_relative 'documents/text'
 require_relative 'documents/zip'
 
 module FileComposer
-  # Factory for building documents.
+  # Factory for building documents.  To register new document types:
+  # - Implement a subclass for FileComposer::Documents::Base or a document compliant class.
+  #   The only real constraint is that it is hashable using the acts_as_hashable class method
+  #   and implements #write!(temp_root = '', store = Stores::Null.new)
+  # - Call FileComposer::Documents#register(name, class_constant_or_name)
   class Documents
     acts_as_hashable_factory
 

data/lib/file_composer/documents/result.rb

@@ -9,7 +9,9 @@
 
 module FileComposer
   class Documents
-    # The production of a document.
+    # Returns the result of a FileComposer::Document#write! call.  Each #write! call can produce
+    # N number of documents and each document will be represented in this instance's file_results
+    # attribute.
     class Result
       attr_reader :file_results,
                   :time_in_seconds

data/lib/file_composer/documents/zip.rb

@@ -23,8 +23,14 @@ module FileComposer
 
       def write!(temp_root = '', store = Stores::Null.new)
         results               = blueprint.write!(temp_root)
-        total_time_in_seconds = results.sum(&:time_in_seconds)
-        physical_filename     = zip!(temp_root, results)
+        write_time_in_seconds = results.sum(&:time_in_seconds)
+        physical_filename     = nil
+
+        zip_time_in_seconds = Benchmark.measure do
+          physical_filename = zip!(temp_root, results)
+        end.real
+
+        total_time_in_seconds = write_time_in_seconds + zip_time_in_seconds
 
         cleanup(results)
 

data/lib/file_composer/stores/local.rb

@@ -9,7 +9,17 @@
 
 module FileComposer
   module Stores
-    # File copier from local file system to the local file system.
+    # File copier from local file system to the local file system but with a sharded path
+    # with YYYY/MM/DD using the passed in date.  The date will default
+    # to the current date in UTC unless specified otherwise.  The filename passed in will be
+    # used to determine the extension but the destination will create a new GUID to use as
+    # the filename.  For example:
+    # - input: some/path/input.txt
+    # - output: 2020/06/25/82d042eb-9592-47f1-8019-2f06f73dc053.txt
+    # The reason it returns a completely random name is to ensure the file truly has a unique
+    # place to live, independent of what was passed in.  You are free to change these assumptions
+    # by creating and using your own store if any of these implementation details do not fit
+    # your specific use case.
     class Local
       attr_reader :date, :root
 
@@ -23,8 +33,7 @@ module FileComposer
       def move!(filename)
         make_final_filename(filename).tap do |final_filename|
           ensure_directory_exists(final_filename)
-          FileUtils.cp(filename, final_filename)
-          FileUtils.rm(filename, force: true)
+          FileUtils.mv(filename, final_filename)
         end
       end
 
@@ -38,17 +47,12 @@ module FileComposer
 
       def random_filename_parts(extension)
         [
+          root,
           date.year.to_s,
           date.month.to_s,
           date.day.to_s,
           "#{SecureRandom.uuid}#{extension}"
-        ].tap do |parts|
-          parts.unshift(root) if root?
-        end
-      end
-
-      def root?
-        !root.empty?
+        ].compact
       end
 
       def ensure_directory_exists(filename)

data/lib/file_composer/version.rb

@@ -8,5 +8,5 @@
 #
 
 module FileComposer
-  VERSION = '1.0.0-alpha'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: file_composer
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha
+  version: 1.0.0
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-09-01 00:00:00.000000000 Z
+date: 2020-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.88.0
+        version: 0.90.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.88.0
+        version: 0.90.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -136,9 +136,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.7.0
-description: "    This library provides a YAML-based configuration, called a Blueprint,
-  that allows you to specify text files and zip files and it will create them.  It
-  is pluggable so other document types and storage mediums can be added.\n"
+description: "    This library provides a declarative API, called a Blueprint, that
+  allows you to specify text files and zip files and it will create them.  It is pluggable
+  so other document types and storage mediums can be added.\n"
 email:
 - mruggio@bluemarblepayroll.com
 executables: []
@@ -192,12 +192,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: High-level, pluggable and YAML-based API for creating files
+summary: High-level, pluggable, and declarative API for creating files
 test_files: []