burner 1.0.0.pre.alpha.6 → 1.0.0.pre.alpha.11

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

@@ -15,16 +15,17 @@ 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.
-      class Exist < Base
-        attr_reader :short_circuit
+      # Note: this does not use Payload#registers.
+      class Exist < Job
+        attr_reader :path, :short_circuit
 
         def initialize(name:, path:, short_circuit: false)
-          super(name: name, path: path)
+          super(name: name)
 
-          @short_circuit = short_circuit || false
+          raise ArgumentError, 'path is required' if path.to_s.empty?
 
-          freeze
+          @path          = path.to_s
+          @short_circuit = short_circuit || false
         end
 
         def perform(output, payload)
@@ -35,9 +36,8 @@ module Burner
 
           output.detail("The path: #{compiled_path} #{verb} exist")
 
-          # if anything but false is returned then the pipeline will not short circuit.  So
-          # we need to make sure we explicitly return false.
-          short_circuit && !exists ? false : nil
+          # if anything but false is returned then the pipeline will not short circuit.
+          payload.halt_pipeline if short_circuit && !exists
         end
       end
     end

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

@@ -14,13 +14,13 @@ 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
 
-        def initialize(name:, path:, binary: false)
-          super(name: name, path: path)
+        def initialize(name:, path:, binary: false, register: '')
+          super(name: name, path: path, register: register)
 
           @binary = binary || false
 
@@ -32,9 +32,7 @@ module Burner
 
           output.detail("Reading: #{compiled_path}")
 
-          payload.value = File.open(compiled_path, mode, &:read)
-
-          nil
+          payload[register] = File.open(compiled_path, mode, &:read)
         end
 
         private

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

@@ -14,13 +14,13 @@ 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
 
-        def initialize(name:, path:, binary: false)
-          super(name: name, path: path)
+        def initialize(name:, path:, binary: false, register: '')
+          super(name: name, path: path, register: register)
 
           @binary = binary || false
 
@@ -35,7 +35,7 @@ module Burner
           output.detail("Writing: #{compiled_path}")
 
           time_in_seconds = Benchmark.measure do
-            File.open(compiled_path, mode) { |io| io.write(payload.value) }
+            File.open(compiled_path, mode) { |io| io.write(payload[register]) }
           end.real
 
           side_effect = SideEffects::WrittenFile.new(
@@ -45,8 +45,6 @@ module Burner
           )
 
           payload.add_side_effect(side_effect)
-
-          nil
         end
 
         private

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

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

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

@@ -12,17 +12,15 @@ 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.
-      class Csv < Job
+      # Expected Payload[register] input: array of arrays.
+      # Payload[register] output: a serialized CSV string.
+      class Csv < JobWithRegister
         def perform(_output, payload)
-          payload.value = CSV.generate(options) do |csv|
-            array(payload.value).each do |row|
+          payload[register] = CSV.generate(options) do |csv|
+            array(payload[register]).each do |row|
               csv << row
             end
           end
-
-          nil
         end
 
         private

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

@@ -12,13 +12,11 @@ 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.
-      class Json < Job
+      # Expected Payload[register] input: anything.
+      # Payload[register] output: string representing the output of the JSON serializer.
+      class Json < JobWithRegister
         def perform(_output, payload)
-          payload.value = payload.value.to_json
-
-          nil
+          payload[register] = payload[register].to_json
         end
       end
     end

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

@@ -12,13 +12,11 @@ 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.
-      class Yaml < Job
+      # Expected Payload[register] input: anything.
+      # Payload[register] output: string representing the output of the YAML serializer.
+      class Yaml < JobWithRegister
         def perform(_output, payload)
-          payload.value = payload.value.to_yaml
-
-          nil
+          payload[register] = payload[register].to_yaml
         end
       end
     end

data/lib/burner/library/set_value.rb

@@ -11,13 +11,13 @@ module Burner
   module Library
     # Arbitrarily set value
     #
-    # Expected Payload#value input: anything.
-    # Payload#value output: whatever value was specified in this job.
-    class SetValue < Job
+    # Expected Payload[register] input: anything.
+    # Payload[register] output: whatever value was specified in this job.
+    class SetValue < JobWithRegister
       attr_reader :value
 
-      def initialize(name:, value: nil)
-        super(name: name)
+      def initialize(name:, register: '', value: nil)
+        super(name: name, register: register)
 
         @value = value
 
@@ -25,9 +25,7 @@ module Burner
       end
 
       def perform(_output, payload)
-        payload.value = value
-
-        nil
+        payload[register] = value
       end
     end
   end

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
 
@@ -27,8 +27,6 @@ module Burner
         output.detail("Going to sleep for #{seconds} second(s)")
 
         Kernel.sleep(seconds)
-
-        nil
       end
     end
   end

data/lib/burner/modeling.rb

@@ -10,3 +10,4 @@
 require_relative 'modeling/attribute'
 require_relative 'modeling/attribute_renderer'
 require_relative 'modeling/key_index_mapping'
+require_relative 'modeling/validations'

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/modeling/validations.rb

@@ -0,0 +1,23 @@
+# 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 'validations/blank'
+require_relative 'validations/present'
+
+module Burner
+  module Modeling
+    # Factory for building sub-classes that can validate an individual object and field value.
+    class Validations
+      acts_as_hashable_factory
+
+      register 'blank',   Validations::Blank
+      register 'present', Validations::Present
+    end
+  end
+end

data/lib/burner/modeling/validations/base.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 Burner
+  module Modeling
+    class Validations
+      # Common logic shared among all Validation subclasses.
+      # This class is an abstract class, make sure to implement:
+      # - #valid?(object, resolver)
+      # - #default_message
+      class Base
+        acts_as_hashable
+
+        attr_reader :key
+
+        def initialize(key:, message: '')
+          raise ArgumentError, 'key is required' if key.to_s.empty?
+
+          @key     = key.to_s
+          @message = message.to_s
+        end
+
+        def message
+          @message.to_s.empty? ? "#{key}#{default_message}" : @message.to_s
+        end
+      end
+    end
+  end
+end

data/lib/burner/modeling/validations/blank.rb

@@ -0,0 +1,31 @@
+# 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 'base'
+
+module Burner
+  module Modeling
+    class Validations
+      # Check if a value is blank, if it is not blank then it is not valid.
+      class Blank < Base
+        acts_as_hashable
+
+        def valid?(object, resolver)
+          resolver.get(object, key).to_s.empty?
+        end
+
+        private
+
+        def default_message
+          ' must be blank'
+        end
+      end
+    end
+  end
+end

data/lib/burner/modeling/validations/present.rb

@@ -0,0 +1,31 @@
+# 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 'base'
+
+module Burner
+  module Modeling
+    class Validations
+      # Check if a value is present.  If it is blank (null or empty) then it is invalid.
+      class Present < Base
+        acts_as_hashable
+
+        def valid?(object_value, resolver)
+          !resolver.get(object_value, key).to_s.empty?
+        end
+
+        private
+
+        def default_message
+          ' is required'
+        end
+      end
+    end
+  end
+end

data/lib/burner/payload.rb

@@ -8,37 +8,77 @@
 #
 
 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_accessor :value
-
     attr_reader :params,
+                :registers,
                 :side_effects,
                 :time
 
     def initialize(
       params: {},
+      registers: {},
       side_effects: [],
-      time: Time.now.utc,
-      value: nil
+      time: Time.now.utc
     )
       @params       = params || {}
+      @registers    = {}
       @side_effects = side_effects || []
       @time         = time || Time.now.utc
-      @value        = value
+
+      add_registers(registers)
     end
 
+    # Add a side effect of a job.  This helps to keep track of things jobs do outside of its
+    # register mutations.
     def add_side_effect(side_effect)
       tap { side_effects << side_effect }
     end
+
+    # Set a register's value.
+    def []=(key, value)
+      set(key, value)
+    end
+
+    # Retrieve a register's value.
+    def [](key)
+      registers[key.to_s]
+    end
+
+    # Set halt_pipeline to true.  This will indicate to the pipeline to stop all
+    # subsequent processing.
+    def halt_pipeline
+      @halt_pipeline = true
+    end
+
+    # Check and see if halt_pipeline was called.
+    def halt_pipeline?
+      @halt_pipeline || false
+    end
+
+    private
+
+    def set(key, value)
+      registers[key.to_s] = value
+    end
+
+    def add_registers(registers)
+      (registers || {}).each { |k, v| set(k, v) }
+    end
   end
 end