the_help 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12d2ca84288d7edcf861be2115e275ea1ebbbf4e5eeb0bd1ad109334e2310b78
-  data.tar.gz: cbbc8bf078f9452d80488f9993dddb615a10c1fc73ffecfc81d9adf2e606309d
+  metadata.gz: 9839566fa2430a430f15129d61d210d5140a9799eb85de929ea3d04768821e90
+  data.tar.gz: fc9e5f57c9e615edd1a2858893ca8529dd2c471dcc7a0e9f57bc16b96f428cdb
 SHA512:
-  metadata.gz: '00586882e22049dfc9ff1aeeed59037d0d8703346495db16a62eda8327171a9c3729d6c733dc27fb29c745ed6304338c530097de929f583331b18ec6fd99857e'
-  data.tar.gz: f1c932128245cf6e7c66a343ca4f815a60308d03a017d8d2f89c6f035c48f3212c5bbc577a67b9638ad1b1c14ec629b26f189b5b46cee17320c23c5e2c061c18
+  metadata.gz: 6a202d3b4725139bec17b7644279486ba9c71abd6ccc6f904f749e473c012460c0264809796523d518c9172e16e36e325e55aa7a1cc03b26b4a7eefe86fed3c8
+  data.tar.gz: df6f0dcbc797265af71b36725e554143f027eeed97c2963318fb56e73cf91cb1323eaa1d59ef6f5be4941a147b501017d28d2fbf396e00a8084ea6c702634259

data/.ruby-version

@@ -0,0 +1 @@
+2.5.0

data/Gemfile.lock

@@ -36,6 +36,7 @@ GEM
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-progressbar (1.9.0)
     unicode-display_width (1.3.0)
+    yard (0.9.12)
 
 PLATFORMS
   ruby
@@ -45,6 +46,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   rubocop (~> 0.50)
   the_help!
+  yard
 
 BUNDLED WITH
    1.16.1

data/lib/the_help/errors.rb

@@ -5,5 +5,6 @@ module TheHelp
     class AbstractClassError < StandardError; end
     class ServiceNotImplementedError < StandardError; end
     class NotAuthorizedError < RuntimeError; end
+    class NoResultError < StandardError; end
   end
 end

data/lib/the_help/provides_callbacks.rb

@@ -4,28 +4,28 @@ module TheHelp
   # Adds a callback DSL to including classes
   #
   # @example
-  # class Foo
-  #   attr_accessor :collaborator
+  #   class Foo
+  #     attr_accessor :collaborator
   #
-  #   def do_something
-  #     collaborator.do_some_other_thing(when_done: callback(:it_was_done))
-  #   end
+  #     def do_something
+  #       collaborator.do_some_other_thing(when_done: callback(:it_was_done))
+  #     end
   #
-  #   callback(:it_was_done) do |some_arg:|
-  #     puts "Yay! #{some_arg}"
+  #     callback(:it_was_done) do |some_arg:|
+  #       puts "Yay! #{some_arg}"
+  #     end
   #   end
-  # end
   #
-  # class Bar
-  #  def do_some_other_thing(when_done:)
-  #    when_done.call('done by Bar')
-  #  end
-  # end
+  #   class Bar
+  #    def do_some_other_thing(when_done:)
+  #      when_done.call('done by Bar')
+  #    end
+  #   end
   #
-  # f = Foo.new
-  # f.collaborator = Bar.new
-  # f.do_something
-  # # STDOUT: "Yay! done by Bar"
+  #   f = Foo.new
+  #   f.collaborator = Bar.new
+  #   f.do_something
+  #   # STDOUT: "Yay! done by Bar"
   #
   # Callbacks can be given to collaborating objects, but the actual methods are
   # defined as private methods. This allows the object to control which other

data/lib/the_help/service.rb

@@ -10,54 +10,92 @@ module TheHelp
   # application.
   #
   # @example
-  # class CreateNewUserAccount < TheHelp::Service
-  #   input :user
-  #   input :send_welcome_message, default: true
-  #
-  #   authorization_policy do
-  #     authorized = false
-  #     call_service(Authorize, permission: :admin_users,
-  #                  allowed: ->() { authorized = true })
-  #     authorized
+  #   class CreateNewUserAccount < TheHelp::Service
+  #     input :user
+  #     input :send_welcome_message, default: true
+  #
+  #     authorization_policy do
+  #       authorized = false
+  #       call_service(Authorize, permission: :admin_users,
+  #                    allowed: ->() { authorized = true })
+  #       authorized
+  #     end
+  #
+  #     main do
+  #       # do something to create the user account
+  #       if send_welcome_message
+  #         call_service(SendWelcomeMessage, user: user,
+  #                      success: callback(:message_sent))
+  #       end
+  #     end
+  #
+  #     callback(:message_sent) do
+  #       # do something really important, I'm sure
+  #     end
   #   end
   #
-  #   main do
-  #     # do something to create the user account
-  #     if send_welcome_message
-  #       call_service(SendWelcomeMessage, user: user,
-  #                    success: callback(:message_sent))
+  #   class Authorize < TheHelp::Service
+  #     input :permission
+  #     input :allowed
+  #
+  #     authorization_policy allow_all: true
+  #
+  #     main do
+  #       if user_has_permission?
+  #         allowed.call
+  #       end
   #     end
   #   end
   #
-  #   callback(:message_sent) do
-  #     # do something really important, I'm sure
+  #   class SendWelcomeMessage < TheHelp::Service
+  #     input :user
+  #     input :success, default: ->() { }
+  #
+  #     main do
+  #       # whatever
+  #       success.call
+  #     end
   #   end
-  # end
   #
-  # class Authorize < TheHelp::Service
-  #   input :permission
-  #   input :allowed
+  #   CreateNewUserAccount.(context: current_user, user: new_user_object)
+  #
+  # @example Calling services with a block
   #
-  #   authorization_policy allow_all: true
+  #   # Calling a service with a block when the service is not designed to
+  #   # receive one will result in an exception being raised
   #
-  #   main do
-  #     if user_has_permission?
-  #       allowed.call
+  #   class DoesNotTakeBlock < TheHelp::Service
+  #     authorization_policy allow_all: true
+  #
+  #     main do
+  #       # whatever
   #     end
   #   end
-  # end
   #
-  # class SendWelcomeMessage < TheHelp::Service
-  #   input :user
-  #   input :success, default: ->() { }
+  #   DoesNotTakeBlock.call { |result| true } # raises TheHelp::NoResultError
+  #
+  #   # However, if the service *is* designed to receive a block (by explicitly
+  #   # assigning to the internal `#result` attribute in the main routine), the
+  #   # result will be yielded to the block if a block is present.
+  #
+  #   class CanTakeABlock < TheHelp::Service
+  #     authorization_policy allow_all: true
   #
-  #   main do
-  #     # whatever
-  #     success.call
+  #     main do
+  #       self.result = :the_service_result
+  #     end
   #   end
-  # end
   #
-  # CreateNewUserAccount.(context: current_user, user: new_user_object)
+  #   service_result = nil
+  #
+  #   CanTakeABlock.call() # works just fine
+  #   service_result
+  #   #=> nil              # but obviously the result is just discarded
+  #
+  #   CanTakeABlock.call { |result| service_result = result }
+  #   service_result
+  #   #=> :the_service_result
+  #
   class Service
     include ProvidesCallbacks
     include ServiceCaller
@@ -87,8 +125,8 @@ module TheHelp
       # Any arguments are passed to #initialize
       #
       # @return [Class] Returns the receiver
-      def call(*args)
-        new(*args).call
+      def call(*args, &block)
+        new(*args, &block).call
         self
       end
 
@@ -152,6 +190,11 @@ module TheHelp
       self.logger = logger
       self.not_authorized = not_authorized
       self.inputs = inputs
+      if block_given?
+        self.result_handler = ->(result) {
+          yield result
+        }
+      end
     end
 
     def call
@@ -160,13 +203,17 @@ module TheHelp
         authorize
         log_service_call
         main
+        unless result_handler.nil?
+          result_handler.call(result)
+        end
       end
       self
     end
 
     private
 
-    attr_accessor :context, :logger, :not_authorized
+    attr_accessor :context, :logger, :not_authorized, :result_handler
+    attr_writer :result
     attr_reader :inputs
 
     alias service_context context
@@ -209,5 +256,10 @@ module TheHelp
     def stop!
       throw :stop
     end
+
+    def result
+      raise TheHelp::NoResultError unless defined?(@result)
+      @result
+    end
   end
 end

data/lib/the_help/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TheHelp
-  VERSION = '1.1.4'
+  VERSION = '1.2.0'
 end

data/the_help.gemspec

@@ -25,4 +25,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 0.50'
+  spec.add_development_dependency 'yard'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: the_help
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - John Wilger
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.50'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A service layer framework
 email:
 - john@johnwilger.com
@@ -63,6 +77,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile