informator 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 53d7f784fa22bf7f691c99d5e59f054c0c0ba3fb
-  data.tar.gz: 37dcc4751f1433fdcfdc9fc5650f6776ec065100
+  metadata.gz: 0de58e03a57880d1061c5810a877e69086c0b71f
+  data.tar.gz: 022a5537c463a1c746a02153d039a87ed9c88b18
 SHA512:
-  metadata.gz: e22da1a142f55e6535b54db59652546cd750d23cfc237329eb7d3a11cb21b2ce6cfaffaab64563f941c91f0336f4f2af197a6bdf6702baf951646a2a7586b34d
-  data.tar.gz: 5463ec47db2b542e465f0bbc546068ee9a48dc9aca6e11c2f03c82c8e0a1be183ff912a0e47a6a69098873ffb6610668bb30e2200885b9581bb9777bd02e1ac7
+  metadata.gz: b9e8716e59f38f6a2a2e0bcad4238fcd6ea13ffd7dd6fc0ce67b76e7410200cc6dadcab8f99619c1cf4075b7bd99616a8e0b048209883eade6d1fe0f25b996b9
+  data.tar.gz: 88c7f671d6b646d0663aa285fccdb9f60ae7d2958ea5fedb288cd5f98b96b22b11cff1741e8eb3bbe0876c972f9948ef072618499f4c8858b72042ee21b478cc

data/.travis.yml

@@ -4,13 +4,19 @@ bundler_args: --without metrics
 cache:        bundler
 script:       bundle exec rake test:coverage:run
 rvm:
+  - '1.9.3'
+  - '2.0'
   - '2.1'
   - '2.2'
   - ruby-head
+  - rbx-2 --1.9
   - rbx-2 --2.1
+  - rbx-head
+  - jruby
   - jruby-9.0.0.0.pre1
   - jruby-head
 matrix:
   allow_failures:
     - rvm: ruby-head
+    - rvm: rbx-head
     - rvm: jruby-head

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## v1.0.0 2015-07-14
+
+The API has been rewritten to support immutability of all instances.
+
+## Added
+
+* `Informator::Publisher` base class for immutable publishers (nepalez).
+* `Informator::Event#publisher` method to check the source of the event (nepalez).
+* `Informator::Event#message` to provide human-readable description on the fly instead legacy `#messages` (nepalez).
+* `Informator::Event#time` for the time of event creation (nepalez).
+* All classes: `Publisher`, `Subscriber`, `Event` become comparable (nepalez).
+* Support for rubies 1.9.3+ (was 2.1+ only) (nepalez).
+
+## Changed
+
+* `Informator::Publisher#publish` publishes the event immediately (nepalez).
+* `Informator::Publisher#subscribe` returns a new publisher instead of mutating the existing one (nepalez).
+
+## Deleted
+
+* `Informator` legacy API (including the module doesn't supported any more) (nepalez).
+* `Informator::Publisher#memoize` (nepalez).
+* `Informator::Event#messages` (nepalez).
+
+## Internal
+
+* Drop internal `Informator::Reporter` class, because no memoization supported any longer (nepalez).
+* 100% mutant covered (nepalez).
+
+[Compare v0.1.0...v1.0.0](https://github.com/nepalez/informator/compare/v0.1.0...v1.0.0)
+
 ## v0.1.0 2015-07-12
 
 ### Changed (backward-incompatible)

data/README.md

@@ -15,82 +15,150 @@ Informator
 [travis]: https://travis-ci.org/nepalez/informator
 [inch]: https://inch-ci.org/github/nepalez/informator
 
-The [wisper]-inspired tiny implementation of publish/subscribe design pattern.
+The [wisper]-inspired micro-gem, that implements publish/subscribe design pattern in immutable style.
 
-The implementation differs from the original wisper's approach in the following aspects:
+**Notice a version `1.0` has been re-written from scratch to provide immutability. Its API has been changed.**
 
-* Unlike `Wisper::Publisher` that calls listener methods depending on the event, the `Informator` uses the same listener's callback for sending all events. Instead it wraps attributes to `Informator::Event` container and uses its as the argument for the callback.
+Motivation
+----------
 
-* The `Informator` has two separate methods - `#remember` and `#publish`. The first one is used to build and collect events, while the second one publishes all unpublished events at once (and clears the list of events to be published).
+The `informator` differs from `wisper` in the following aspects:
 
-* The `Informator` also defines `#publish!` method that is the same as `#publish` except for it throws the `:published`, that should be catched somewhere. This is just a shortcut for exiting from a use cases.
+* While `Wisper::Publisher#subscribe` mutates the state of the publisher, `Informator::Publisher` is immutable.
+  Its `#subscribe` method returns the new publisher instance to which a subscriber being added.
 
-* The `#publish` method returns the list of published events. The exception thrown by `#publish!` carries that list as well. This allows not only to publish them to listeners but to return them to caller. This is necessary to simplify chaining of service objects that includes the `Informator`.
+* The `Wisper::Publisher#publish` calls various listener methods depending on the published event.
+  The `Informator::Publisher#publish` uses the same listener's callback for all published events. It sends the `Invormator::Event` with info about the name, the attributes, and the publisher of the event.
 
-* The `Informator` has no global neither async subscribers. The gem's scope is narrower. Its main goal is to support service objects, that are either chained to each other, or publishes their results to decoupled listeners.
+* The `Informator::Publisher` defines `#publish!` method that is the same as `#publish`, except for it throws the `:published` exception.
+  This can be used to stop execution when some events occurs.
+
+* The `Informator` has no global neither async subscribers.
 
 [wisper]: https://github.com/krisleech/wisper
 
-Synopsis
---------
+API
+---
+
+The `Informator::Publisher` class describes immutable publishers with 6 instance methods:
 
-The `Informator` module API defines 4 instance methods:
+* `#initialize` that takes a hash of attributes.
+* `#attributes` that stores a hash of initialized attributes.
+* `#subscribers` that returns an array of subscribers.
+* `#subscribe` that returns a new immutable publisher with the same attributes and new subscriber being added.
+* `#publish` to create and publish an event to all `#subscribers`.
+* `#publish!` that calls `#publish` and then throws `:published` exception.
 
-* `#subscribe` to subscribe listeners for receiving events, published by the informator
-* `#remember` to build an event and keep it unpublished
-* `#publish` to publish all events keeped since last publishing
-* `#publish!` the same as `#publish`, except for it throws `:published` exception which carries a list of events
+The `Informator::Event` class describes immutable events with 5 instance methods:
 
-Except for the `Informator` the module defines public class `Informator::Event` for immutable events, that has 3 attributes:
+* `#publisher` for the source of the event.
+* `#time` for event creation time.
+* `#name` for symbolic name of the event.
+* `#attributes` for hash of attributes, carried by the event.
+* `#message` for the human-readable description of the event.
 
-* `#type` for symbolic type of the event
-* `#attributes` for hash of attributes, carried by the event
-* `#messages` for array of human-readable messages, describing the event
+Both publishers and events instances are comparable (respond to `==` and `eql?`).
 
-The event instance is build by the `#remember`, `#publish` or `#publish!` methods and is sent to listeners by either `#publish` or `#publish!`. When sending an event, the informator just calls the listeners callback, defined by `#subscribe` method, and gives it a corresponding event object as the only argument.
+Synopsis
+--------
+
+Define the custom publisher, inherited from the `Informator::Publisher` base class:
 
 ```ruby
 require "informator"
 
-class Listener
-  def receive(event)
-    puts "The listener received #{ event.type }: #{ event.messages }"
+class MyPublisher < Informator::Publisher
+  def call
+    if attributes[:luck]
+      publish :success, exclamation: "Wow"
+    else
+      publish :error, exclamation: "OMG"
+    end
   end
 end
+```
 
-listener = Listener.new
+Provide translations for events:
 
-class Service
-  include Informator
+```yaml
+# config/locales/fr.yml
+---
+fr:
+  informator:
+    my_publisher:
+      success: "éditeur dit: %{exclamation}, succès!"
+      error: "éditeur dit: faute, %{exclamation}!"
+```
 
-  def call
-    catch(:published) { do_some_staff }
-  end
+Provide a listener with a callback method:
 
-  def do_some_staff
-    # ...
-    remember :success, "for now all is fine", foo: :bar
-    #
-    publish! :error, "OMG!", bar: :baz
+```ruby
+class MyListener
+  def listen(event)
+    puts event
+    puts event.message
   end
 end
 
-service = Service.new
-service.subscribe listener, :receive
-result = service.call
-# The listener received success: ["for now all is fine"]
-# The listener received error: ["OMG!"]
-# => [
-#      #<Informator::Event @type=:success @attributes={ foo: :bar } @messages=["for now all is fine"]>,
-#      #<Informator::Event @type=:error @attributes={ bar: :baz } @messages=["OMG!"]>
-#    ]
+listener = MyListener.new
+```
+
+Subscribe the listener, and publish the event:
 
+```ruby
+MyPublisher
+  .new(luck: true)
+  .subscribe(listener, :listen)
+  .call
+# => #<Informator::Event
+#      @publisher=#<MyPublisher @attributes={ :luck => true }>,
+#      @name=:success,
+#      @attributes={ exclamation: "Wow" }
+#    >
+# => "éditeur dit: Wow, succès!"
+```
+
+```ruby
+MyPublisher
+  .new
+  .subscribe(listener, :listen)
+  .call
+# => #<Informator::Event
+#      @publisher=#<MyPublisher @attributes={}>,
+#      @name=:success,
+#      @attributes={ exclamation: "OMG" }
+#    >
+# => "éditeur dit: faute, OMG!"
 ```
 
-In the example above the `listener#receive` method is called twice with the first, and then with the second event as an argument.
+Testing
+-------
+
+Use `:publishing_event` shared examples (defined at `informator/rspec`) to specify publisher.
+
+```ruby
+require "informator/rspec"
 
-Then the `publish!` throws an exception that carries the list of messages.
-The `service#call` catches it and returns the array of events. With this feature it is possible not only to subscribe for the service's events but receive it directly, combining [both telling and asking](http://martinfowler.com/bliki/TellDontAsk.html) when necessary.
+describe MyPublisher do
+
+  let(:publisher) { described_class.new(attributes)     }
+  let(:listener)  { double callback => nil, freeze: nil }
+  let(:callback)  { :call                               }
+
+  subject { publisher.subscribe(listener, callback).call }
+
+  it_behaves_like :publishing_event do
+    # configurable context
+    let(:attributes) { { luck: true } }
+    let(:locale)     { :fr            } # :en by default
+
+    # configurable expectations (can be skipped)
+    let(:event_name)       { :success                    }
+    let(:event_attributes) { { exclamation: "Wow" }      }
+    let(:event_message)    { "éditeur dit: Wow, succès!" }
+  end
+end
+```
 
 Installation
 ------------
@@ -117,7 +185,7 @@ gem install informator
 Compatibility
 -------------
 
-Tested under rubies [compatible to MRI 2.1+](.travis.yml).
+Tested under rubies [compatible to MRI 1.9.3+](.travis.yml).
 
 Uses [RSpec] 3.0+ for testing and [hexx-suit] for dev/test tools collection.
 

data/Rakefile

@@ -24,6 +24,6 @@ task :mutant do
 end
 
 desc "Exhort all evils"
-task :mutant do
+task :exhort do
   system "bundle exec mutant -r informator --use rspec Informator*"
 end

data/config/metrics/metric_fu.yml

@@ -1,7 +1,7 @@
 ---
 folders: # The list of folders to be used by any metric.
-- lib
-- app
+- lib/informator.rb
+- lib/informator
 metrics: # The list of allowed metrics. The other metrics are disabled.
 - cane
 - churn

data/config/metrics/rubocop.yml

@@ -15,6 +15,10 @@ Lint/RescueException:
   Exclude:
     - '**/*_spec.rb'
 
+Metrics/LineLength:
+  Exclude:
+    - 'lib/rspec/*.rb'
+
 Style/AccessorMethodName:
   Exclude:
     - '**/*_spec.rb'

data/informator.gemspec

@@ -3,24 +3,27 @@ require "informator/version"
 
 Gem::Specification.new do |gem|
 
-  gem.name        = "informator"
-  gem.version     = Informator::VERSION.dup
-  gem.author      = "Andrew Kozin"
-  gem.email       = "andrew.kozin@gmail.com"
-  gem.homepage    = "https://github.com/nepalez/informator"
-  gem.summary     = "Implementation of publish/subscribe design pattern"
-  gem.license     = "MIT"
+  gem.name     = "informator"
+  gem.version  = Informator::VERSION.dup
+  gem.author   = "Andrew Kozin"
+  gem.email    = "andrew.kozin@gmail.com"
+  gem.homepage = "https://github.com/nepalez/informator"
+  gem.summary  = "Implementation of publish/subscribe design pattern"
+  gem.license  = "MIT"
 
   gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   gem.test_files       = Dir["spec/**/*.rb"]
   gem.extra_rdoc_files = Dir["README.md", "LICENSE"]
   gem.require_paths    = ["lib"]
 
-  gem.required_ruby_version = "~> 2.1"
+  gem.required_ruby_version = "~> 1.9.3"
 
-  gem.add_runtime_dependency "equalizer", "~> 0.0"
+  gem.add_runtime_dependency "i18n", "~> 0.7"
   gem.add_runtime_dependency "ice_nine", "~> 0.11"
+  gem.add_runtime_dependency "inflecto", "~> 0.0"
+  gem.add_runtime_dependency "equalizer", "~> 0.0"
 
   gem.add_development_dependency "hexx-rspec", "~> 0.5"
+  gem.add_development_dependency "timecop", "~> 0.7"
 
 end # Gem::Specification

data/lib/informator.rb

@@ -1,85 +1,15 @@
 # encoding: utf-8
 
+require "inflecto"
 require "ice_nine"
 require "equalizer"
 
 require_relative "informator/event"
 require_relative "informator/subscriber"
-require_relative "informator/reporter"
+require_relative "informator/publisher"
 
-# The module provides subscribe/publish/report features
+# The module implements immutable event publisher
 #
 module Informator
 
-  # Subscribes the listener for receiving events notifications via callback
-  #
-  # @param [Object] listener
-  #   The object to send events to
-  # @param [#to_sym] callback (:receive)
-  #   The name of the listener method to send events through
-  #
-  # @return [self] itself
-  #
-  def subscribe(listener, callback = :receive)
-    sub = Subscriber.new(listener, callback)
-    __subscribers__ << sub unless __subscribers__.include? sub
-
-    self
-  end
-
-  # @!method remember(type, messages, attributes)
-  # Builds and stores the event waiting for being published
-  #
-  # @param (see Informator::Event.new)
-  #
-  # @return [self] itself
-  #
-  def remember(*args)
-    __reporter__.remember(*args)
-
-    self
-  end
-
-  # @overload publish(type, messages, attributes)
-  #   Builds the event and then publishes all unpublished events
-  #
-  #   @param (see #remember)
-  #
-  # @overload publish
-  #   Publishes all unpublished events without adding a new one
-  #
-  # @return [Array<Informator::Event>] list of events having been published
-  #
-  def publish(*args)
-    remember(*args) if args.any?
-    __reporter__.notify __subscribers__
-  end
-
-  # The same as `publish` except for it throws `:published` afterwards
-  #
-  # @overload publish(type, messages, attributes)
-  #   Builds the event and then publishes all unpublished events
-  #
-  #   @param (see #remember)
-  #
-  # @overload publish
-  #   Publishes all unpublished events without adding a new one
-  #
-  # @raise [UncaughtThrowError, ArgumentError]
-  #   for `:published` events being carried
-  #
-  def publish!(*args)
-    throw :published, publish(*args)
-  end
-
-  private
-
-  def __reporter__
-    @__reporter__ ||= Reporter.new
-  end
-
-  def __subscribers__
-    @__subscribers__ ||= []
-  end
-
 end # module Informator

data/lib/informator/event.rb

@@ -2,63 +2,68 @@
 
 module Informator
 
-  # Class Event provides an immutable container for hash of some attributes, to
-  # which a type is attached. It also contains an array of human-readable
-  # messages describing the event.
+  # Describes events provided by publishers and being sent to their subscribers
   #
-  # The primary goal of events is folding attributes to be returned and/or sent
-  # between various objects into unified format.
-  #
-  # @example
-  #   event = Event[:success, "bingo!", foo: :bar]
-  #   # <Event @type=:success @messages=["bingo!"] @attributes={ :foo => :bar }>
-  #
-  #   event.frozen?
-  #   # => true
+  # @api public
   #
   class Event
 
-    include Equalizer.new(:type, :attributes)
+    include Equalizer.new(:publisher, :name, :attributes, :time)
+
+    # @!attribute [r] publisher
+    #
+    # @return [Informator::Publisher] The source of the event
+    #
+    attr_reader :publisher
 
-    # @!attribute [r] type
+    # @!attribute [r] name
     #
-    # @return [Symbol] the type of the event
+    # @return [Symbol] The name of the event
     #
-    attr_reader :type
+    attr_reader :name
 
     # @!attribute [r] attributes
     #
-    # @return [Hash] the event-specific attributes
+    # @return [Hash] The event-specific attributes
     #
     attr_reader :attributes
 
-    # @!attribute [r] messages
+    # @!attribute [r] time
     #
-    # @return [Array<String>] human-readable messages, describing the event
+    # @return [Time] The time the event was created
     #
-    attr_reader :messages
+    attr_reader :time
 
     # @!scope class
-    # @!method [](type, messages, attributes)
+    # @!method new(publisher, name, attributes)
     # Builds the event
     #
-    # @param [#to_sym] type
-    # @param [#to_s, Array<#to_s>] messages
+    # @param [Informator::Publisher] publisher
+    # @param [#to_sym] name
     # @param [Hash] attributes
     #
     # @return [Informator::Event]
-    def self.[](*args)
-      new(*args)
-    end
+    #
+    # @api private
 
     # @private
-    def initialize(type, *messages, **attributes)
-      @type       = type.to_sym
-      @messages   = messages.flatten.map(&:to_s)
-      @attributes = attributes
+    def initialize(publisher, name, attributes = {})
+      @publisher  = publisher
+      @name       = name.to_sym
+      @attributes = Hash[attributes]
+      @time       = Time.now
       IceNine.deep_freeze(self)
     end
 
+    # The human-readable message for the event
+    #
+    # @return [String]
+    #
+    def message
+      scope = [:informator, Inflecto.underscore(publisher.class)]
+      I18n.translate(name, attributes.merge(scope: scope)).freeze
+    end
+
   end # class Event
 
 end # module Informator