ianwhite-hark 0.0.3 → 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 613e390efbcf4b85473a608ceb85ddf80a466a71
+  data.tar.gz: 0e135cd5077287cdfee91caa8fd3d98b2768d89c
+SHA512:
+  metadata.gz: 0144dab15f39746e69b7bf31e47996bb3b5dc6d25cb0a06259c6c25287bccee67b0f3ac1a9a80ee8c2c9420bcb6aaf710c65e7c8c6169e49680a71e83175ae8a
+  data.tar.gz: 8a3971eaf75d614426179ecf6752a01b5ecb3deb185e1963da51b9f2dbc343134b2aff23066ce4c3311e4c5851ec49440239c54873dc8f92c8e8592e51a78998

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/History.md

@@ -0,0 +1,13 @@
+# History
+
+## master
+
+* Adds coveralls & History
+
+## 0.0.3
+
+* Adds ruby < 1.9 support
+
+## 0.0.1 - 0.0.2
+
+* Initial release, slims API down to Kernel#hark

data/README.md

@@ -1,6 +1,12 @@
-# Hark [![Code Climate](https://codeclimate.com/repos/52691919c7f3a37a2301dfc5/badges/8f5a4caa333ec7a654ec/gpa.png)](https://codeclimate.com/repos/52691919c7f3a37a2301dfc5/feed) [![Build Status](https://travis-ci.org/ianwhite/hark.png)](https://travis-ci.org/ianwhite/hark)
+# Hark
 
-Create an ad-hoc listener object with hark.
+[![Gem Version](https://badge.fury.io/rb/ianwhite-hark.png)](https://rubygems.org/gems/ianwhite-hark)
+[![Build Status](https://travis-ci.org/ianwhite/hark.png)](https://travis-ci.org/ianwhite/hark)
+[![Dependency Status](https://gemnasium.com/ianwhite/hark.png)](https://gemnasium.com/ianwhite/hark)
+[![Code Climate](https://codeclimate.com/github/ianwhite/hark.png)](https://codeclimate.com/github/ianwhite/hark)
+[![Coverage Status](https://coveralls.io/repos/ianwhite/hark/badge.png)](https://coveralls.io/r/ianwhite/hark)
+
+Create a ad-hoc listeners with hark.
 
 ## Installation
 
@@ -16,64 +22,301 @@ Or install it yourself as:
 
     $ gem install ianwhite-hark
 
+## What & Why?
+
+**hark** enables you to create a 'listener' object very easily.  It's for programming in the *hexagonal* or *tell, don't ask* style.
+The consumers of hark listeners don't know anything about hark.  Because hark makes it easy to create ad-hoc object, it's easy to get
+started with a tell-dont-ask style, in rails controllers for example.  For more detail see the 'Rationale' section.
+
 ## Usage
 
-The idea behind hark is that the objects that receive listeners shouldn't need to perform any ceremony on
-them, just treat them as objects that respond to messages.  It's up to the caller to provide these lsitener objects,
-and to decide how they behave, perhaps combining together listeners (in an subscriber fashion).  If required, these ad-hoc
-listeners can easily be refactored into classes in their own right, as the recievers don't need to know anything about
-hark.
+### Create a listener
+
+To create a listener object use `hark`.
+
+You can pass a symbol and block
+
+    hark :created do |user|
+      redirect_to(user, notice: "You have signed up!")
+    end
+
+The following methods are more suitable for a listener with multiple messages.
+
+A hash with callables as keys
+
+    hark(
+      created: ->(user) { redirect_to(user, notice: "You have signed up!") },
+      invalid: ->(user) { @user = user; render "new" }
+    )
+
+    # assuming some methods for rendering and redirecting exist on the controller
+    hash created: method(:redirect_to_user), invalid: method(:render_new)
+
+Or, a 'respond_to' style block
+
+    hark do |on|
+      on.created {|user| redirect_to(user, notice: "You have signed up!") }
+      on.invalid {|user| @user = user; render "new" }
+    end
+
+### Strict & lax listeners
+
+By default, hark listeners are 'strict', they will only respond to the methods defined on them.
+
+You create a 'lax' listener, responding to any message, by sending the `lax` message.
+
+    listener = hark(:foo) { "Foo" }
+
+    listener.bar
+    # => NoMethodError: undefined method `bar' for #<Hark::StrictListener:0x007fc91a03e568>
+
+    listener = listener.lax
+    listener.bar
+    # => []
+
+To make a strict listener send the `strict` message.
+
+### Combining listeners
+
+Here are some ways of combining listeners.
+
+    # redirect listener
+    listener = hark(created: method(:redirect_to_user))
+
+Add a message
+
+    listener = listener.hark :created do |user|
+      WelomeMailer.send_email(user)
+    end
+
+Combine with another listener
+
+    logger = listener.hark(created: ->(u) { logger.info "User #{u} created" } )
+    listener = listener.hark(logger)
+
+Combine with any object that support the same protocol
+
+    logger = UserLogger.new # responds to :created
+    listener = listener.hark(logger)
+
+Now, when listener is sent #created, all create handlers are called.
+
+### Sugar: #hearken
+
+Because of the precedence of the block operator, constructing ad-hoc listeners requires
+you to insert some parens, which might be seen as unsightly, e.g:
+
+    seller.request_valuation(item, (hark do |on|
+      on.valuation_requested {|valuation| redirect_to valuation}
+      on.invalid_item {|item| redirect_to item, error: "Item not evaluable" }
+    end))
+
+You may use Kernerl#hearken to create an ad-hoc listener using a passed block as follows
+
+    seller.hearken :request_valuation, item do |on|
+      on.valuation_requested {|valuation| redirect_to valuation}
+      on.invalid_item {|item| redirect_to item, error: "Item not evaluable" }
+    end
+
+If you want to combine listeners with an ad-hoc blokc, you may pass a 0-arity block that is
+yielded as the listener
+
+    seller.hearken :request_valuation, item do
+      hark valuation_notifier do |on|
+        on.valuation_requested {|valuation| redirect_to valuation}
+        on.invalid_item {|item| redirect_to item, error: "Item not evaluable" }
+      end
+    end
+
+### Return value
+
+Using the return value of a listener is not encouraged.  Hark is designed for a *tell, don't ask*
+style of coding.  That said the return value of a hark listener is an array of its handlers return values.
+
+    a = hark(:foo) { 'a' }
+    b = Object.new.tap {|o| o.singleton_class.send(:define_method, :foo) { 'b' } }
+    c = hark(foo: -> { 'c' }, bar: -> { 'c bar' })
+
+    a.foo           # => ["a"]
+    hark(a,b).foo   # => ["a", "b"]
+    hark(a,b,c).foo # => ["a", "b", "c"]
 
-Tell don't ask style is encouraged with hark.  That said, the return value for a message sent to a hark listener is an array of all of the return values.
+### Immutable
 
-    listener = hark success: ->{ "succeeded" }, failure: ->{ "failed" }
-    listener.success # => ["succeeded"]
-    listener.failure # => ["failed"]
-    listener.unknown # raises NoMethodError
+Hark listeners are immutable and `#lax`, `#strict`, and `#hark` all return new listeners.
 
-Listeners return an array of return values, but using return values is discouraged (tell don't ask)
+## Rationale
 
-To create a listener that silently swallows unknown messages, send it the #lax method
+When programming in the 'tell-dont-ask' or 'hexagonal' style, program flow is managed by passing listener, or
+response, objects to service objects, which call back depending on what happened.  This allows logic that is concerned with the caller's domain to remain isolated from the service object.
 
-    listener = hark(success: ->{ "succeeded" }).lax
-    listener.success # => ["succeeded"]
-    listener.unknown # => []
+The idea behind **hark** is that there should be little ceremony involved in the listener/response mechanics, and
+that simple listeners can easily be refactored into objects in their own right, without changing the protocols between
+the calling and servcie objects.
 
-To make a lax listener strict again, send it the #strict method
+To that end, service objects should not know anything other than the listener/response protocol, and shouldn't have to 'publish' their
+results beyond a simple method call.
 
-    listener = listener.strict
+As a simple example, a user creation service object defines a response protocol as follows:
 
-To smush together listeners, use #hark
+* created_user(user) _the user was succesfully created_
+* invalid_user(user) _the user couldn't be created because it was invalid_
 
-    listener = listener.hark other_listener
-    listener = listener.hark emailer, logger
-    listener = hark(emailer, logger, twitter_notifier)
+The UserCreator object's main method will have some code as follows:
 
-To add new messages to a listener, use #hark
+    if # some logic that means the user params were valid and we could persist the user
+      response.created_user(user)
+    else
+      response.invalid_user(user)
+    end
+
+Let's say a controller is calling this, and you are using hark.  In the beginning you would do something like this:
+
+    def create
+      user_creator.call(user_params, hark do |on|
+        on.created_user {|user| redirect_to user, notice: "Welome!" }
+        on.invalid_user {|user| @user = user; render "new" }
+      end)
+    end
 
-    listener = listener.hark(:success) { "extra success" }
-    listener.success # => ["success", "extra success"]
+This keeps the controller's handling of the user creation nicely separate from the saving of the user creator.
 
-To decorate an object (of any sort) so that it becomes a hark listener (and therefore can be smushed etc)
+Then, a requirement comes in to log the creation of users.  The first attempt might be this:
 
-    listener = hark(object)
+    def create
+      user_creator.call(user_params, hark do |on|
+        on.created_user do |user|
+          redirect_to user, notice: "Welome!"
+          logger.info "User #{user} created"
+        end
+        on.invalid_user {|user| @user = user; render "new" }
+      end
+    end
 
-The listener is immutable, #strict, #lax, and #hark all return new listeners
+Then a requirement comes in to email users on succesful creation, there's an UserEmailer that responds
+to the same protocol.  Also, the UX team want to log invalid users.
 
-Here's an example from a rails controller
+There's quite a lot going on now, we can tie it up as follows:
 
     def create
-      SignupNewUser.new params, hark(create_response, SignupEmailer.new)
+      response = hark(ui_response, UserEmailer.new, ux_team_response)
+      user_creator.call user_params, response
     end
 
-    # response block style
-    def create_response
+    # UserEmailer responds to #created_user(user)
+
+    def ui_response
       hark do |on|
-        on.signed_up {|user| redirect_to user, notice: "Signed up!" }
-        on.invalid {|user| render "new", user: user }
+        on.created_user {|user| redirect_to user, notice: "Welome!" }
+        on.invalid_user {|user| @user = user; render "new" }
+      end
+    end
+
+    def ux_team_response
+      hark(:invalid_user) {|user| logger.info("User invalid: #{user}") }
+    end
+
+If some of the response code gets hairy, we can easily swap out hark ad-hoc objects for 'proper' ones.
+For example, the UI response might get a bit hairy, and so we make a new object.
+
+    def create
+      response = hark(UiResponse.new(self), UserEmailer.new, ux_team_response)
+      user_creator.call user_params, response
+    end
+
+    class UiResponse < SimpleDelegator
+      def created_user user
+        if request.format.json?
+          # ...
+        else
+          # ...
+        end
+      end
+
+      def invalid_user user
+        # ...
+      end
+    end
+
+Note that throughout this process we didn't have to modify the UserCreator code, even when we transitioned
+to/from hark for different repsonses/styles.
+
+### Testing your listeners
+
+Don't pay any attention to hark when you're testing, hark is just a utility to create listeners, and so what
+you should be testing is the protocol.
+
+For example the service object tests will test functionality that pertains to the actual creation of the user,
+and will test that the correct message is sent to the response in those circumstances.  Whereas the controller tests
+will mock out the service object, and test what happens when the service object sends the messages to the response as
+dictated by the protocol.
+
+    describe UserCreator do
+      let(:service) { described_class.new }
+
+      describe "#call params, response" do
+        subject { service.call params, response }
+
+        let(:response) { double }
+
+        context "when the user succesfully saves"
+          let(:params) { {name: "created user", # and other successful user params }
+
+          it "sends #created_user to the response with the created user" do
+            response.should_receive(:created_user) do |user|
+              user.name.should == "created user"
+            end
+            subject
+          end
+        end
+
+        context "when the user succesfully saves"
+          let(:params) { {name: "invalid user", # and invalid user params }
+
+          it "sends #invalid_user to the response with the created user" do
+            response.should_receive(:invalid_user) do |user|
+              # test that the object passed is the invalid user
+            end
+            subject
+          end
+        end
       end
     end
 
+    describe NewUserController do
+      before { controller.stub(user_creator: user_creator) } # or some other sensible way of injecting a fake user_creator
+
+      let(:user_creator) { double "User creator" }
+      let(:user) { double "A user" }
+
+      context "when the user_creator is succesful" do
+        before do
+          user_creator.stub :call do |params, response|
+            response.created_user(user)
+          end
+        end
+
+        it "should redirect to the user"
+
+        it "should email the user"
+
+        it "should log the creation of the user"
+      end
+
+      context "when the user_creator says the params are invalid" do
+        before do
+          user_creator.stub :call do |params, response|
+            response.invalid_user(user)
+          end
+        end
+
+        it "should render new with the user"
+
+        it "should log something for the UX team"
+      end
+    end
+
+
 ## Contributing
 
 1. Fork it

data/hark.gemspec

@@ -21,4 +21,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+
+  if RUBY_VERSION > "1.9"
+    spec.add_development_dependency "coveralls"
+  end
 end

data/lib/hark/core_ext.rb

@@ -2,4 +2,13 @@ module Kernel
   def hark *args, &block
     Hark.from *args, &block
   end
+
+  def to_hark *args, &block
+    hark self, *args, &block
+  end
+
+  def hearken method, *args, &block
+    listener = (block.arity == 1) ? hark(&block) : block.call
+    send method, *args, listener
+  end
 end

data/lib/hark/dispatcher.rb

@@ -12,11 +12,7 @@ module Hark
     #
     def self.from(*args, &block)
       if block
-        if args.last.is_a?(Symbol)
-          args << {args.pop => block}
-        elsif args.empty?
-          args << block
-        end
+        args << (args.last.is_a?(Symbol) ? {args.pop => block} : block)
       end
 
       new args.map{|o| to_handler(o) }.flatten.freeze

data/lib/hark/version.rb

@@ -1,3 +1,3 @@
 module Hark
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/hark_spec.rb

@@ -91,21 +91,43 @@ describe Hark do
     it_should_behave_like "a success/failure hark listener"
   end
 
-  describe "hark object" do
+  describe "#hark(object)" do
     let(:listener) { hark PlainListener.new(transcript) }
 
     it_should_behave_like "a success/failure hark listener"
   end
 
+  describe "object.to_hark" do
+    let(:listener) { PlainListener.new(transcript).to_hark }
+
+    it_should_behave_like "a success/failure hark listener"
+  end
+
   describe "combine two listeners together" do
     let(:logger) { hark(:signup_user) {|user| transcript << "User #{user} signed up" } }
     let(:emailer) { hark(:signup_user) {|user| transcript << "Emailed #{user}" } }
 
-    let(:listener) { logger.hark(emailer) }
+    shared_examples_for "combined listeners" do
+      before { listener.signup_user("Fred") }
 
-    before { listener.signup_user("Fred") }
+      it { transcript.should == ["User Fred signed up", "Emailed Fred"] }
+    end
 
-    it { transcript.should == ["User Fred signed up", "Emailed Fred"] }
+    it_behaves_like "combined listeners" do
+      let(:listener) { logger.hark(emailer) }
+    end
+
+    it_behaves_like "combined listeners" do
+      let(:listener) { hark(logger, emailer) }
+    end
+
+    it_behaves_like "combined listeners" do
+      let(:listener) do
+        hark logger do |on|
+          on.signup_user {|user| transcript << "Emailed #{user}" }
+        end
+      end
+    end
   end
 
   describe "lax/strict is preserved on #hark" do
@@ -119,4 +141,38 @@ describe Hark do
     it { expect{ listener.foo }.to_not raise_error }
     it { listener.foo.should == [false] }
   end
+
+  describe "#hearken :method" do
+    let(:object) do
+      Object.new.tap do |obj|
+        class << obj
+          def foo arg1, arg2, listener
+            listener.foo(arg1)
+            listener.bar(arg2)
+          end
+        end
+      end
+    end
+
+    context "with 1 arity block" do
+      it "sends :method with an ad-hoc listener created from the block" do
+        object.hearken :foo, "ONE", "TWO" do |on|
+          on.foo {|a| transcript << [:foo, a] }
+          on.bar {|a| transcript << [:bar, a] }
+        end
+        transcript.should == [[:foo, "ONE"], [:bar, "TWO"]]
+      end
+    end
+
+    context "with 0 arity block" do
+      it "sends :method with listener created by yielding to the block" do
+        foo = hark(:foo) {|a| transcript << [:foo, a] }
+
+        object.hearken :foo, "ONE", "TWO" do
+          hark(foo, :bar) {|a| transcript << [:bar, a] }
+        end
+        transcript.should == [[:foo, "ONE"], [:bar, "TWO"]]
+      end
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,3 +1,9 @@
 $LOAD_PATH.unshift File.dirname('../lib')
 
 require 'rspec'
+
+begin
+  require 'coveralls'
+  Coveralls.wear!
+rescue LoadError
+end

metadata

@@ -1,78 +1,83 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ianwhite-hark
-version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 3
-  version: 0.0.3
+version: !ruby/object:Gem::Version
+  version: 0.0.4
 platform: ruby
-authors: 
+authors:
 - Ian White
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-11-14 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bundler
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        hash: 9
-        segments: 
-        - 1
-        - 3
-        version: "1.3"
-  prerelease: false
+      - !ruby/object:Gem::Version
+        version: '1.3'
   type: :development
-  requirement: *id001
-- !ruby/object:Gem::Dependency 
-  name: rake
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
   prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  requirement: *id002
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
   name: rspec
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+  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'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  requirement: *id003
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Create ad-hoc listener objects with impunity
-email: 
+email:
 - ian.w.white@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
+- .coveralls.yml
 - .gitignore
 - .travis.yml
 - Gemfile
+- History.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -86,38 +91,30 @@ files:
 - spec/hark_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/ianwhite/hark
-licenses: 
+licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.0.6
 signing_key: 
-specification_version: 3
-summary: Hark is a gem that enables  writing code in a "hexagonal architecture" or "tell don't ask" style
-test_files: 
+specification_version: 4
+summary: Hark is a gem that enables  writing code in a "hexagonal architecture" or
+  "tell don't ask" style
+test_files:
 - spec/hark_spec.rb
 - spec/spec_helper.rb