composable_operations 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2815a0e9caf243a6e502b0f277cb98c36b44b9d5
-  data.tar.gz: 668f9e8de07e9287f7498909fca06f2d61ab4904
+  metadata.gz: c6eeabae9917ce517a8f6ba380b3485479edde5a
+  data.tar.gz: 94ab6cddddbea6be52e2e426a9cc56088bd4b5ac
 SHA512:
-  metadata.gz: 962cef4189be9cabea7c2df388d1f6be24929a211eafe43f9fadddec9ff4375fd553a977a01641ee812fb1e887fc2d62853bdb3eb29e2636b336f10899d3473f
-  data.tar.gz: e3f3d3df80f08542fa285e27fbe7d4ca9a7c217a41f0d74dfa97e737dc95e9d6742877ec08d2f5f41ccc9f28ac75bffc6b419a33ca1983d6047ea76dfe36db8f
+  metadata.gz: bb094f4b9cd7c25d96cb1ebdc27727c0e23d9dd86ad6c386aa1b40107bad8060cc8635a27d4a01bbb91cad34b1cb3644a6eed92ed88ba27c0df456f8671afb73
+  data.tar.gz: 62f381ac83ebdf643a5e04d1e1d61b60cd1e578fa6202e386fe88db20972d187223a606ba67fd9b091a02a434a78baaf0a1b0230425114b18e65bad46e3686b6

data/README.md

@@ -1,6 +1,12 @@
 # ComposableOperations
 
-TODO: Write a gem description
+Composable Operations is a tool set for creating operations and assembling
+multiple of these operations in operation pipelines.  An operation is, at its
+core, an implementation of the [strategy
+pattern](http://en.wikipedia.org/wiki/Strategy_pattern) and in this sense an
+encapsulation of an algorithm. An operation pipeline is an assembly of multiple
+operations and useful for implementing complex algorithms. Pipelines themselves
+can be part of other pipelines.
 
 ## Installation
 
@@ -18,7 +24,212 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Operations can be defined by subclassing `ComposableOperations::Operation` and
+operation pipelines by subclassing `ComposableOperations::ComposedOperation`.
+
+### Defining an Operation
+
+To define an operation, two steps are necessary:
+
+1. create a new subclass of `ComposableOperations::Operations`, and
+2. implement the `#execute` method.
+
+The listing below shows an operation that extracts a timestamp in the format
+`yyyy-mm-dd` from a string.
+
+```ruby
+class DateExtractor < ComposableOperations::Operation
+
+  processes :text
+
+  def execute
+    text.scan(/(\d{4})-(\d{2})-(\d{2})/)
+  end
+
+end
+```
+
+The macro method `.processes` followed by a single argument denotes that the
+operation expects a single object as input and results in the definition of a
+getter method named as specified by this argument. The macro method can also be
+called with multiple arguments resulting in the creation of multiple getter
+methods. The latter is useful if the operation requires more than one object as
+input to operate. Calling the macro method is entirely optional. An operation's
+input can always be accessed by calling the getter method `#input`. This method
+returns either a single object or an array of objects.
+
+There are two ways to execute this operation:
+
+1. create a new instance of this operation and call `#perform`, or
+2. directly call `.perform` on the operation class.
+
+The major difference between these two approaches is that in case of a failure
+the latter raises an exception while the former returns `nil` and sets the
+operation's state to `failed`. For more information on canceling the execution
+of an operation, see below. Please note that directly calling the `#execute`
+method is prohibited. To enforce this constraint, the method is automatically
+marked as protected upon definition.
+
+The listing below demonstrates how to execute the operation defined above.
+
+```ruby
+text = "This gem was first published on 2013-06-10."
+
+extractor = DateExtractor.new(text)
+extractor.perform # => [["2013", "06", "10"]]
+
+DateExtractor.perform(text) # => [["2013", "06", "10"]]
+```
+
+### Defining an Operation Pipeline
+
+Assume that we are provided an operation that converts these arrays of strings
+into actual `Time` objects. The following listing provides a potential
+implementation of such an operation.
+
+```ruby
+class DateArrayToTimeObjectConverter < ComposableOperations::Operation
+
+  processes :collection_of_date_arrays
+
+  def execute
+    collection_of_date_arrays.map do |date_array|
+      Time.new(*(date_array.map(&:to_i)))
+    end
+  end
+
+end
+```
+
+Using these two operations, it is possible to create a composed operation that
+extracts dates from a string and directly converts them into `Time` objects. To
+define a composed operation, two steps are necessary:
+
+1. create a subclass of `ComposableOperations::ComposedOperation`, and
+2. use the macro method `use` to assemble the operation.
+
+The listing below shows how to assemble the two operations, `DateExtractor` and
+`DateArrayToTimeObjectConverter`, into a composed operation named `DateParser`.
+
+```ruby
+class DateParser < ComposableOperations::ComposedOperation
+
+  use DateExtractor
+  use DateArrayToTimeObjectConverter
+
+end
+```
+
+Composed operations provide the same interface as normal operations. Hence,
+they can be invoked the same way. For the sake of completeness, the listing
+below shows how to use the `DateParser` operation.
+
+```ruby
+text = "This gem was first published on 2013-06-10."
+
+parser = DateParser.new(text)
+parser.perform # => 2013-06-07 00:00:00 +0200
+
+DateParser.perform(text) # => 2013-06-07 00:00:00 +0200
+```
+
+### Control Flow
+
+An operation can be *halted* or *aborted* if a successful execution is not
+possible. Aborting an operation will result in an exception if the operation
+was invoked using the class method `.perform`. If the operation was invoked
+using the instance method `#perform`, the operation's state will be updated
+accordingly, but no exception will be raised. The listing below provides, among
+other things, examples on how to access an operation's state.
+
+```ruby
+class StrictDateParser < DateParser
+
+  def execute
+    result = super
+    fail "no timestamp found" if result.empty?
+    result
+  end
+
+end
+
+class LessStrictDateParser < DateParser
+
+  def execute
+    result = super
+    halt "no timestamp found" if result.empty?
+    result
+  end
+
+end
+
+parser = StrictDateParser.new("")
+parser.message # => "no timestamp found"
+parser.perform # => nil
+parser.succeeded? # => false
+parser.halted? # => false
+parser.failed? # => true
+
+StrictDateParser.perform("") # => ComposableOperations::OperationError: no timestamp found
+
+parser = LessStricDateParser.new("")
+parser.message # => "no timestamp found"
+parser.perform # => nil
+parser.succeeded? # => false
+parser.halted? # => true
+parser.failed? # => false
+
+StrictDateParser.perform("") # => nil
+```
+
+Instead of cluttering the `#execute` method with sentinel code or in general
+with code that is not part of an operation's algorithmic core, we can move this
+code into `before` or `after` callbacks. The listing below provides an alternative
+implementation of the `StrictDateParser` operation.
+
+
+```ruby
+class StrictDateParser < DateParser
+
+  after do
+    fail "no timestamp found" if result.empty?
+  end
+
+end
+
+parser = StrictDateParser.new("")
+parser.message # => "no timestamp found"
+parser.perform # => nil
+parser.failed? # => true
+
+StrictDateParser.perform("") # => ComposableOperations::OperationError: no timestamp found
+```
+
+### Configuring Operations
+
+Operations and composed operations support
+[SmartProperties](http://github.com/t6d/smart_properties) to conveniently
+provide additional settings upon initialization of an operation. In the
+example, below an operation is defined that indents a given string. The indent
+is set to 2 by default but can easily be changed by supplying an options hash
+to the initializer.
+
+```ruby
+class Indention < ComposableOperations::Operation
+
+  property :indent, default: 2,
+                    converts: lambda { |value| value.to_s.to_i },
+                    accepts: lambda { |value| value >= 0 },
+                    required: true
+
+  def execute
+    input.split("\n").map { |line| " " * indent + line }.join("\n")
+  end
+
+end
+
+Indention.perform("Hello World", indent: 4) # => "    Hello World"
+```
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,4 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/composable_operations.gemspec

@@ -9,7 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Konstantin Tennhard"]
   spec.email         = ["me@t6d.de"]
   spec.summary       = %q{Tool set for operation pipelines.}
-  spec.description   = %q{Composable Operations is a tool set for creating easy-to-use operation pipelines.}
+  spec.description   = %q{Composable Operations is a tool set for creating operations and assembling
+multiple of these operations in operation pipelines.}
   spec.homepage      = "http://github.com/t6d/composable_operations"
   spec.license       = "MIT"
 
@@ -22,5 +23,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec", "~> 2.11"
+  spec.add_development_dependency "rspec", "~> 2.13"
 end

data/lib/composable_operations/operation.rb

@@ -140,7 +140,7 @@ module ComposableOperations
         throw :halt, return_value
       end
 
-      def halt(message = nil, return_value = input)
+      def halt(message = nil, return_value = nil)
         raise "Operation execution has already been aborted" if halted? or failed?
 
         self.state = :halted

data/lib/composable_operations/version.rb

@@ -1,3 +1,3 @@
 module ComposableOperations
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/composable_operations/composed_operation_spec.rb

@@ -88,7 +88,7 @@ describe ComposableOperations::ComposedOperation do
     end
 
     it "should return a capitalized version of the generated string" do
-      composed_operation.perform.should be == "chunky bacon"
+      composed_operation.perform.should be == nil
     end
 
     it "should only execute the first two operations" do

data/spec/composable_operations/control_flow_spec.rb

@@ -108,31 +108,31 @@ describe "An operation with two before and two after filters =>" do
     }, {
       :context => "halting in outer_before filter =>",
       :input   => [:halt_in_outer_before],
-      :output  => [:halt_in_outer_before],
+      :output  => nil,
       :trace   => [:initialize, :outer_before, :inner_after, :outer_after],
       :state   => :halted
     }, {
       :context => "halting in inner_before filter =>",
       :input   => [:halt_in_inner_before],
-      :output  => [:halt_in_inner_before],
+      :output  => nil,
       :trace   => [:initialize, :outer_before, :inner_before, :inner_after, :outer_after],
       :state   => :halted
     }, {
       :context => "halting in execute =>",
       :input   => [:halt_in_execute],
-      :output  => [:halt_in_execute],
+      :output  => nil,
       :trace   => [:initialize, :outer_before, :inner_before, :execute_start, :inner_after, :outer_after],
       :state   => :halted
     }, {
       :context => "halting in inner_after filter =>",
       :input   => [:halt_in_inner_after],
-      :output  => [:halt_in_inner_after],
+      :output  => nil,
       :trace   => [:initialize, :outer_before, :inner_before, :execute_start, :execute_stop, :inner_after, :outer_after],
       :state   => :halted
     }, {
       :context => "halting in outer_after filter =>",
       :input   => [:halt_in_outer_after],
-      :output  => [:halt_in_outer_after],
+      :output  => nil,
       :trace   => [:initialize, :outer_before, :inner_before, :execute_start, :execute_stop, :inner_after, :outer_after],
       :state   => :halted
     }

data/spec/composable_operations/operation_spec.rb

@@ -17,12 +17,12 @@ describe ComposableOperations::Operation do
 
   end
 
-  context "that always halts" do
+  context "that always halts and returns its original input" do
 
     let(:halting_operation) do
       Class.new(described_class) do
         def execute
-          halt "Full stop!"
+          halt "Full stop!", input
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: composable_operations
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Konstantin Tennhard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-10 00:00:00.000000000 Z
+date: 2013-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: smart_properties
@@ -58,16 +58,17 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.11'
+        version: '2.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.11'
-description: Composable Operations is a tool set for creating easy-to-use operation
-  pipelines.
+        version: '2.13'
+description: |-
+  Composable Operations is a tool set for creating operations and assembling
+  multiple of these operations in operation pipelines.
 email:
 - me@t6d.de
 executables: []