signal_lamp 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cb205a2b3a0cab05eae3328eaf5affb360d36d87
+  data.tar.gz: a2db4a1d041c62e527d924b96c5714a1ea08942c
+SHA512:
+  metadata.gz: e127a9527fc7216aea6142e4f3d5247e1f03862e6a80c9a7eee6333ed3b2e1f595721ed9fb50dc067559527dc03d9ff97505f90df36f15b74d941722f42a62c8
+  data.tar.gz: 2aba2811fb0e485e0aacb5095589860ce6328c9731b142444b3fc8e2c084061f4817322c9c86576378c2476fab0a82c95973a66e1937f4c044230776a3fa32dd

data/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+Gemfile.lock
+doc
+pkg

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 James Edward Gray II
+
+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,126 @@
+# Signal Lamp
+
+A simple tool for decoupling Ruby object systems.
+
+## Synopsis
+
+```ruby
+require "signal_lamp"  # Step 0:  load Signal Lamp
+
+class Datum
+  include SignalLamp::LampHolder  # Step 1:  include the event methods
+
+  def initialize(value)
+    @value = value
+  end
+
+  attr_reader :value
+
+  def value=(new_value)
+    old_value = @value
+    @value    = new_value
+
+    # Step 2:  signal events when interesting things happen
+    lamp.signal("changed:value", self, old: old_value, new: new_value)
+  end
+end
+
+class TotalWatcher
+  def initialize
+    @total = 0
+  end
+
+  attr_reader :total
+
+  def watch(datum)
+    record_value(datum.value)
+    # Step 3:  watch for those events
+    datum.lamp.watch_for("changed:value") do |_, _, details|
+      record_value_change(details)
+    end
+  end
+
+  private
+
+  def record_value(value)
+    @total += value
+  end
+
+  def record_value_change(old: , new: )
+    record_value(new - old)
+  end
+end
+
+ones = Datum.new(1)
+tens = Datum.new(30)
+
+#
+# variation on the theme:
+#
+# 1. You don't have to use objects
+# 2. You can watch for multiple event types at once
+# 3. All signal arguments are passed through to the watcher
+#
+changed_event_regex = /\Achanged:/
+[ones, tens].each do |datum|
+  datum.lamp.watch_for(changed_event_regex) do |event, changed_datum, details|
+    printf "%s's `%s' changed from %i to %i\n",
+           changed_datum.object_id,
+           event.sub(changed_event_regex, ""),
+           details.fetch(:old),
+           details.fetch(:new)
+  end
+end
+
+# this hooks event signalers to watchers
+watcher = TotalWatcher.new
+watcher.watch(ones)
+watcher.watch(tens)
+
+# this signals events
+ones.value += 1
+tens.value += 10
+
+# this shows that the objects communicated
+watcher.total  # => 42
+# >> 70302533065580's `value' changed from 1 to 2
+# >> 70302533065560's `value' changed from 30 to 40
+```
+
+## Description
+
+This library is pretty much a port of [the Events module in Backbone.js](http://backbonejs.org/#Events), with minor changes:
+
+* The interface was made a little more Rubyish with the use of blocks, `===`, etc.
+* All event methods were moved behind an prefix to minimize the impact on an object's API
+* Simple identifiers are used to classify, and optionally remove, watcher to signaler relationships
+
+In other words, this is a system for decoupling objects.  Some objects become "signalers" that tell anyone who is interested when "events" happen.  Other objects act as "watchers" waiting for and acting on those events.
+
+This library has nothing to do with multiprocessing.  This is just a tool for managing object communication.
+
+## Installation
+
+Install the gem:
+
+```
+gem install signal_lamp
+```
+
+or add it to your `Gemfile`:
+
+```ruby
+gem "signal_lamp"
+```
+
+## Contributing
+
+If you have grand ideas about cool new features that could be added to Signal Lamp, I'm probably not interested.  Sorry.  I very much want this library to stay a simple tool that is easy to fully understand.
+
+Of course, I'm very interested in fixing any bugs or other problems with this code.  [Please do send those along.](https://github.com/JEG2/signal_lamp/issues)
+
+If you're unsure, [feel free to create an issue](https://github.com/JEG2/signal_lamp/issues).  I'm happy to discuss it with you.  Just don't get too mad if I pass.  You are always welcome to release extensions to Signal Lamp as add-on gems.
+
+## Author
+
+Signal Lamp was coded up by James Edward Gray II (JEG2).

data/Rakefile

@@ -0,0 +1,15 @@
+require "bundler/gem_tasks"
+require "rdoc/task"
+require "rspec/core/rake_task"
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.main     = "README.md"
+  rdoc.rdoc_files.include(
+    "README.md",
+    `git ls-files -z`.split("\x0").grep(%r{\Alib/})
+  )
+end
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/lib/signal_lamp.rb

@@ -0,0 +1,11 @@
+require_relative "signal_lamp/version"
+require_relative "signal_lamp/lamp_holder"
+
+#
+# A simple tool for decoupling Ruby object systems.
+#
+# See SignalLamp::Lamp and SignalLamp::LampHolder for documentation.
+#
+module SignalLamp
+  # namespace filled in by the files above
+end

data/lib/signal_lamp/lamp.rb

@@ -0,0 +1,97 @@
+require "securerandom"
+
+module SignalLamp
+  #
+  # A Lamp keeps track of the watchers waiting for events and allows events to
+  # be signaled to those watchers.  The primary methods used for this are
+  # #watch_for() and #signal().
+  #
+  class Lamp
+    #
+    # It's not common to construct these objects directly.  Instead, most code
+    # should use the SignalLamp::LampHolder mix-in.
+    #
+    def initialize
+      @watchers = { }
+    end
+
+    attr_reader :watchers
+    private     :watchers
+
+    #
+    # This is the primary interface for watching for events to occur.
+    #
+    # The +event_matcher+ parameter will be tested against signaled event names
+    # using the <tt>===</tt> operator.  This allows you to match a +String+
+    # directly, use a +Regexp+ to wildcard various event types (I recommend
+    # naming events with words separated by colons because these are easy to
+    # match), or a +Proc+ that uses any kind of logic to select events.  For
+    # example, you could match all events signaled on this object with
+    # <tt>->(event_name) { true }</tt>.
+    #
+    # You only need to worry about passing an +identifier+ if you want to later
+    # stop watching for the events you will pick up with this call.  Alternately
+    # you can save the generated +identifier+ returned from this call and later
+    # feed that to #stop_watching().  Any Ruby object that can be used as a
+    # +Hash+ key is a valid +identifier+.  By default, a UUID +String+ will be
+    # generated.
+    #
+    # The block passed to this call is the code that will actually be invoked
+    # when an event is signaled and the name is matched.  The block will be
+    # passed the matched event name (useful with dynamic matchers that could
+    # select various events) followed by all arguments passed to #signal() for
+    # the event.
+    #
+    def watch_for(event_matcher, identifier: generate_identifier, &event_handler)
+      watchers[identifier] = [event_matcher, event_handler]
+      identifier
+    end
+
+    #
+    # This is a shortcut used to create a #watch_for() call that will only
+    # trigger for one event.  After the block is called the first time,
+    # #stop_watching() is automatically called.
+    #
+    def watch_for_one(event_matcher, &event_handler)
+      identifier = generate_identifier
+      watch_for(event_matcher, identifier: identifier) do |*event_args|
+        begin
+          event_handler.call(*event_args)
+        ensure
+          stop_watching(identifier)
+        end
+      end
+    end
+
+    #
+    # Given an +identifier+ passed to or returned from a previous call to
+    # #watch_for(), this method will stop that code from being invoked for any
+    # future events.
+    #
+    def stop_watching(identifier)
+      watchers.delete(identifier)
+    end
+
+    #
+    # This method will invoke the block code of all previous calls to
+    # #watch_for() that are still in effect and that match the passed
+    # +event_name+.
+    #
+    # All other arguments passed to this method, assumed to be details related
+    # to the event, are passed through to all blocks invoked for this event.
+    #
+    def signal(event_name, *event_details)
+      watchers.each_value do |event_matcher, event_handler|
+        if event_matcher === event_name
+          event_handler.call(event_name, *event_details)
+        end
+      end
+    end
+
+    private
+
+    def generate_identifier
+      SecureRandom.uuid
+    end
+  end
+end

data/lib/signal_lamp/lamp_holder.rb

@@ -0,0 +1,18 @@
+require_relative "lamp"
+
+module SignalLamp
+  #
+  # The primary interface of SignalLamp.  Mix this into an object, then use
+  # the #lamp() method to reach any features provided by SignalLamp::Lamp.
+  #
+  module LampHolder
+    #
+    # Returns a memoized SignalLamp::Lamp instance that can be used to
+    # SignalLamp::Lamp#signal() events and SignalLamp::Lamp#watch_for() events
+    # related to the object this module is mixed into.
+    #
+    def lamp
+      @lamp ||= SignalLamp::Lamp.new
+    end
+  end
+end

data/lib/signal_lamp/version.rb

@@ -0,0 +1,3 @@
+module SignalLamp
+  VERSION = "0.0.1"
+end

data/signal_lamp.gemspec

@@ -0,0 +1,28 @@
+require_relative "lib/signal_lamp/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = File.basename(__FILE__, ".gemspec")
+  spec.version       = SignalLamp::VERSION
+  spec.authors       = ["James Edward Gray II (JEG2)"]
+  spec.email         = %w[james@graysoftinc.com]
+  spec.summary       = "A simple tool for decoupling Ruby object systems."
+  spec.description   = <<END_DESCRIPTION
+This is a system for decoupling objects. Some objects become "signalers" that
+tell anyone who is interested when "events" happen. Other objects act as
+"watchers" waiting for and acting on those events.
+END_DESCRIPTION
+  spec.homepage      = "https://github.com/JEG2/signal_lamp"
+  spec.license       = "MIT"
+
+  spec.files            = `git ls-files -z`.split("\x0")
+  spec.test_files       = spec.files.grep(%r{\Aspec/})
+  spec.extra_rdoc_files = %w[README.md]
+  spec.rdoc_options    << "--main" << "README.md"
+  spec.require_paths    = %w[lib]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake",    "~> 10.3"
+  spec.add_development_dependency "rspec",   "~> 2.14"
+  spec.add_development_dependency "ZenTest", "~> 4.10"
+  spec.add_development_dependency "rdoc",    "~> 4.1"
+end

data/spec/lamp_holder_spec.rb

@@ -0,0 +1,18 @@
+require_relative "spec_helper"
+
+require_relative "../lib/signal_lamp/lamp_holder"
+
+describe SignalLamp::LampHolder do
+  let(:object) { Object.new }
+
+  it "adds the lamp interface to any object" do
+    expect(object.respond_to?(:lamp)).not_to be_true
+    object.extend(SignalLamp::LampHolder)
+    expect(object.respond_to?(:lamp)).to be_true
+  end
+
+  it "always returns the same lamp attached to an object" do
+    object.extend(SignalLamp::LampHolder)
+    expect(object.lamp).to be(object.lamp)
+  end
+end

data/spec/lamp_spec.rb

@@ -0,0 +1,86 @@
+require_relative "spec_helper"
+
+require_relative "../lib/signal_lamp/lamp"
+
+describe SignalLamp::Lamp do
+  let(:events_seen) { [ ] }
+
+  it "allows you to watch for signaled events" do
+    subject.watch_for("test_event") do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("test_event")
+    expect(events_seen).to eq(%w[test_event])
+  end
+
+  it "does not notify you of events that don't match" do
+    subject.watch_for("match") do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("match")
+    subject.signal("no_match")
+    expect(events_seen).to eq(%w[match])
+  end
+
+  it "understands dynamic event name matchers" do
+    subject.watch_for(/\Achanged:/) do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("changed:font")
+    subject.signal("changed:color")
+    subject.signal("deleted:content")
+    expect(events_seen).to eq(%w[changed:font changed:color])
+  end
+
+  it "passes signaled arguments to the watcher" do
+    subject.watch_for("args") do |event_name, *args|
+      events_seen << args
+    end
+    subject.signal("args")
+    subject.signal("args", 1)
+    subject.signal("args", 2, :three)
+    expect(events_seen).to eq([[ ], [1], [2, :three]])
+  end
+
+  it "notifies all watches of matching events" do
+    subject.watch_for("changed:value") do |event_name|
+      events_seen << "static"
+    end
+    subject.watch_for(/\Achanged:/) do |event_name|
+      events_seen << "dynamic"
+    end
+    subject.signal("changed:value")
+    expect(events_seen.sort).to eq(%w[dynamic static])
+  end
+
+  it "allows you to stop watching for events by identifier" do
+    subject.watch_for("identifiers", identifier: :test_watcher) do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("identifiers")
+    subject.signal("identifiers")
+    subject.stop_watching(:test_watcher)
+    subject.signal("identifiers")
+    expect(events_seen).to eq(%w[identifiers identifiers])
+  end
+
+  it "returns autogenerated identifiers" do
+    identifier = subject.watch_for("generated") do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("generated")
+    subject.signal("generated")
+    subject.stop_watching(identifier)
+    subject.signal("generated")
+    expect(events_seen).to eq(%w[generated generated])
+  end
+
+  it "provides a one event shortcut" do
+    subject.watch_for_one("once") do |event_name|
+      events_seen << event_name
+    end
+    subject.signal("once")
+    subject.signal("once")
+    expect(events_seen).to eq(%w[once])
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: signal_lamp
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- James Edward Gray II (JEG2)
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: ZenTest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.10'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+description: |
+  This is a system for decoupling objects. Some objects become "signalers" that
+  tell anyone who is interested when "events" happen. Other objects act as
+  "watchers" waiting for and acting on those events.
+email:
+- james@graysoftinc.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/signal_lamp.rb
+- lib/signal_lamp/lamp.rb
+- lib/signal_lamp/lamp_holder.rb
+- lib/signal_lamp/version.rb
+- signal_lamp.gemspec
+- spec/lamp_holder_spec.rb
+- spec/lamp_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/JEG2/signal_lamp
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A simple tool for decoupling Ruby object systems.
+test_files:
+- spec/lamp_holder_spec.rb
+- spec/lamp_spec.rb
+- spec/spec_helper.rb