blather 0.4.7 → 0.4.8

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

@@ -2,53 +2,93 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Items Stanza
+  #
+  # [XEP-0060 Section 6.5 - Retrieve Items from a Node](http://xmpp.org/extensions/xep-0060.html#subscriber-retrieve)
+  #
+  # @handler :pubsub_items
   class Items < PubSub
     register :pubsub_items, :items, self.registered_ns
 
     include Enumerable
     alias_method :find, :xpath
 
+    # Create a new Items request
+    #
+    # @param [String] host the pubsub host to send the request to
+    # @param [String] path the path of the node
+    # @param [Array<String>] list an array of IDs to request
+    # @param [#to_s] max the maximum number of items to return
+    #
+    # @return [Blather::Stanza::PubSub::Items]
     def self.request(host, path, list = [], max = nil)
       node = self.new :get, host
 
       node.node = path
       node.max_items = max
 
-      (list || []).each { |id| node.items_node << PubSubItem.new(id, nil, node.document) }
+      (list || []).each do |id|
+        node.items_node << PubSubItem.new(id, nil, node.document)
+      end
 
       node
     end
 
+    # Overrides the parent to ensure an items node is created
+    # @private
     def self.new(type = nil, host = nil)
       new_node = super
       new_node.items
       new_node
     end
 
+    # Get the node name
+    #
+    # @return [String]
     def node
       items_node[:node]
     end
 
+    # Set the node name
+    #
+    # @param [String, nil] node
     def node=(node)
       items_node[:node] = node
     end
 
+    # Get the max number of items requested
+    #
+    # @return [Fixnum, nil]
     def max_items
       items_node[:max_items].to_i if items_node[:max_items]
     end
 
+    # Set the max number of items requested
+    #
+    # @param [Fixnum, nil] max_items
     def max_items=(max_items)
       items_node[:max_items] = max_items
     end
 
+    # Iterate over the list of items
+    #
+    # @yieldparam [Blather::Stanza::PubSub::PubSubItem] item
     def each(&block)
       items.each &block
     end
 
+    # Get the list of items on this stanza
+    #
+    # @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
 
+    # Get or create the actual items node
+    #
+    # @return [Blather::XMPPNode]
     def items_node
       unless node = self.pubsub.find_first('ns:items', :ns => self.class.registered_ns)
         (self.pubsub << (node = XMPPNode.new('items', self.document)))
@@ -56,8 +96,8 @@ class PubSub
       end
       node
     end
-  end
+  end  # Items
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -2,12 +2,23 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Publish Stanza
+  #
+  # [XEP-0060 Section 7.1 - Publish an Item to a Node](http://xmpp.org/extensions/xep-0060.html#publisher-publish)
+  #
+  # @handler :pubsub_publish
   class Publish < PubSub
     register :pubsub_publish, :publish, self.registered_ns
 
     include Enumerable
     alias_method :find, :xpath
 
+    # Create a new publish node
+    #
+    # @param [String, nil] host the host to pushlish the node to
+    # @param [String, nil] node the name of the node to publish to
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the node type
+    # @param [#to_s] payload the payload to publish see {#payload=}
     def self.new(host = nil, node = nil, type = :set, payload = nil)
       new_node = super(type, host)
       new_node.node = node
@@ -15,23 +26,45 @@ class PubSub
       new_node
     end
 
+    # Set the payload to publish
+    #
+    # @overload payload=(hash)
+    #   Set the payload as a set of ID => payload entries
+    #   @param [Hash<id => payload>] hash
+    # @overload payload=(array)
+    #   Set the list of payloads all at once
+    #   @param [Array<#to_s>] array
+    # @overload payload=(string)
+    #   Set the payload as a string
+    #   @param [#to_s] string
     def payload=(payload)
       payload = case payload
       when Hash   then  payload.to_a
       when Array  then  payload.map { |v| [nil, v] }
-      else              [[nil, payload.to_s]]
+      else              [[nil, payload]]
+      end
+      payload.each do |id, value|
+        self.publish << PubSubItem.new(id, value, self.document)
       end
-      payload.each { |id,value| self.publish << PubSubItem.new(id, value, self.document) }
     end
 
+    # Get the name of the node to publish to
+    #
+    # @return [String, nil]
     def node
       publish[:node]
     end
 
+    # Set the name of the node to publish to
+    #
+    # @param [String, nil] node
     def node=(node)
       publish[:node] = node
     end
 
+    # Get or create the actual publish node
+    #
+    # @return [Blather::XMPPNode]
     def publish
       unless publish = pubsub.find_first('ns:publish', :ns => self.class.registered_ns)
         self.pubsub << (publish = XMPPNode.new('publish', self.document))
@@ -40,19 +73,31 @@ class PubSub
       publish
     end
 
+    # Get the list of items
+    #
+    # @return [Array<Blather::Stanza::PubSub::PubSubItem>]
     def items
-      publish.find('ns:item', :ns => self.class.registered_ns).map { |i| PubSubItem.new(nil,nil,self.document).inherit i }
+      publish.find('ns:item', :ns => self.class.registered_ns).map do |i|
+        PubSubItem.new(nil,nil,self.document).inherit i
+      end
     end
 
+    # Iterate over the list of items
+    #
+    # @yield [item] a block to accept each item
+    # @yieldparam [Blather::Stanza::PubSub::PubSubItem]
     def each(&block)
       items.each &block
     end
 
+    # Get the size of the items list
+    #
+    # @return [Fixnum]
     def size
       items.size
     end
-  end #Publish
+  end  # Publish
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -2,12 +2,23 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Retract Stanza
+  #
+  # [XEP-0060 Section 7.2 - Delete an Item from a Node](http://xmpp.org/extensions/xep-0060.html#publisher-delete)
+  #
+  # @handler :pubsub_retract
   class Retract < PubSub
     register :pubsub_retract, :retract, self.registered_ns
 
     include Enumerable
     alias_method :find, :xpath
 
+    # Createa new Retraction stanza
+    #
+    # @param [String] host the host to send the request to
+    # @param [String] node the node to retract items from
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ stanza type
+    # @param [Array<String>] retractions an array of ids to retract
     def self.new(host = nil, node = nil, type = :set, retractions = [])
       new_node = super(type, host)
       new_node.node = node
@@ -15,14 +26,23 @@ class PubSub
       new_node
     end
 
+    # Get the name of the node to retract from
+    #
+    # @return [String]
     def node
       retract[:node]
     end
 
+    # Set the name of the node to retract from
+    #
+    # @param [String] node
     def node=(node)
       retract[:node] = node
     end
 
+    # Get or create the actual retract node
+    #
+    # @return [Blather::XMPPNode]
     def retract
       unless retract = pubsub.find_first('ns:retract', :ns => self.class.registered_ns)
         self.pubsub << (retract = XMPPNode.new('retract', self.document))
@@ -31,23 +51,42 @@ class PubSub
       retract
     end
 
+    # Set the retraction ids
+    #
+    # @overload retractions=(id)
+    #   @param [String] id an ID to retract
+    # @overload retractions=(ids)
+    #   @param [Array<String>] ids an array of IDs to retract
     def retractions=(retractions = [])
-      [retractions].flatten.each { |id| self.retract << PubSubItem.new(id, nil, self.document) }
+      [retractions].flatten.each do |id|
+        self.retract << PubSubItem.new(id, nil, self.document)
+      end
     end
 
+    # Get the list of item IDs to retract
+    #
+    # @return [Array<String>]
     def retractions
-      retract.find('ns:item', :ns => self.class.registered_ns).map { |i| i[:id] }
+      retract.find('ns:item', :ns => self.class.registered_ns).map do |i|
+        i[:id]
+      end
     end
 
+    # Iterate over each retraction ID
+    #
+    # @yieldparam [String] id an ID to retract
     def each(&block)
       retractions.each &block
     end
 
+    # The size of the retractions array
+    #
+    # @return [Fixnum]
     def size
       retractions.size
     end
-  end #Retract
+  end  # Retract
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -2,9 +2,20 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Subscribe Stanza
+  #
+  # [XEP-0060 Section 6.1 - Subscribe to a Node](http://xmpp.org/extensions/xep-0060.html#subscriber-subscribe)
+  #
+  # @handler :pubsub_subscribe
   class Subscribe < PubSub
     register :pubsub_subscribe, :subscribe, self.registered_ns
 
+    # Create a new subscription node
+    #
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ stanza type
+    # @param [String] host the host name to send the request to
+    # @param [String] node the node to subscribe to
+    # @param [Blather::JID, #to_s] jid see {#jid=}
     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 entity to subscribe
+    #
+    # @return [Blather::JID]
     def jid
       JID.new(subscribe[:jid])
     end
 
+    # Set the JID of the entity to subscribe
+    #
+    # @param [Blather::JID, #to_s] jid
     def jid=(jid)
       subscribe[:jid] = jid
     end
 
+    # Get the name of the node to subscribe to
+    #
+    # @return [String]
     def node
       subscribe[:node]
     end
 
+    # Set the name of the node to subscribe to
+    #
+    # @param [String] node
     def node=(node)
       subscribe[:node] = node
     end
 
+    # Get or create the actual subscribe node on the stanza
+    #
+    # @return [Blather::XMPPNode]
     def subscribe
       unless subscribe = pubsub.find_first('ns:subscribe', :ns => self.class.registered_ns)
         self.pubsub << (subscribe = XMPPNode.new('subscribe', self.document))
@@ -35,8 +61,8 @@ class PubSub
       end
       subscribe
     end
-  end #Subscribe
+  end  # Subscribe
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -2,11 +2,24 @@ module Blather
 class Stanza
 class PubSub
 
+  # # PubSub Subscription Stanza
+  #
+  # [XEP-0060 Section 8.8 Manage Subscriptions](http://xmpp.org/extensions/xep-0060.html#owner-subscriptions)
+  #
+  # @handler :pubsub_subscription
   class Subscription < PubSub
     VALID_TYPES = [:none, :pending, :subscribed, :unconfigured]
 
     register :pubsub_subscription, :subscription, self.registered_ns
 
+    # Create a new subscription request node
+    #
+    # @param [Blather::Stanza::Iq::VALID_TYPES] type the IQ type
+    # @param [String] host the host to send the request to
+    # @param [String] node the node to look for requests on
+    # @param [Blather::JID, #to_s] jid the JID of the subscriber
+    # @param [String] subid the subscription ID
+    # @param [VALID_TYPES] subscription the subscription type
     def self.new(type = :result, host = nil, node = nil, jid = nil, subid = nil, subscription = nil)
       new_node = super(type, host)
       new_node.node = node
@@ -16,42 +29,97 @@ class PubSub
       new_node
     end
 
-    attribute_helpers_for :subscription, VALID_TYPES
+    # Check if the type is none
+    #
+    # @return [Boolean]
+    def none?
+      self.subscription == :none
+    end
+
+    # Check if the type is pending
+    #
+    # @return [Boolean]
+    def pending?
+      self.subscription == :pending
+    end
+
+    # Check if the type is subscribed
+    #
+    # @return [Boolean]
+    def subscribed?
+      self.subscription == :subscribed
+    end
+
+    # Check if the type is unconfigured
+    #
+    # @return [Boolean]
+    def unconfigured?
+      self.subscription == :unconfigured
+    end
 
+    # Get the JID of the subscriber
+    #
+    # @return [Blather::JID]
     def jid
       JID.new(subscription_node[:jid])
     end
 
+    # Set the JID of the subscriber
+    #
+    # @param [Blather::JID, #to_s] jid
     def jid=(jid)
       subscription_node[:jid] = jid
     end
 
+    # Get the name of the subscription node
+    #
+    # @return [String]
     def node
       subscription_node[:node]
     end
 
+    # Set the name of the subscription node
+    #
+    # @param [String] node
     def node=(node)
       subscription_node[:node] = node
     end
 
+    # Get the ID of the subscription
+    #
+    # @return [String]
     def subid
       subscription_node[:subid]
     end
 
+    # Set the ID of the subscription
+    #
+    # @param [String] subid
     def subid=(subid)
       subscription_node[:subid] = subid
     end
 
+    # Get the subscription type
+    #
+    # @return [VALID_TYPES, nil]
     def subscription
       s = subscription_node[:subscription]
       s.to_sym if s
     end
 
+    # Set the subscription type
+    #
+    # @param [VALID_TYPES, nil] subscription
     def subscription=(subscription)
-      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if subscription && !VALID_TYPES.include?(subscription.to_sym)
+      if subscription && !VALID_TYPES.include?(subscription.to_sym)
+        raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
+      end
       subscription_node[:subscription] = subscription
     end
 
+    # Get or create the actual subscription node
+    #
+    # @return [Blather::XMPPNode]
     def subscription_node
       unless subscription = pubsub.find_first('ns:subscription', :ns => self.class.registered_ns)
         self.pubsub << (subscription = XMPPNode.new('subscription', self.document))
@@ -59,8 +127,8 @@ class PubSub
       end
       subscription
     end
-  end #Subscribe
+  end  # Subscribe
 
-end #PubSub
-end #Stanza
-end #Blather
+end  # PubSub
+end  # Stanza
+end  # Blather