blather 0.4.7 → 0.4.8

data/lib/blather/client/dsl.rb

@@ -1,121 +1,248 @@
 require File.join(File.dirname(__FILE__), 'client')
 
 module Blather
+
+  # # Blather DSL
+  #
+  # The DSL is a set of methods that enables you to write cleaner code. Being a
+  # module means it can be included in or extend any class you may want to
+  # create.
+  #
+  # Every stanza handler is registered as a method on the DSL.
+  #
+  # @example Include the DSL in the top level namespace.
+  #
+  #     require 'blather/client'
+  #     when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #     subscription :request? do |s|
+  #       write_to_stream s.approve!
+  #     end
+  #
+  #     message :chat?, :body => 'exit' do |m|
+  #       say m.from, 'Exiting ...'
+  #       shutdown
+  #     end
+  #
+  #     message :chat?, :body do |m|
+  #       say m.from, "You sent: #{m.body}"
+  #     end
+  #
+  # @example Set the DSL to its own namespace.
+  #
+  #     require 'blather/client/dsl'
+  #     module Echo
+  #       extend Blather::DSL
+  #       def self.run
+  #         client.run
+  #       end
+  #
+  #       when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #       subscription :request? do |s|
+  #         write_to_stream s.approve!
+  #       end
+  #
+  #       message :chat?, :body => 'exit' do |m|
+  #         say m.from, 'Exiting ...'
+  #         shutdown
+  #       end
+  #
+  #       message :chat?, :body do |m|
+  #         say m.from, "You sent: #{m.body}"
+  #       end
+  #     end
+  #
+  #     EM.run { Echo.run }
+  #
+  # @example Create a class out of it
+  #
+  #     require 'blather/client/dsl'
+  #     class Echo
+  #       include Blather::DSL
+  #     end
+  #
+  #     echo = Echo.new
+  #     echo.when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #     echo.subscription :request? do |s|
+  #       write_to_stream s.approve!
+  #     end
+  #
+  #     echo.message :chat?, :body => 'exit' do |m|
+  #       say m.from, 'Exiting ...'
+  #       shutdown
+  #     end
+  #
+  #     echo.message :chat?, :body do |m|
+  #       say m.from, "You sent: #{m.body}"
+  #     end
+  #
+  #     EM.run { echo.client.run }
   module DSL
 
     autoload :PubSub, File.expand_path(File.join(File.dirname(__FILE__), *%w[dsl pubsub]))
 
+    # The actual client connection
+    #
+    # @return [Blather::Client]
     def client
       @client ||= Client.new
     end
     module_function :client
 
+    # A pubsub helper
+    #
+    # @return [Blather::PubSub]
     def pubsub
       @pubsub ||= PubSub.new client, jid.domain
     end
 
-    ##
     # Push data to the stream
     # This works such that it can be chained:
-    #   self << stanza1 << stanza2 << "raw data"
+    #     self << stanza1 << stanza2 << "raw data"
+    #
+    # @param [#to_xml, #to_s] stanza data to send down the wire
+    # @return [self]
     def <<(stanza)
       client.write stanza
       self
     end
 
-    ##
     # Prepare server settings
-    #   setup [node@domain/resource], [password], [host], [port]
-    # host and port are optional defaulting to the domain in the JID and 5222 respectively
+    #
+    # @param [#to_s] jid the JID to authenticate with
+    # @param [#to_s] password the password to authenticate with
+    # @param [String] host (optional) the host to connect to (can be an IP). If
+    # this is `nil` the domain on the JID will be used
+    # @param [Fixnum, String] (optional) port the port to connect on
     def setup(jid, password, host = nil, port = nil)
       client.setup(jid, password, host, port)
     end
 
-    ##
     # Shutdown the connection.
     # Flushes the write buffer then stops EventMachine
     def shutdown
       client.close
     end
 
-    ##
     # Setup a before filter
+    #
+    # @param [Symbol] handler (optional) the stanza handler the filter should
+    # run before
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
     def before(handler = nil, *guards, &block)
       client.register_filter :before, handler, *guards, &block
     end
 
-    ##
     # Setup an after filter
+    #
+    # @param [Symbol] handler (optional) the stanza handler the filter should
+    # run after
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
     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)
-      client.register_handler stanza_type, *guards, &block
+    #
+    # @param [Symbol] handler the stanza type it should handle
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
+    def handle(handler, *guards, &block)
+      client.register_handler handler, *guards, &block
     end
 
-    ##
     # Wrapper for "handle :ready" (just a bit of syntactic sugar)
+    #
+    # This is run after the connection has been completely setup
     def when_ready(&block)
       handle :ready, &block
     end
 
-    ##
     # Wrapper for "handle :disconnected"
+    #
+    # This is run after the connection has been shut down.
+    #
+    # @example Reconnect after a disconnection
+    #     disconnected { client.run }
     def disconnected(&block)
       handle :disconnected, &block
     end
 
-    ##
     # Set current status
+    #
+    # @param [Blather::Stanza::Presence::State::VALID_STATES] state the current
+    # state
+    # @param [#to_s] msg the status message to use
     def set_status(state = nil, msg = nil)
       client.status = state, msg
     end
 
-    ##
     # Direct access to the roster
+    #
+    # @return [Blather::Roster]
     def my_roster
       client.roster
     end
 
-    ##
     # Write data to the stream
-    # Anything that resonds to #to_s can be paseed to the stream
+    #
+    # @param [#to_xml, #to_s] stanza the data to send down the wire.
     def write_to_stream(stanza)
       client.write stanza
     end
 
-    ##
     # Helper method to make sending basic messages easier
-    #   say [jid], [msg]
+    #
+    # @param [Blather::JID, #to_s] to the JID of the message recipient
+    # @param [#to_s] msg the message to send
     def say(to, msg)
       client.write Blather::Stanza::Message.new(to, msg)
     end
 
-    ##
-    # Wrapper to grab the current JID
+    # The JID according to the server
+    #
+    # @return [Blather::JID]
     def jid
       client.jid
     end
 
-    ##
     # Halt the handler chain
+    #
+    # Use this to stop the propogation of the stanza though the handler chain.
+    #
+    # @example
+    # Ignore all IQ stanzas
+    #
+    #     before(:iq) { halt }
     def halt
       throw :halt
     end
 
-    ##
     # Pass responsibility to the next handler
+    #
+    # Use this to jump out of the current handler and let the next registered
+    # handler take care of the stanza
+    #
+    # @example
+    # This is contrive and should be handled with guards, but pass a message
+    # to the next handler based on the content
+    #
+    #     message { |s| puts "message caught" }
+    #     message { |s| pass if s.body =~ /pass along/ }
     def pass
       throw :pass
     end
 
-    ##
     # Request items or info from an entity
-    #   discover (items|info), [jid], [node] do |response|
-    #   end
+    #     discover (items|info), [jid], [node] do |response|
+    #     end
     def discover(what, who, where, &callback)
       stanza = Blather::Stanza.class_from_registration(:query, "http://jabber.org/protocol/disco##{what}").new
       stanza.to = who
@@ -125,10 +252,7 @@ module Blather
       client.write stanza
     end
 
-    ##
-    # Checks to see if the method is part of the handlers list.
-    # If so it creates a handler, otherwise it'll pass it back
-    # to Ruby's method_missing handler
+    # Generate a method for every stanza handler that exists.
     Blather::Stanza.handler_list.each do |handler_name|
       module_eval <<-METHOD, __FILE__, __LINE__
         def #{handler_name}(*args, &callback)
@@ -136,5 +260,5 @@ module Blather
         end
       METHOD
     end
-  end #DSL
-end #Blather
+  end  # DSL
+end  # Blather

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

@@ -4,31 +4,36 @@ module DSL
   class PubSub
     attr_accessor :host
 
+    # Create a new pubsub DSL
+    #
+    # @param [Blather::Client] client the client who's connection will be used
+    # @param [#to_s] host the PubSub host
     def initialize(client, host)
       @client = client
       @host = host
     end
 
-    ##
     # Retrieve Affiliations
-    # Yields a hash of affiliations in the form:
-    #   {:aff_type => ['node1', 'node2']}
+    #
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Hash] affiliations See {Blather::Stanza::PubSub::Affiliations#list}
     def affiliations(host = nil, &callback)
       request Stanza::PubSub::Affiliations.new(:get, send_to(host)), :list, callback
     end
 
-    ##
     # Retrieve Subscriptions
-    # Yields a hash of subscriptions in the form:
-    #   {:sub_type => [{:node => 'node1', :jid => 'j@d'}]}
+    #
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Hash] affiliations See {Blather::Stanza::PubSub::Subscriptions#list}
     def subscriptions(host = nil, &callback)
       request Stanza::PubSub::Subscriptions.new(:get, send_to(host)), :list, callback
     end
 
-    ##
     # Discover Nodes
-    # Yields a list of DiscoItem::Item objects
-    # * +path+ is the node's path. Default is '/'
+    #
+    # @param [#to_s] path the node path
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Array<Blather::Stanza::DiscoItems::Item>] items
     def nodes(path = nil, host = nil, &callback)
       path ||= '/'
       stanza = Stanza::DiscoItems.new(:get, path)
@@ -36,91 +41,118 @@ module DSL
       request stanza, :items, callback
     end
 
-    ##
     # Discover node information
-    # Yields a DiscoInfo node
-    # * +path+ is the node's path
+    #
+    # @param [#to_s] path the node path
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza::DiscoInfo>] info
     def node(path, host = nil, &callback)
       stanza = Stanza::DiscoInfo.new(:get, path)
       stanza.to = send_to(host)
       request stanza, nil, callback
     end
 
-    ##
     # 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
+    #
+    # @param [#to_s] path the node path
+    # @param [Array<#to_s>] list a list of IDs to retrieve
+    # @param [Fixnum, #to_s] max the maximum number of items to return
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Array<Blather::Stanza::PubSub::PubSubItem>] items see {Blather::Stanza::PubSub::Items#items}
     def items(path, list = [], max = nil, host = nil, &callback)
-      request Stanza::PubSub::Items.request(send_to(host), path, list, max), :items, callback
+      request(
+        Stanza::PubSub::Items.request(send_to(host), path, list, max),
+        :items,
+        callback
+      )
     end
 
-    ##
     # 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
+    #
+    # @param [#to_s] node the node to subscribe to
+    # @param [Blather::JID, #to_s] jid is the jid that should be used.
+    # Defaults to the stripped current JID
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def subscribe(node, jid = nil, host = nil)
       jid ||= client.jid.stripped
-      request(Stanza::PubSub::Subscribe.new(:set, send_to(host), node, jid)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSub::Subscribe.new(:set, send_to(host), node, jid)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # 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
+    #
+    # @param [#to_s] node the node to unsubscribe from
+    # @param [Blather::JID, #to_s] jid is the jid that should be used.
+    # Defaults to the stripped current JID
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def unsubscribe(node, jid = nil, host = nil)
       jid ||= client.jid.stripped
-      request(Stanza::PubSub::Unsubscribe.new(:set, send_to(host), node, jid)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSub::Unsubscribe.new(:set, send_to(host), node, jid)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # 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)
+    #
+    # @param [#to_s] node the node to publish to
+    # @param [#to_s] payload the payload to send see {Blather::Stanza::PubSub::Publish}
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def publish(node, payload, host = nil)
-      request(Stanza::PubSub::Publish.new(send_to(host), node, :set, payload)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSub::Publish.new(send_to(host), node, :set, payload)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # 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
+    #
+    # @param [#to_s] node the node to delete from
+    # @param [Array<#to_s>] ids a list of ids to delete
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def retract(node, ids = [], host = nil)
-      request(Stanza::PubSub::Retract.new(send_to(host), node, :set, ids)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSub::Retract.new(send_to(host), node, :set, ids)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # Create a node
-    # Yields the resulting node
-    # This does not (yet) handle configuration
-    # * +node+ is the node to create
+    #
+    # @param [#to_s] node the node to create
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def create(node, host = nil)
-      request(Stanza::PubSub::Create.new(:set, send_to(host), node)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSub::Create.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # Purge all node items
-    # Yields the resulting node
-    # * +node+ is the node to purge
+    #
+    # @param [#to_s] node the node to purge
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def purge(node, host = nil)
-      request(Stanza::PubSubOwner::Purge.new(:set, send_to(host), node)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSubOwner::Purge.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
     end
 
-    ##
     # Delete a node
-    # Yields the resulting node
-    # * +node+ is the node to delete
+    #
+    # @param [#to_s] node the node to delete
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
     def delete(node, host = nil)
-      request(Stanza::PubSubOwner::Delete.new(:set, send_to(host), node)) { |n| yield n if block_given? }
+      stanza = Stanza::PubSubOwner::Delete.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
     end
 
   private
     def request(node, method = nil, callback = nil, &block)
-      block = lambda { |node| callback.call(method ? node.__send__(method) : node) } unless block_given?
+      unless block_given?
+        block = lambda do |node|
+          callback.call(method ? node.__send__(method) : node)
+        end
+      end
+
       client.write_with_handler(node, &block)
     end
 
@@ -132,7 +164,7 @@ module DSL
     def client
       @client
     end
-  end
+  end  # PubSub
 
-end
-end
+end  # DSL
+end  # Blather