informator 0.1.0 → 1.0.0

data/lib/informator/publisher.rb

@@ -0,0 +1,103 @@
+# encoding: utf-8
+
+module Informator
+
+  # The base class for publishers
+  #
+  # @api public
+  #
+  class Publisher
+
+    include Comparable
+
+    # @!attribute [r] subscribers
+    #
+    # @return [Array<Informator::Subscriber>] The list of subscribers
+    #
+    attr_reader :subscribers
+
+    # @!attribute [r] attributes
+    #
+    # @return [Hash] Initialized attributes
+    #
+    attr_reader :attributes
+
+    # @!scope class
+    # @!method new(attributes = {})
+    # Creates the immutable publisher
+    #
+    # @param [Hash] attributes
+    #
+    # @return [Informator::Publisher]
+
+    # @private
+    def initialize(attributes = {})
+      @attributes  = Hash[attributes]
+      @subscribers = block_given? ? yield : Set.new
+      IceNine.deep_freeze(self)
+    end
+
+    # Returns a new publisher with the listener being added to its subscribers
+    #
+    # @param [Object] listener
+    # @param [Symbol, String] callback
+    #   The name of the listener method, that should receive events
+    #   The method is expected to accept one argument (for the event)
+    #
+    # @return (see .new)
+    #
+    def subscribe(listener, callback)
+      subscriber = Subscriber.new(listener, callback)
+      self.class.new(attributes) { subscribers | [subscriber] }
+    end
+
+    # Creates the immutable event and sends it to all subscribers
+    #
+    # @param [#to_sym] name The name of the event
+    # @param [Hash] arguments The arguments of the event
+    #
+    # @return [Informator::Event] The published event
+    #
+    def publish(name, arguments)
+      event = Event.new(self, name, arguments)
+      subscribers.each { |subscriber| subscriber.notify(event) }
+      event
+    end
+
+    # Does the same as [#publish], and then throws the `:published` exception,
+    # that carries an event
+    #
+    # @param (see #publish)
+    #
+    # @return (see #publish)
+    #
+    # @raise [UncaughtThrowError] The exception to be catched later
+    #
+    def publish!(name, arguments)
+      event = publish(name, arguments)
+      throw :published, event
+    end
+
+    # Treats two publishers of the same class with the same attributes as equal
+    #
+    # @param [Object] other
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      other.instance_of?(self.class) && attributes.eql?(other.attributes)
+    end
+    alias_method :eql?, :==
+
+    # Human-readable description of the publisher
+    #
+    # @return [String]
+    #
+    def inspect
+      "#<#{self.class} @attributes=#{attributes}>"
+    end
+    alias_method :to_s, :inspect
+
+  end # class Publisher
+
+end # module Informator

data/lib/informator/rspec.rb

@@ -0,0 +1,3 @@
+
+# This file added to allow `require "informator/rspec"`
+require_relative "../rspec/shared"

data/lib/informator/subscriber.rb

@@ -2,64 +2,50 @@
 
 module Informator
 
-  # Class Subscriber wraps the [#object] along with its [#callback] method
-  # to receive event notifications.
-  #
-  # @example The method [#notify] sends event to the [#object] via [#callback]
-  #   object     = Struct.new(:event).new
-  #   subscriber = Subscriber.new object, :event=
-  #   subscriber.frozen? # => true
-  #
-  #   event  = Informator::Event.new :success
-  #   # => #<Event @type=:success @attributes={} @messages=[]>
-  #
-  #   subscriber.notify event
-  #   object.event
-  #   # => #<Event @type=:success @attributes={} @messages=[]>
+  # Describes a subscriber for publisher's notifications
   #
   # @api private
   #
   class Subscriber
 
-    include Equalizer.new(:object, :callback)
+    include Equalizer.new(:listener, :callback)
 
-    # @!attribute [r] object
+    # @!attribute [r] listener
     #
-    # @return [Object] the object to send events to
+    # @return [Object] The listener to send events to
     #
-    attr_reader :object
+    attr_reader :listener
 
     # @!attribute [r] callback
     #
-    # @return [Symbol] the name of the object methods to listen to events
+    # @return [Symbol] The name of the listener's method that receives events
     #
     attr_reader :callback
 
     # @!scope class
-    # @!method new(object, callback)
-    # Builds the subscriber for given object and callback
+    # @!method new(listener, callback)
+    # Builds the subscriber for given listener and callback
     #
-    # @param [Object] object
-    # @param [#to_sym] callback (:receive)
+    # @param [Object] listener
+    # @param [#to_sym] callback
     #
     # @return [Informator::Subscriber]
 
     # @private
-    def initialize(object, callback = :receive)
-      @object   = object
+    def initialize(listener, callback)
+      @listener = listener
       @callback = callback.to_sym
       IceNine.deep_freeze(self)
     end
 
-    # Sends the event to the subscriber object via its callback
+    # Sends the event to the subscriber listener via its callback
     #
     # @param [Informator::Event] event
     #
     # @return [Informator::Event] published event
     #
     def notify(event)
-      object.public_send callback, event
-
+      listener.public_send callback, event
       event
     end
 

data/lib/informator/version.rb

@@ -4,6 +4,6 @@ module Informator
 
   # The semantic version of the module.
   # @see http://semver.org/ Semantic versioning 2.0
-  VERSION = "0.1.0".freeze
+  VERSION = "1.0.0".freeze
 
 end # module Informator

data/lib/rspec/shared.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+shared_context :event_translations do
+
+  let(:__locale__) { defined?(locale) ? locale : :en }
+
+  around do |example|
+    old, I18n.locale = I18n.locale, __locale__
+    example.run
+    I18n.locale = old
+  end
+
+end # shared context
+
+# @example
+#   it_behaves_like :publishing_event do
+#
+#     # required settings for the specification
+#     subject { MyPublisher.new(attributes).subscribe(listener, callback).call }
+#     let(:listener) { double callback => nil } # required
+#     let(:callback) { "foo"     }              # required
+#
+#     # optional settings
+#     let(:event) { Event.new publisher, :success, exclamation: "Wow" }
+#     let(:event_name)       { :success               } # The name of the event
+#     let(:event_attributes) { { exclamation: "Wow" } } # The attributes for the event
+#     let(:locale)           { :en                    } # :en by default
+#     let(:event_message)    { "Wow, success!"        } # The message
+#
+#   end
+#
+shared_examples :publishing_event do
+
+  include_context :event_translations
+
+  before do
+    fail SyntaxError.new "subject should be defined"  unless defined? subject
+    fail SyntaxError.new "listener should be defined" unless defined? listener
+    fail SyntaxError.new "callback should be defined" unless defined? callback
+  end
+
+  it "[publishes event]" do
+    expect(listener).to receive(callback) do |received|
+      if defined? event
+        expect(received).to eql(event), <<-REPORT.gsub(/ *\|/, "")
+          |
+          |#{listener}##{callback} should have received the event:
+          |
+          |  expected: #{event.inspect}
+          |       got: #{received.inspect}
+        REPORT
+      else
+        expect(received)
+          .to be_kind_of(Informator::Event), <<-REPORT.gsub(/ *\|/, "")
+            |
+            |#{listener}##{callback} should have received an event.
+            |
+            |  expected: instance of Informator::Event subclass
+            |       got: #{received.inspect}
+          REPORT
+
+        if defined? event_name
+          expect(received.name)
+            .to eql(event_name), <<-REPORT.gsub(/ *\|/, "")
+              |
+              |#{listener}##{callback} should have received an event with the name:
+              |
+              |  expected: #{event_name}
+              |       got: #{received.name}
+              |from event: #{received.inspect}
+            REPORT
+        end
+
+        if defined? event_attributes
+          expect(received.attributes)
+            .to eql(event_attributes), <<-REPORT.gsub(/ *\|/, "")
+              |
+              |#{listener}##{callback} should have received an event with the attributes:
+              |
+              |  expected: #{event_attributes}
+              |       got: #{received.attributes}
+              |from event: #{received.inspect}
+            REPORT
+        end
+      end
+
+      if defined? event_message
+        expect(received.message)
+          .to eql(event_message), <<-REPORT.gsub(/ *\|/, "")
+            |
+            |Language: #{__locale__.to_s.upcase}
+            |#{listener}##{callback} should have received an event with the message:
+            |
+            |  expected: #{event_message}
+            |       got: #{received.message}
+            |from event: #{received.inspect}
+          REPORT
+      end
+    end
+
+    subject
+  end
+
+end # shared examples

data/spec/integration/en.yml

@@ -0,0 +1,6 @@
+---
+en:
+  informator:
+    informator/foo:
+      success: "publisher said: %{exclamation}!"
+      error: "publisher said: %{exclamation}!"

data/spec/integration/fr.yml

@@ -0,0 +1,6 @@
+---
+fr:
+  informator:
+    informator/foo:
+      success: "éditeur dit: %{exclamation}!"
+      error: "éditeur dit: %{exclamation}!"

data/spec/integration/i18n.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+shared_context :preloaded_translations do
+
+  around do |example|
+
+    load_path = Dir[File.expand_path "../*.yml", __FILE__]
+
+    old_locale, I18n.locale = I18n.locale, :en
+    old_path, I18n.load_path = I18n.load_path, load_path
+    I18n.backend.load_translations
+
+    example.run
+
+    I18n.locale    = old_locale
+    I18n.load_path = old_path
+    I18n.backend.reload!
+
+  end
+
+end # shared context

data/spec/integration/rspec_spec.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+require "informator/rspec"
+require "timecop"
+require_relative "i18n"
+
+describe "shared examples" do
+
+  include_context :preloaded_translations
+
+  before do
+    class Informator::Foo < Informator::Publisher
+      def call
+        if attributes[:exclamation] == "Wow"
+          publish :success, attributes
+        else
+          publish :error, attributes
+        end
+      end
+    end
+    Timecop.freeze
+  end
+
+  let(:lucky)    { Informator::Foo.new exclamation: "Wow" }
+  let(:unlucky)  { Informator::Foo.new exclamation: "OMG" }
+
+  let(:listener) { double callback => nil, freeze: nil }
+  let(:callback) { :call }
+
+  it_behaves_like :publishing_event do
+    subject { lucky.subscribe(listener, callback).call }
+
+    let(:event) { Informator::Event.new lucky, :success, exclamation: "Wow" }
+    let(:event_message) { "publisher said: Wow!" }
+  end
+
+  it_behaves_like :publishing_event do
+    subject { unlucky.subscribe(listener, callback).call }
+    let(:locale) { :fr }
+
+    let(:event_name)       { :error                 }
+    let(:event_attributes) { { exclamation: "OMG" } }
+    let(:event_message)    { "éditeur dit: OMG!"    }
+  end
+
+  after do
+    Timecop.return
+    Informator.send :remove_const, :Foo
+  end
+
+end # describe shared examples

data/spec/unit/informator/event_spec.rb

@@ -1,81 +1,135 @@
 # encoding: utf-8
 
+require "timecop"
+
 describe Informator::Event do
 
-  subject(:event) { described_class.new type, :foo, [:bar], baz: :qux }
+  let!(:pub_class) { Informator::Foo = Class.new                     }
+  let(:publisher)  { pub_class.new                                   }
+  let(:name)       { "success"                                       }
+  let(:attributes) { { foo: :FOO }                                   }
+  let(:event)      { described_class.new publisher, name, attributes }
 
-  let(:type) { "success" }
+  before { Timecop.freeze }
+  after  { Timecop.return }
 
   describe ".new" do
 
-    it { is_expected.to be_frozen }
-
-  end # describe .new
-
-  describe ".[]" do
+    subject { event }
 
-    before { allow(described_class).to receive(:new) }
+    it { is_expected.to be_frozen }
 
-    it "builds the event" do
-      expect(described_class).to receive(:new).with(:foo, :bar, :baz)
-      described_class[:foo, :bar, :baz]
+    it "doesn't freeze attributes" do
+      expect { subject }.not_to change { attributes.frozen? }
     end
 
   end # describe .new
 
-  describe "#type" do
+  describe "#publisher" do
+
+    subject { event.publisher }
+
+    it { is_expected.to eql publisher }
+    it { is_expected.to be_frozen     }
 
-    subject { event.type }
-    it { is_expected.to eql type.to_sym }
+  end # describe #publisher
 
-  end # describe #type
+  describe "#name" do
 
-  describe "#messages" do
+    subject { event.name }
 
-    subject { event.messages }
-    it { is_expected.to eql %w(foo bar) }
+    it { is_expected.to eql name.to_sym }
 
-  end # describe #messages
+  end # describe #name
 
   describe "#attributes" do
 
     subject { event.attributes }
-    it { is_expected.to eq(baz: :qux) }
+
+    it { is_expected.to eql attributes }
+    it { is_expected.to be_frozen      }
 
   end # describe #attributes
 
+  describe "#time" do
+
+    subject { event.time }
+
+    it "returns the time of event" do
+      expect(subject).to eql Time.now
+    end
+
+  end # describe #time
+
+  describe "#message" do
+
+    subject { event.message }
+
+    it do
+      is_expected
+        .to eql "translation missing: en.informator.informator/foo.success"
+    end
+
+    it "sends event attributes to translator" do
+      expect(I18n).to receive(:translate) do |_, opts|
+        expect(opts.merge(attributes)).to eql opts
+      end
+      subject
+    end
+
+    it { is_expected.to be_frozen }
+
+  end # describe #message
+
   describe "#==" do
 
     subject { event == other }
 
-    context "to event with the same type and attributes" do
+    context "with the same publisher, times, names and attributes" do
 
-      let(:other) { Class.new(described_class).new type, baz: :qux }
+      let(:other) { described_class.new publisher, name, attributes }
       it { is_expected.to eql true }
 
     end # context
 
-    context "to event with another type" do
+    context "with different publishers" do
+
+      let(:new_publisher) { Informator::Publisher.new }
 
-      let(:other) { described_class.new :error, baz: :qux }
+      let(:other) { described_class.new new_publisher, name, attributes }
       it { is_expected.to eql false }
 
     end # context
 
-    context "to event with other attributes" do
+    context "with different times" do
+
+      let!(:event) { described_class.new publisher, name, attributes }
+      let!(:other) do
+        new_time = Time.now + 1
+        Timecop.travel(new_time)
+        described_class.new publisher, name, attributes
+      end
 
-      let(:other) { described_class.new :success, baz: "qux" }
       it { is_expected.to eql false }
 
     end # context
 
-    context "to non-event" do
+    context "with different names" do
 
-      let(:other) { :foo }
+      let(:other) { described_class.new publisher, "other", attributes }
+      it { is_expected.to eql false }
+
+    end # context
+
+    context "with different attributes" do
+
+      let(:other) { described_class.new publisher, "other" }
       it { is_expected.to eql false }
 
     end # context
 
   end # describe #==
 
+  after { Informator.send :remove_const, :Foo }
+
 end # describe Informator::Event