octiron 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0a1d5d04db3e10eb26f3292976922347550a8174
+  data.tar.gz: 609b4ac6d312fc78d74bbe3d3a127cc937584798
+SHA512:
+  metadata.gz: 8783e03aa012d7b3049ea7824b00a8699d94ac703ee1506bc6bd9e080367506aebc022e060fa6099a565620ce3146d808743adb5585cbac152271baec5b0471b
+  data.tar.gz: b0d09e6f7d9336fb965272a7d2d66264f1e698377563acd4988472c95901959b8434a8fa20ac757a1dda3b0f5129842db7e7454ff1fe414dbd575f9ac6ea6f01

data/.codeclimate.yml

@@ -0,0 +1,31 @@
+---
+engines:
+  bundler-audit:
+    enabled: true
+  duplication:
+    enabled: true
+    exclude_fingerprints:
+      - 8d15a3402e79d161b5ae30535883e4e4
+      engines:
+    config:
+      languages:
+      - ruby
+      - javascript
+      - python
+      - php
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - Gemfile.lock
+  - "**.inc"
+  - "**.js"
+  - "**.jsx"
+  - "**.module"
+  - "**.php"
+  - "**.py"
+  - "**.rb"
+exclude_paths:
+- spec/

data/.gitignore

@@ -0,0 +1,39 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Editor files
+.*.sw*

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,78 @@
+AllCops:
+  TargetRubyVersion: 2.2
+
+# Metrics
+
+Metrics/LineLength:
+  Max: 83
+  Details: >-
+    Line length of 80 is ideal for readability and compatibility; we'll accept
+    an extra 3 for minor edge cases.
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/BlockNesting:
+  Max: 5
+
+Metrics/AbcSize:
+  Max: 50
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/ClassLength:
+  Max: 300
+
+Metrics/ModuleLength:
+  Max: 300
+
+# Style
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/AndOr:
+  Enabled: false
+
+Style/Not:
+  Enabled: false
+
+Style/NegatedIf:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/TrailingCommaInLiteral:
+  Enabled: false
+
+Style/FirstParameterIndentation:
+  Enabled: false
+
+Style/TrailingUnderscoreVariable:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/SpaceAfterNot:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+script:
+  - bundle exec rake
+  - bundle exec codeclimate-test-reporter || true
+addons:
+  code_climate:
+    repo_token: 1e1df0108edbfdab88f77281556d0a95487b7a38437697ebbb55af9b0798f5e8

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in octiron.gemspec
+gemspec
+
+gem "codeclimate-test-reporter", group: :test, require: nil

data/Gemfile.lock

@@ -0,0 +1,70 @@
+PATH
+  remote: .
+  specs:
+    octiron (0.1.0)
+      collapsium (~> 0.8)
+      rgl (~> 0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.3.0)
+    codeclimate-test-reporter (1.0.3)
+      simplecov
+    collapsium (0.8.2)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    json (2.0.2)
+    lazy_priority_queue (0.1.1)
+    parser (2.3.3.1)
+      ast (~> 2.2)
+    powerpack (0.1.1)
+    rainbow (2.1.0)
+    rake (11.3.0)
+    rgl (0.5.2)
+      lazy_priority_queue (~> 0.1.0)
+      stream (~> 0.5.0)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    rubocop (0.46.0)
+      parser (>= 2.3.1.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    stream (0.5)
+    unicode-display_width (1.1.1)
+    yard (0.9.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.13)
+  codeclimate-test-reporter
+  octiron!
+  rake (~> 11.3)
+  rspec (~> 3.5)
+  rubocop (~> 0.46)
+  simplecov (~> 0.12)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   1.13.6

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) Jens Finkhaeuser (http://finkhaeuser.de/) and other octiron
+contributors. All rights not covered below are reserved.
+
+The MIT +no-false-attribs License (MITNFA)
+
+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.
+
+Distributions of all or part of the Software intended to be used by the
+recipients as they would use the unmodified Software, containing modifications
+that substantially alter, remove, or disable functionality of the Software,
+outside of the documented configuration mechanisms provided by the Software,
+shall be modified such that the Original Author's bug reporting email addresses
+and urls are either replaced with the contact information of the parties
+responsible for the changes, or removed entirely.
+
+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,159 @@
+# octiron
+
+*Octiron is an event bus with the ability to magically transform events.*
+
+Events octiron responds to can be any classes or Hash prototypes. Using
+transmogrifiers, events can be turned into other kinds of events
+transparently.
+
+[![Gem Version](https://badge.fury.io/rb/octiron.svg)](https://badge.fury.io/rb/octiron)
+[![Build status](https://travis-ci.org/jfinkhaeuser/octiron.svg?branch=master)](https://travis-ci.org/jfinkhaeuser/octiron)
+[![Code Climate](https://codeclimate.com/github/jfinkhaeuser/octiron/badges/gpa.svg)](https://codeclimate.com/github/jfinkhaeuser/octiron)
+[![Test Coverage](https://codeclimate.com/github/jfinkhaeuser/octiron/badges/coverage.svg)](https://codeclimate.com/github/jfinkhaeuser/octiron/coverage)
+
+# Usage
+
+So what does this all mean?
+
+## Fundamentals
+
+First of all, the gem contains a publish/subscribe event bus, which easily
+allows you to subscribe handlers to events of a particular class:
+
+```ruby
+require 'octiron'
+
+class MyEvent
+  # ...
+end
+
+on_event(MyEvent) do |event|
+  # event.is_a?(MyEvent) == true
+  # do something with the event
+end
+```
+
+You can subscribe as many handlers to an event class as you want.
+
+Next, you can transmogrify objects - typically events. Similar to suscribing
+event handlers, you can register transmogrifiers for a particular
+transmogrification.
+
+```ruby
+class AnotherEvent
+end
+
+on_transmogrify(MyEvent).to AnotherEvent do |my_event|
+  # guaranteed: my_event.is_a?(MyEvent) == true
+  AnotherEvent.new
+end
+```
+
+As long as the transmogrifier returns an object of the `AnotherEvent` type,
+all is well.
+
+Putting this together with the hitherto unmentioned `#publish` method, you can
+easily build processing pipelines.
+
+```ruby
+on_transmogrify(MyEvent).to AnotherEvent do |my_event|
+  # do something more meaningful
+  AnotherEvent.new
+end
+
+on_event(MyEvent) do |event|
+  publish transmogrify(event).to AnotherEvent
+end
+
+on_event(AnotherEvent) do |event|
+  # We'll end up here with the transmogrified event
+end
+
+publish MyEvent.new
+```
+
+## Advanced Usage
+
+There are some more advanced topics that might be useful to understand.
+
+### Singletons vs. API
+
+The octiron gem exposes a number of simple wrapper functions we've used so far
+to hide the API complexity a little. These wrapper functions make use of a
+singleton event bus instance, and a singleton transmogrifier registry:
+
+- `#on_event` delegates `Octiron::Events::Bus#subscribe`
+- `#publish` delegates `Octiron::Events::Bus#publish`
+- `#on_transmogrify` delegates to `Octiron::Transmogrifiers::Registry#register`
+- `#transmogrify` delegates to `Octiron::Transmogrifiers::Registry#transmogrify`
+
+You can just as well use these underlying API functions with multiple instances
+of the event bus or the transmogrifier registry.
+
+### Hash Prototypes
+
+The octiron gem implements something of a prototyping mechanic for using Hashes
+as events, but also as sources and targets of transmogrification. If the event
+bus would register handlers for the Hash class, all Hashes would trigger the
+same handlers (and similar for the transmogrifier registry).
+
+Instead, where you would normally provide classes (e.g. `#on_event`), you can
+specify a Hash that acts as a prototype. Then, where you would normally use
+instances (e.g. `#publish`), you can provide a Hash again. If that published
+Hash matches the prototype Hash, the handler associated with the prototype is
+triggered.
+
+So how does this matching work?
+
+- If a prototype specifies a key without value (i.e. a nil value), the published
+  instance *must* contain the key, but the value or value type is ignored.
+- If a prototype specifies a key with a value, the published instance *must*
+  contain the key, and it's value *must* match the respective value in the
+  prototype.
+
+```ruby
+proto1 = {
+  a: nil,
+}
+
+proto2 = {
+  b: 42,
+}
+
+published1 = {
+  a: 'foo',
+}
+# published1 matches proto1, but not proto2
+
+published2 = {
+  b: 42,
+}
+# published2 matches proto2, but not proto1
+```
+
+Hash prototyping is supported both for subscribing event handlers, and
+registering transmogrifiers, allowing for something of the following:
+
+```ruby
+on_transmogrify(proto1).to proto2 do |event|
+  x = event.dup
+  x.delete(:a)
+  x[:b] = 42
+  x
+end
+
+on_event(proto1) do |event|
+  publish transmogrify(event).to proto2
+end
+
+on_event(proto2) do |event|
+  # we'll end up here
+end
+
+publish published1
+```
+
+*Note* that you can produce closed loops by publishing events from within event
+handlers. In the above example, if the transmogrifier did not delete the `:a`
+key from the newly created event, it would still match the `proto1` prototype,
+which would trigger that handler and the transmogrifier again and again.

data/Rakefile

@@ -0,0 +1,25 @@
+# Rubocop
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+# Rspec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:rspec)
+
+# Documentation
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['-m', 'markdown']
+  t.stats_options = ['--list-undoc']
+end
+
+# Combined test task
+desc "Test all the things!"
+task :test do
+  Rake::Task[:rubocop].invoke
+  Rake::Task[:rspec].invoke
+end
+
+# Default is the test task
+task default: :test