publican 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4904aa4b07d98990de7b90899ddd1929894a94a5
+  data.tar.gz: 615f70556ec38f6f0b8aa3384856b7e3ce6ae814
+SHA512:
+  metadata.gz: 1b4b09c539ffa17c823cf05b3d2be170d213e44d247760dc2ad135aa1be8e18e534a160deeb00fc73512bad4fb8b1e382c42fed0a67d3d83519e21f8a5641b35
+  data.tar.gz: cdec61a0f38a303b2d13c922ad35b49098f46107a779b190f0825cf990124f64708312d3d70868ccbf7f34c20e1d6ff5ec67062db743758a1aefaaac21ced1d2

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright 2015 Powershop New Zealand Limited, Roger Nesbitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# Publican
+
+A super-simple subscribe/publish library for your Ruby objects.
+
+Often you want to let your caller know what happened in your method call. You might return a symbol or custom-made
+Struct, and expect your caller to use a `case` statement to work out what happened.  The problem is that if you
+return a symbol the caller isn't expecting, or if the caller types in the symbol incorrectly, they might not handle
+it correctly.
+
+Another traditional way to handle this is to make an exception classes for every outcome.  That's pretty
+code-heavy, and it doesn't let you notify that multiple events happened either.
+
+Enter Publican.  Your method can publish events for its callers to listen to, with as much additional data as you
+like.  You can publish as many events as you like, as well as progress upgrades if it's long-running.  You can have
+multiple listeners.  You can also guarantee that your callers are listening for important events.
+
+## Using Publican
+
+Publican can just be `include`d into a class.  By doing so, it adds one public method, `on`, and two protected
+methods, `publish` and `publish!`.
+
+Here's an example of Publican in use.  An ideal use case is a service class:
+
+```ruby
+class SaveImage
+  include Publican
+
+  def call(image)
+  	if image.width < 300
+      publish!(:invalid_size, "Image must be at least 300 pixels wide")
+	  return
+	end
+
+	if image.height < 300
+	  image.resize!(height: 300)
+	  publish(:resized)
+	end
+
+	File.write("image_data/#{image.id}", image.data)
+	publish(:success)
+  end
+end
+```
+
+You'll notice that, instead of using return values, we're publishing events for our subscribers to hear.
+
+Here's some code that uses our Publican-powered service:
+
+```ruby
+SaveImage
+  .new
+  .on(:invalid_size) { |error| puts "Error: #{error}" }
+  .on(:resized)      { puts "The image was resized" }
+  .on(:success)      { puts "Everything was awesome!" }
+  .call(image)
+```
+
+Or maybe you'd like to use the same service in your Rails app?  No problem.
+
+```ruby
+class ImagesController < ApplicationController
+  def create
+    image = Image.find(params[:id])
+
+	SaveImage
+	  .new
+	  .on(:invalid_size) { |error| flash.alert = "Error: #{error}" }
+	  .on(:success)      { flash.notice = "Image successfully saved." }
+	  .call(image)
+
+	redirect_to root_path
+  end
+end
+```
+
+Note that the above example doesn't listen to the `:resized` event.  That's OK, because the event was published
+with the `publish` method, not `publish!`.  What's the difference?  See the next section.
+
+## publish vs publish!
+
+`publish` sends out your event and doesn't care whether anyone's listening.
+
+`publish!` ensures at least something is listening to the event, otherwise it'll raise
+a `Publican::NoListenersError` exception.  This is useful when you want to ensure some action is taken on the
+event occurring.
+
+## Licence and Copyright
+
+Copyright Powershop New Zealand Limited and Roger Nesbitt.  MIT licence.

data/lib/publican.rb

@@ -0,0 +1,25 @@
+module Publican
+  NoListenersError = Class.new(StandardError)
+
+  def on(*events, &block)
+    @_publican_listeners ||= {}
+
+    events.each do |event|
+      (@_publican_listeners[event] ||= []) << block
+    end
+
+    self
+  end
+
+  protected
+
+  def publish(event, *args)
+    listeners = @_publican_listeners && @_publican_listeners[event] || []
+    listeners.each { |listener| listener.call(*args) }
+    !listeners.empty?
+  end
+
+  def publish!(event, *args)
+    publish(event, *args) or raise NoListenersError, "No listeners are listening for event #{event}"
+  end
+end

data/publican.gemspec

@@ -0,0 +1,25 @@
+spec = Gem::Specification.new do |gem|
+  gem.name = 'publican'
+  gem.version = '1.0.0'
+  gem.summary = 'Simple subscribe/publish library for your Ruby objects'
+  gem.description = <<EOT
+Simple subscribe/publish library for your Ruby objects.  Instead of returning symbols or raising custom-made exceptions,
+let your callers know what happened in your method by publishing events.  You can choose whether these events can be
+ignored or whether the caller must listen to them.
+EOT
+  gem.has_rdoc = false
+  gem.author = "Roger Nesbitt"
+  gem.email = "roger@seriousorange.com"
+  gem.homepage = "http://github.com/mogest/publican"
+  gem.license = 'MIT'
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.add_development_dependency "rspec", "~> 3.0"
+  gem.add_development_dependency "rake", "~> 10.1"
+end

data/spec/publican_spec.rb

@@ -0,0 +1,84 @@
+require_relative '../lib/publican'
+
+RSpec.describe Publican do
+  class Sample
+    include Publican
+
+    def fire(event, *args)
+      publish(event, *args)
+    end
+
+    def fire!(event, *args)
+      publish!(event, *args)
+    end
+  end
+
+  let(:sample) { Sample.new }
+  let(:tracker) { Struct.new(:ok, :count).new(false, 0) }
+
+  def ok
+    tracker.ok = true
+    tracker.count += 1
+  end
+
+  def expect_ok
+    expect(tracker.ok).to be true
+  end
+
+  it "publishes an event with no arguments" do
+    sample.on(:a) { ok }
+    sample.fire(:a)
+    expect_ok
+  end
+
+  it "publishes an event with arguments" do
+    sample.on(:a) {|arg| ok if arg == "hello"}
+    sample.fire(:a, "hello")
+    expect_ok
+  end
+
+  it "publishes an event where multiple events were defined in the on block" do
+    sample.on(:a, :b) { ok }
+    sample.fire(:b)
+    expect_ok
+  end
+
+  it "does nothing if no events have been declared for a fired event" do
+    sample.on(:b) { raise }
+    sample.fire(:a)
+  end
+
+  it "handles multiple event definitions for a single event" do
+    sample.on(:a) { ok }
+    sample.on(:a) { ok }
+    sample.fire(:a)
+    expect(tracker.count).to eq 2
+  end
+
+  it "publishes an event, ensuring that there are listeners that are going to respond" do
+    sample.on(:a) { ok }
+    sample.fire!(:a)
+    expect_ok
+  end
+
+  it "raises if an event published using publish! has no listeners" do
+    expect { sample.fire!(:a) }.to raise_error(Publican::NoListenersError, "No listeners are listening for event a")
+  end
+
+  describe "#on" do
+    it "returns self for method chaining" do
+      expect(sample.on(:a) { ok }).to eq(sample)
+    end
+  end
+
+  describe "#publish" do
+    it "returns true when someone was listening" do
+      sample.on(:a) { }
+      expect(sample.fire(:a)).to be true
+    end
+
+    it "returns false when no-one was listening" do
+      expect(sample.fire(:a)).to be false
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: publican
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Roger Nesbitt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+description: |
+  Simple subscribe/publish library for your Ruby objects.  Instead of returning symbols or raising custom-made exceptions,
+  let your callers know what happened in your method by publishing events.  You can choose whether these events can be
+  ignored or whether the caller must listen to them.
+email: roger@seriousorange.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- LICENSE
+- README.md
+- lib/publican.rb
+- publican.gemspec
+- spec/publican_spec.rb
+homepage: http://github.com/mogest/publican
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Simple subscribe/publish library for your Ruby objects
+test_files:
+- spec/publican_spec.rb