emittance 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 000a59df54901139fde2f395a810c5f8a7baf8fd
-  data.tar.gz: c23462f13256fbc860bd5bf56ae244f49e09d2bf
+  metadata.gz: 480d65a814b24509517a96de13d0590117504f2d
+  data.tar.gz: 3c41c536af288cb32adc9cc00f2be9c0f8c7f15c
 SHA512:
-  metadata.gz: eafdc2ad4b68f42a04f075aefee0a3359bea3c765b58130d33571e9bf1e802b124d6151e6ac183922cce24b2d84ad780fb0b2c7f94ab93d2adb9245d4fb47cea
-  data.tar.gz: cdc43830eb7f439764fb8e284bcf6c87bf415c69d09f1195282c4297f018cbe1dacab6c52fc2e2aa1fdb5ae46f14b35d3889c156b0b5afd7cf78952042ca47e9
+  metadata.gz: d1946bdae18b76de6989aef2342a8ed87341a9d0475dfc1f5459598bdd804c69a97c789f6bbb37af270341d1a8cbda2d2249e0f1adada2a74066883fcf5b5729
+  data.tar.gz: 2b1735b0f9f56884ae2e9520b48df74b7540f26565c125a3272ec9165614cbebfa8b3ee2e36a64918b3c244589ff71a6100daeb667947abbe2fb25fc3fae3739

data/.gitignore

@@ -15,3 +15,6 @@ tmp/**
 .yardoc/**
 coverage/**
 doc/**
+
+# Other
+.rspec_status

data/.rubocop.yml

@@ -0,0 +1,12 @@
+# Metrics
+
+Metrics/LineLength:
+  Max: 120
+
+# Layout
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/MultilineOperationIndentation:
+  EnforcedStyle: indented

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.4.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at tyguillen@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Tyler Guillen
+
+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

@@ -1,9 +1,12 @@
 # Emittance
 
+[![Build Status](https://travis-ci.org/aastronautss/emittance.svg?branch=master)](https://travis-ci.org/aastronautss/emittance)
+[![Maintainability](https://api.codeclimate.com/v1/badges/b5900e32c5a385c96c95/maintainability)](https://codeclimate.com/github/aastronautss/emittance/maintainability)
+
 Emittance is a flexible eventing library that provides a clean interface for both emitting and capturing events. It follows the following workflow:
 
 1. Objects (and therefore, classes) can emit events, identified by a symbol.
-2. Events are objects that know who emitted them. Their
+2. Events are objects that know who emitted them, what time the event was emitted, and any additional information.
 3. Objects (and therefore, classes) can watch for events that get emitted.
 
 Per this pattern, objects are responsible for knowing what events they want to listen to. While this is pragmatically the same as a "push"-style message system (watchers don't need to go check a topic themselves), the semantics are a little different.
@@ -28,7 +31,92 @@ Or install it yourself as:
 
 ## Usage
 
-Coming soon!
+If you want a class and its instances to be able to emit events, have it extend `Emittance::Emitter`.
+
+```ruby
+class Foo
+  extend Emittance::Emitter
+end
+```
+
+Emitters can emit events like so:
+
+```ruby
+my_foo = Foo.new
+my_foo.emit :something_happened
+Foo.emit :something_else_happened # Classes who extended Emitter can also emit events!
+```
+
+As you can see, event types are identified by a symbol. More on that later. You can also pass in an optional payload, which can be any object:
+
+```ruby
+my_foo.emit :something_happened, "Here's a payload!"
+```
+
+The above examples are cool, but it's generally a better idea to have an object emit its own events:
+
+```ruby
+class Foo
+  extend Emittance::Emitter
+
+  def make_something_happen
+    emit :something_happened, "Here's a payload!"
+  end
+end
+
+my_foo = Foo.new
+my_foo.make_something_happen
+```
+
+What happens with these events? Watchers are objects that capture these event emissions. You can set up a watcher by including or extending `Emittance::Watcher`:
+
+```ruby
+class Bar
+  extend Emittance::Watcher
+end
+```
+
+To watch for these events, you can just call the `watch` method, which takes the symbol identifier and a block that serves as a callback:
+
+```ruby
+Bar.watch :something_happened do |event|
+  puts 'Something definitely happened!'
+  puts event.identifier.inspect
+  puts event.payload
+end
+
+my_foo.make_something_happen
+# prints:
+# Something definitely happened!
+# :something_happened
+# Here's a payload!
+```
+
+Note that the block gets passed an "event" object, which has some attributes. See the docs for more details.
+
+You can also make `watch` call a method:
+
+```ruby
+class Bar
+  extend Emittance::Watcher
+
+  def self.greet(event)
+    puts 'Hello, something must have happened!'
+    puts event.identifier.inspect
+    puts event.payload
+  end
+end
+
+Bar.watch :something_happened, :greet
+
+my_foo.make_something_happen
+# prints:
+# Hello, something must have happened!
+# :something_happened
+# Here's a payload!
+```
+
+Those are the basics--for more info, check the docs!
 
 ## Development
 
@@ -38,4 +126,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/aastronauts/emittance.
+Bug reports and pull requests are welcome on GitHub at https://github.com/aastronautss/emittance.

data/lib/emittance/action.rb

@@ -1,199 +1,192 @@
-##
-# There are certain classes (ergo objects) that represent an action taken by another object. This pattern goes like so:
-#
-#   class Foo
-#     def assign
-#       Assignment.new(self).call
-#     end
-#   end
-#
-#   class Assignment
-#     attr_reader :assignable
-#
-#     def initialize(assignable)
-#       @assignable = assignable
-#     end
-#
-#     def call
-#       do_stuff
-#     end
-#
-#     # ...
-#   end
-#
-# This pattern is useful for maintaining the single responsibility principle, delegating complex tasks to other objects
-# even when (in this particular case), it might be sensible for the +assign+ message to be sent to +Foo+. This has
-# numerous benefits, including the ability for actions like +Assignment+ to take a duck type.
-#
-# However, this can easily just become a proxy for the same antipattern it was made to solve. We might wind up with a
-# +#call+ method like the following:
-#
-#   class Assignment
-#     # ...
-#
-#     def call
-#       do_stuff
-#       do_stuff_to_another_object
-#       do_stuff_to_something_else
-#       do_stuff_to_yet_another_thing
-#     end
-#
-#     # ...
-#   end
-#
-# +Assignment+ is suddenly collaborating with a whole bunch of objects! This isn't bad in itself, but it might cause
-# some problems further on down the road as we add more responsibilities to +Assignment+. Do we really want all these
-# things to happen every time an +Assignment+ happens? If not, assuming this pattern we'll have to add a bunch of
-# control flow:
-#
-#   class Assignment
-#     # ...
-#
-#     def call
-#       do_stuff
-#
-#       if some_condition
-#         do_stuff_to_another_object
-#
-#         if some_other_condition
-#           do_stuff_to_something_else
-#         else
-#           do_stuff_to_yet_another_thing
-#         end
-#       elsif yet_another_condition
-#         do_other_stuff_to_that_other_object
-#       else
-#         dont_actually_do_anything_but_notify_someone
-#       end
-#     end
-#
-#     # ...
-#   end
-#
-# This is obviously an extreme example (but not unheard of!), but it gets to the core of what this module tries to
-# solve. +Emittance::Action+ helps facilitate the single responsibility principle by emitting an event whenever we
-# invoke +#call+ on an object like +Assignment+.
-#
-# == Usage
-#
-# First, define a class and include this module:
-#
-#   class Assignment
-#     include Emittance::Action
-#
-#     attr_reader :assignable
-#
-#     def initialize(assignable)
-#       @assignable = assignable
-#     end
-#   end
-#
-# Per the pattern explained above, instances of this class are representations of an action being carried out. This
-# class should have a very minimal interface (maybe, at most, some getter methods for its instance variables so the
-# handler can make decisions based on its state).
-#
-# Next, we'll implement the +#call+ instance method. +Emittance::Action+ will take care of the dirty work for us:
-#
-#   class Assignment
-#     # ...
-#
-#     def call
-#       do_one_and_i_mean_only_one_thing
-#     end
-#
-#     # ...
-#   end
-#
-# Again, this method should do a single thing. From here, your code should be able to run without error! You might
-# notice, though, that a mysterious class will have been defined after loading this file.
-#
-#   defined? AssignmentHandler
-#   => "constant"
-#
-# Next, we can open up this class to implement the event handler. +Emittance+ will look for a method called
-# +#handle_call+, and invoke it whenever, in this example, +Assignment#call+ is called.
-#
-#   class AssignmentHandler
-#     def handle_call
-#       notify_someone(action)
-#     end
-#
-#     # ...
-#   end
-#
-# The "Action" object is stored as the instance variable +@action+, made available with a getter class +#action+. This
-# will allow us to access its data and make decisions based on it.
-#
-# Now, this seems like we're passing the buck of all that control flow to yet another object, but this pattern has
-# several advantages. First, we can disable +Emittance+ at will, so if we ever want to shut +Assignment+ actions
-# off from their listeners, that is always an option to us. Second, to address the concern raised at the beginning of
-# this paragraph, this paradigm puts us into the mindset of spreading the flow of our program out across multiple
-# action/handler pairs, allowing us to think more clearly about what our code is doing.
-#
-# One possible disadvantage of this pattern is that it suggests a one-to-one pairing between events and handlers.
-#
-module Emittance::Action
-  EMITTING_METHOD = :call
-  HANDLER_METHOD_NAME = "handle_#{EMITTING_METHOD}".to_sym
-
-  class NoHandlerMethodError < StandardError; end
-
-  # @private
-  class << self
-    def included(action_klass)
-      handler_klass_name = Emittance::Action.handler_klass_name(action_klass)
-      handler_klass = Emittance::Action.find_or_create_klass(handler_klass_name)
-
-      action_klass.class_eval do
-        extend Emittance::Emitter
-
-        class << self
-          # @private
-          def method_added(method_name)
-            emitting_method = Emittance::Action::EMITTING_METHOD
-            emits_on method_name if method_name == emitting_method
-            super
+# frozen_string_literal: true
+
+module Emittance
+  ##
+  # Consider the usual "Service Object" pattern:
+  #
+  #   class Foo
+  #     def assign
+  #       FooAssignment.new(self).call
+  #     end
+  #   end
+  #
+  #   class FooAssignment
+  #     attr_reader :assignable
+  #
+  #     def initialize(assignable)
+  #       @assignable = assignable
+  #     end
+  #
+  #     def call
+  #       do_stuff
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  # There are variations on this pattern, the idea is that the service object represents something that your application
+  # is doing. However, this can easily just become a proxy for the same antipattern it was made to solve. We might wind
+  # up with a +#call+ method like the following:
+  #
+  #   class FooAssignment
+  #     # ...
+  #
+  #     def call
+  #       do_stuff
+  #       do_stuff_to_another_object
+  #       do_stuff_to_something_else
+  #       do_stuff_to_yet_another_thing
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  # We can use the +Emittance+ core features to prune those method calls:
+  #
+  #   class FooAssignment
+  #     extend Emittance::Emitter
+  #
+  #     # ...
+  #
+  #     def call
+  #       do_stuff
+  #       emit :foo_assignment
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  # +Emittance::Action+ provides a shortcut for this. Just mix it in and implement +#call+! This allows us to keep the
+  # expressitivity that a Service Object is made to provide, while preventing us from having to give such an object too
+  # many responsibilities.
+  #
+  # == Usage
+  #
+  # First, define a class and include this module:
+  #
+  #   class FooAssignment
+  #     include Emittance::Action
+  #
+  #     attr_reader :assignable
+  #
+  #     def initialize(assignable)
+  #       @assignable = assignable
+  #     end
+  #   end
+  #
+  # Next, we'll implement the +#call+ instance method. +Emittance::Action+ will take care of the dirty work for us:
+  #
+  #   class FooAssignment
+  #     # ...
+  #
+  #     def call
+  #       do_one_and_i_mean_only_one_thing
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  # From here, your code should be able to run without error! You might notice, though, that a mysterious class will
+  # have been defined after loading this file.
+  #
+  #   defined? FooAssignmentHandler
+  #   => "constant"
+  #
+  # Next, we can open up this class to implement the event handler. +Emittance+ will look for a method called
+  # +#handle_call+, and invoke it whenever, in this example, +FooAssignment#call+ is called.
+  #
+  #   class FooAssignmentHandler
+  #     def handle_call
+  #       notify_someone(action)
+  #     end
+  #
+  #     # ...
+  #   end
+  #
+  # The "Action" object is stored as the instance variable +@action+, made available with a getter class +#action+. This
+  # will allow us to access its data and make decisions based on it.
+  #
+  # Now, this seems like we're passing the buck of all that control flow to yet another object, but this pattern has
+  # several advantages. First, we can disable +Emittance+ at will, so if we ever want to shut +FooAssignment+ actions
+  # off from their listeners, that is always an option to us. Second, to address the concern raised at the beginning of
+  # this paragraph, this paradigm puts us into the mindset of spreading the flow of our program out across multiple
+  # action/handler pairs, allowing us to think more clearly about what our code is doing.
+  #
+  # One possible disadvantage of this pattern is that it suggests a one-to-one pairing between events and handlers.
+  #
+  module Action
+    # Name of the method that will emit an event when invoked.
+    EMITTING_METHOD = :call
+    # Name of the method that will be invoked when the handler class captures an event.
+    HANDLER_METHOD_NAME = "handle_#{EMITTING_METHOD}".to_sym
+
+    # @private
+    class << self
+      def included(action_klass)
+        handler_klass_name = Emittance::Action.handler_klass_name(action_klass)
+        handler_klass = Emittance::Action.find_or_create_klass(handler_klass_name)
+
+        action_klass.class_eval do
+          extend Emittance::Emitter
+
+          class << self
+            # @private
+            def method_added(method_name)
+              emitting_method = Emittance::Action::EMITTING_METHOD
+              emits_on method_name if method_name == emitting_method
+              super
+            end
           end
         end
-      end
 
-      handler_klass.class_eval do
-        attr_reader :action
+        handler_klass.class_eval do
+          attr_reader :action
 
-        extend Emittance::Watcher
+          extend Emittance::Watcher
 
-        def initialize(action_obj)
-          @action = action_obj
-        end
+          def initialize(action_obj)
+            @action = action_obj
+          end
 
-        watch Emittance::Action.emitting_event_name(action_klass) do |event|
-          handler_obj = new(event.emitter)
-          handler_method_name = Emittance::Action::HANDLER_METHOD_NAME
+          watch Emittance::Action.emitting_event_name(action_klass) do |event|
+            handler_obj = new(event.emitter)
+            handler_method_name = Emittance::Action::HANDLER_METHOD_NAME
 
-          if handler_obj.respond_to? handler_method_name
-            handler_obj.send handler_method_name
+            if handler_obj.respond_to? handler_method_name
+              handler_obj.send handler_method_name
+            end
           end
         end
       end
-    end
 
-    # @private
-    def handler_klass_name(action_klass)
-      "#{action_klass}Handler"
-    end
+      # @private
+      def handler_klass_name(action_klass)
+        "#{action_klass}Handler"
+      end
 
-    # @private
-    def emitting_event_name(action_klass)
-      Emittance::Emitter.emitting_method_event(action_klass, Emittance::Action::EMITTING_METHOD)
-    end
+      # @private
+      def emitting_event_name(action_klass)
+        Emittance::Emitter.emitting_method_event(action_klass, Emittance::Action::EMITTING_METHOD)
+      end
 
-    # @private
-    def find_or_create_klass(klass_name)
-      unless Object.const_defined? klass_name
-        Object.const_set klass_name, Class.new(Object)
+      # @private
+      def find_or_create_klass(klass_name)
+        unless Object.const_defined? klass_name
+          set_namespaced_constant_by_name klass_name, Class.new
+        end
+
+        Object.const_get klass_name
       end
 
-      Object.const_get klass_name
+      private
+
+      def set_namespaced_constant_by_name(const_name, obj)
+        names = const_name.split('::')
+        names.shift if names.size > 1 && names.first.empty?
+
+        namespace = names.size == 1 ? Object : Object.const_get(names[0...-1].join('::'))
+        namespace.const_set names.last, obj
+      end
     end
   end
 end