heed 0.0.8 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9aa08585301fcc08e8968c5773f0e7c4ecadc65d
-  data.tar.gz: 3f0cea242cd9ac55909ed9b67c6bb2be83c82a2e
+  metadata.gz: 1eee3efa688c2c5129607edf8cfa0f259921556d
+  data.tar.gz: 6af68b66b4511904cb27a555759ffa12295579df
 SHA512:
-  metadata.gz: b2a21bc055d7676ea2c7a658ce6d58e2c5d77830653e47338a794d4046f68483dcd7116bb209bffe886fb51d471a0235bee393aeeab2420ab83f68f74025071b
-  data.tar.gz: d6aaf0eff296699a569f32536a8c3dcf490689519f78d926cad5ba217a803dac3f2adf34fa7ef38a3a96aef7fc2a605890ff32f50bfba5a43d5db95bf0843a03
+  metadata.gz: cae07b49dc966fcdb17f1a0df686b79d3ed44a2a867802559bd035170f5f4218dd96ed0b2a8d82a94ca6e2ebbaf8254830b8469a51671b8c93d7528b68f957dd
+  data.tar.gz: 1873db35c58e1425834ec2d37a1d16c383874eec96420a9ad060be25f16b95d83ad54ca590ecaa0e8ef60f71d9eabf53d948feef5bcbc7b7d1e4686d5689f3ee

data/History.md

@@ -1,5 +1,9 @@
 # History
 
+## 0.1.0
+
+* Hark becomes Heed
+
 ## 0.0.8
 
 * #hearken becomes #heed, with more functional semantics

data/README.md

@@ -1,18 +1,18 @@
-# Hark
+# `heed` (and `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)
+[![Gem Version](https://badge.fury.io/rb/heed.png)](https://rubygems.org/gems/heed)
+[![Build Status](https://travis-ci.org/ianwhite/heed.png)](https://travis-ci.org/ianwhite/heed)
+[![Dependency Status](https://gemnasium.com/ianwhite/heed.png)](https://gemnasium.com/ianwhite/heed)
+[![Code Climate](https://codeclimate.com/github/ianwhite/heed.png)](https://codeclimate.com/github/ianwhite/heed)
+[![Coverage Status](https://coveralls.io/repos/ianwhite/heed/badge.png)](https://coveralls.io/r/ianwhite/heed)
 
-Create a ad-hoc listeners with hark.
+Create and use ad-hoc listeners with hark and heed.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'ianwhite-hark', :require => 'hark'
+    gem 'heed'
 
 And then execute:
 
@@ -20,12 +20,12 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install ianwhite-hark
+    $ gem install heed
 
 ## 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
+**heed** enables you to use 'listener' objects very easily.  It's for programming in the *hexagonal* or *tell, don't ask* style.
+The consumers of heed listeners don't know anything about heed.  Because heed 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
@@ -61,14 +61,14 @@ Or, a 'respond_to' style block
 
 ### Strict & lax listeners
 
-By default, hark listeners are 'strict', they will only respond to the methods defined on them.
+By default, heed 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>
+    # => NoMethodError: undefined method `bar' for #<Heed::StrictListener:0x007fc91a03e568>
 
     listener = listener.lax
     listener.bar
@@ -102,7 +102,7 @@ Combine with any object that support the same protocol
 Turn any object into a listener, adding new methods as we go
 
     hark UserLogger.new do |on|
-      on.created {|user| Emailer.send_welcom_email(user) }
+      on.created {|user| Emailer.send_welcome_email(user) }
     end
 
 Now, when listener is sent #created, all create handlers are called.
@@ -125,7 +125,8 @@ You may use #heed to create an ad-hoc listener using a passed block as follows
     end
 
 If you want to combine listeners with an ad-hoc block, you may pass a 0-arity block that is
-yielded as the listener
+yielded as the listener.  This means you can use the block to wire up listeners, adding
+extra ones that have the caller's binding (useful in controllers for example)
 
     heed seller, :request_valuation, item do
       hark valuation_notifier do |on|
@@ -136,8 +137,8 @@ yielded as the listener
 
 ### 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.
+Using the return value of a listener is not encouraged.  Heed is designed for a *tell, don't ask*
+style of coding.  That said the return value of a heed 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' } }
@@ -149,14 +150,14 @@ style of coding.  That said the return value of a hark listener is an array of i
 
 ### Immutable
 
-Hark listeners are immutable and `#lax`, `#strict`, and `#hark` all return new listeners.
+Heed listeners are immutable and `#lax`, `#strict`, and `#heed` all return new listeners.
 
 ## Rationale
 
 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.
 
-The idea behind **hark** is that there should be little ceremony involved in the listener/response mechanics, and
+The idea behind **heed** 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.
 
@@ -176,13 +177,13 @@ The UserCreator object's main method will have some code as follows:
       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:
+Let's say a controller is calling this, and you are using heed.  In the beginning you would do something like this:
 
     def create
-      user_creator.call(user_params, hark do |on|
+      heed user_creator, :create_user, user_params do |on|
         on.created_user {|user| redirect_to user, notice: "Welome!" }
         on.invalid_user {|user| @user = user; render "new" }
-      end)
+      end
     end
 
 This keeps the controller's handling of the user creation nicely separate from the saving of the user creator.
@@ -190,7 +191,7 @@ This keeps the controller's handling of the user creation nicely separate from t
 Then, a requirement comes in to log the creation of users.  The first attempt might be this:
 
     def create
-      user_creator.call(user_params, hark do |on|
+      heed user_creator, :create_user, user_params do |on|
         on.created_user do |user|
           redirect_to user, notice: "Welome!"
           logger.info "User #{user} created"
@@ -205,8 +206,9 @@ to the same protocol.  Also, the UX team want to log invalid users.
 There's quite a lot going on now, we can tie it up as follows:
 
     def create
-      response = hark(ui_response, UserEmailer.new, ux_team_response)
-      user_creator.call user_params, response
+      heed user_creator, :create_user, user_params do
+        hark ui_response, UserEmailer.new, ux_team_response
+      end
     end
 
     # UserEmailer responds to #created_user(user)
@@ -222,12 +224,13 @@ There's quite a lot going on now, we can tie it up as follows:
       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.
+If some of the response code gets hairy, we can easily swap out heed 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
+      heed user_creator, :create_user, user_params do
+        hark UiResponse.new(self), UserEmailer.new, ux_team_response
+      end
     end
 
     class UiResponse < SimpleDelegator
@@ -245,11 +248,11 @@ For example, the UI response might get a bit hairy, and so we make a new object.
     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.
+to/from heed/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
+Don't pay any attention to heed when you're testing, heed 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,
@@ -322,6 +325,8 @@ dictated by the protocol.
       end
     end
 
+    Note that in the above tests, there is *no mention of hark or heed*.  This ensures a smooth transition to 'full blown'
+    response objects should the need occur.
 
 ## Contributing
 

data/{hark.gemspec → heed.gemspec}

@@ -1,16 +1,16 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'hark/version'
+require 'heed/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "heed"
-  spec.version       = Hark::VERSION
+  spec.version       = Heed::VERSION
   spec.authors       = ["Ian White"]
   spec.email         = ["ian.w.white@gmail.com"]
-  spec.description   = %q{Create ad-hoc listener objects with impunity}
-  spec.summary       = %q{Hark is a gem that enables  writing code in a "hexagonal architecture" or "tell don't ask" style}
-  spec.homepage      = "http://github.com/ianwhite/hark"
+  spec.description   = %q{Create and use ad-hoc listeners with hark and heed}
+  spec.summary       = %q{Heed is a gem that enables  writing code in a "hexagonal architecture" or "tell don't ask" style}
+  spec.homepage      = "http://github.com/ianwhite/heed"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/lib/heed.rb

@@ -0,0 +1,11 @@
+require "heed/version"
+require "heed/ad_hoc"
+require "heed/dispatcher"
+require "heed/listener"
+require "heed/core_ext"
+
+module Heed
+  def self.listener(*args, &block)
+    Listener.new(*args, &block)
+  end
+end

data/lib/{hark → heed}/ad_hoc.rb

@@ -1,4 +1,4 @@
-module Hark
+module Heed
   # AdHoc is a tiny class to facilitate creating an ad-hoc object that from either a hash or proc.
   #
   # Eg. from a hash:

data/lib/{hark → heed}/core_ext.rb

@@ -1,10 +1,10 @@
 module Kernel
   def hark *args, &block
-    Hark.from *args, &block
+    Heed.listener *args, &block
   end
 
   def heed object, *args, &block
-    listener = (block.arity == 1) ? hark(&block) : block.call
+    listener = (block.arity == 1) ? Heed.listener(&block) : block.call
     object.send *args + [listener]
   end
 end

data/lib/{hark → heed}/dispatcher.rb

@@ -1,4 +1,4 @@
-module Hark
+module Heed
   class Dispatcher
     #  from(:success) do
     #    "success"

data/lib/{hark → heed}/listener.rb

@@ -1,4 +1,4 @@
-module Hark
+module Heed
   # A Listener holds a dispatcher, which it dispatches messages to
   #
   # A listener is by default a 'strict' listener, it will raise NoMethodError if

data/lib/heed/version.rb

@@ -0,0 +1,3 @@
+module Heed
+  VERSION = "0.1.0"
+end

data/spec/{hark_spec.rb → heed_spec.rb}

@@ -1,7 +1,7 @@
 require 'spec_helper'
-require 'hark'
+require 'heed'
 
-describe Hark do
+describe Heed do
   let(:transcript) { [] }
 
   class PlainListener < Struct.new(:transcript)
@@ -125,8 +125,8 @@ describe Hark do
   end
 
   describe "lax/strict is preserved on #hark" do
-    it { hark.lax.hark.should be_a Hark::LaxListener }
-    it { hark.strict.hark.should be_a Hark::StrictListener }
+    it { hark.lax.hark.should be_a Heed::LaxListener }
+    it { hark.strict.hark.should be_a Heed::StrictListener }
   end
 
   describe "when methods return falsy" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: heed
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.1.0
 platform: ruby
 authors:
 - Ian White
@@ -66,7 +66,7 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Create ad-hoc listener objects with impunity
+description: Create and use ad-hoc listeners with hark and heed
 email:
 - ian.w.white@gmail.com
 executables: []
@@ -81,16 +81,16 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- hark.gemspec
-- lib/hark.rb
-- lib/hark/ad_hoc.rb
-- lib/hark/core_ext.rb
-- lib/hark/dispatcher.rb
-- lib/hark/listener.rb
-- lib/hark/version.rb
-- spec/hark_spec.rb
+- heed.gemspec
+- lib/heed.rb
+- lib/heed/ad_hoc.rb
+- lib/heed/core_ext.rb
+- lib/heed/dispatcher.rb
+- lib/heed/listener.rb
+- lib/heed/version.rb
+- spec/heed_spec.rb
 - spec/spec_helper.rb
-homepage: http://github.com/ianwhite/hark
+homepage: http://github.com/ianwhite/heed
 licenses:
 - MIT
 metadata: {}
@@ -113,8 +113,8 @@ rubyforge_project:
 rubygems_version: 2.0.6
 signing_key: 
 specification_version: 4
-summary: Hark is a gem that enables  writing code in a "hexagonal architecture" or
+summary: Heed is a gem that enables  writing code in a "hexagonal architecture" or
   "tell don't ask" style
 test_files:
-- spec/hark_spec.rb
+- spec/heed_spec.rb
 - spec/spec_helper.rb

data/lib/hark.rb

@@ -1,11 +0,0 @@
-require "hark/version"
-require "hark/ad_hoc"
-require "hark/dispatcher"
-require "hark/listener"
-require "hark/core_ext"
-
-module Hark
-  def self.from(*args, &block)
-    Listener.new(*args, &block)
-  end
-end

data/lib/hark/version.rb

@@ -1,3 +0,0 @@
-module Hark
-  VERSION = "0.0.8"
-end