blather 0.4.1 → 0.4.2

data/README.rdoc

@@ -101,6 +101,21 @@ The different types of guards are:
   #   Equivalent to !stanza.find('/iq/ns:pubsub', :ns => 'pubsub:namespace').empty?
   iq '/iq/ns:pubsub', :ns => 'pubsub:namespace'
 
+=== Filters
+
+Blather provides before and after filters that work much the way regular handlers work. Filters come in a before and after
+flavor. They're called in order of definition and can be guarded like handlers.
+
+  before { |s| "I'm run before any handler" }
+  before { |s| "I'm run next" }
+
+  before(:message) { |s| "I'm only run in front of message stanzas" }
+  before(nil, :id => 1) { |s| "I'll only be run when the stanza's ID == 1" }
+
+  # ... handlers
+
+  after { |s| "I'm run after everything" }
+
 == On the Command Line:
 
 Default usage is:
@@ -126,7 +141,7 @@ Command line options:
 
 Jeff Smick <sprsquish@gmail.com>
 
-= Contributors
+=== Contributors
 
 Nolan Darilek <nolan@thewordnerd.info>
 

data/examples/echo.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require 'blather/client'
-Blather.logger.level = Logger::DEBUG
+
 when_ready { puts "Connected ! send messages to #{jid.stripped}." }
 
 subscription :request? do |s|

data/examples/ping.rb

@@ -0,0 +1,11 @@
+require 'blather/client'
+
+setup 'echo@jabber.local/ping', 'echo'
+
+status :from => Blather::JID.new('echo@jabber.local/pong') do |s|
+  say s.from, 'ping'
+end
+
+message :chat?, :body => 'pong' do |m|
+  say m.from, 'ping'
+end

data/examples/pong.rb

@@ -0,0 +1,6 @@
+require 'blather/client'
+
+setup 'echo@jabber.local/pong', 'echo'
+message :chat?, :body => 'ping' do |m|
+  say m.from, 'pong'
+end

data/lib/blather/client.rb

@@ -7,8 +7,8 @@ options = {}
 optparse = OptionParser.new do |opts|
   opts.banner = "Run with #{$0} [options] user@server/resource password [host] [port]"
 
-  opts.on('-D', '--debug', 'Run in debug mode (you will see all XMPP communication)') do |debug|
-    options[:debug] = debug
+  opts.on('-D', '--debug', 'Run in debug mode (you will see all XMPP communication)') do
+    options[:debug] = true
   end
 
   opts.on('-d', '--daemonize', 'Daemonize the process') do |daemonize|
@@ -60,10 +60,12 @@ at_exit do
     if options[:log]
       log = File.new(options[:log], 'a')
       log.sync = options[:debug]
-      Blather.logger.level = Logger::DEBUG if options[:debug]
       $stdout.reopen log
       $stderr.reopen $stdout
     end
+
+    Blather.logger.level = Logger::DEBUG if options[:debug]
+
     trap(:INT) { EM.stop }
     trap(:TERM) { EM.stop }
     EM.run { client.run }

data/lib/blather/client/client.rb

@@ -2,29 +2,67 @@ require File.join(File.dirname(__FILE__), *%w[.. .. blather])
 
 module Blather #:nodoc:
 
-  class Client #:nodoc:
+  # = Blather Client
+  #
+  # Blather's Client class provides a set of helpers for working with common XMPP tasks such as setting up and starting
+  # the connection, settings status, registering and dispatching filters and handlers and roster management.
+  #
+  # Client can be used separately from the DSL if you'd like to implement your own DSL
+  # Here's the echo example using the client without the DSL:
+  #
+  #   require 'blather/client/client'
+  #   client = Client.setup 'echo@jabber.local', 'echo'
+  #
+  #   client.register_handler(:ready) { puts "Connected ! send messages to #{client.jid.stripped}." }
+  #
+  #   client.register_handler :subscription, :request? do |s|
+  #     client.write s.approve!
+  #   end
+  #
+  #   client.register_handler :message, :chat?, :body => 'exit' do |m|
+  #     client.write Blather::Stanza::Message.new(m.from, 'Exiting...')
+  #     client.close
+  #   end
+  #
+  #   client.register_handler :message, :chat?, :body do |m|
+  #     client.write Blather::Stanza::Message.new(m.from, "You sent: #{m.body}")
+  #   end
+  #
+  class Client
     attr_reader :jid,
                 :roster
 
-    def initialize
+    ##
+    # Initialize and setup the client
+    # * +jid+ - the JID to login with
+    # * +password+ - password associated with the JID
+    # * +host+ - hostname or IP to connect to. If nil the stream will look one up based on the domain in the JID
+    # * +port+ - port to connect to
+    def self.setup(jid, password, host = nil, port = nil)
+      self.new.setup(jid, password, host, port)
+    end
+
+    def initialize # :nodoc:
       @state = :initializing
 
       @status = Stanza::Presence::Status.new
       @handlers = {}
       @tmp_handlers = {}
+      @filters = {:before => [], :after => []}
       @roster = Roster.new self
 
       setup_initial_handlers
     end
 
-    def jid=(new_jid)
-      @jid = JID.new new_jid
-    end
-
+    ##
+    # Get the current status. Taken from the +state+ attribute of Status
     def status
       @status.state
     end
 
+    ##
+    # Set the status. Status can be set with either a single value or an array containing
+    # [state, message, to].
     def status=(state)
       state, msg, to = state
 
@@ -35,77 +73,121 @@ module Blather #:nodoc:
       write status
     end
 
-    def setup?
-      @setup.is_a? Array
-    end
-
-    def setup(jid, password, host = nil, port = nil)
-      @jid = JID.new(jid)
-      @setup = [@jid, password]
-      @setup << host if host
-      @setup << port if port
-      self
-    end
-
+    ##
+    # Start the connection.
     def run
       raise 'not setup!' unless setup?
       klass = @setup[0].node ? Blather::Stream::Client : Blather::Stream::Component
       @stream = klass.start self, *@setup
     end
 
+    ##
+    # Register a filter to be run before or after the handler chain is run.
+    # * +type+ - the type of filter. Must be +:before+ or +:after+
+    # * +guards+ - guards that should be checked before the filter is called
+    def register_filter(type, handler = nil, *guards, &filter)
+      raise "Invalid filter: #{type}. Must be :before or :after" unless [:before, :after].include?(type)
+      @filters[type] << [guards, handler, filter]
+    end
+
+    ##
+    # Register a temporary handler. Temporary handlers are based on the ID of the JID and live 
+    # only until a stanza with said ID is received. 
+    # * +id+ - the ID of the stanza that should be handled
     def register_tmp_handler(id, &handler)
       @tmp_handlers[id] = handler
     end
 
+    ##
+    # Register a handler
+    # * +type+ - the handler type. Should be registered in Stanza.handler_list. Blather will log a warning if it's not.
+    # * +guards+ - the list of guards that must be verified before the handler will be called
     def register_handler(type, *guards, &handler)
-      check_guards guards
+      check_handler type, guards
       @handlers[type] ||= []
       @handlers[type] << [guards, handler]
     end
 
+    ##
+    # Write data to the stream
     def write(stanza)
       @stream.send(stanza) if @stream
     end
 
+    ##
+    # Helper that will create a temporary handler for the stanza being sent before writing it to the stream.
+    #
+    #   client.write_with_handler(stanza) { |s| "handle stanza here" }
+    #
+    # is equivalent to:
+    #
+    #   client.register_tmp_handler(stanza.id) { |s| "handle stanza here" }
+    #   client.write stanza
     def write_with_handler(stanza, &handler)
       register_tmp_handler stanza.id, &handler
       write stanza
     end
 
-    def post_init
-      self.jid.node ? client_post_init : ready!
-    end
-
+    ##
+    # Close the connection
     def close
       @stream.close_connection_after_writing
     end
 
-    def unbind
+    def post_init # :nodoc:
+      self.jid.node ? client_post_init : ready!
+    end
+
+    def unbind # :nodoc:
       EM.stop if EM.reactor_running?
     end
 
-    def receive_data(stanza)
-      if handler = @tmp_handlers.delete(stanza.id)
-        handler.call stanza
-      else
-        stanza.handler_heirarchy.each do |type|
-          break if call_handler_for(type, stanza)# && (stanza.is_a?(BlatherError) || stanza.type == :iq)
-        end
+    def receive_data(stanza) # :nodoc:
+      catch(:halt) do
+        run_filters :before, stanza
+        handle_stanza stanza
+        run_filters :after, stanza
       end
     end
 
+    def jid=(new_jid) # :nodoc :
+      @jid = JID.new new_jid
+    end
+
+    def setup? # :nodoc:
+      @setup.is_a? Array
+    end
+
+    def setup(jid, password, host = nil, port = nil) # :nodoc:
+      @jid = JID.new(jid)
+      @setup = [@jid, password]
+      @setup << host if host
+      @setup << port if port
+      self
+    end
+
   protected
-    def setup_initial_handlers
+    def check_handler(type, guards)
+      Blather.logger.warn "Handler for type \"#{type}\" will never be called as it's not a registered type" unless current_handlers.include?(type)
+      check_guards guards
+    end
+
+    def current_handlers
+      [:ready] + Stanza.handler_list + BlatherError.handler_list
+    end
+
+    def setup_initial_handlers # :nodoc:
       register_handler :error do |err|
         raise err
       end
 
       register_handler :iq, :type => [:get, :set] do |iq|
-        write(StanzaError.new(iq, 'service-unavailable', :cancel).to_node)
+        write StanzaError.new(iq, 'service-unavailable', :cancel).to_node
       end
 
       register_handler :status do |status|
         roster[status.from].status = status if roster[status.from]
+        nil
       end
 
       register_handler :roster do |node|
@@ -113,12 +195,12 @@ module Blather #:nodoc:
       end
     end
 
-    def ready!
+    def ready! # :nodoc:
       @state = :ready
       call_handler_for :ready, nil
     end
 
-    def client_post_init
+    def client_post_init # :nodoc:
       write_with_handler Stanza::Iq::Roster.new do |node|
         roster.process node
         write @status
@@ -126,25 +208,43 @@ module Blather #:nodoc:
       end
     end
 
-    def call_handler_for(type, stanza)
-      if @handlers[type]
-        @handlers[type].find do |guards, handler|
-          if guards.first.is_a?(String)
-            unless (result = stanza.find(*guards)).empty?
-              handler.call(stanza, result)
-            end
-          elsif !guarded?(guards, stanza)
-            handler.call(stanza)
-          end
+    def run_filters(type, stanza) # :nodoc:
+      @filters[type].each do |guards, handler, filter|
+        next if handler && !stanza.handler_heirarchy.include?(handler)
+        catch(:pass) { call_handler filter, guards, stanza }
+      end
+    end
+
+    def handle_stanza(stanza) # :nodoc:
+      if handler = @tmp_handlers.delete(stanza.id)
+        handler.call stanza
+      else
+        stanza.handler_heirarchy.each do |type|
+          break if call_handler_for(type, stanza)
         end
       end
     end
 
+    def call_handler_for(type, stanza) # :nodoc:
+      return unless handler = @handlers[type]
+      handler.find do |guards, handler|
+        catch(:pass) { call_handler handler, guards, stanza }
+      end
+    end
+
+    def call_handler(handler, guards, stanza) # :nodoc:
+      if guards.first.respond_to?(:to_str) && !(result = stanza.find(*guards)).empty?
+        handler.call(stanza, result)
+      elsif !guarded?(guards, stanza)
+        handler.call(stanza)
+      end
+    end
+
     ##
     # If any of the guards returns FALSE this returns true
     # the logic is reversed to allow short circuiting
     # (why would anyone want to loop over more values than necessary?)
-    def guarded?(guards, stanza)
+    def guarded?(guards, stanza) # :nodoc:
       guards.find do |guard|
         case guard
         when Symbol
@@ -156,10 +256,9 @@ module Blather #:nodoc:
           # return FALSE unless any inequality is found
           guard.find do |method, test|
             value = stanza.__send__(method)
-            case test
-            when Regexp
-              !value.to_s.match(test)
-            when Array
+            if test.class.respond_to?(:last_match)
+              !(test =~ value)
+            elsif test.is_a?(Array)
               !test.include? value
             else
               test != value
@@ -171,7 +270,7 @@ module Blather #:nodoc:
       end
     end
 
-    def check_guards(guards)
+    def check_guards(guards) # :nodoc:
       guards.each do |guard|
         case guard
         when Array

data/lib/blather/client/dsl.rb

@@ -38,6 +38,18 @@ module Blather
       client.close
     end
 
+    ##
+    # Setup a before filter
+    def before(handler = nil, *guards, &block)
+      client.register_filter :before, handler, *guards, &block
+    end
+
+    ##
+    # Setup an after filter
+    def after(handler = nil, *guards, &block)
+      client.register_filter :after, handler, *guards, &block
+    end
+
     ##
     # Set handler for a stanza type
     def handle(stanza_type, *guards, &block)
@@ -82,6 +94,18 @@ module Blather
       client.jid
     end
 
+    ##
+    # Halt the handler chain
+    def halt
+      throw :halt
+    end
+
+    ##
+    # Pass responsibility to the next handler
+    def pass
+      throw :pass
+    end
+
     ##
     # Request items or info from an entity
     #   discover (items|info), [jid], [node] do |response|

data/lib/blather/client/dsl/pubsub.rb

@@ -27,7 +27,7 @@ module DSL
     ##
     # Discover Nodes
     # Yields a list of DiscoItem::Item objects
-    #   +path+ is the node's path. Default is '/'
+    # * +path+ is the node's path. Default is '/'
     def nodes(path = nil, host = nil, &callback)
       path ||= '/'
       stanza = Stanza::DiscoItems.new(:get, path)
@@ -38,7 +38,7 @@ module DSL
     ##
     # Discover node information
     # Yields a DiscoInfo node
-    #   +path+ is the node's path
+    # * +path+ is the node's path
     def node(path, host = nil, &callback)
       stanza = Stanza::DiscoInfo.new(:get, path)
       stanza.to = send_to(host)
@@ -47,9 +47,9 @@ module DSL
 
     ##
     # Retrieve items for a node
-    #   +path+ is the node's path
-    #   +list+ can be an array of items to retrieve
-    #   +max+ can be the maximum number of items to return
+    # * +path+ is the node's path
+    # * +list+ can be an array of items to retrieve
+    # * +max+ can be the maximum number of items to return
     def items(path, list = [], max = nil, host = nil, &callback)
       request Stanza::PubSub::Items.request(send_to(host), path, list, max), :items, callback
     end
@@ -57,8 +57,8 @@ module DSL
     ##
     # Subscribe to a node
     # Yields the resulting Subscription object
-    #   +node+ is the node to subscribe to
-    #   +jid+ is the jid that should be used. Defaults to the stripped current JID
+    # * +node+ is the node to subscribe to
+    # * +jid+ is the jid that should be used. Defaults to the stripped current JID
     def subscribe(node, jid = nil, host = nil)
       jid ||= DSL.client.jid.stripped
       request(Stanza::PubSub::Subscribe.new(:set, send_to(host), node, jid)) { |n| yield n if block_given? }
@@ -67,8 +67,8 @@ module DSL
     ##
     # Unsubscribe from a node
     # Yields the resulting Unsubscribe object
-    #   +node+ is the node to subscribe to
-    #   +jid+ is the jid that should be used. Defaults to the stripped current JID
+    # * +node+ is the node to subscribe to
+    # * +jid+ is the jid that should be used. Defaults to the stripped current JID
     def unsubscribe(node, jid = nil, host = nil)
       jid ||= DSL.client.jid.stripped
       request(Stanza::PubSub::Unsubscribe.new(:set, send_to(host), node, jid)) { |n| yield n if block_given? }
@@ -77,8 +77,8 @@ module DSL
     ##
     # Publish an item to a node
     # Yields the resulting Publish node
-    #   +node+ is the node to publish to
-    #   +payload+ is the payload to send (see Blather::Stanza::PubSub::Publish for details)
+    # * +node+ is the node to publish to
+    # * +payload+ is the payload to send (see Blather::Stanza::PubSub::Publish for details)
     def publish(node, payload, host = nil)
       request(Stanza::PubSub::Publish.new(send_to(host), node, :set, payload)) { |n| yield n if block_given? }
     end
@@ -86,8 +86,8 @@ module DSL
     ##
     # Delete items from a node
     # Yields the resulting node
-    #   +node+ is the node to retract items from
-    #   +ids+ is a list of ids to retract. This can also be a single id
+    # * +node+ is the node to retract items from
+    # * +ids+ is a list of ids to retract. This can also be a single id
     def retract(node, ids = [], host = nil)
       request(Stanza::PubSub::Retract.new(send_to(host), node, :set, ids)) { |n| yield n if block_given? }
     end
@@ -96,7 +96,7 @@ module DSL
     # Create a node
     # Yields the resulting node
     # This does not (yet) handle configuration
-    #   +node+ is the node to create
+    # * +node+ is the node to create
     def create(node, host = nil)
       request(Stanza::PubSub::Create.new(:set, send_to(host), node)) { |n| yield n if block_given? }
     end
@@ -104,7 +104,7 @@ module DSL
     ##
     # Purge all node items
     # Yields the resulting node
-    #   +node+ is the node to purge
+    # * +node+ is the node to purge
     def purge(node, host = nil)
       request(Stanza::PubSubOwner::Purge.new(:set, send_to(host), node)) { |n| yield n if block_given? }
     end
@@ -112,7 +112,7 @@ module DSL
     ##
     # Delete a node
     # Yields the resulting node
-    #   +node+ is the node to delete
+    # * +node+ is the node to delete
     def delete(node, host = nil)
       request(Stanza::PubSubOwner::Delete.new(:set, send_to(host), node)) { |n| yield n if block_given? }
     end