orator 0.0.1 → 0.1.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MDJhNWFlYjk5NjdjZTI1Nzk5MGEzMzVhMjc5N2NhNjRkY2JkMGVlZA==
+    M2JlMGJkOWU0OGIzMWEwM2ZmNmRjMTZkZDFhZTlmMGI5ZDUzZjlhZg==
   data.tar.gz: !binary |-
-    Zjk5YzBmNjNiMzFhZTNkMGNlYTZiYmMxN2ExMWRkNTAwMDk4OWU1MQ==
+    MTI4Yzg5NmZlOTJhNTc4ZmM1MzI4ZTlmNzYxMTVjYWUzOWVhMDIyNQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    ZWE2N2Y4ZTU3ZWM4ZDRiNmZhMWQyNGRlY2RkNzQ5ZWVhMTRhZmUyODc1ZGMy
-    ZjYwMWY4YWU3Y2FjN2QxOGQ2YzBiMzQ4MzQ1YmVhOWZhMjk0NDNkYzNhYzgx
-    MTk2ZWQxMjdmMGViZmVlODg3ZTU3MmIwOTFmMThmOGQ4NDE1OGY=
+    OWYxOGY0ZDVmNWEzY2JmNTkxZjdkMjlmMTc5OTI4NTgxNDdhMzFlYjQxYWVl
+    N2IwOTE4YzlkZjU4ZjQzYmEwNzI0NTIwZmFlYTlhOWUxNWQ4MWFhM2VjNGJk
+    YmU5NDg1ZTYxNWFlMzNhYzhjMjM2ODRhYTNjNjRjZTRjNzQyNDU=
   data.tar.gz: !binary |-
-    NzJhODQzZWNhZDhkZDU3NGViN2ZiYmYzYTY4NDU3NTVkZWQ0ZGE3YmJjYzc3
-    ZTkxYTJlOGExZjI5MmQ0NzFhNDI0MGE2YTBhZGNmOTRhOWE0Mjg0YzA0MzU2
-    YTFjYTM0ZmE1ODcwYTFiZmM1MWI4OTQyNjgxMjUyMGZiNDQ3ODU=
+    OTQ3YzgzOTc5YmY5YmY5OTk1MzcyMWM3YzNjNGU1YzI5ZmEzZmI4OTg2NzU4
+    ZjNjOTQ4MjkyZTJmNDc3ZGE5MDQ0NjFjN2Q3MmM2OGJiZDUxOGZjZTM4YWJh
+    YzFkYWU2OTU3YmFiOWU1MmNlZjBlMzM3MDg5NmE1Nzc4YzEyNWQ=

data/README.md

@@ -9,7 +9,7 @@ well as [em-websocket](https://github.com/igrigorik/em-websocket).
 ## Ruby on Rails Integration
 Orator integrates easily with Ruby on Rails.  Just add
   
-    gem 'orator', :github => "redjazz96/orator"
+    gem 'orator'
 
 to your Gemfile and `bundle install` away.  In order to use it, you'll need to
 add the following line to your `application.js` file:
@@ -19,51 +19,142 @@ add the following line to your `application.js` file:
 Now you can use the orator client in your JavaScript!  If the browser doesn't
 support JavaScript, it'll fall back to a flash object.
 
+## Server Handlers
+We'll start with the server-side stuff.  A simple `rails g orator:config` will
+place the file `orator_config.yml` in `config/`, and an example handler in
+`app/handlers`.  Feel free to modify the configuration file (I'll add
+documentation to it).  Let's set up a handler here:
+
+```Ruby
+class TestHandler < Orator::Handlers::Base
+```
+
+This is important.  Orator will not accept the Handler unless it is a child
+of `Orator::Handlers::Base`.  `Orator::Handlers::Base` implements methods that
+are used by Orator.
+
+```Ruby
+  before do
+    self.number_of_messages ||= 0
+    self.number_of_messages += 1
+
+    if self.number_of_messages > 9_000
+      prevent_event
+    end
+  end
+```
+
+Here we have a basic before block that increments a number every time we get
+a message.  If the number of messages is over 9,000, it will prevent the event
+from occuring (but any after blocks will still run).
+
+```Ruby
+  on :ping
+  def ping(data)
+    send message('test.pong', message: 'pong')
+  end
+```
+
+Here we define a basic event named `ping`.  When the server receives it, it
+sends back an event named `test.pong`, with the message `pong`.  Cool, eh?
+
+```Ruby
+  on :pong
+  def pong(data)
+    puts data["message"] # => "pong"
+  end
+```
+
+In this we're assuming that somewhere else in our code the client sent us a
+`test.pong` event; maybe they did so in response to a ping that we sent.
+Either way, we're outputting a message that we received.
+
+```Ruby
+end
+
+Orator.add_handler(TestHandler)
+```
+
+Here we register our handler with Orator, so it can use it for routing events.
+But say we also want to handle a `socket.open` event.  Our handler above can't
+handle that, sadly, so we use this method:
+
+```Ruby
+Orator.add_handler do |events|
+  events.on('socket.open') do |data|
+    self.user = {}
+
+    send mesasge('test.ping', message: 'ping')
+  end
+
+  events.on('user.alias') do |data|
+    self.user[:name] = json["name"]
+  end
+end
+```
+
+So when the socket opens in `socket.open`, we set `#user` to an empty hash and
+send a ping message (whose response will be handled by our TestHandler).  When
+we receive the `user.alias` message, we set the key-pair `:name => json["name"]`
+on the `#user` hash.  Cool, eh?
+
 ## JavaScript Client
 Let's go through an example together.
-    
-    $(document).ready(function() {      
-      Orator.setup("ws://host:port/path?query", function(events){
+
+```JavaScript    
+$(document).ready(function() {      
+  Orator.setup("ws://host:port/path?query", function(events){
+```
 
 `Orator.setup` handles setting up our socket for us.  It also sets up the
 events and routing, as well.  There are some locally defined events that are
 triggered even if the server hadn't sent them, such as `socket.open` and
 `socket.close`.
         
-        events.on('some.event', function() {})
+```JavaScript
+  events.on('some.event', function() {})
+```
 
 Here we're binding some event named `some.event` to an empty function.  Boring.
 Note that the name of the event doesn't matter here.
 
-        events.on('test.ping', function() { 
-          this.server.send('test.pong', { message: 'pong' });
-        });
+```JavaScript
+  events.on('test.ping', function() { 
+    this.server.send('test.pong', { message: 'pong' });
+  });
+```
 
 Here we're responding to a ping that a server might send to this client.  We
 send back a `test.pong` event, with the message 'pong'.  The contents of the
 event can be anything.
 
-        events.on('test.pong', function(data) {
-          console.log(data.message) # => "pong"
-        });
+```JavaScript
+  events.on('test.pong', function(data) {
+    console.log(data.message) // => "pong"
+  });
+```
 
 Here we received a pong back from the server - this was triggered by the server
 in response to our ping, which we could have sent at any time.
 
-        events.on('socket.open', function() {
-          this.user = {}
+```JavaScript
+  events.on('socket.open', function() {
+    this.user = {}
 
-          this.server.send('user.alias', { name: some_name })
-        });
+    this.server.send('user.alias', { name: some_name })
+  });
+```
 
 Here we defined an event that will set up a an empty object on the property
 user of `this`.  This will become important.  We then send the event
 `user.alias` to the server (which probably changes the name of the user) with
 the new name (assuming `some_name` has a string value).
 
-        events.on('user.alias', function(data) {
-          this.user.name = data.name;
-        });
+```JavaScript
+  events.on('user.alias', function(data) {
+    this.user.name = data.name;
+  });
+```
 
 It is common place for the server's response events to be named the same as the
 request events (although the response events may be sent at any time, with no
@@ -71,15 +162,10 @@ context).  Here we see setting the name of the user object to the name the
 server sent back.  This is the same user object that we defined in the event
 above.
 
-      });
+```JavaScript
+  });
 
-    });
+});
+```
 
 And we close our braces.
-
-## Server Stuff
-I'm not entirely sure how to set this part up...  any ideas?
-
-I'm trying to provide support for all types of rails applications, including
-those on passenger.  I'll probably require a settings file in 
-`Rails.root/config` for orator...

data/lib/generators/orator/config_generator.rb

@@ -0,0 +1,14 @@
+module Orator
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+
+      source_root File.expand_path('../../templates', __FILE__)
+
+      def copy_configuration
+        template "config.yml", "config/orator_config.yml"
+        directory "handlers", "app/handlers"
+      end
+
+    end
+  end
+end

data/lib/generators/orator/handler_generator.rb

@@ -0,0 +1,15 @@
+module Orator
+  module Generators
+    class HandlerGenerator < Rails::Generators::Base
+
+      source_root File.expand_path('../../templates', __FILE__)
+      argument :handler_name, :required => true,
+        :desc => "The name of the handler to use."
+
+      def copy_configuration
+        template "template_handler.rb", "app/handlers/#{handler_name}_handler.rb"
+      end
+
+    end
+  end
+end

data/lib/generators/templates/config.yml

@@ -0,0 +1,7 @@
+---
+:pid_file: tmp/orator.pid
+:log_file: log/orator.log
+:server_options:
+  :host: 0.0.0.0
+  :port: 8080
+:handlers_path: app/handlers/*

data/lib/generators/templates/handlers/example_handler.rb

@@ -0,0 +1,31 @@
+class ExampleHandler < Orator::Handlers::Base
+
+  # This defines the name of the handler.  THIS IS REQUIRED.  Orator will not
+  # be able to correctly route your events to this handler if it is not put
+  # here.
+  #handler_name 'example'
+
+  # This defines a before event.  It can take a block or a symbol.  If it's a
+  # symbol, it'll call the method.
+  #before do
+  #  something
+  #end
+
+  # This defines the event `some_event`.  Note that the two have to have the
+  # same value.  If they're different, you need to add a second argument
+  # describing the method name (i.e. `on 'some_event', :some_method`).
+  #on 'some_event'
+  #def some_event(json)
+  #  do_something
+  #end
+
+  # Inline syntax.
+  #on 'other_event' do; end
+
+  #after do
+  #  other_thing
+  #end
+
+end
+
+#Orator.add_handler(ExampleHandler)

data/lib/generators/templates/template_handler.rb

@@ -0,0 +1,6 @@
+class <%= handler_name.camelcase %>Handler < Orator::Handlers::Base
+  
+  handler_name '<%= handler_name.underscore %>'
+
+  
+end

data/lib/orator/cli.rb

@@ -8,7 +8,7 @@ module Orator
 
     DEFAULT_OPTIONS = {
       :command   => :help,
-      :file      => "./orator_config.yml",
+      :file      => "config/orator_config.yml",
       :daemonize => false
     }
 
@@ -27,10 +27,14 @@ module Orator
           @options[:command] = command
         end
 
-        opts.on('-D', '--[no-]daemonize', "Whether or not to daemonize the process.") do |d|
+        opts.on('-d', '--[no-]daemonize', "Whether or not to daemonize the process.") do |d|
           @options[:daemonize] = d
         end
 
+        opts.on('-D', '--debug', "Run Orator in debug mode.") do
+          Orator.debug = true
+        end
+
         opts.on('-h', '--help', "Shows this message.") { puts opts; exit }
         opts.on('-v', '--version', "Shows the version of orator.") do
           puts Orator::VERSION
@@ -45,7 +49,6 @@ module Orator
     end
 
     def handle_command
-      Orator.debug = yaml_options[:debug]
       send(@options[:command])
     end
 
@@ -119,21 +122,9 @@ module Orator
     #
     # @return [void]
     def load_handlers
-      handlers = []
-      if yaml_options[:handler]
-        handlers << yaml_options[:handler]
-      end
-
-      if yaml_options[:handlers]
-        handlers.concat(yaml_options[:handlers])
-      end
-
-      handlers.each do |handler|
-        begin
-          require_relative handler
-        rescue LoadError
-          require handler
-        end
+      p yaml_options, yaml_options[:handlers_path]
+      Dir[yaml_options[:handlers_path]].each do |file|
+        load file
       end
     end
 

data/lib/orator/handlers/base.rb

@@ -20,23 +20,17 @@ module Orator
       #
       # @param event [Symbol, String] the event to trigger.
       # @raise [NoMethodError] if the event isn't defined on the handler.
-      # @return [Array<Object>] the values of the trigger.
+      # @return [Array<Object>, nil] the values of the trigger, or nil if the
+      #   event was prevented.
       def __trigger(event, *args)
         handler, method_name = event.to_s.split('.')
+        __check_event(handler, method_name)
 
-        if handler != self.class.name 
-          raise NoMethodError, 
-            "Event #{handler} does not match #{self.class.name}"
-          return
-        elsif !__method_exists?(method_name)
-          raise NoMethodError, 
-            "Method #{method_name} does not exist on #{self.class.name}"
-          return
-        end
+        __run_callbacks(:before)
+        out = __run_event(method_name, args) unless @__prevent_event
+        __run_callbacks(:after)
 
-        self.class.before_list.map { |b| instance_exec &b }
-
-        __run_event(method_name, args) unless @__prevent_event
+        out
       end
 
       # Checks the event list to see if this class responds to it.
@@ -86,23 +80,54 @@ module Orator
 
       private
 
+      # Run the event.
       def __run_event(method_name, args)
         result = __event_list[method_name].map do |responder|
           responder = method(responder) if responder.is_a? Symbol
           instance_exec *args, &responder
         end
 
-        self.class.after_list.map { |a| instance_exec &a }
-
         result
       end
 
+      # Check the event, making sure that this handler can respond to it.
+      def __check_event(handler, method)
+        if handler != self.class.handler_name
+          raise NoMethodError, 
+            "Event #{handler} does not match #{self.class.name}"
+          return
+        elsif !__method_exists?(method)
+          raise NoMethodError, 
+            "Method #{method} does not exist on #{self.class.name}"
+          return
+        end
+      end
+
+      # Runs the callbacks.
+      def __run_callbacks(type)
+        self.class.send("#{type}_list").map do |cb|
+          if cb.is_a? Symbol
+            method(cb).call
+          else
+            instance_exec &cb
+          end
+        end
+      end
+
       module ClassMethods
-        # The name of the handler.  This is used to determine whether or not
-        # the handler can run it.
+        
+        # This manages the handler's name.  If an argument is passed, the name
+        # is set to that.  Otherwise, it returns the handler's name.
         #
-        # @return [String]
-        attr_accessor :name
+        # @param value [String, nil] the new name.
+        # @return [String] the handler name.
+        def handler_name(value = nil)
+          if value
+            @_handler_name = value
+          end
+
+          @_handler_name
+        end
 
         # This registers a method for this Handler.
         #
@@ -132,7 +157,7 @@ module Orator
         # @param event_handler [EventHandler]
         def register_with(event_handler)
           event_list.keys.each do |event|
-            event_handler.on("#{self.name}.#{event}", self)
+            event_handler.on("#{self.handler_name}.#{event}", self)
           end
         end
 
@@ -150,7 +175,7 @@ module Orator
       end
 
       extend ClassMethods
-      self.name = ''
+      handler_name ''
 
     end
 

data/lib/orator/middle_ground.rb

@@ -11,6 +11,7 @@ module Orator
     # Initialize the class.
     def initialize(client)
       @client = client
+      @struct = OpenStruct.new
     end
 
     # This sends a message to the client.
@@ -34,5 +35,17 @@ module Orator
 
       new_data
     end
+
+    # This delegates the rest of the requests to the struct.
+    def method_missing(method, *args, &block)
+      super unless respond_to_missing?(method)
+
+      @struct.__send__(method, *args, &block)
+    end
+
+    # Lets ruby know we're doing some {#method_missing} magic.
+    def respond_to_missing?(method, include_private = false)
+      @struct.respond_to?(method, include_private)
+    end
   end
 end

data/lib/orator/version.rb

@@ -1,5 +1,5 @@
 module Orator
 
   # Version of Orator.
-  VERSION = '0.0.1'
+  VERSION = '0.1.1'
 end

data/lib/orator.rb

@@ -2,6 +2,7 @@
 
 require 'oj'
 require 'set'
+require 'ostruct'
 require 'em-websocket'
 
 require 'orator/server'
@@ -17,5 +18,9 @@ module Orator
 
   class << self; attr_accessor :debug; end
   Orator.debug = false
+
+  def self.add_handler(*args, &block)
+    Orator::CLI.add_handler(*args, &block)
+  end
   
 end

data/lib/tasks/orator.rake

@@ -0,0 +1,3 @@
+namespace :orator do
+  
+end

data/spec/base_handler_spec.rb

@@ -3,7 +3,7 @@ describe Orator::Handlers::Base do
     something = double('something')
     something.should_receive(:to_call)
     klass = Class.new(described_class) do
-      self.name = 'test'
+      handler_name 'test'
       before { something.to_call }
       on 'some_event'
       def some_event; end
@@ -21,7 +21,7 @@ describe Orator::Handlers::Base do
     something = double('something')
     something.should_not_receive(:to_call)
     klass = Class.new(described_class) do
-      self.name = 'test'
+      handler_name 'test'
       before { prevent_event }
       on('some_event') { something.to_call }
     end
@@ -33,7 +33,7 @@ describe Orator::Handlers::Base do
     event_handler = double('event_handler')
 
     klass = Class.new(described_class) do
-      self.name = 'test'
+      handler_name 'test'
 
       on('some_event') { }
     end
@@ -42,4 +42,34 @@ describe Orator::Handlers::Base do
 
     klass.register_with(event_handler)
   end
+
+  it "should be able to take a before method" do
+    something = double('something')
+    something.should_not_receive(:to_call)
+
+    klass = Class.new(described_class) do
+      handler_name 'test'
+
+      before :do_something
+
+      def do_something; prevent_event; end
+
+      on 'some_event' do; something.to_call; end
+    end
+
+    klass.new(nil).__trigger('test.some_event')
+  end
+
+  it "should be able to use a different method" do
+
+    klass = Class.new(described_class) do
+      handler_name 'test'
+
+      on 'some_event', :other_method
+      def other_method; end
+      def some_event; raise StandardError; end
+    end
+
+    klass.new(nil).__trigger('test.some_event')
+  end
 end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'coveralls'
+Coveralls.wear!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: orator
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Jeremy Rodi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-07 00:00:00.000000000 Z
+date: 2013-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: em-websocket
@@ -84,9 +84,16 @@ files:
 - lib/orator/handlers/base.rb
 - lib/orator/engine.rb
 - lib/orator/event_handler.rb
+- lib/generators/orator/handler_generator.rb
+- lib/generators/orator/config_generator.rb
+- lib/generators/templates/template_handler.rb
+- lib/generators/templates/config.yml
+- lib/generators/templates/handlers/example_handler.rb
 - lib/orator.rb
+- lib/tasks/orator.rake
 - bin/orator
 - spec/client_spec.rb
+- spec/spec_helper.rb
 - spec/middle_ground_spec.rb
 - spec/event_handler_spec.rb
 - spec/base_handler_spec.rb