blather 0.4.7 → 0.4.8

data/README.md

@@ -0,0 +1,162 @@
+# Blather
+
+XMPP DSL (and more) for Ruby written on EventMachine and Nokogiri.
+
+## Features
+
+* evented architecture
+* uses Nokogiri
+* simplified starting point
+
+## Project Pages
+
+* [Docs](http://blather.squishtech.com)
+* [GitHub](https://github.com/sprsquish/blather)
+* [Gemcutter](http://gemcutter.org/gems/blather)
+* [Google Group](http://groups.google.com/group/xmpp-blather)
+
+# Usage
+
+## Installation
+
+    sudo gem install blather
+
+## Example
+
+See the examples directory for more advanced examples.
+
+This will auto-accept any subscription requests and echo back any chat messages.
+
+    require 'rubygems'
+    require 'blather/client'
+
+    setup 'echo@jabber.local', 'echo'
+
+    # Auto approve subscription requests
+    subscription :request? do |s|
+      write_to_stream s.approve!
+    end
+
+    # Echo back what was said
+    message :chat?, :body do |m|
+      write_to_stream m.reply
+    end
+
+## Handlers
+
+Setup handlers by calling their names as methods.
+
+    # Will only be called for messages where #chat? responds positively
+    # and #body == 'exit'
+    message :chat?, :body => 'exit'
+
+### Non-Stanza Handlers
+
+So far there are two non-stanza related handlers.
+
+    # Called after the connection has been connected. It's good for initializing
+    # your system.
+    # DSL:
+    when_ready {}
+    # Client:
+    client.register_handler(:ready) {}
+
+    # Called after the connection has been terminated. Good for teardown or
+    # automatic reconnection.
+    # DSL:
+    disconnected {}
+    # Client
+    client.register_handler(:disconnected) {}
+    # The following will reconnect every time the connection is lost:
+    disconnected { client.connect }
+
+### Handler Guards
+
+Guards act like AND statements. Each condition must be met if the handler is to
+be used.
+
+    # Equivalent to saying (stanza.chat? && stanza.body)
+    message :chat?, :body
+
+The different types of guards are:
+
+    # Symbol
+    #   Checks for a non-false reply to calling the symbol on the stanza
+    #   Equivalent to stanza.chat?
+    message :chat?
+
+    # Hash with any value (:body => 'exit')
+    #   Calls the key on the stanza and checks for equality
+    #   Equivalent to stanza.body == 'exit'
+    message :body => 'exit'
+
+    # Hash with regular expression (:body => /exit/)
+    #   Calls the key on the stanza and checks for a match
+    #   Equivalent to stanza.body.match /exit/
+    message :body => /exit/
+
+    # Hash with array (:name => [:gone, :forbidden])
+    #   Calls the key on the stanza and check for inclusion in the array
+    #   Equivalent to [:gone, :forbidden].include?(stanza.name)
+    stanza_error :name => [:gone, :fobidden]
+
+    # Proc
+    #   Calls the proc passing in the stanza
+    #   Checks that the ID is modulo 3
+    message proc { |m| m.id % 3 == 0 }
+
+    # Array
+    #   Use arrays with the previous types effectively turns the guard into
+    #   an OR statement.
+    #   Equivalent to stanza.body == 'foo' || stanza.body == 'baz'
+    message [{:body => 'foo'}, {:body => 'baz'}]
+
+    # XPath
+    #   Runs the xpath query on the stanza and checks for results
+    #   This guard type cannot be combined with other guards
+    #   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:
+
+    [blather_script] [options] node@domain.com/resource password [host] [port]
+
+Command line options:
+
+    -D, --debug       Run in debug mode (you will see all XMPP communication)
+    -d, --daemonize   Daemonize the process
+        --pid=[PID]   Write the PID to this file
+        --log=[LOG]   Write to the [LOG] file instead of stdout/stderr
+    -h, --help        Show this message
+    -v, --version     Show version
+
+
+# Author
+
+[Jeff Smick](http://github.com/sprsquish)
+
+### Contributors
+
+[Nolan Darilek](http://github.com/thewordnerd)
+
+# Copyright
+
+Copyright (c) 2009 Jeff Smick. See LICENSE for details.

data/examples/{print_heirarchy.rb → print_hierarchy.rb}

@@ -8,7 +8,7 @@ class Object
     # We check defined? in case we find a removed class that has yet to be
     # garbage collected. This also fails for anonymous classes -- please
     # submit a patch if you have a workaround.
-    def subclasses_of(*superclasses) #:nodoc:
+    def subclasses_of(*superclasses)
       subclasses = []
 
       superclasses.each do |sup|
@@ -24,7 +24,7 @@ class Object
   rescue RuntimeError
     # JRuby and any implementations which cannot handle the objectspace traversal
     # above fall back to this implementation
-    def subclasses_of(*superclasses) #:nodoc:
+    def subclasses_of(*superclasses)
       subclasses = []
 
       superclasses.each do |sup|
@@ -52,7 +52,7 @@ end
 
 handlers = {}
 (Object.subclasses_of(Blather::Stanza) + Object.subclasses_of(Blather::BlatherError)).each do |klass|
-  handlers = handlers.deep_merge klass.handler_heirarchy.inject('klass' => klass.to_s.gsub('Blather::', '')) { |h,k| {k.to_s => h} }
+  handlers = handlers.deep_merge klass.handler_hierarchy.inject('klass' => klass.to_s.gsub('Blather::', '')) { |h,k| {k.to_s => h} }
 end
 
 level = 0
@@ -61,8 +61,8 @@ runner = proc do |k,v|
 
   str = ''
   if level > 0
-    (level - 1).times { str << '|   ' }
-    str << '|-- '
+    (level - 1).times { str << '|  ' }
+    str << '|- '
   end
 
   puts str+k

data/examples/stream_only.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require 'blather'
+
+trap(:INT) { EM.stop }
+trap(:TERM) { EM.stop }
+EM.run do
+  Blather::Stream::Client.start(Class.new {
+    attr_accessor :jid
+
+    def post_init(stream, jid = nil)
+      @stream = stream
+      self.jid = jid
+
+      @stream.send_data Blather::Stanza::Presence::Status.new
+      puts "Stream started!"
+    end
+
+    def receive_data(stanza)
+      @stream.send_data stanza.reply!
+    end
+
+    def unbind
+      puts "Stream ended!"
+    end
+  }.new, 'echo@jabber.local', 'echo')
+end

data/lib/blather.rb

@@ -58,7 +58,10 @@
 ].each { |r| require r }
 
 module Blather
+  # @private
   @@logger = nil
+
+  # Get or create an instance of Logger
   def self.logger
     unless @@logger
       self.logger = Logger.new($stdout)
@@ -67,6 +70,7 @@ module Blather
     @@logger
   end
 
+  # Set the Logger
   def self.logger=(logger)
     @@logger = logger
   end

data/lib/blather/client/client.rb

@@ -1,48 +1,54 @@
 require File.join(File.dirname(__FILE__), *%w[.. .. blather])
 
-module Blather #:nodoc:
-
-  # = Blather Client
+module Blather
+  # # 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.
+  # 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:
+  # 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'
+  #     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(:ready) do
+  #       puts "Connected ! send messages to #{client.jid.stripped}."
+  #     end
   #
-  #   client.register_handler :subscription, :request? do |s|
-  #     client.write s.approve!
-  #   end
+  #     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 => '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
+  #     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
 
-    ##
-    # 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
+    # Create a new client and set it up
+    #
+    # @param [Blather::JID, #to_s] jid the JID to authorize with
+    # @param [String] password the password to authorize with
+    # @param [String] host if this isn't set it'll be resolved off the JID's
+    # domain
+    # @param [Fixnum, String] port the port to connect to.
+    #
+    # @return [Blather::Client]
     def self.setup(jid, password, host = nil, port = nil)
       self.new.setup(jid, password, host, port)
     end
 
-    def initialize # :nodoc:
+    def initialize  # @private
       @state = :initializing
 
       @status = Stanza::Presence::Status.new
@@ -54,14 +60,14 @@ module Blather #:nodoc:
       setup_initial_handlers
     end
 
-    ##
-    # Get the current status. Taken from the +state+ attribute of Status
+    # 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
+    # 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
@@ -73,8 +79,10 @@ module Blather #:nodoc:
       write status
     end
 
-    ##
     # Start the connection.
+    #
+    # The stream type used is based on the JID. If a node exists it uses
+    # Blather::Stream::Client otherwise Blather::Stream::Component
     def run
       raise 'not setup!' unless setup?
       klass = @setup[0].node ? Blather::Stream::Client : Blather::Stream::Component
@@ -82,70 +90,79 @@ module Blather #:nodoc:
     end
     alias_method :connect, :run
 
-    ##
     # 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
+    #
+    # @param [<:before, :after>] type the filter type
+    # @param [Symbol, nil] handler set the filter on a specific handler
+    # @param [guards] guards take a look at the guards documentation
+    # @yield [Blather::Stanza] stanza the incomming stanza
     def register_filter(type, handler = nil, *guards, &filter)
-      raise "Invalid filter: #{type}. Must be :before or :after" unless [:before, :after].include?(type)
+      unless [:before, :after].include?(type)
+        raise "Invalid filter: #{type}. Must be :before or :after"
+      end
       @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
+    # 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.
+    #
+    # @param [#to_s] id the ID of the stanza that should be handled
+    # @yield [Blather::Stanza] stanza the incomming stanza
     def register_tmp_handler(id, &handler)
-      @tmp_handlers[id] = handler
+      @tmp_handlers[id.to_s] = 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
+    #
+    # @param [Symbol, nil] handler set the filter on a specific handler
+    # @param [guards] guards take a look at the guards documentation
+    # @yield [Blather::Stanza] stanza the incomming stanza
     def register_handler(type, *guards, &handler)
       check_handler type, guards
       @handlers[type] ||= []
       @handlers[type] << [guards, handler]
     end
 
-    ##
     # Write data to the stream
+    #
+    # @param [#to_xml, #to_s] stanza the content to send down the wire
     def write(stanza)
       self.stream.send(stanza)
     end
 
-    ##
-    # Helper that will create a temporary handler for the stanza being sent before writing it to the stream.
+    # 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" }
+    #     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
+    #     client.register_tmp_handler(stanza.id) { |s| "handle stanza here" }
+    #     client.write stanza
+    #
+    # @param [Blather::Stanza] stanza the stanza to send down the wire
+    # @yield [Blather::Stanza] stanza the reply stanza
     def write_with_handler(stanza, &handler)
       register_tmp_handler stanza.id, &handler
       write stanza
     end
 
-    ##
     # Close the connection
     def close
       self.stream.close_connection_after_writing
     end
 
-    def post_init(stream, jid = nil) # :nodoc:
+    def post_init(stream, jid = nil)  # @private
       @stream = stream
       @jid = JID.new(jid) if jid
       self.jid.node ? client_post_init : ready!
     end
 
-    def unbind # :nodoc:
+    def unbind  # @private
       call_handler_for(:disconnected, nil) || (EM.reactor_running? && EM.stop)
     end
 
-    def receive_data(stanza) # :nodoc:
+    def receive_data(stanza)  # @private
       catch(:halt) do
         run_filters :before, stanza
         handle_stanza stanza
@@ -153,11 +170,11 @@ module Blather #:nodoc:
       end
     end
 
-    def setup? # :nodoc:
+    def setup?  # @private
       @setup.is_a? Array
     end
 
-    def setup(jid, password, host = nil, port = nil) # :nodoc:
+    def setup(jid, password, host = nil, port = nil)  # @private
       @jid = JID.new(jid)
       @setup = [@jid, password]
       @setup << host if host
@@ -166,20 +183,20 @@ module Blather #:nodoc:
     end
 
   protected
-    def stream
+    def stream  # @private
       @stream || raise('Stream not ready!')
     end
 
-    def check_handler(type, guards)
+    def check_handler(type, guards)  # @private
       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
+    def current_handlers  # @private
       [:ready, :disconnected] + Stanza.handler_list + BlatherError.handler_list
     end
 
-    def setup_initial_handlers # :nodoc:
+    def setup_initial_handlers  # @private
       register_handler :error do |err|
         raise err
       end
@@ -198,12 +215,12 @@ module Blather #:nodoc:
       end
     end
 
-    def ready! # :nodoc:
+    def ready!  # @private
       @state = :ready
       call_handler_for :ready, nil
     end
 
-    def client_post_init # :nodoc:
+    def client_post_init  # @private
       write_with_handler Stanza::Iq::Roster.new do |node|
         roster.process node
         write @status
@@ -211,31 +228,31 @@ module Blather #:nodoc:
       end
     end
 
-    def run_filters(type, stanza) # :nodoc:
+    def run_filters(type, stanza)  # @private
       @filters[type].each do |guards, handler, filter|
-        next if handler && !stanza.handler_heirarchy.include?(handler)
+        next if handler && !stanza.handler_hierarchy.include?(handler)
         catch(:pass) { call_handler filter, guards, stanza }
       end
     end
 
-    def handle_stanza(stanza) # :nodoc:
+    def handle_stanza(stanza)  # @private
       if handler = @tmp_handlers.delete(stanza.id)
         handler.call stanza
       else
-        stanza.handler_heirarchy.each do |type|
+        stanza.handler_hierarchy.each do |type|
           break if call_handler_for(type, stanza)
         end
       end
     end
 
-    def call_handler_for(type, stanza) # :nodoc:
+    def call_handler_for(type, stanza)  # @private
       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:
+    def call_handler(handler, guards, stanza)  # @private
       if guards.first.respond_to?(:to_str)
         result = stanza.find(*guards)
         handler.call(stanza, result) unless result.empty?
@@ -244,11 +261,12 @@ module Blather #:nodoc:
       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) # :nodoc:
+    #
+    # @private
+    def guarded?(guards, stanza)
       guards.find do |guard|
         case guard
         when Symbol
@@ -275,7 +293,7 @@ module Blather #:nodoc:
       end
     end
 
-    def check_guards(guards) # :nodoc:
+    def check_guards(guards)  # @private
       guards.each do |guard|
         case guard
         when Array
@@ -287,6 +305,6 @@ module Blather #:nodoc:
         end
       end
     end
+  end  # Client
 
-  end #Client
-end #Blather
+end  # Blather