interactor 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f90c2385a676f054e225898505feb66133199adb
-  data.tar.gz: f2f66a7c046fe90cd9cc8ee3c54797654f4dd5fd
+  metadata.gz: eef8d6afd5557c08a2400afb30b40209bb17fec5
+  data.tar.gz: 8513cec42b1bbb273b96803ec06cce6144a4078f
 SHA512:
-  metadata.gz: 224044e19387797e7e2cfc3b930cceb348078eee3b4ff6b2c7f44e54fefb7200ed490468131a31d813c2e0534c517311057aa048e70f90d04b1269cdcbbb5977
-  data.tar.gz: 92e8e877cc317445d33b4c7b32b5eae7c88d156a206f2e313d70c6abe01151819eb2b151a580f627ec9b0deeb862d24fae4cd5fd8c3b189018064be91dac3305
+  metadata.gz: 856f697f4443750d4fe95473ca44674669a8148582c5bff2dbff5ecd46d4ff5626b42c216eb4247c909c4d9bba0511d5a8bbfb50f9a6432f23f88c2a40d6be9f
+  data.tar.gz: 3ebed0429d15e0d9faa85d345523e0f0d9c3adf90ece48c0105761f8fbc1aea833fa718f07c2a362e194499bae18f79fe1309c14d55d720b6c9183c8a576326a

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 3.0.1 / 2014-09-09
+
+* [ENHANCEMENT] Add TomDoc code documentation
+
 ## 3.0.0 / 2014-09-07
 
 * [FEATURE] Halt performance if the interactor fails prior

data/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Please consider:
 
 * adding a feature
 * squashing a bug
-* writing documentation
+* writing [documentation](http://tomdoc.org)
 * reporting an issue
 * fixing a typo
 * correcting [style](https://github.com/styleguide/ruby)

data/interactor.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name    = "interactor"
-  spec.version = "3.0.0"
+  spec.version = "3.0.1"
 
   spec.author      = "Collective Idea"
   spec.email       = "info@collectiveidea.com"

data/lib/interactor.rb

@@ -3,35 +3,141 @@ require "interactor/error"
 require "interactor/hooks"
 require "interactor/organizer"
 
+# Public: Interactor methods. Because Interactor is a module, custom Interactor
+# classes should include Interactor rather than inherit from it.
+#
+# Examples
+#
+#   class MyInteractor
+#     include Interactor
+#
+#     def call
+#       puts context.foo
+#     end
+#   end
 module Interactor
+  # Internal: Install Interactor's behavior in the given class.
   def self.included(base)
     base.class_eval do
       extend ClassMethods
       include Hooks
 
+      # Public: Gets the Interactor::Context of the Interactor instance.
       attr_reader :context
     end
   end
 
+  # Internal: Interactor class methods.
   module ClassMethods
+    # Public: Invoke an Interactor. This is the primary public API method to an
+    # interactor.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. An existing Interactor::Context may
+    #           also be given. (default: {})
+    #
+    # Examples
+    #
+    #   MyInteractor.call(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #
+    #   MyInteractor.call
+    #   # => #<Interactor::Context>
+    #
+    # Returns the resulting Interactor::Context after manipulation by the
+    #   interactor.
     def call(context = {})
       new(context).tap(&:run).context
     end
 
+    # Public: Invoke an Interactor. The "call!" method behaves identically to
+    # the "call" method with one notable exception. If the context is failed
+    # during invocation of the interactor, the Interactor::Failure is raised.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. An existing Interactor::Context may
+    #           also be given. (default: {})
+    #
+    # Examples
+    #
+    #   MyInteractor.call!(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #
+    #   MyInteractor.call!
+    #   # => #<Interactor::Context>
+    #
+    #   MyInteractor.call!(foo: "baz")
+    #   # => Interactor::Failure: #<Interactor::Context foo="baz">
+    #
+    # Returns the resulting Interactor::Context after manipulation by the
+    #   interactor.
+    # Raises Interactor::Failure if the context is failed.
     def call!(context = {})
       new(context).tap(&:run!).context
     end
   end
 
+  # Internal: Initialize an Interactor.
+  #
+  # context - A Hash whose key/value pairs are used in initializing the
+  #           interactor's context. An existing Interactor::Context may also be
+  #           given. (default: {})
+  #
+  # Examples
+  #
+  #   MyInteractor.new(foo: "bar")
+  #   # => #<MyInteractor @context=#<Interactor::Context foo="bar">>
+  #
+  #   MyInteractor.new
+  #   # => #<MyInteractor @context=#<Interactor::Context>>
   def initialize(context = {})
     @context = Context.build(context)
   end
 
+  # Internal: Invoke an interactor instance along with all defined hooks. The
+  # "run" method is used internally by the "call" class method. The following
+  # are equivalent:
+  #
+  #   MyInteractor.call(foo: "bar")
+  #   # => #<Interactor::Context foo="bar">
+  #
+  #   interactor = MyInteractor.new(foo: "bar")
+  #   interactor.run
+  #   interactor.context
+  #   # => #<Interactor::Context foo="bar">
+  #
+  # After successful invocation of the interactor, the instance is tracked
+  # within the context. If the context is failed or any error is raised, the
+  # context is rolled back.
+  #
+  # Returns nothing.
   def run
     run!
   rescue Failure
   end
 
+  # Internal: Invoke an Interactor instance along with all defined hooks. The
+  # "run!" method is used internally by the "call!" class method. The following
+  # are equivalent:
+  #
+  #   MyInteractor.call!(foo: "bar")
+  #   # => #<Interactor::Context foo="bar">
+  #
+  #   interactor = MyInteractor.new(foo: "bar")
+  #   interactor.run!
+  #   interactor.context
+  #   # => #<Interactor::Context foo="bar">
+  #
+  # After successful invocation of the interactor, the instance is tracked
+  # within the context. If the context is failed or any error is raised, the
+  # context is rolled back.
+  #
+  # The "run!" method behaves identically to the "run" method with one notable
+  # exception. If the context is failed during invocation of the interactor,
+  # the Interactor::Failure is raised.
+  #
+  # Returns nothing.
+  # Raises Interactor::Failure if the context is failed.
   def run!
     with_hooks do
       call
@@ -42,9 +148,19 @@ module Interactor
     raise
   end
 
+  # Public: Invoke an Interactor instance without any hooks, tracking, or
+  # rollback. It is expected that the "call" instance method is overwritten for
+  # each interactor class.
+  #
+  # Returns nothing.
   def call
   end
 
+  # Public: Reverse prior invocation of an Interactor instance. Any interactor
+  # class that requires undoing upon downstream failure is expected to overwrite
+  # the "rollback" instance method.
+  #
+  # Returns nothing.
   def rollback
   end
 end

data/lib/interactor/context.rb

@@ -1,35 +1,179 @@
 require "ostruct"
 
 module Interactor
+  # Public: The object for tracking state of an Interactor's invocation. The
+  # context is used to initialize the interactor with the information required
+  # for invocation. The interactor manipulates the context to produce the result
+  # of invocation.
+  #
+  # The context is the mechanism by which success and failure are determined and
+  # the context is responsible for tracking individual interactor invocations
+  # for the purpose of rollback.
+  #
+  # The context may be maniupulated using arbitrary getter and setter methods.
+  #
+  # Examples
+  #
+  #   context = Interactor::Context.new
+  #   # => #<Interactor::Context>
+  #   context.foo = "bar"
+  #   # => "bar"
+  #   context
+  #   # => #<Interactor::Context foo="bar">
+  #   context.hello = "world"
+  #   # => "world"
+  #   context
+  #   # => #<Interactor::Context foo="bar" hello="world">
+  #   context.foo = "baz"
+  #   # => "baz"
+  #   context
+  #   # => #<Interactor::Context foo="baz" hello="world">
   class Context < OpenStruct
+    # Internal: Initialize an Interactor::Context or preserve an existing one.
+    # If the argument given is an Interactor::Context, the argument is returned.
+    # Otherwise, a new Interactor::Context is initialized from the provided
+    # hash.
+    #
+    # The "build" method is used during interactor initialization.
+    #
+    # context - A Hash whose key/value pairs are used in initializing a new
+    #           Interactor::Context object. If an existing Interactor::Context
+    #           is given, it is simply returned. (default: {})
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.build(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #   context.object_id
+    #   # => 2170969340
+    #   context = Interactor::Context.build(context)
+    #   # => #<Interactor::Context foo="bar">
+    #   context.object_id
+    #   # => 2170969340
+    #
+    # Returns the Interactor::Context.
     def self.build(context = {})
       self === context ? context : new(context)
     end
 
+    # Public: Whether the Interactor::Context is successful. By default, a new
+    # context is successful and only changes when explicitly failed.
+    #
+    # The "success?" method is the inverse of the "failure?" method.
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.success?
+    #   # => true
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.success?
+    #   # => false
+    #
+    # Returns true by default or false if failed.
     def success?
       !failure?
     end
 
+    # Public: Whether the Interactor::Context has failed. By default, a new
+    # context is successful and only changes when explicitly failed.
+    #
+    # The "failure?" method is the inverse of the "success?" method.
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.failure?
+    #   # => false
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.failure?
+    #   # => true
+    #
+    # Returns false by default or true if failed.
     def failure?
       @failure || false
     end
 
+    # Public: Fail the Interactor::Context. Failing a context raises an error
+    # that may be rescued by the calling interactor. The context is also flagged
+    # as having failed.
+    #
+    # Optionally the caller may provide a hash of key/value pairs to be merged
+    # into the context before failure.
+    #
+    # context - A Hash whose key/value pairs are merged into the existing
+    #           Interactor::Context instance. (default: {})
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context.fail!
+    #   # => Interactor::Failure: #<Interactor::Context>
+    #   context.fail! rescue false
+    #   # => false
+    #   context.fail!(foo: "baz")
+    #   # => Interactor::Failure: #<Interactor::Context foo="baz">
+    #
+    # Raises Interactor::Failure initialized with the Interactor::Context.
     def fail!(context = {})
       modifiable.update(context)
       @failure = true
       raise Failure, self
     end
 
+    # Internal: Track that an Interactor has been called. The "called!" method
+    # is used by the interactor being invoked with this context. After an
+    # interactor is successfully called, the interactor instance is tracked in
+    # the context for the purpose of potential future rollback.
+    #
+    # interactor - An Interactor instance that has been successfully called.
+    #
+    # Returns nothing.
     def called!(interactor)
       _called << interactor
     end
 
+    # Public: Roll back the Interactor::Context. Any interactors to which this
+    # context has been passed and which have been successfully called are asked
+    # to roll themselves back by invoking their "rollback" instance methods.
+    #
+    # Examples
+    #
+    #   context = MyInteractor.call(foo: "bar")
+    #   # => #<Interactor::Context foo="baz">
+    #   context.rollback!
+    #   # => true
+    #   context
+    #   # => #<Interactor::Context foo="bar">
+    #
+    # Returns true if rolled back successfully or false if already rolled back.
     def rollback!
       return false if @rolled_back
       _called.reverse_each(&:rollback)
       @rolled_back = true
     end
 
+    # Internal: An Array of successfully called Interactor instances invoked
+    # against this Interactor::Context instance.
+    #
+    # Examples
+    #
+    #   context = Interactor::Context.new
+    #   # => #<Interactor::Context>
+    #   context._called
+    #   # => []
+    #
+    #   context = MyInteractor.call(foo: "bar")
+    #   # => #<Interactor::Context foo="baz">
+    #   context._called
+    #   # => [#<MyInteractor @context=#<Interactor::Context foo="baz">>]
+    #
+    # Returns an Array of Interactor instances or an empty Array.
     def _called
       @called ||= []
     end

data/lib/interactor/error.rb

@@ -1,7 +1,28 @@
 module Interactor
+  # Internal: Error raised during Interactor::Context failure. The error stores
+  # a copy of the failed context for debugging purposes.
   class Failure < StandardError
+    # Internal: Gets the Interactor::Context of the Interactor::Failure
+    # instance.
     attr_reader :context
 
+    # Internal: Initialize an Interactor::Failure.
+    #
+    # context - An Interactor::Context to be stored within the
+    #           Interactor::Failure instance. (default: nil)
+    #
+    # Examples
+    #
+    #   Interactor::Failure.new
+    #   # => #<Interactor::Failure: Interactor::Failure>
+    #
+    #   context = Interactor::Context.new(foo: "bar")
+    #   # => #<Interactor::Context foo="bar">
+    #   Interactor::Failure.new(context)
+    #   # => #<Interactor::Failure: #<Interactor::Context foo="bar">>
+    #
+    #   raise Interactor::Failure, context
+    #   # => Interactor::Failure: #<Interactor::Context foo="bar">
     def initialize(context = nil)
       @context = context
       super

data/lib/interactor/hooks.rb

@@ -1,26 +1,123 @@
 module Interactor
+  # Internal: Methods relating to supporting hooks around Interactor invocation.
   module Hooks
+    # Internal: Install Interactor's behavior in the given class.
     def self.included(base)
       base.class_eval do
         extend ClassMethods
       end
     end
 
+    # Internal: Interactor::Hooks class methods.
     module ClassMethods
+      # Public: Declare hooks to run before Interactor invocation. The before
+      # method may be called multiple times; subsequent calls append declared
+      # hooks to existing before hooks.
+      #
+      # hooks - Zero or more Symbol method names representing instance methods
+      #         to be called before interactor invocation.
+      # block - An optional block to be executed as a hook. If given, the block
+      #         is executed after methods corresponding to any given Symbols.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     before :set_start_time
+      #
+      #     before do
+      #       puts "started"
+      #     end
+      #
+      #     def call
+      #       puts "called"
+      #     end
+      #
+      #     private
+      #
+      #     def set_start_time
+      #       context.start_time = Time.now
+      #     end
+      #   end
+      #
+      # Returns nothing.
       def before(*hooks, &block)
         hooks << block if block
         hooks.each { |hook| before_hooks.push(hook) }
       end
 
+      # Public: Declare hooks to run after Interactor invocation. The after
+      # method may be called multiple times; subsequent calls prepend declared
+      # hooks to existing after hooks.
+      #
+      # hooks - Zero or more Symbol method names representing instance methods
+      #         to be called after interactor invocation.
+      # block - An optional block to be executed as a hook. If given, the block
+      #         is executed before methods corresponding to any given Symbols.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     after :set_finish_time
+      #
+      #     after do
+      #       puts "finished"
+      #     end
+      #
+      #     def call
+      #       puts "called"
+      #     end
+      #
+      #     private
+      #
+      #     def set_finish_time
+      #       context.finish_time = Time.now
+      #     end
+      #   end
+      #
+      # Returns nothing.
       def after(*hooks, &block)
         hooks << block if block
         hooks.each { |hook| after_hooks.unshift(hook) }
       end
 
+      # Internal: An Array of declared hooks to run before Interactor
+      # invocation. The hooks appear in the order in which they will be run.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     before :set_start_time, :say_hello
+      #   end
+      #
+      #   MyInteractor.before_hooks
+      #   # => [:set_start_time, :say_hello]
+      #
+      # Returns an Array of Symbols and Procs.
       def before_hooks
         @before_hooks ||= []
       end
 
+      # Internal: An Array of declared hooks to run before Interactor
+      # invocation. The hooks appear in the order in which they will be run.
+      #
+      # Examples
+      #
+      #   class MyInteractor
+      #     include Interactor
+      #
+      #     after :set_finish_time, :say_goodbye
+      #   end
+      #
+      #   MyInteractor.after_hooks
+      #   # => [:say_goodbye, :set_finish_time]
+      #
+      # Returns an Array of Symbols and Procs.
       def after_hooks
         @after_hooks ||= []
       end
@@ -28,24 +125,64 @@ module Interactor
 
     private
 
+    # Internal: Run before and after hooks around yielded execution. The
+    # required block is surrounded with hooks and executed.
+    #
+    # Examples
+    #
+    #   class MyProcessor
+    #     include Interactor::Hooks
+    #
+    #     def process_with_hooks
+    #       with_hooks do
+    #         process
+    #       end
+    #     end
+    #
+    #     def process
+    #       puts "processed!"
+    #     end
+    #   end
+    #
+    # Returns nothing.
     def with_hooks
       run_before_hooks
       yield
       run_after_hooks
     end
 
+    # Internal: Run before hooks.
+    #
+    # Returns nothing.
     def run_before_hooks
       run_hooks(self.class.before_hooks)
     end
 
+    # Internal: Run after hooks.
+    #
+    # Returns nothing.
     def run_after_hooks
       run_hooks(self.class.after_hooks)
     end
 
+    # Internal: Run a colection of hooks. The "run_hooks" method is the common
+    # interface by which collections of either before or after hooks are run.
+    #
+    # hooks - An Array of Symbol and Proc hooks.
+    #
+    # Returns nothing.
     def run_hooks(hooks)
       hooks.each { |hook| run_hook(hook) }
     end
 
+    # Internal: Run an individual hook. The "run_hook" method is the common
+    # interface by which an individual hook is run. If the given hook is a
+    # symbol, the method is invoked whether public or private. If the hook is a
+    # proc, the proc is evaluated in the context of the current instance.
+    #
+    # hook - A Symbol or Proc hook.
+    #
+    # Returns nothing.
     def run_hook(hook)
       hook.is_a?(Symbol) ? send(hook) : instance_eval(&hook)
     end

data/lib/interactor/organizer.rb

@@ -1,5 +1,17 @@
 module Interactor
+  # Public: Interactor::Organizer methods. Because Interactor::Organizer is a
+  # module, custom Interactor::Organizer classes should include
+  # Interactor::Organizer rather than inherit from it.
+  #
+  # Examples
+  #
+  #   class MyOrganizer
+  #     include Interactor::Organizer
+  #
+  #     organizer InteractorOne, InteractorTwo
+  #   end
   module Organizer
+    # Internal: Install Interactor::Organizer's behavior in the given class.
     def self.included(base)
       base.class_eval do
         include Interactor
@@ -9,17 +21,59 @@ module Interactor
       end
     end
 
+    # Internal: Interactor::Organizer class methods.
     module ClassMethods
+      # Public: Declare Interactors to be invoked as part of the
+      # Interactor::Organizer's invocation. These interactors will invoked in
+      # the order in which they are declared.
+      #
+      # interactors - Zero or more (or an Array of) Interactor classes.
+      #
+      # Examples
+      #
+      #   class MyFirstOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organize InteractorOne, InteractorTwo
+      #   end
+      #
+      #   class MySecondOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organize [InteractorThree, InteractorFour]
+      #   end
+      #
+      # Returns nothing.
       def organize(*interactors)
         @organized = interactors.flatten
       end
 
+      # Internal: An Array of declared Interactors to be invoked.
+      #
+      # Examples
+      #
+      #   class MyOrganizer
+      #     include Interactor::Organizer
+      #
+      #     organizer InteractorOne, InteractorTwo
+      #   end
+      #
+      #   MyOrganizer.organized
+      #   # => [InteractorOne, InteractorTwo]
+      #
+      # Returns an Array of Interactor classes or an empty Array.
       def organized
         @organized ||= []
       end
     end
 
+    # Internal: Interactor::Organizer instance methods.
     module InstanceMethods
+      # Internal: Invoke the organized Interactors. An Interactor::Organizer is
+      # expected not to define its own "call" method in favor of this default
+      # implementation.
+      #
+      # Returns nothing.
       def call
         self.class.organized.each do |interactor|
           interactor.call!(context)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: interactor
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Collective Idea
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-07 00:00:00.000000000 Z
+date: 2014-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler