carry_out 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2527666eec64444e35bf101c6b084c6a4397a20b
-  data.tar.gz: da3bd9e8d2f51dbbb758d99565858f2cd9aeb5ce
+  metadata.gz: 543d46be1752e9734d13693aac9feffc8723eee0
+  data.tar.gz: 03d4914f2f692cde520ee6988098e665ba2d80e5
 SHA512:
-  metadata.gz: 25154eb134c0f970e4f23fe896278b94a87a68fc5edb1e8836a87a37b94f9226fe76da2a8b39283b2853591969eae5f111912c93c7e30ff35d761bac50f91e9f
-  data.tar.gz: 8e088f4e96b57d1f7cc80548cdfe764c72d29f8c9ee63411492b09d8ab0407ba49697f7357d579f0115e5c6d92233bc9c510025f28499438742d1e8d64c79d98
+  metadata.gz: ac4aaf4de3a8a1a107cad42305b6b3f40f29059c650b0f7055c653d0c7519b6e5719f334f543f9c0c1113f5528c64a8aa3bc4d5b4e79881a463435d425e0eba2
+  data.tar.gz: 20f606a99d159642d18bc0eefbc47b099de04be5a45264b2059ec008e7391603a81c0cbebcd002eca27a4f96e5556f6755dc2e44375b1a0e9a548a13095efe80

data/README.md

@@ -25,9 +25,9 @@ Or install it yourself as:
 Execution units extend CarryOut::Unit and should implement ```CarryOut::Unit#execute(result)```.
 ```ruby
 class SayHello < CarryOut::Unit
-    def execute(result)
-        puts "Hello, World!"
-    end
+  def execute(result)
+    puts "Hello, World!"
+  end
 end
 ```
 
@@ -44,51 +44,85 @@ result = plan.execute
 ### Parameters
 Execution units can be passed parameters statically during plan creation, or dynamically via a block.
 
+#### parameter
+
 Redefine the example above to greet someone by name:
 ```ruby
 class SayHello < CarryOut::Unit
-    parameter :to, :name
+  parameter :to, :name
     
-    def execute(result)
-        puts "Hello, #{@name}!"
-    end
+  def execute(result)
+    puts "Hello, #{@name}!"
+  end
 end
 ```
 
 Define the plan as:
 ```ruby
 plan = CarryOut
-    .will(SayHello)
-    .to("Ryan")
+  .will(SayHello)
+  .to("Ryan")
     
 # or
 
 plan = CarryOut
-    .will(SayHello)
-    .to { "Ryan" }
+  .will(SayHello)
+  .to { "Ryan" }
 ```
 
 And execute the same way as above.
 
-### Artifacts and References
-Execution units can publish artifacts to the plan's result.  Parameter blocks can be used to pass these artifacts on to subsequent execution units in the plan.
+#### appending_parameter
+
+Appending parameters will convert the value of an existing parameter to an array and push new values into that array.  These parameters can improve the readability of a plan, and are also helpful if creating a plan dynamically.
+
+```ruby
+class SayHello < CarryOut::Unit
+  parameter :to, :names
+  appending_parameter :and, :names
+
+  def execute
+    puts "Hello, #{@names}.join(", ")}!"
+  end
+end
+
+plan = CarryOut
+  .will(SayHello)
+  .to("John")
+  .and("Jane")
+  .and("Ryan")
+```
+
+Unlike `parameter`, `appending_parameter` must provide both a method name and an instance variable name.
+
+A non-appending parameter does not need to be called (or even exist) in order for appending parameters to operate.
+
+Calling the non-appending version of a parameter *after* calling the appending version will result in the array being lost, replaced by the explicit non-appending value provided.
+
+A unit may wish to provide the syntactic sugar while ensuring the underlying instance variable is always an array.  This can be accomplished by defining two (or more) appending parameters pointed at the same instance variable.
+
+### Results and Artifact References
+
+Plan executions return a `CarryOut::Result` object that contains any artifacts returned by units (in `Result#artifacts`), along with any errors raised (in `Result#errors`).  If `errors` is empty, `Result#success?` will return `true`.
+
+Parameter blocks can be used to pass result artifacts on to subsequent execution units in the plan.
 
 ```ruby
 class AddToCart < CarryOut::Unit
-    parameter :items
+  parameter :items
     
-    def execute(result)
-        result.add :contents, @items
-    end
+  def execute(result)
+    result.add :contents, @items
+  end
 end
 
 class CalculateSubtotal < CarryOut::Unit
-    parameters :items
+  parameters :items
     
-    def execut(result)
-        subtotal = items.inject { |sum, item| sum + item.price }
-        result.add :subtotal, subtotal
-    end
+  def execut(result)
+    subtotal = items.inject { |sum, item| sum + item.price }
+    result.add :subtotal, subtotal
+  end
 end
 ```
 ```ruby
@@ -99,10 +133,61 @@ plan = CarryOut
     .items { |refs| refs[:cart][:contents] }
     
 plan.execute do |result|
-    puts "Subtotal: #{result.artifacts[:invoice][:subtotal]}"
+  puts "Subtotal: #{result.artifacts[:invoice][:subtotal]}"
 end
 ```
 
+### Wrapping the Execution Context
+
+Contexts can be "baked into" a plan for purposes such as ensuring files get closed, or keeping the entire plan within a database transaction.
+
+```ruby
+class FileContext
+  def initialize(file_path)
+    @file_path = file_path
+  end
+  
+  def execute
+    File.open(@file_path, "r") do |f|
+      yield file: f
+    end
+  end
+end
+
+plan = CarryOut
+  .within(FileContext.new("path/to/file"))  # Expects instance, not class
+  .will(DoAThing)
+    .with_file { |refs| refs[:file] }
+```
+
+The wrapping context can also be a block.
+
+```ruby
+plan = CarryOut
+  .within { |proc| ActiveRecordBase.transaction { proc.call } }
+  .will(CreateModel)
+```
+
+When using a block, `proc.call` can be used to seed the references hash in the same manner as `yield` in the first example.
+
+Wrapper contexts will always be applied to an entire plan.  If a plan has multiple phases that need to be wrapped in different contexts, it is better to create multiple plans and embed them together in a larger plan as shown below.
+
+### Embedding Plans
+
+A plan can be used in place of a `CarryOut::Unit`.  This allows plans to be reused as part of larger strategies.
+
+```ruby
+inner_plan = CarryOut.will(SayHello)
+
+outer_plan = CarryOut
+  .will(DisplayBanner)
+  .then(inner_plan)
+```
+
+Passing a plan to `#then` works similar to passing a `CarryOut::Unit` class or instance.  If the `as` option is added, the inner plan's result artifacts will be added to the outer plan's result at the specified key.
+
+**One caveat to be aware of**:  There is no way to specify parameters for an embedded plan.  If an embedded plan depends on an external context, `CarryOut#within` is sufficient to work around this limitation.  However, there is currently no way for an inner plan to access an outer plan's artifacts.  This is considered a bug and will be fixed in a future release.
+
 ## Motivation
 
 I've been trying to keep my Rails controllers clean, but I prefer to avoid shoving inter-model business logic inside database models.  The recommendation I most frequently run into is to move that kind of logic into something akin to service objects.  I like that idea, but I want to keep my services small and composable, and I want to separate the "what" from the "how" of my logic.

data/lib/carry_out/result.rb

@@ -14,7 +14,7 @@ module CarryOut
         artifacts[group] ||= {}
         object.each { |k,v| artifacts[group][k] = v }
       elsif !artifacts[group].nil?
-        artifacts[group] = [ artifacts[group], object ].flatten
+        artifacts[group] = [ artifacts[group], object ].flatten(1)
       else
         artifacts[group] = object
       end

data/lib/carry_out/unit.rb

@@ -4,6 +4,22 @@ module CarryOut
     def execute
     end
 
+    def self.appending_parameter(method_name, var)
+      var = var.to_s
+      instance_var = "@#{var}"
+
+      define_method(method_name.to_sym) do |value|
+        existing = if instance_variable_defined?(instance_var)
+          [ instance_variable_get("@#{var.to_s}") ].flatten(1)
+        else
+          []
+        end
+        
+        instance_variable_set(instance_var, (existing || []) << value)
+        self
+      end
+    end
+
     def self.parameter(method_name, var = nil)
       unless var.nil?
         define_method(method_name.to_sym) do |value|

data/lib/carry_out/version.rb

@@ -1,3 +1,3 @@
 module CarryOut
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carry_out
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Ryan Fields
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-23 00:00:00.000000000 Z
+date: 2017-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler