cuprum 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d393a222eda76e4b943c721df4a4d54c89966e9
-  data.tar.gz: d0e9efa6075c9346114ecb02883b380621873510
+  metadata.gz: cafecaeff8b2c0209616cd9303613d88723c2477
+  data.tar.gz: b4d1c2cdde687815ac835631c460a45d15a3306d
 SHA512:
-  metadata.gz: 196f5f4472c76d664f4d6b8764503a7fee5fabae50061edc877d1cc060421b05067861c96fc654a8a2586911c318b6ff9d65e515c299ffaed647f9742021dd88
-  data.tar.gz: c1cd4f744cdfb37493f100de095ef89d1e3c080ae59f99af76ca43c69f8aaeaf14cfddc9068a824956da2e19aed4017bb70e6bb6d608969ea6e4acc5f096f875
+  metadata.gz: f465ecb20dd65d5e835f6f506bbaca272e39637a5b127fac31929fef88a880069ed8b7f86802b207b01b767de952d641a688344dfabd8b1d4347d904daf926d7
+  data.tar.gz: be12f0a8d8be45ba1aabc854b48be53be13e2716d39e1c48fecae038b99019880c19686fd96bb1d1ff04272400650723df47b789ebe48b60da1e6ba844175f3a

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.0
+
+The "We Have The Technology" Update.
+
+### Commands
+
+Added protected chaining methods `#chain!`, `#tap_result!` and `#yield_result!`. These methods function as their non-imperative counterparts, but add the chained command or block to the current command instead of a clone.
+
+Removed the ResultHelpers mixin from the default Command class. To use the result helper methods, include Cuprum::ResultHelpers in your command class.
+
+Removed the #build_errors helper - each Result is now responsible for building its own errors object. To use a custom errors object, define a subclass of Cuprum::Result and override its #build_errors method, then update your Command's #build_result method to use your custom result class.
+
+### Command Factory
+
+Implemented the CommandFactory class, which provides a builder interface and DSL for grouping and creating commands with a common purpose or with shared configuration.
+
 ## 0.7.0
 
 The "To Strive, To Seek, To Find, And Not To Yield" Update.

data/DEVELOPMENT.md

@@ -1,43 +1,36 @@
 # Development
 
-## Version 1.0.0+
+## Version 0.9.0
 
-'The "Look On My Works, Ye Mighty, and Despair" Update'
+The "Second Star To The Right" Update
 
-- Integration specs.
-- Configuration option to raise, warn, ignore discarded results.
+### Actions
+
+#### LifecycleHooks
+
+- :before, :after hooks
+  - NOT included in Command by default
+
+## Version 0.10.0
+
+'The "Out Of Context Problem" Update'
 
 ### Commands
 
-- Protected Chaining Methods:
-  - #chain!, #success!, #failure!, #tap_chain!, #yield_result!
-  - adds chained command to current command instead of a clone.
-- Command#to_proc
-- :clear_errors => true option on #chain
 - #context object
-- command currying
 
-#### Cuprum::DSL
+## Version 1.0.0
 
-- ::process - shortcut for defining #process
-- ::rescue - `rescue StandardError do ... end`, rescues matched errors in #process
-- chaining methods:
-  - ::chain (::success, ::failure):
-    on #initialize, chains the given command. Can be given a command class
-    (if ::new takes no arguments) or a block that returns a command.
-- constructor methods:
-  - Programmatically generate a constructor method. Raises an error if
-    #initialize is defined. Automatically sets instance variables on initialize,
-    and defines reader methods.
-  - ::arguments - sets all positional arguments in the constructor. Takes 0 or
-    more String or Symbol arguments representing required arguments. Takes an
-    optional hash with String/Symbol keys and arbitrary values, representing
-    optional arguments and their default values.
-  - ::keywords - sets keyword arguments; same arguments as ::arguments.
+'The "Look On My Works, Ye Mighty, and Despair" Update'
 
-#### Hooks
+- Integration specs.
+- Configuration option to raise, warn, ignore discarded results.
+- Code cleanup: Hash syntax, remove end comments, remove file headers
+
+### Commands
 
-- :before, :around, :after hooks
+- Command#to_proc
+- :clear_errors => true option on #chain
 
 ### Commands - Built In
 
@@ -45,19 +38,6 @@
   as array
 - RetryCommand
 
-### CommandFactory
-
-- builder/aggregator for command objects, esp. with shared
-  initializers/parameters, e.g. actions for a resource
-- Syntax: |
-
-  actions = ResourceCommandFactory.new(Book)
-  command = actions::Build.new        #=> returns a book builder command
-  result  = command.call(attributes)  #=> returns a result with value => a Book
-  # OR
-  result  = actions.build(attributes) #=> returns a result with value => a Book
-  book    = result.value
-
 ### Documentation
 
 Chaining Case Study: |
@@ -73,3 +53,29 @@ Chaining Case Study: |
   Create Content
   Create ContentVersion
   Tags.each { FindOrCreate Tag }
+
+## Future Versions
+
+### Commands
+
+- command currying
+
+#### Cuprum::DSL
+
+- ::process - shortcut for defining #process
+- ::rescue - `rescue StandardError do ... end`, rescues matched errors in #process
+- chaining methods:
+  - ::chain (::success, ::failure):
+    on #initialize, chains the given command. Can be given a command class
+    (if ::new takes no arguments) or a block that returns a command.
+- constructor methods:
+  - Programmatically generate a constructor method. Raises an error if
+    #initialize is defined. Automatically sets instance variables on initialize,
+    and defines reader methods.
+  - ::arguments - sets all positional arguments in the constructor. Takes 0 or
+    more String or Symbol arguments representing required arguments. Takes an
+    optional hash with String/Symbol keys and arbitrary values, representing
+    optional arguments and their default values.
+  - ::keywords - sets keyword arguments; same arguments as ::arguments.
+
+#### Hooks

data/README.md

@@ -31,7 +31,7 @@ If you want to extract your logic but Cuprum is not the right solution for you,
 
 ### Compatibility
 
-Cuprum is tested against Ruby (MRI) 2.4.
+Cuprum is tested against Ruby (MRI) 2.3 through 2.5.
 
 ### Documentation
 
@@ -650,6 +650,43 @@ result.success? #=> true
 
 Under the hood, both `#chain` and `#tap_result` are implemented on top of `#yield_result`.
 
+#### Protected Chaining Methods
+
+Each Command also defines the `#chain!`, `#tap_result!`, and `#yield_result!` methods - note the imperative `!`. These methods behave identically to their non-imperative counterparts, but they modify the current command directly instead of creating a clone. They are also protected methods, so they cannot be called from outside the command itself. These methods are designed for use when defining commands.
+
+```ruby
+# We subclass the build command, which will be executed first.
+class CreateCommentCommand < BuildCommentCommand
+  include Cuprum::Chaining
+  include Cuprum::Processing
+  #
+  def initialize
+    # After the build step is run, we validate the comment.
+    chain!(ValidateCommentCommand.new)
+  #
+    # If the validation passes, we then save the comment.
+    chain!(SaveCommentCommand.new, on: :success)
+  end
+end
+
+Comment.count #=> 0
+
+body   = 'Why do hot dogs come in packages of ten, and hot dog buns come in ' \
+         'packages of eight?'
+result = CreateCommentCommand.new.call({ user_id: '12345', body: body })
+
+result.value    #=> an instance of Comment with the given user_id and body.
+result.success? #=> true
+Comment.count   #=> 1; the comment was added to the database
+
+result = CreateCommentCommand.new.call({ user_id: nil, body: body })
+
+result.value    #=> an instance of Comment with the given user_id and body.
+result.success? #=> false
+result.errors   #=> ["User id can't be blank"]
+Comment.count   #=> 1; the comment was not added to the database
+```
+
 ### Results
 
     require 'cuprum'
@@ -734,6 +771,306 @@ result.halt!
 result.halted? #=> true
 ```
 
+### Command Factories
+
+[Class Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum%2FCommandFactory)
+
+Commands are powerful and flexible objects, but they do have a few disadvantages compared to traditional service objects which allow the developer to group together related functionality and shared implementation details. To bridge this gap, Cuprum implements the CommandFactory class. Command factories provide a DSL to quickly group together related commands and create context-specific command classes or instances.
+
+For example, consider a basic entity command:
+
+```ruby
+class Book
+  def initialize(attributes = {})
+    @title  = attributes[:title]
+    @author = attributes[:author]
+  end
+
+  attr_accessor :author, :publisher, :title
+end
+
+class BuildBookCommand < Cuprum::Command
+  private
+
+  def process(attributes = {})
+    Book.new(attributes)
+  end
+end
+
+class BookFactory < Cuprum::CommandFactory
+  command :build, BuildBookCommand
+end
+```
+
+Our factory is defined by subclassing `Cuprum::CommandFactory`, and then we map the individual commands with the `::command` or `::command_class` class methods. In this case, we've defined a Book factory with the build command. The build command can be accessed on a factory instance in one of two ways.
+
+First, the command class can be accessed directly as a constant on the factory instance.
+
+```ruby
+factory = BookFactory.new
+factory::Build #=> BuildBookCommand
+```
+
+Second, the factory instance now defines a `#build` method, which returns an instance of our defined command class. This command instance can be called like any command, or returned or passed around like any other object.
+
+```ruby
+factory = BookFactory.new
+
+attrs   = { title: 'A Wizard of Earthsea', author: 'Ursula K. Le Guin' }
+command = factory.build()     #=> an instance of BuildBookCommand
+result  = command.call(attrs) #=> an instance of Cuprum::Result
+book    = result.value        #=> an instance of Book
+
+book.title     #=> 'A Wizard of Earthsea'
+book.author    #=> 'Ursula K. Le Guin'
+book.publisher #=> nil
+```
+
+#### The ::command Method And A Command Class
+
+The first way to define a command for a factory is by calling the `::command` method and passing it the name of the command and a command class:
+
+```ruby
+class BookFactory < Cuprum::CommandFactory
+  command :build, BuildBookCommand
+end
+```
+
+This makes the command class available on a factory instance as `::Build`, and generates the `#build` method which returns an instance of `BuildBookCommand`.
+
+#### The ::command Method And A Block
+
+By calling the `::command` method with a block, you can define a command with additional control over how the generated command. The block must return an instance of a subclass of Cuprum::Command.
+
+```ruby
+class PublishBookCommand < Cuprum::Command
+  def initialize(publisher:)
+    @publisher = publisher
+  end
+
+  attr_reader :publisher
+
+  private
+
+  def process(book)
+    book.publisher = publisher
+
+    book
+  end
+end
+
+class BookFactory < Cuprum::CommandFactory
+  command :publish do |publisher|
+    PublishBookCommand.new(publisher: publisher)
+  end
+end
+```
+
+This defines the `#publish` method on an instance of the factory. The method takes one argument (the publisher), which is then passed on to the constructor for `PublishBookCommand` by our block. Finally, the block returns an instance of the publish command, which is then returned by `#publish`.
+
+```ruby
+factory = BookFactory.new
+book    = Book.new(title: 'The Tombs of Atuan', author: 'Ursula K. Le Guin')
+book.publisher #=> nil
+
+command = factory.publish('Harper & Row') #=> an instance of PublishBookCommand
+result  = command.call(book)              #=> an instance of Cuprum::Result
+book.publisher #=> 'Harper & Row'
+```
+
+Note that unlike when `::command` is called with a command class, calling `::command` with a block will not set a constant on the factory instance. In this case, trying to access the `PublishBookCommand` at `factory::Publish` will raise a `NameError`.
+
+The block is evaluated in the context of the factory instance. This means that instance variables or methods are available to the block, allowing you to create commands with instance-specific configuration.
+
+```ruby
+class PublishedBooksCommand < Cuprum::Command
+  def initialize(collection = [])
+    @collection = collection
+  end
+
+  attr_reader :collection
+
+  private
+
+  def process
+    books.reject { |book| book.publisher.nil? }
+  end
+end
+
+class BookFactory < Cuprum::CommandFactory
+  command :published do
+    PublishedBooksCommand.new(books_collection)
+  end
+
+  def initialize(books)
+    @books_collection = books
+  end
+
+  attr_reader :books_collection
+end
+```
+
+This defines the `#published` method on an instance of the factory. The method takes no arguments, but grabs the books collection from the factory instance. The block returns an instance of `PublishedBooksCommand`, which is then returned by `#published`.
+
+```ruby
+books   = [Book.new, Book.new(publisher: 'Baen'), Book.new(publisher: 'Tor')]
+factory = BookFactory.new(books)
+factory.books_collection #=> the books array
+
+command = factory.published #=> an instance of PublishedBooksCommand
+result  = command.call      #=> an instance of Cuprum::Result
+ary     = result.value      #=> an array with the published books
+
+ary.count                                    #=> 2
+ary.any? { |book| book.publisher == 'Baen' } #=> true
+ary.any? { |book| book.publisher.nil? }      #=> false
+```
+
+Simple commands can be defined directly in the block, rather than referencing an existing command class:
+
+```ruby
+class BookFactory < Cuprum::CommandFactory
+  command :published_by_baen do
+    Cuprum::Command.new do |books|
+      books.select { |book| book.publisher == 'Baen' }
+    end
+  end
+end
+
+books   = [Book.new, Book.new(publisher: 'Baen'), Book.new(publisher: 'Tor')]
+factory = BookFactory.new(books)
+
+command = factory.published_by_baen #=> an instance of the anonymous command
+result  = command.call              #=> an instance of Cuprum::Result
+ary     = result.value              #=> an array with the selected books
+
+ary.count #=> 1
+```
+
+#### The ::command_class Method
+
+The final way to define a command for a factory is calling the `::command_class` method with the command name and a block. The block must return a subclass (not an instance) of Cuprum::Command. This offers a balance between flexibility and power.
+
+```ruby
+class SelectByAuthorCommand < Cuprum::Command
+  def initialize(author)
+    @author = author
+  end
+
+  attr_reader :author
+
+  private
+
+  def process(books)
+    books.select { |book| book.author == author }
+  end
+end
+
+class BooksFactory < Cuprum::CommandFactory
+  command_class :select_by_author do
+    SelectByAuthorCommand
+  end
+end
+```
+
+The command class can be accessed directly as a constant on the factory instance:
+
+```ruby
+factory = BookFactory.new
+factory::SelectByAuthor #=> SelectByAuthorCommand
+```
+
+The factory instance now defines a `#select_by_author` method, which returns an instance of our defined command class. This command instance can be called like any command, or returned or passed around like any other object.
+
+```ruby
+factory = BookFactory.new
+books   = [
+  Book.new,
+  Book.new(author: 'Arthur C. Clarke'),
+  Book.new(author: 'Ursula K. Le Guin')
+]
+
+command = factory.select_by_author('Ursula K. Le Guin')
+#=> an instance of SelectByAuthorCommand
+command.author #=> 'Ursula K. Le Guin'
+
+result = command.call(books)      #=> an instance of Cuprum::Result
+ary    = result.value             #=> an array with the selected books
+
+ary.count                                              #=> 1
+ary.any? { |book| book.author == 'Ursula K. Le Guin' } #=> true
+ary.any? { |book| book.author == 'Arthur C. Clarke'  } #=> false
+ary.any? { |book| book.author.nil? }                   #=> false
+```
+
+The block is evaluated in the context of the factory instance. This means that instance variables or methods are available to the block, allowing you to create custom command subclasses with instance-specific configuration.
+
+```ruby
+class SaveBookCommand < Cuprum::Command
+  def initialize(collection = [])
+    @collection = collection
+  end
+
+  attr_reader :collection
+
+  private
+
+  def process(book)
+    books << book
+
+    book
+  end
+end
+
+class BookFactory < Cuprum::CommandFactory
+  command :save do
+    collection = self.books_collection
+
+    Class.new(SaveBookCommand) do
+      define_method(:initialize) do
+        @books = collection
+      end
+    end
+  end
+
+  def initialize(books)
+    @books_collection = books
+  end
+
+  attr_reader :books_collection
+end
+```
+
+The custom command subclass can be accessed directly as a constant on the factory instance:
+
+```ruby
+books   = [Book.new, Book.new, Book.new]
+factory = BookFactory.new(books)
+factory::Save #=> a subclass of SaveBookCommand
+
+command = factory::Save.new # an instance of the command subclass
+command.collection          #=> the books array
+command.collection.count    #=> 3
+```
+
+The factory instance now defines a `#save` method, which returns an instance of our custom command subclass. This command instance can be called like any command, or returned or passed around like any other object.
+
+The custom command subclass can be accessed directly as a constant on the factory instance:
+
+```ruby
+books   = [Book.new, Book.new, Book.new]
+factory = BookFactory.new(books)
+command = factory.save   # an instance of the command subclass
+command.collection       #=> the books array
+command.collection.count #=> 3
+
+book   = Book.new(title: 'The Farthest Shore', author: 'Ursula K. Le Guin')
+result = command.call(book) #=> an instance of Cuprum::Result
+
+books.count          #=> 4
+books.include?(book) #=> true
+```
+
 ### Built In Commands
 
 Cuprum includes a small number of predefined commands and their equivalent operations.
@@ -880,7 +1217,7 @@ Generates an empty errors object. When the command is called, the result will ha
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#build_errors-instance_method)
 
-#### #call
+#### `#call`
 
     call(*arguments, **keywords) { ... } #=> Cuprum::Result
 
@@ -888,7 +1225,7 @@ Executes the logic encoded in the constructor block, or the #process method if n
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#call-instance_method)
 
-#### #chain
+#### `#chain`
 
     chain(on: nil) { |result| ... } #=> Cuprum::Command
 
@@ -904,6 +1241,18 @@ If the block returns a Cuprum::Result (or an object responding to #value and #su
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain-instance_method)
 
+#### `#chain!`
+
+*(Protected Method)*
+
+    chain!(on: nil) { |result| ... } #=> Cuprum::Command
+
+    chain!(command, on: nil) #=> Cuprum::Command
+
+As `#chain`, but modifies the current command instead of creating a clone.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#chain!-instance_method)
+
 #### `#else`
 
     else(command) #=> Cuprum::Command
@@ -920,68 +1269,25 @@ If the block returns a Cuprum::Result (or an object responding to #value and #su
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#else-instance_method)
 
-#### `#errors`
-
-*(Private Method)*
-
-    errors() #=> Array
-
-Only available while the Command is being called. Provides access to the errors object of the generated Cuprum::Result, which is by default an instance of Array.
-
-Inside of the Command block or the `#process` method, you can add errors to the result.
-
-    command =
-      Cuprum::Command.new do
-        errors << "I'm sorry, something went wrong."
-
-        nil
-      end # command
-
-    result = command.call
-    result.failure?
-    #=> true
-    result.errors
-    #=> ["I'm sorry, something went wrong."]
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#errors-instance_method)
-
-#### `#failure!`
-
-    failure!() #=> NilClass
-
-*(Private Method)*
-
-Only available while the Command is being called. If called, marks the result object as failing, even if the result does not have errors.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#failure!-instance_method)
-
-#### `#halt!`
-
-    halt!() #=> NilClass
-
-*(Private Method)*
-
-Only available while the Command is being called. If called, halts the command chain (see Chaining Commands, below). Subsequent chained commands will not be called unless they were chained with the `:on => :always` option.
-
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#halt!-instance_method)
+#### `#tap_result`
 
-#### `#success!`
+    tap_result(on: nil) { |previous_result| } #=> Cuprum::Result
 
-    success!() #=> NilClass
+Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the previous result returned or yielded to the next block. The return value of the block is discarded.
 
-*(Private Method)*
+If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
 
-Only available while the Command is being called. If called, marks the result object as passing, even if the result has errors.
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result-instance_method)
 
-[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#success!-instance_method)
+#### `#tap_result!`
 
-#### `#tap_result`
+*(Protected Method)*
 
-    tap_result(on: nil) { |previous_result| } #=> Cuprum::Result
+    tap_result!(on: nil) { |previous_result| } #=> Cuprum::Result
 
-Creates a copy of the command, and then chains the block to execute after the command implementation. When #call is executed, each chained block will be yielded the previous result, and the previous result returned or yielded to the next block. The return value of the block is discarded.
+As `#tap_result`, but modifies the current command instead of creating a clone.
 
-If the `on` parameter is omitted, the block will be called if the last result is not halted. If the `on` parameter is set to `:success`, the block will be called if the last result is successful and not halted. If the `on` parameter is set to `:failure`, the block will be called if the last result is failing and not halted. Finally, if the `on` parameter is set to `:always`, the block will always be called, even if the last result is halted.
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#tap_result!-instance_method)
 
 #### `#then`
 
@@ -1009,6 +1315,16 @@ If the `on` parameter is omitted, the block will be called if the last result is
 
 [Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result-instance_method)
 
+#### `#yield_result!`
+
+*(Protected Method)*
+
+    yield_result!(on: nil) { |previous_result| } #=> Cuprum::Result
+
+As `#yield_result`, but modifies the current command instead of creating a clone.
+
+[Method Documentation](http://www.rubydoc.info/github/sleepingkingstudios/cuprum/master/Cuprum/Command#yield_result!-instance_method)
+
 ### Cuprum::Operation
 
     require 'cuprum'