blather 0.4.7 → 0.4.8

data/lib/blather/stanza/presence/subscription.rb

@@ -2,9 +2,22 @@ module Blather
 class Stanza
 class Presence
 
+  # # Subscription Stanza
+  #
+  # [RFC 3921 Section 8 - Integration of Roster Items and Presence Subscriptions](http://xmpp.org/rfcs/rfc3921.html#rfc.section.8)
+  #
+  # Blather handles subscription request/response through this class. It
+  # provides a set of helper methods to quickly transform the stanza into a
+  # response.
+  #
+  # @handler :subscription
   class Subscription < Presence
     register :subscription, :subscription
 
+    # Create a new Subscription stanza
+    #
+    # @param [Blather::JID, #to_s] to the JID to subscribe to
+    # @param [Symbol, nil] type the subscription type
     def self.new(to = nil, type = nil)
       node = super()
       node.to = to
@@ -12,50 +25,71 @@ class Presence
       node
     end
 
+    # @private
     def inherit(node)
       inherit_attrs node.attributes
       self
     end
 
+    # Set the to value on the stanza
+    #
+    # @param [Blather::JID, #to_s] to a JID to subscribe to
     def to=(to)
       super JID.new(to).stripped
     end
 
-    ##
-    # Create an approve stanza
+    # Transform the stanza into an approve stanza
+    # makes approving requests simple
+    #
+    # @example approve an incoming request
+    #   subscription(:request?) { |s| write_to_stream s.approve! }
+    # @return [self]
     def approve!
       self.type = :subscribed
       reply_if_needed!
     end
 
-    ##
-    # Create a refuse stanza
+    # Transform the stanza into a refuse stanza
+    # makes refusing requests simple
+    #
+    # @example refuse an incoming request
+    #   subscription(:request?) { |s| write_to_stream s.refuse! }
+    # @return [self]
     def refuse!
       self.type = :unsubscribed
       reply_if_needed!
     end
 
-    ##
-    # Create an unsubscribe stanza
+    # Transform the stanza into an unsubscribe stanza
+    # makes unsubscribing simple
+    #
+    # @return [self]
     def unsubscribe!
       self.type = :unsubscribe
       reply_if_needed!
     end
 
-    ##
-    # Create a cancel stanza
+    # Transform the stanza into a cancel stanza
+    # makes canceling simple
+    #
+    # @return [self]
     def cancel!
       self.type = :unsubscribed
       reply_if_needed!
     end
 
-    ##
-    # Create a request stanza
+    # Transform the stanza into a request stanza
+    # makes requests simple
+    #
+    # @return [self]
     def request!
       self.type = :subscribe
       reply_if_needed!
     end
 
+    # Check if the stanza is a request
+    #
+    # @return [true, false]
     def request?
       self.type == :subscribe
     end

data/lib/blather/stanza/pubsub.rb

@@ -1,19 +1,34 @@
 module Blather
 class Stanza
 
+  # # Pubsub Stanza
+  #
+  # [XEP-0060 - Publish-Subscribe](http://xmpp.org/extensions/xep-0060.html)
+  #
+  # The base class for all PubSub nodes. This provides helper methods common to
+  # all PubSub nodes.
+  #
+  # @handler :pubsub_node
   class PubSub < Iq
     register :pubsub_node, :pubsub, 'http://jabber.org/protocol/pubsub'
 
+    # @private
     def self.import(node)
       klass = nil
       if pubsub = node.document.find_first('//ns:pubsub', :ns => self.registered_ns)
-        pubsub.children.each { |e| break if klass = class_from_registration(e.element_name, (e.namespace.href if e.namespace)) }
+        pubsub.children.detect do |e|
+          ns = e.namespace ? e.namespace.href : nil
+          klass = class_from_registration(e.element_name, ns)
+        end
       end
       (klass || self).new(node[:type]).inherit(node)
     end
 
-    ##
-    # Ensure the namespace is set to the query node
+    # Overwrites the parent constructor to ensure a pubsub node is present.
+    # Also allows the addition of a host attribute
+    #
+    # @param [<Blather::Stanza::Iq::VALID_TYPES>] type the IQ type
+    # @param [String, nil] host the host the node should be sent to
     def self.new(type = nil, host = nil)
       new_node = super type
       new_node.to = host
@@ -21,13 +36,18 @@ class Stanza
       new_node
     end
 
-    ##
-    # Kill the pubsub node before running inherit
+    # Overrides the parent to ensure the current pubsub node is destroyed before
+    # inheritting the new content
+    #
+    # @private
     def inherit(node)
       remove_children :pubsub
       super
     end
 
+    # Get or create the pubsub node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def pubsub
       p = find_first('ns:pubsub', :ns => self.class.registered_ns) ||
           find_first('pubsub', :ns => self.class.registered_ns)
@@ -38,9 +58,21 @@ class Stanza
       end
       p
     end
-  end
+  end  # PubSub
 
+  # # PubSubItem Fragment
+  #
+  # This fragment is found in many places throughout the pubsub spec
+  # This is a convenience class to attach methods to the node
   class PubSubItem < XMPPNode
+    ATOM_NS = 'http://www.w3.org/2005/Atom'.freeze
+
+    # Create a new PubSubItem
+    #
+    # @param [String, nil] id the id of the stanza
+    # @param [#to_s, nil] payload the payload to attach to this item.
+    # @param [XML::Document, nil] document the document the node should be
+    # attached to. This should be the document of the parent PubSub node.
     def self.new(id = nil, payload = nil, document = nil)
       new_node = super 'item', document
       new_node.id = id
@@ -48,27 +80,50 @@ class Stanza
       new_node
     end
 
-    attribute_accessor :id
+    # Get the item's ID
+    #
+    # @return [String, nil]
+    def id
+      read_attr :id
+    end
 
-    def payload=(payload = nil)
-      self.entry.content = payload
+    # Set the item's ID
+    #
+    # @param [#to_s] id the new ID
+    def id=(id)
+      write_attr :id, id
     end
 
+    # Get the item's payload
+    #
+    # To get the XML representation use #entry
+    #
+    # @return [String, nil]
     def payload
       self.entry.content.empty? ? nil : content
     end
 
+    # Set the item's payload
+    #
+    # @param [String, nil] payload the payload
+    def payload=(payload)
+      self.entry.content = payload
+    end
+
+    # Get or create the entry node
+    #
+    # @return [Blather::XMPPNode]
     def entry
-      e = find_first('ns:entry', :ns => 'http://www.w3.org/2005/Atom') ||
-          find_first('entry', :ns => 'http://www.w3.org/2005/Atom')
+      e = find_first('ns:entry', :ns => ATOM_NS) ||
+          find_first('entry', :ns => ATOM_NS)
 
       unless e
         self << (e = XMPPNode.new('entry', self.document))
-        e.namespace = 'http://www.w3.org/2005/Atom'
+        e.namespace = ATOM_NS
       end
       e
     end
-  end
+  end  # PubSubItem
 
-end #Stanza
-end #Blather
+end  # Stanza
+end  # Blather

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

@@ -2,39 +2,68 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Affiliations Stanza
+  #
+  # [XEP-0060 Section 8.9 - Manage Affiliations](http://xmpp.org/extensions/xep-0060.html#owner-affiliations)
+  #
+  # @handler :pubsub_affiliations
   class Affiliations < PubSub
     register :pubsub_affiliations, :affiliations, self.registered_ns
 
     include Enumerable
     alias_method :find, :xpath
 
+    # Overrides the parent to ensure an affiliation node is created
+    # @private
     def self.new(type = nil, host = nil)
       new_node = super
       new_node.affiliations
       new_node
     end
 
-    ##
     # Kill the affiliations node before running inherit
+    # @private
     def inherit(node)
       affiliations.remove
       super
     end
 
+    # Get or create the affiliations node
+    #
+    # @return [Blather::XMPPNode]
     def affiliations
-      aff = pubsub.find_first('pubsub_ns:affiliations', :pubsub_ns => self.class.registered_ns)
-      self.pubsub << (aff = XMPPNode.new('affiliations', self.document)) unless aff
+      aff = pubsub.find_first('ns:affiliations', :ns => self.class.registered_ns)
+      unless aff
+        self.pubsub << (aff = XMPPNode.new('affiliations', self.document))
+      end
       aff
     end
 
+    # Convenience method for iterating over the list
+    #
+    # @see #list for the format of the yielded input
     def each(&block)
       list.each &block
     end
 
+    # Get the number of affiliations
+    #
+    # @return [Fixnum]
     def size
       list.size
     end
 
+    # Get the hash of affilations as affiliation-type => [nodes]
+    #
+    # @example
+    #
+    #     { :owner => ['node1', 'node2'],
+    #       :publisher => ['node3'],
+    #       :outcast => ['node4'],
+    #       :member => ['node5'],
+    #       :none => ['node6'] }
+    #
+    # @return [Hash<String => Array<String>>]
     def list
       items = affiliations.find('//ns:affiliation', :ns => self.class.registered_ns)
       items.inject({}) do |hash, item|
@@ -43,8 +72,8 @@ class PubSub
         hash
       end
     end
-  end #Affiliations
+  end  # Affiliations
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -2,9 +2,19 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Create Stanza
+  #
+  # [XEP-0060 Section 8.1 - Create a Node](http://xmpp.org/extensions/xep-0060.html#owner-create)
+  #
+  # @handler :pubsub_create
   class Create < PubSub
     register :pubsub_create, :create, self.registered_ns
 
+    # Create a new Create Stanza
+    #
+    # @param [<Blather::Stanza::Iq::VALID_TYPES>] type the node type
+    # @param [String, nil] host the host to send the request to
+    # @param [String, nil] node the name of the node to create
     def self.new(type = :set, host = nil, node = nil)
       new_node = super(type, host)
       new_node.create_node
@@ -13,14 +23,23 @@ class PubSub
       new_node
     end
 
+    # Get the name of the node to create
+    #
+    # @return [String, nil]
     def node
       create_node[:node]
     end
 
+    # Set the name of the node to create
+    #
+    # @param [String, nil] node
     def node=(node)
       create_node[:node] = node
     end
 
+    # Get or create the actual create node on the stanza
+    #
+    # @return [Balther::XMPPNode]
     def create_node
       unless create_node = pubsub.find_first('ns:create', :ns => self.class.registered_ns)
         self.pubsub << (create_node = XMPPNode.new('create', self.document))
@@ -29,6 +48,9 @@ class PubSub
       create_node
     end
 
+    # Get or create the actual configure node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def configure_node
       unless configure_node = pubsub.find_first('ns:configure', :ns => self.class.registered_ns)
         self.pubsub << (configure_node = XMPPNode.new('configure', self.document))
@@ -36,8 +58,8 @@ class PubSub
       end
       configure_node
     end
-  end #Retract
+  end  # Create
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -1,9 +1,18 @@
 module Blather
 class Stanza
 
+  # # PusSub Error Stanza
+  #
+  # @private
   class PubSubErrors < PubSub
-    attribute_accessor :node, :to_sym => false
-  end
+    def node
+      read_attr :node
+    end
 
-end #Stanza
-end #Blather
+    def node=(node)
+      write_attr :node, node
+    end
+  end  # PubSubErrors
+
+end  # Stanza
+end  # Blather

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

@@ -2,48 +2,83 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Event Stanza
+  #
+  # [XEP-0060](http://xmpp.org/extensions/xep-0060.html)
+  #
+  # The PubSub Event stanza is used in many places. Please see the XEP for more
+  # information.
+  #
+  # @handler :pubsub_event
   class Event < Message
+    SHIM_NS = 'http://jabber.org/protocol/shim'.freeze
+
     register :pubsub_event, :event, 'http://jabber.org/protocol/pubsub#event'
 
-    ##
-    # Ensure the event_node is created
+    # Ensures the event_node is created
+    # @private
     def self.new(type = nil)
       node = super
       node.event_node
       node
     end
 
-    ##
     # Kill the event_node node before running inherit
+    # @private
     def inherit(node)
       event_node.remove
       super
     end
 
+    # Get the name of the node
+    #
+    # @return [String, nil]
     def node
       !purge? ? items_node[:node] : purge_node[:node]
     end
 
+    # Get a list of retractions
+    #
+    # @return [Array<String>]
     def retractions
-      items_node.find('//ns:retract', :ns => self.class.registered_ns).map { |i| i[:id] }
+      items_node.find('//ns:retract', :ns => self.class.registered_ns).map do |i|
+        i[:id]
+      end
     end
 
+    # Check if this is a retractions stanza
+    #
+    # @return [Boolean]
     def retractions?
       !retractions.empty?
     end
 
+    # Get the list of items attached to this event
+    #
+    # @return [Array<Blather::Stanza::PubSub::PubSubItem>]
     def items
-      items_node.find('//ns:item', :ns => self.class.registered_ns).map { |i| PubSubItem.new(nil,nil,self.document).inherit i }
+      items_node.find('//ns:item', :ns => self.class.registered_ns).map do |i|
+        PubSubItem.new(nil,nil,self.document).inherit i
+      end
     end
 
+    # Check if this stanza has items
+    #
+    # @return [Boolean]
     def items?
       !items.empty?
     end
 
+    # Check if this is a purge stanza
+    #
+    # @return [XML::Node, nil]
     def purge?
       purge_node
     end
 
+    # Get or create the actual event node
+    #
+    # @return [Blather::XMPPNode]
     def event_node
       node = find_first('//ns:event', :ns => self.class.registered_ns)
       node = find_first('//event', self.class.registered_ns) unless node
@@ -54,6 +89,9 @@ class PubSub
       node
     end
 
+    # Get or create the actual items node
+    #
+    # @return [Blather::XMPPNode]
     def items_node
       node = find_first('ns:event/ns:items', :ns => self.class.registered_ns)
       unless node
@@ -63,15 +101,23 @@ class PubSub
       node
     end
 
+    # Get the actual purge node
+    #
+    # @return [Blather::XMPPNode]
     def purge_node
       event_node.find_first('//ns:purge', :ns => self.class.registered_ns)
     end
 
+    # Get the subscription IDs associated with this event
+    #
+    # @return [Array<String>]
     def subscription_ids
-      find('//ns:header[@name="SubID"]', :ns => 'http://jabber.org/protocol/shim').map { |n| n.content }
+      find('//ns:header[@name="SubID"]', :ns => SHIM_NS).map do |n|
+        n.content
+      end
     end
-  end
+  end  # Event
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather