burner 1.0.0.pre.alpha.10 → 1.0.0.pre.alpha.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 070f757d857aa8f1e07dd5cdaea5bdd261b050ef343c5f16f2692c6a5ba85eb1
-  data.tar.gz: 719a284fde5030e3e92fbaebd8c1f91f4445703710b6c00c9e2acf68c108a853
+  metadata.gz: adf7e5e1ea0c19d59b6edcbb1c5073e25f533bf32076df4ec7d9122edc852958
+  data.tar.gz: 40009afdb93c5ee3971513971dd47a8f416acd04b33eb0c8e9720806cce4a515
 SHA512:
-  metadata.gz: bd8938f87808a5c71a64839bc4d6cbc05bdfbb3f8df98a4aba92bbbb1a6163527ff5ba702525ad972a952faf05e35eda39adafe916540b94c775e2a96e71fcc0
-  data.tar.gz: debd08acef4aa54f88d796a0e217a83477af63d3a82bb7f07123d2360d8b40787e621831ea9d0d58cd39b088684ac6219f23c5aed49d274e39be360cdb16af1a
+  metadata.gz: cf255e3021e975451354a3d9537b464ffc61843c59b780ceace9dc6be04e4e2499f5d874aa905608ed3c4b60c4989e6bb3c8cccd2116e8286ca045ea4202bea7
+  data.tar.gz: 569a44eb9a5915d946b4de3038ead60094b170481583ea6974391eedaba209162df03883757b917b2e9c3ed3be6d8c2f80f64f43e6420d5fbc2d711eedc81a8c

data/README.md

@@ -262,8 +262,8 @@ This library only ships with very basic, rudimentary jobs that are meant to just
 
 #### General
 
-* **b/dummy** []: Do nothing
 * **b/echo** [message]: Write a message to the output.  The message parameter can be interpolated using  `Payload#params`.
+* **b/nothing** []: Do nothing.
 * **b/set** [register, value]: Set the value to any arbitrary value.
 * **b/sleep** [seconds]: Sleep the thread for X number of seconds.
 

data/lib/burner/job.rb

@@ -31,10 +31,11 @@ module Burner
     # The #perform method takes in two arguments: output (an instance of Burner::Output)
     # and payload (an instance of Burner::Payload).  Jobs can leverage output to emit
     # information to the pipeline's log(s).  The payload is utilized to pass data from job to job,
-    # with its most important attribute being #value.  The value attribute is mutable
-    # per the individual job's context (meaning of it is unknown without understanding a job's
-    # input and output value of #value.).  Therefore #value can mean anything and it is up to the
-    # engineers to clearly document the assumptions of its use.
+    # with its most important attribute being #registers.  The registers attribute is a mutable
+    # and accessible hash per the individual job's context
+    # (meaning of it is unknown without understanding a job's input and output value
+    # of #registers.).  Therefore #register key values can mean anything
+    # and it is up to consumers to clearly document the assumptions of its use.
     #
     # Returning false will short-circuit the pipeline right after the job method exits.
     # Returning anything else besides false just means "continue".
@@ -47,9 +48,15 @@ module Burner
     protected
 
     def job_string_template(expression, output, payload)
-      templatable_params = payload.params.merge(__id: output.id, __value: payload[''])
+      templatable_params = payload.params
+                                  .merge(__id: output.id)
+                                  .merge(templatable_register_values(payload))
 
       Util::StringTemplate.instance.evaluate(expression, templatable_params)
     end
+
+    def templatable_register_values(payload)
+      payload.registers.transform_keys { |key| "__#{key}_register" }
+    end
   end
 end

data/lib/burner/jobs.rb

@@ -16,10 +16,10 @@ module Burner
   class Jobs
     acts_as_hashable_factory
 
-    # Dummy is the default as noted by the ''.  This means if a type is omitted, nil, or blank
-    # string then the dummy job will be used.
-    register 'b/dummy', '',                    Library::Dummy
+    # Nothing is the default as noted by the ''.  This means if a type is omitted, nil, or blank
+    # string then the nothing job will be used.
     register 'b/echo',                         Library::Echo
+    register 'b/nothing', '',                  Library::Nothing
     register 'b/set_value',                    Library::SetValue
     register 'b/sleep',                        Library::Sleep
 

data/lib/burner/library.rb

@@ -9,6 +9,11 @@
 
 require_relative 'job_with_register'
 
+require_relative 'library/echo'
+require_relative 'library/nothing'
+require_relative 'library/set_value'
+require_relative 'library/sleep'
+
 require_relative 'library/collection/arrays_to_objects'
 require_relative 'library/collection/graph'
 require_relative 'library/collection/objects_to_arrays'
@@ -17,16 +22,15 @@ require_relative 'library/collection/transform'
 require_relative 'library/collection/unpivot'
 require_relative 'library/collection/validate'
 require_relative 'library/collection/values'
+
 require_relative 'library/deserialize/csv'
 require_relative 'library/deserialize/json'
 require_relative 'library/deserialize/yaml'
-require_relative 'library/dummy'
-require_relative 'library/echo'
+
 require_relative 'library/io/exist'
 require_relative 'library/io/read'
 require_relative 'library/io/write'
+
 require_relative 'library/serialize/csv'
 require_relative 'library/serialize/json'
 require_relative 'library/serialize/yaml'
-require_relative 'library/set_value'
-require_relative 'library/sleep'

data/lib/burner/library/collection/arrays_to_objects.rb

@@ -14,8 +14,8 @@ module Burner
       # Burner::Modeling::KeyIndexMapping instances or hashable configurations which specifies
       # the index-to-key mappings to use.
       #
-      # Expected Payload#value input: array of arrays.
-      # Payload#value output: An array of hashes.
+      # Expected Payload[register] input: array of arrays.
+      # Payload[register] output: An array of hashes.
       #
       # An example using a configuration-first pipeline:
       #
@@ -47,6 +47,11 @@ module Burner
       #   }
       #
       #   Burner::Pipeline.make(config).execute
+      #
+      # Given the above example, the expected output would be:
+      #  [
+      #    { 'id' => 1, 'name' => 'funky' }
+      #  ]
       class ArraysToObjects < JobWithRegister
         attr_reader :mappings
 

data/lib/burner/library/collection/graph.rb

@@ -13,8 +13,8 @@ module Burner
       # Take an array of (denormalized) objects and create an object hierarchy from them.
       # Under the hood it uses Hashematics: https://github.com/bluemarblepayroll/hashematics.
       #
-      # Expected Payload#value input: array of objects.
-      # Payload#value output: An array of objects.
+      # Expected Payload[register] input: array of objects.
+      # Payload[register] output: An array of objects.
       class Graph < JobWithRegister
         attr_reader :key, :groups
 

data/lib/burner/library/collection/objects_to_arrays.rb

@@ -15,39 +15,41 @@ module Burner
       # Burner::Modeling::KeyIndexMapping instances or hashable configurations which specifies
       # the key-to-index mappings to use.
       #
-      # Expected Payload#value input: array of hashes.
-      # Payload#value output: An array of arrays.
+      # Expected Payload[register] input: array of hashes.
+      # Payload[register] output: An array of arrays.
       #
       # An example using a configuration-first pipeline:
       #
-      #   config = {
-      #     jobs: [
-      #       {
-      #         name: 'set',
-      #         type: 'b/set_value',
-      #         value: [
-      #           [1, 'funky']
-      #         ]
-      #       },
-      #       {
-      #         name: 'map',
-      #         type: 'b/collection/objects_to_arrays',
-      #         mappings: [
-      #           { index: 0, key: 'id' },
-      #           { index: 1, key: 'name' }
-      #         ]
-      #       },
-      #       {
-      #         name: 'output',
-      #         type: 'b/echo',
-      #         message: 'value is currently: {__value}'
-      #       },
+      #  config = {
+      #    jobs: [
+      #      {
+      #        name: 'set',
+      #        type: 'b/set_value',
+      #        value: [
+      #          { 'id' => 1, 'name' => 'funky' }
+      #        ],
+      #        register: register
+      #      },
+      #      {
+      #        name: 'map',
+      #        type: 'b/collection/objects_to_arrays',
+      #        mappings: [
+      #          { index: 0, key: 'id' },
+      #          { index: 1, key: 'name' }
+      #        ],
+      #        register: register
+      #      },
+      #      {
+      #        name: 'output',
+      #        type: 'b/echo',
+      #        message: 'value is currently: {__value}'
+      #      },
       #
-      #     ],
-      #     steps: %w[set map output]
-      #   }
+      #    ],
+      #    steps: %w[set map output]
+      #  }
       #
-      #   Burner::Pipeline.make(config).execute
+      #  Burner::Pipeline.make(config).execute
       class ObjectsToArrays < JobWithRegister
         attr_reader :mappings
 

data/lib/burner/library/collection/shift.rb

@@ -14,8 +14,8 @@ module Burner
       # attribute.  The initial use case for this was to remove "header" rows from arrays,
       # like you would expect when parsing CSV files.
       #
-      # Expected Payload#value input: nothing.
-      # Payload#value output: An array with N beginning elements removed.
+      # Expected Payload[register] input: nothing.
+      # Payload[register] output: An array with N beginning elements removed.
       class Shift < JobWithRegister
         DEFAULT_AMOUNT = 0
 

data/lib/burner/library/collection/transform.rb

@@ -18,8 +18,8 @@ module Burner
       # For more information on the specific contract for attributes, see the
       # Burner::Modeling::Attribute class.
       #
-      # Expected Payload#value input: array of objects.
-      # Payload#value output: An array of objects.
+      # Expected Payload[register] input: array of objects.
+      # Payload[register] output: An array of objects.
       class Transform < JobWithRegister
         BLANK = ''
 

data/lib/burner/library/collection/unpivot.rb

@@ -14,8 +14,8 @@ module Burner
       # Under the hood it uses HashMath's Unpivot class:
       # https://github.com/bluemarblepayroll/hash_math
       #
-      # Expected Payload#value input: array of objects.
-      # Payload#value output: An array of objects.
+      # Expected Payload[register] input: array of objects.
+      # Payload[register] output: An array of objects.
       class Unpivot < JobWithRegister
         attr_reader :unpivot
 

data/lib/burner/library/collection/validate.rb

@@ -14,8 +14,9 @@ module Burner
       # of validations.  The main register will include the valid objects and the invalid_register
       # will contain the invalid objects.
       #
-      # Expected Payload#value input: array of objects.
-      # Payload#value output: An array of objects.
+      # Expected Payload[register] input: array of objects.
+      # Payload[register] output: An array of objects that are valid.
+      # Payload[invalid_register] output: An array of objects that are invalid.
       class Validate < JobWithRegister
         DEFAULT_INVALID_REGISTER = 'invalid'
         DEFAULT_JOIN_CHAR        = ', '

data/lib/burner/library/collection/values.rb

@@ -14,8 +14,8 @@ module Burner
       # If include_keys is true (it is false by default), then call #keys on the first
       # object and inject that as a "header" object.
       #
-      # Expected Payload#value input: array of objects.
-      # Payload#value output: An array of arrays.
+      # Expected Payload[register] input: array of objects.
+      # Payload[register] output: An array of arrays.
       class Values < JobWithRegister
         attr_reader :include_keys
 

data/lib/burner/library/deserialize/csv.rb

@@ -12,8 +12,8 @@ module Burner
     module Deserialize
       # Take a CSV string and de-serialize into object(s).
       #
-      # Expected Payload#value input: nothing.
-      # Payload#value output: an array of arrays.  Each inner array represents one data row.
+      # Expected Payload[register] input: nothing.
+      # Payload[register] output: an array of arrays.  Each inner array represents one data row.
       class Csv < JobWithRegister
         # This currently only supports returning an array of arrays, including the header row.
         # In the future this could be extended to offer more customizable options, such as

data/lib/burner/library/deserialize/json.rb

@@ -12,8 +12,8 @@ module Burner
     module Deserialize
       # Take a JSON string and deserialize into object(s).
       #
-      # Expected Payload#value input: string of JSON data.
-      # Payload#value output: anything, as specified by the JSON de-serializer.
+      # Expected Payload[register] input: string of JSON data.
+      # Payload[register] output: anything, as specified by the JSON de-serializer.
       class Json < JobWithRegister
         def perform(_output, payload)
           payload[register] = JSON.parse(payload[register])

data/lib/burner/library/deserialize/yaml.rb

@@ -15,8 +15,8 @@ module Burner
       # YAML.  If you wish to ease this restriction, for example if you have custom serialization
       # for custom classes, then you can pass in safe: false.
       #
-      # Expected Payload#value input: string of YAML data.
-      # Payload#value output: anything as specified by the YAML de-serializer.
+      # Expected Payload[register] input: string of YAML data.
+      # Payload[register]output: anything as specified by the YAML de-serializer.
       class Yaml < JobWithRegister
         attr_reader :safe
 

data/lib/burner/library/echo.rb

@@ -11,7 +11,7 @@ module Burner
   module Library
     # Output a simple message to the output.
     #
-    # Note: this does not use Payload#value.
+    # Note: this does not use Payload#registers.
     class Echo < Job
       attr_reader :message
 

data/lib/burner/library/io/exist.rb

@@ -15,7 +15,7 @@ module Burner
       # Check to see if a file exists.  If short_circuit is set to true and the file
       # does not exist then the job will return false and short circuit the pipeline.
       #
-      # Note: this does not use Payload#value.
+      # Note: this does not use Payload#registers.
       class Exist < Job
         attr_reader :path, :short_circuit
 

data/lib/burner/library/io/read.rb

@@ -14,8 +14,8 @@ module Burner
     module IO
       # Read value from disk.
       #
-      # Expected Payload#value input: nothing.
-      # Payload#value output: contents of the specified file.
+      # Expected Payload[register] input: nothing.
+      # Payload[register] output: contents of the specified file.
       class Read < Base
         attr_reader :binary
 

data/lib/burner/library/io/write.rb

@@ -14,8 +14,8 @@ module Burner
     module IO
       # Write value to disk.
       #
-      # Expected Payload#value input: anything.
-      # Payload#value output: whatever was passed in.
+      # Expected Payload[register] input: anything.
+      # Payload[register] output: whatever was passed in.
       class Write < Base
         attr_reader :binary
 

data/lib/burner/library/{dummy.rb → nothing.rb}

@@ -11,8 +11,8 @@ module Burner
   module Library
     # Do nothing.
     #
-    # Note: this does not use Payload#value.
-    class Dummy < Job
+    # Note: this does not use Payload#registers.
+    class Nothing < Job
       def perform(_output, _payload); end
     end
   end

data/lib/burner/library/serialize/csv.rb

@@ -12,8 +12,8 @@ module Burner
     module Serialize
       # Take an array of arrays and create a CSV.
       #
-      # Expected Payload#value input: array of arrays.
-      # Payload#value output: a serialized CSV string.
+      # Expected Payload[register] input: array of arrays.
+      # Payload[register] output: a serialized CSV string.
       class Csv < JobWithRegister
         def perform(_output, payload)
           payload[register] = CSV.generate(options) do |csv|

data/lib/burner/library/serialize/json.rb

@@ -12,8 +12,8 @@ module Burner
     module Serialize
       # Treat value like a Ruby object and serialize it using JSON.
       #
-      # Expected Payload#value input: anything.
-      # Payload#value output: string representing the output of the JSON serializer.
+      # Expected Payload[register] input: anything.
+      # Payload[register] output: string representing the output of the JSON serializer.
       class Json < JobWithRegister
         def perform(_output, payload)
           payload[register] = payload[register].to_json

data/lib/burner/library/serialize/yaml.rb

@@ -12,8 +12,8 @@ module Burner
     module Serialize
       # Treat value like a Ruby object and serialize it using YAML.
       #
-      # Expected Payload#value input: anything.
-      # Payload#value output: string representing the output of the YAML serializer.
+      # Expected Payload[register] input: anything.
+      # Payload[register] output: string representing the output of the YAML serializer.
       class Yaml < JobWithRegister
         def perform(_output, payload)
           payload[register] = payload[register].to_yaml

data/lib/burner/library/set_value.rb

@@ -11,8 +11,8 @@ module Burner
   module Library
     # Arbitrarily set value
     #
-    # Expected Payload#value input: anything.
-    # Payload#value output: whatever value was specified in this job.
+    # Expected Payload[register] input: anything.
+    # Payload[register] output: whatever value was specified in this job.
     class SetValue < JobWithRegister
       attr_reader :value
 

data/lib/burner/library/sleep.rb

@@ -11,7 +11,7 @@ module Burner
   module Library
     # Arbitrarily put thread to sleep for X number of seconds
     #
-    # Payload#value output: whatever value was specified in this job.
+    # Note: this does not use Payload#registers.
     class Sleep < Job
       attr_reader :seconds
 

data/lib/burner/modeling/attribute.rb

@@ -10,7 +10,9 @@
 module Burner
   module Modeling
     # Defines a top-level key and the associated transformers for deriving the final value
-    # to set the key to.
+    # to set the key to.  The transformers that can be passed in can be any Realize::Transformers
+    # subclasses.  For more information, see the Realize library at:
+    # https://github.com/bluemarblepayroll/realize
     class Attribute
       acts_as_hashable
 

data/lib/burner/payload.rb

@@ -8,16 +8,22 @@
 #
 
 module Burner
-  # The input for all Job#perform methods.  The main notion of this object is its "value"
-  # attribute.  This is dynamic and weak on purpose and is subject to whatever the Job#perform
-  # methods decides it is.  This definitely adds an order-of-magnitude complexity to this whole
-  # library and lifecycle, but I am not sure there is any other way around it: trying to build
-  # a generic, open-ended object pipeline to serve almost any use case.
+  # The input for all Job#perform methods.  The main notion of this object is its 'registers'
+  # attribute.  This registers attribute is a key-indifferent hash, accessible on Payload using
+  # the brackets setter and getter methods.  This is dynamic and weak on purpose and is subject
+  # to whatever the Job#perform methods decides it is.  This definitely adds an order-of-magnitude
+  # complexity to this whole library and lifecycle, but I am not sure there is any other way
+  # around it: trying to build a generic, open-ended processing pipeline to serve almost
+  # any use case.
   #
   # The side_effects attribute can also be utilized as a way for jobs to emit any data in a more
   # structured/additive manner.  The initial use case for this was for Burner's core IO jobs to
   # report back the files it has written in a more structured data way (as opposed to simply
   # writing some information to the output.)
+  #
+  # The 'time' attribute is important in that it should for the replaying of pipelines and jobs.
+  # Instead of having job's utilizing Time.now, Date.today, etc... they should rather opt to
+  # use this value instead.
   class Payload
     attr_reader :params,
                 :registers,

data/lib/burner/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Burner
-  VERSION = '1.0.0-alpha.10'
+  VERSION = '1.0.0-alpha.11'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: burner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha.10
+  version: 1.0.0.pre.alpha.11
 platform: ruby
 authors:
 - Matthew Ruggio
@@ -235,12 +235,12 @@ files:
 - lib/burner/library/deserialize/csv.rb
 - lib/burner/library/deserialize/json.rb
 - lib/burner/library/deserialize/yaml.rb
-- lib/burner/library/dummy.rb
 - lib/burner/library/echo.rb
 - lib/burner/library/io/base.rb
 - lib/burner/library/io/exist.rb
 - lib/burner/library/io/read.rb
 - lib/burner/library/io/write.rb
+- lib/burner/library/nothing.rb
 - lib/burner/library/serialize/csv.rb
 - lib/burner/library/serialize/json.rb
 - lib/burner/library/serialize/yaml.rb