blather 0.4.7 → 0.4.8

data/lib/blather/stanza/disco/disco_info.rb

@@ -1,36 +1,62 @@
 module Blather
 class Stanza
 
-  ##
-  # DiscoInfo object ()
-  # 
+  # # DiscoInfo Stanza
+  #
+  # [XEP-0030 Disco Info](http://xmpp.org/extensions/xep-0030.html#info)
+  #
+  # Disco Info node that provides or retreives information about a jabber entity
+  #
+  # @handler :disco_info
   class DiscoInfo < Disco
     register :disco_info, nil, 'http://jabber.org/protocol/disco#info'
 
+    # Create a new DiscoInfo stanza
+    # @param [:get, :set, :result, :error, nil] type the Iq stanza type
+    # @param [String, nil] node the name of the node the info belongs to
+    # @param [Array<Array, DiscoInfo::Identity>, nil] identities a list of
+    # identities. these are passed directly to DiscoInfo::Identity.new
+    # @param [Array<Array, DiscoInfo::Identity>, nil] features a list of
+    # features. these are passed directly to DiscoInfo::Feature.new
+    # @return [DiscoInfo] a new DiscoInfo stanza
     def self.new(type = nil, node = nil, identities = [], features = [])
       new_node = super type
       new_node.node = node
-      [identities].flatten.each { |id|      new_node.query << Identity.new(id)      }
-      [features].flatten.each   { |feature| new_node.query << Feature.new(feature)  }
+      [identities].flatten.each { |i| new_node.query << Identity.new(i) }
+      [features].flatten.each   { |f| new_node.query << Feature.new(f) }
       new_node
     end
 
-    ##
     # List of identity objects
     def identities
-      query.find('//query_ns:identity', :query_ns => self.class.registered_ns).map { |i| Identity.new i }
+      query.find('//ns:identity', :ns => self.class.registered_ns).map do |i|
+        Identity.new i
+      end
     end
 
-    ##
     # List of feature objects
     def features
-      query.find('//query_ns:feature', :query_ns => self.class.registered_ns).map { |i| Feature.new i }
+      query.find('//ns:feature', :ns => self.class.registered_ns).map do |f|
+        Feature.new f
+      end
     end
 
     class Identity < XMPPNode
-      attribute_accessor :category, :type, :call => :to_sym
-      attribute_accessor :name
-
+      # Create a new DiscoInfo Identity
+      # @overload new(node)
+      #   Imports the XML::Node to create a Identity object
+      #   @param [XML::Node] node the node object to import
+      # @overload new(opts = {})
+      #   Creates a new Identity using a hash of options
+      #   @param [Hash] opts a hash of options
+      #   @option opts [String] :name the name of the identity
+      #   @option opts [String] :type the type of the identity
+      #   @option opts [String] :category the category of the identity
+      # @overload new(name, type = nil, category = nil)
+      #   Create a new Identity by name
+      #   @param [String] name the name of the Identity
+      #   @param [String, nil] type the type of the Identity
+      #   @param [String, nil] category the category of the Identity
       def self.new(name, type = nil, category = nil)
         new_node = super :identity
 
@@ -49,18 +75,66 @@ class Stanza
         new_node
       end
 
+      # The Identity's category
+      # @return [Symbol, nil]
+      def category
+        read_attr :category, :to_sym
+      end
+
+      # Set the Identity's category
+      # @param [String, Symbol] category the new category
+      def category=(category)
+        write_attr :category, category
+      end
+
+      # The Identity's type
+      # @return [Symbol, nil]
+      def type
+        read_attr :type, :to_sym
+      end
+
+      # Set the Identity's type
+      # @param [String, Symbol] type the new category
+      def type=(type)
+        write_attr :type, type
+      end
+
+      # The Identity's name
+      # @return [String]
+      def name
+        read_attr :name
+      end
+
+      # Set the Identity's name
+      # @param [String] name the new name for the identity
+      def name=(name)
+        write_attr :name, name
+      end
+
+      # Compare two Identity objects by name, type and category
+      # @param [DiscoInfo::Identity] o the Identity object to compare against
+      # @return [true, false]
       def eql?(o)
-        raise "Cannot compare #{self.class} with #{o.class}" unless o.is_a?(self.class)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
         o.name == self.name &&
         o.type == self.type &&
         o.category == self.category
       end
       alias_method :==, :eql?
-    end
+    end # Identity
 
     class Feature < XMPPNode
-      attribute_accessor :var
-
+      # Create a new DiscoInfo::Feature object
+      # @overload new(node)
+      #   Create a new Feature by importing an XML::Node
+      #   @param [XML::Node] node an XML::Node to import
+      # @overload new(var)
+      #   Create a new feature by var
+      #   @param [String] var a the Feautre's var
+      # @return [DiscoInfo::Feature]
       def self.new(var)
         new_node = super :feature
         case var
@@ -72,13 +146,31 @@ class Stanza
         new_node
       end
 
+      # The Feature's var
+      # @return [String]
+      def var
+        read_attr :var
+      end
+
+      # Set the Feature's var
+      # @param [String] var the new var
+      def var=(var)
+        write_attr :var, var
+      end
+
+      # Compare two Feature objects by var
+      # @param [DiscoInfo::Feature] o the Feature object to compare against
+      # @return [true, false]
       def eql?(o)
-        raise "Cannot compare #{self.class} with #{o.class}" unless o.is_a?(self.class)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
         o.var == self.var
       end
       alias_method :==, :eql?
     end
-  end
+  end # Feature
 
-end #Stanza
-end #Blather
+end # Stanza
+end # Blather

data/lib/blather/stanza/disco/disco_items.rb

@@ -1,9 +1,23 @@
 module Blather
 class Stanza
 
+  # # DiscoItems Stanza
+  #
+  # [XEP-0030 Disco Info](http://xmpp.org/extensions/xep-0030.html#items)
+  #
+  # Disco Items node that provides or retreives items associated with a
+  # jabbery entity
+  #
+  # @handler :disco_items
   class DiscoItems < Disco
     register :disco_items, nil, 'http://jabber.org/protocol/disco#items'
 
+    # Create a new DiscoItems node
+    #
+    # @param [#to_s] type the IQ type
+    # @param [#to_s] node the node the items are associated with
+    # @param [Array<Blather::XMPPNode>] items an array of Disco::Items
+    # @return [Blather::Stanza::DiscoItems]
     def self.new(type = nil, node = nil, items = [])
       new_node = super type
       new_node.node = node
@@ -11,19 +25,33 @@ class Stanza
       new_node
     end
 
+    # Set of items associated with the node
+    #
+    # @return [Array<Blather::Stanza::DiscoItems::Item>]
     def items
-      query.find('//query_ns:item', :query_ns => self.class.registered_ns).map { |i| Item.new i }
-    end
-
-    def node=(node)
-      query[:node] = node
-    end
-
-    def node
-      query[:node]
+      query.find('//ns:item', :ns => self.class.registered_ns).map do |i|
+        Item.new i
+      end
     end
 
+    # An individual Disco Item
     class Item < XMPPNode
+      # Create a new Blather::Stanza::DiscoItems::Item
+      #
+      # @overload new(node)
+      #   Create a new Item by inheriting an existing node
+      #   @param [XML::Node] node an XML::Node to inherit from
+      # @overload new(opts)
+      #   Create a new Item through a hash of options
+      #   @param [Hash] opts a hash options
+      #   @option opts [Blather::JID, String] :jid the JID to attach to the item
+      #   @option opts [#to_s] :node the node the item is attached to
+      #   @option opts [#to_S] :name the name of the Item
+      # @overload new(jid, node = nil, name  = nil)
+      #   Create a new Item
+      #   @param [Blather::JID, String] jid the JID to attach to the item
+      #   @param [#to_s] node the node the item is attached to
+      #   @param [#to_s] name the name of the Item
       def self.new(jid, node = nil, name = nil)
         new_node = super :item
 
@@ -42,15 +70,56 @@ class Stanza
         new_node
       end
 
+      # Get the JID attached to the node
+      #
+      # @return [Blather::JID, nil]
       def jid
         (j = self[:jid]) ? JID.new(j) : nil
       end
-      attribute_writer :jid
 
-      attribute_accessor :node, :name
+      # Set the JID of the node
+      #
+      # @param [Blather::JID, String, nil] jid the new JID
+      def jid=(jid)
+        write_attr :jid, jid
+      end
+
+      # Get the name of the node
+      #
+      # @return [String, nil]
+      def node
+        read_attr :node
+      end
+
+      # Set the name of the node
+      #
+      # @param [String, nil] node the new node name
+      def node=(node)
+        write_attr :node, node
+      end
+
+      # Get the Item name
+      #
+      # @return [String, nil]
+      def name
+        read_attr :name
+      end
+
+      # Set the Item name
+      #
+      # @param [#to_s] name the Item name
+      def name=(name)
+        write_attr :name, name
+      end
 
+      # Check for equality based on jid, node, and name
+      #
+      # @param [Blather::Stanza::DiscoItems::Item] o the other Item
       def eql?(o)
-        raise "Cannot compare #{self.class} with #{o.class}" unless o.is_a?(self.class)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
         o.jid == self.jid &&
         o.node == self.node &&
         o.name == self.name

data/lib/blather/stanza/iq.rb

@@ -1,52 +1,69 @@
 module Blather
 class Stanza
 
-  # = Iq Stanza
+  # # Iq Stanza
   #
-  # Info/Query, or IQ, is a request-response mechanism, similar in some ways to HTTP. The semantics of IQ enable an entity
-  # to make a request of, and receive a response from, another entity. The data content of the request and response is
-  # defined by the namespace declaration of a direct child element of the IQ element, and the interaction is tracked by the
-  # requesting entity through use of the 'id' attribute. Thus, IQ interactions follow a common pattern of structured data
-  # exchange such as get/result or set/result (although an error may be returned in reply to a request if appropriate).
+  # [RFC 3920 Section 9.2.3 - IQ Semantics](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.2.3)
   #
-  # == ID Attribute
+  # Info/Query, or IQ, is a request-response mechanism, similar in some ways
+  # to HTTP. The semantics of IQ enable an entity to make a request of, and
+  # receive a response from, another entity. The data content of the request
+  # and response is defined by the namespace declaration of a direct child
+  # element of the IQ element, and the interaction is tracked by the
+  # requesting entity through use of the 'id' attribute. Thus, IQ interactions
+  # follow a common pattern of structured data exchange such as get/result or
+  # set/result (although an error may be returned in reply to a request if
+  # appropriate).
   #
-  # Iq Stanzas require the ID attribute be set. Blather will handle this automatically when a new Iq is created.
+  # ## "ID" Attribute
   #
-  # == Type Attribute
+  # Iq Stanzas require the ID attribute be set. Blather will handle this
+  # automatically when a new Iq is created.
   #
-  # * +:get+ -- The stanza is a request for information or requirements.
-  # * +:set+ -- The stanza provides required data, sets new values, or replaces existing values.
-  # * +:result+ -- The stanza is a response to a successful get or set request.
-  # * +:error+ -- An error has occurred regarding processing or delivery of a previously-sent get or set (see Stanza Errors).
+  # ## "Type" Attribute
+  #
+  # * `:get` -- The stanza is a request for information or requirements.
+  #
+  # * `:set` -- The stanza provides required data, sets new values, or
+  #   replaces existing values.
+  #
+  # * `:result` -- The stanza is a response to a successful get or set request.
+  #
+  # * `:error` -- An error has occurred regarding processing or delivery of a
+  #   previously-sent get or set (see Stanza Errors).
   #
   # Blather provides a helper for each possible type:
   #
-  #   Iq#get?
-  #   Iq#set?
-  #   Iq#result?
-  #   Iq#error?
+  #     Iq#get?
+  #     Iq#set?
+  #     Iq#result?
+  #     Iq#error?
   #
-  # Blather treats the +type+ attribute like a normal ruby object attribute providing a getter and setter.
-  # The default +type+ is +get+.
+  # Blather treats the `type` attribute like a normal ruby object attribute
+  # providing a getter and setter. The default `type` is `get`.
   #
-  #   iq = Iq.new
-  #   iq.type               # => :get
-  #   iq.get?               # => true
-  #   iq.type = :set
-  #   iq.set?               # => true
-  #   iq.get?               # => false
+  #     iq = Iq.new
+  #     iq.type               # => :get
+  #     iq.get?               # => true
+  #     iq.type = :set
+  #     iq.set?               # => true
+  #     iq.get?               # => false
   #
-  #   iq.type = :invalid    # => RuntimeError
+  #     iq.type = :invalid    # => RuntimeError
   #
+  # @handler :iq
   class Iq < Stanza
-    VALID_TYPES = [:get, :set, :result, :error] # :nodoc:
+    VALID_TYPES = [:get, :set, :result, :error].freeze
 
     register :iq
 
-    def self.import(node) # :nodoc:
+    # @private
+    def self.import(node)
       klass = nil
-      node.children.each { |e| break if klass = class_from_registration(e.element_name, (e.namespace.href if e.namespace)) }
+      node.children.detect do |e|
+        ns = e.namespace ? e.namespace.href : nil
+        klass = class_from_registration(e.element_name, ns)
+      end
 
       if klass && klass != self
         klass.import(node)
@@ -55,11 +72,12 @@ class Stanza
       end
     end
 
-    ##
     # Create a new Iq
-    # * +type+ - the type of stanza (:get, :set, :result, :error)
-    # * +to+ - the JID of the inteded recipient
-    # * +id+ - the stanza's ID. Leaving this nil will set the ID to the next unique number
+    #
+    # @param [Symbol, nil] type the type of stanza (:get, :set, :result, :error)
+    # @param [Blather::JID, String, nil] jid the JID of the inteded recipient
+    # @param [#to_s] id the stanza's ID. Leaving this nil will set the ID to
+    #                the next unique number
     def self.new(type = nil, to = nil, id = nil)
       node = super :iq
       node.type = type || :get
@@ -68,15 +86,53 @@ class Stanza
       node
     end
 
-    attribute_helpers_for :type, VALID_TYPES
+    # Check if the IQ is of type :get
+    #
+    # @return [true, false]
+    def get?
+      self.type == :get
+    end
+
+    # Check if the IQ is of type :set
+    #
+    # @return [true, false]
+    def set?
+      self.type == :set
+    end
+
+    # Check if the IQ is of type :result
+    #
+    # @return [true, false]
+    def result?
+      self.type == :result
+    end
+
+    # Check if the IQ is of type :error
+    #
+    # @return [true, false]
+    def error?
+      self.type == :error
+    end
 
-    ##
     # Ensures type is :get, :set, :result or :error
-    def type=(type) # :nodoc:
-      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
+    #
+    # @param [#to_sym] type the Iq type. Must be one of VALID_TYPES
+    def type=(type)
+      if type && !VALID_TYPES.include?(type.to_sym)
+        raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
+      end
       super
     end
+
+    # Overrides the parent method to ensure the reply is of type :result
+    #
+    # @return [self]
+    def reply!
+      super
+      self.type = :result
+      self
+    end
   end
 
-end #Stanza
+end
 end