blather 0.4.7 → 0.4.8

data/lib/blather/stanza/pubsub/subscriptions.rb

@@ -2,14 +2,19 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Subscriptions Stanza
+  #
+  # [XEP-0060 Section 5.6 Retrieve Subscriptions](http://xmpp.org/extensions/xep-0060.html#entity-subscriptions)
+  #
+  # @handler :pubsub_subscriptions
   class Subscriptions < PubSub
     register :pubsub_subscriptions, :subscriptions, self.registered_ns
 
     include Enumerable
     alias_method :find, :xpath
 
-    ##
-    # Ensure the namespace is set to the query node
+    # Overrides the parent to ensure a subscriptions node is created
+    # @private
     def self.new(type = nil, host = nil)
       new_node = super type
       new_node.to = host
@@ -17,27 +22,48 @@ class PubSub
       new_node
     end
 
-    ##
-    # Kill the pubsub node before running inherit
+    # Overrides the parent to ensure the subscriptions node is destroyed
+    # @private
     def inherit(node)
       subscriptions.remove
       super
     end
 
+    # Get or create the actual subscriptions node
+    #
+    # @return [Blather::XMPPNode]
     def subscriptions
       aff = pubsub.find_first('subscriptions', self.class.registered_ns)
-      (self.pubsub << (aff = XMPPNode.new('subscriptions', self.document))) unless aff
+      unless aff
+        (self.pubsub << (aff = XMPPNode.new('subscriptions', self.document)))
+      end
       aff
     end
 
+    # Iterate over the list of subscriptions
+    #
+    # @yieldparam [Hash] subscription
+    # @see {#list}
     def each(&block)
       list.each &block
     end
 
+    # Get the size of the subscriptions list
+    #
+    # @return [Fixnum]
     def size
       list.size
     end
 
+    # Get a hash of subscriptions
+    #
+    # @example
+    #   { :subscribed => [{:node => 'node1', :jid => 'francisco@denmark.lit'}, {:node => 'node2', :jid => 'francisco@denmark.lit'}],
+    #     :unconfigured => [{:node => 'node3', :jid => 'francisco@denmark.lit'}],
+    #     :pending => [{:node => 'node4', :jid => 'francisco@denmark.lit'}],
+    #     :none => [{:node => 'node5', :jid => 'francisco@denmark.lit'}] }
+    #
+    # @return [Hash]
     def list
       subscriptions.find('//ns:subscription', :ns => self.class.registered_ns).inject({}) do |hash, item|
         hash[item[:subscription].to_sym] ||= []
@@ -48,8 +74,8 @@ class PubSub
         hash
       end
     end
-  end #Subscriptions
+  end  # Subscriptions
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

data/lib/blather/stanza/pubsub/unsubscribe.rb

@@ -2,9 +2,20 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Unsubscribe Stanza
+  #
+  # [XEP-0060 Section 6.2 - Unsubscribe from a Node](http://xmpp.org/extensions/xep-0060.html#subscriber-unsubscribe)
+  #
+  # @handler :pubsub_unsubscribe
   class Unsubscribe < PubSub
     register :pubsub_unsubscribe, :unsubscribe, self.registered_ns
 
+    # Create a new unsubscribe node
+    #
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ stanza type
+    # @param [String] host the host to send the request to
+    # @param [String] node the node to unsubscribe from
+    # @param [Blather::JID, #to_s] jid the JID of the unsubscription
     def self.new(type = :set, host = nil, node = nil, jid = nil)
       new_node = super(type, host)
       new_node.node = node
@@ -12,22 +23,37 @@ class PubSub
       new_node
     end
 
+    # Get the JID of the unsubscription
+    #
+    # @return [Blather::JID]
     def jid
       JID.new(unsubscribe[:jid])
     end
 
+    # Set the JID of the unsubscription
+    #
+    # @param [Blather::JID, #to_s] jid
     def jid=(jid)
       unsubscribe[:jid] = jid
     end
 
+    # Get the name of the node to unsubscribe from
+    #
+    # @return [String]
     def node
       unsubscribe[:node]
     end
 
+    # Set the name of the node to unsubscribe from
+    #
+    # @param [String] node
     def node=(node)
       unsubscribe[:node] = node
     end
 
+    # Get or create the actual unsubscribe node
+    #
+    # @return [Blather::XMPPNode]
     def unsubscribe
       unless unsubscribe = pubsub.find_first('ns:unsubscribe', :ns => self.class.registered_ns)
         self.pubsub << (unsubscribe = XMPPNode.new('unsubscribe', self.document))
@@ -35,8 +61,8 @@ class PubSub
       end
       unsubscribe
     end
-  end #Unsubscribe
+  end  # Unsubscribe
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

data/lib/blather/stanza/pubsub_owner.rb

@@ -1,9 +1,16 @@
 module Blather
 class Stanza
 
+  # # PubSubOwner Base Class
+  #
+  # [XEP-0060 - Publish-Subscribe](http://xmpp.org/extensions/xep-0060.html)
+  #
+  # @handler :pubsub_owner
   class PubSubOwner < Iq
     register :pubsub_owner, :pubsub, 'http://jabber.org/protocol/pubsub#owner'
 
+    # Creates the proper class from the stana's child
+    # @private
     def self.import(node)
       klass = nil
       if pubsub = node.document.find_first('//ns:pubsub', :ns => self.registered_ns)
@@ -12,8 +19,8 @@ class Stanza
       (klass || self).new(node[:type]).inherit(node)
     end
 
-    ##
-    # Ensure the namespace is set to the query node
+    # Overrides the parent to ensure a pubsub node is created
+    # @private
     def self.new(type = nil, host = nil)
       new_node = super type
       new_node.to = host
@@ -21,13 +28,16 @@ class Stanza
       new_node
     end
 
-    ##
-    # Kill the pubsub node before running inherit
+    # Overrides the parent to ensure the pubsub node is destroyed
+    # @private
     def inherit(node)
       remove_children :pubsub
       super
     end
 
+    # Get or create the pubsub node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def pubsub
       unless p = find_first('ns:pubsub', :ns => self.class.registered_ns)
         self << (p = XMPPNode.new('pubsub', self.document))
@@ -35,7 +45,7 @@ class Stanza
       end
       p
     end
-  end
+  end  # PubSubOwner
 
-end #Stanza
-end #Blather
+end  # Stanza
+end  # Blather

data/lib/blather/stanza/pubsub_owner/delete.rb

@@ -2,24 +2,42 @@ module Blather
 class Stanza
 class PubSubOwner
 
+  # # PubSubOwner Delete Stanza
+  #
+  # [XEP-0060 Section 8.4 Delete a Node](http://xmpp.org/extensions/xep-0060.html#owner-delete)
+  #
+  # @handler :pubsub_delete
   class Delete < PubSubOwner
-    
     register :pubsub_delete, :delete, self.registered_ns
 
+    # Create a new delete stanza
+    #
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ stanza type
+    # @param [String] host the host to send the request to
+    # @param [String] node the name of the node to delete
     def self.new(type = :set, host = nil, node = nil)
       new_node = super(type, host)
       new_node.node = node
       new_node
     end
 
+    # Get the name of the node to delete
+    #
+    # @return [String]
     def node
       delete_node[:node]
     end
 
+    # Set the name of the node to delete
+    #
+    # @param [String] node
     def node=(node)
       delete_node[:node] = node
     end
 
+    # Get or create the actual delete node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def delete_node
       unless delete_node = pubsub.find_first('ns:delete', :ns => self.class.registered_ns)
         self.pubsub << (delete_node = XMPPNode.new('delete', self.document))
@@ -27,8 +45,8 @@ class PubSubOwner
       end
       delete_node
     end
-  end #Retract
+  end  # Retract
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

data/lib/blather/stanza/pubsub_owner/purge.rb

@@ -2,24 +2,42 @@ module Blather
 class Stanza
 class PubSubOwner
 
+  # # PubSubOwner Purge Stanza
+  #
+  # [XEP-0060 Section 8.5 - Purge All Node Items](http://xmpp.org/extensions/xep-0060.html#owner-purge)
+  #
+  # @handler :pubsub_purge
   class Purge < PubSubOwner
-    
     register :pubsub_purge, :purge, self.registered_ns
 
+    # Create a new purge stanza
+    #
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ stanza type
+    # @param [String] host the host to send the request to
+    # @param [String] node the name of the node to purge
     def self.new(type = :set, host = nil, node = nil)
       new_node = super(type, host)
       new_node.node = node
       new_node
     end
 
+    # Get the name of the node to delete
+    #
+    # @return [String]
     def node
       purge_node[:node]
     end
 
+    # Set the name of the node to delete
+    #
+    # @param [String] node
     def node=(node)
       purge_node[:node] = node
     end
 
+    # Get or create the actual purge node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def purge_node
       unless purge_node = pubsub.find_first('ns:purge', :ns => self.class.registered_ns)
         self.pubsub << (purge_node = XMPPNode.new('purge', self.document))
@@ -27,8 +45,8 @@ class PubSubOwner
       end
       purge_node
     end
-  end #Retract
+  end  # Retract
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

data/lib/blather/stream.rb

@@ -1,5 +1,52 @@
 module Blather
 
+  # # A pure XMPP stream.
+  #
+  # Blather::Stream can be used to build your own handler system if Blather's
+  # doesn't suit your needs. It will take care of the entire connection
+  # process then start sending Stanza objects back to the registered client.
+  #
+  # The client you register with Blather::Stream needs to implement the following
+  # methods:
+  # * #post_init(stream, jid = nil)
+  #   Called after the stream has been initiated.
+  #   @param [Blather::Stream] stream is the connected stream object
+  #   @param [Blather::JID, nil] jid is the full JID as recognized by the server
+  #
+  # * #receive_data(stanza)
+  #   Called every time the stream receives a new stanza
+  #   @param [Blather::Stanza] stanza a stanza object from the server
+  #
+  # * #unbind
+  #   Called when the stream is shutdown. This will be called regardless of which
+  #   side shut the stream down.
+  #
+  # @example Create a new stream and handle it with our own class
+  #     class MyClient
+  #       attr :jid
+  #
+  #       def post_init(stream, jid = nil)
+  #         @stream = stream
+  #         self.jid = jid
+  #         p "Stream Started"
+  #       end
+  #
+  #       # Pretty print the stream
+  #       def receive_data(stanza)
+  #         pp stanza
+  #       end
+  #
+  #       def unbind
+  #         p "Stream Ended"
+  #       end
+  #
+  #       def write(what)
+  #         @stream.write what
+  #       end
+  #     end
+  #
+  #     client = Blather::Stream.start MyClient.new, "jid@domain/res", "pass"
+  #     client.write "[pure xml over the wire]"
   class Stream < EventMachine::Connection
     class NoConnection < RuntimeError; end
 
@@ -7,13 +54,16 @@ module Blather
     attr_accessor :password
     attr_reader :jid
 
-    ##
     # Start the stream between client and server
-    #   [client] must be an object that will respond to #call and #jid=
-    #   [jid] must be a valid argument for JID.new (see JID)
-    #   [pass] must be the password
-    #   [host] (optional) must be the hostname or IP to connect to. defaults to the domain of [jid]
-    #   [port] (optional) must be the port to connect to. defaults to 5222
+    #
+    # @param [Object] client an object that will respond to #post_init,
+    # #unbind #receive_data
+    # @param [Blather::JID, #to_s] jid the jid to authenticate with
+    # @param [String] pass the password to authenticate with
+    # @param [String, nil] host the hostname or IP to connect to. Default is
+    # to use the domain on the JID
+    # @param [Fixnum, nil] port the port to connect on. Default is the XMPP
+    # default of 5222
     def self.start(client, jid, pass, host = nil, port = 5222)
       jid = JID.new jid
       if host
@@ -21,20 +71,32 @@ module Blather
       else
         require 'resolv'
         srv = []
-        Resolv::DNS.open { |dns| srv = dns.getresources("_xmpp-client._tcp.#{jid.domain}", Resolv::DNS::Resource::IN::SRV) }
+        Resolv::DNS.open do |dns|
+          srv = dns.getresources(
+            "_xmpp-client._tcp.#{jid.domain}",
+            Resolv::DNS::Resource::IN::SRV
+          )
+        end
+
         if srv.empty?
           connect jid.domain, port, self, client, jid, pass
         else
-          srv.sort! { |a,b| (a.priority != b.priority) ? (a.priority <=> b.priority) : (b.weight <=> a.weight) }
-          srv.each { |r| break unless connect(r.target.to_s, r.port, self, client, jid, pass) === false }
+          srv.sort! do |a,b|
+            (a.priority != b.priority) ? (a.priority <=> b.priority) :
+                                         (b.weight <=> a.weight)
+          end
+
+          srv.detect do |r|
+            not connect(r.target.to_s, r.port, self, client, jid, pass) === false
+          end
         end
       end
     end
 
-    ##
     # Attempt a connection
     # Stream will raise +NoConnection+ if it receives #unbind before #post_init
     # this catches that and returns false prompting for another attempt
+    # @private
     def self.connect(host, port, conn, client, jid, pass)
       EM.connect host, port, conn, client, jid, pass
     rescue NoConnection
@@ -45,19 +107,19 @@ module Blather
       define_method("#{state}?") { @state == state }
     end
 
-    ##
     # Send data over the wire
-    #   The argument for this can be anything that
-    #   responds to #to_s
+    #
+    # @todo Queue if not ready
+    #
+    # @param [#to_xml, #to_s] stanza the stanza to send over the wire
     def send(stanza)
-      #TODO Queue if not ready
       Blather.logger.debug "SENDING: (#{caller[1]}) #{stanza}"
       send_data stanza.respond_to?(:to_xml) ? stanza.to_xml : stanza.to_s
     end
 
-    ##
     # Called by EM.connect to initialize stream variables
-    def initialize(client, jid, pass) # :nodoc:
+    # @private
+    def initialize(client, jid, pass)
       super()
 
       @error = nil
@@ -68,17 +130,17 @@ module Blather
       @password = pass
     end
 
-    ##
     # Called when EM completes the connection to the server
     # this kicks off the starttls/authorize/bind process
-    def connection_completed # :nodoc:
+    # @private
+    def connection_completed
 #      @keepalive = EM::PeriodicTimer.new(60) { send_data ' ' }
       start
     end
 
-    ##
     # Called by EM with data from the wire
-    def receive_data(data) # :nodoc:
+    # @private
+    def receive_data(data)
       Blather.logger.debug "\n#{'-'*30}\n"
       Blather.logger.debug "STREAM IN: #{data}"
       @parser << data
@@ -89,13 +151,15 @@ module Blather
       stop
     end
 
+    # Called by EM after the connection has started
+    # @private
     def post_init
       @connected = true
     end
 
-    ##
     # Called by EM when the connection is closed
-    def unbind # :nodoc:
+    # @private
+    def unbind
       raise NoConnection unless @connected
 
 #      @keepalive.cancel
@@ -104,9 +168,9 @@ module Blather
       @client.unbind
     end
 
-    ##
     # Called by the parser with parsed nodes
-    def receive(node) # :nodoc:
+    # @private
+    def receive(node)
       Blather.logger.debug "RECEIVING (#{node.element_name}) #{node}"
       @node = node
 
@@ -133,16 +197,16 @@ module Blather
       @receiver.receive_data @node.to_stanza
     end
 
-    ##
     # Ensure the JID gets attached to the client
-    def jid=(new_jid) # :nodoc:
+    # @private
+    def jid=(new_jid)
       Blather.logger.debug "NEW JID: #{new_jid}"
       @jid = JID.new new_jid
     end
 
   protected
-    ##
     # Stop the stream
+    # @private
     def stop
       unless @state == :stopped
         @state = :stopped
@@ -150,15 +214,18 @@ module Blather
       end
     end
 
+    # @private
     def handle_stream_error
       @error = StreamError.import(@node)
       stop
     end
 
+    # @private
     def ready!
       @state = :started
       @receiver = @client
       @client.post_init self, @jid
     end
-  end
-end
+  end  # Stream
+
+end  # Blather