blather 0.4.7 → 0.4.8

data/lib/blather/core_ext/active_support.rb

@@ -1,44 +1,44 @@
 require File.join(File.dirname(__FILE__), 'active_support', 'inheritable_attributes')
 
-class Object # :nodoc:
+class Object  # @private
   def duplicable?; true; end
   def blank?; respond_to?(:empty?) ? empty? : !self; end
   def present?; !blank?; end
 end
 
-class Array #:nodoc:
+class Array  # @private
   alias_method :blank?, :empty?
   def extract_options!; last.is_a?(::Hash) ? pop : {}; end
 end
 
-class Hash #:nodoc:
+class Hash  # @private
   alias_method :blank?, :empty?
 end
 
-class String #:nodoc:
+class String  # @private
   def blank?; self !~ /\S/; end
 end
 
-class NilClass #:nodoc:
+class NilClass  # @private
   def duplicable?; false; end
   def blank?; true; end
 end
 
-class FalseClass #:nodoc:
+class FalseClass  # @private
   def duplicable?; false; end
   def blank?; true; end
 end
 
-class TrueClass #:nodoc:
+class TrueClass  # @private
   def duplicable?; false; end
   def blank?; false; end
 end
 
-class Symbol #:nodoc:
+class Symbol  # @private
   def duplicable?; false; end
 end
 
-class Numeric #:nodoc:
+class Numeric  # @private
   def duplicable?; false; end
   def blank?; false; end
 end

data/lib/blather/core_ext/active_support/inheritable_attributes.rb

@@ -4,7 +4,7 @@
 # their parents' attributes, instead of just a pointer to the same. This means that the child can add elements
 # to, for example, an array without those additions being shared with either their parent, siblings, or
 # children, which is unlike the regular class-level attributes that are shared across the entire hierarchy.
-class Class # :nodoc:
+class Class  # @private
   def class_inheritable_reader(*syms)
     syms.each do |sym|
       next if sym.is_a?(Hash)
@@ -114,4 +114,4 @@ class Class # :nodoc:
 
     alias inherited_without_inheritable_attributes inherited
     alias inherited inherited_with_inheritable_attributes
-end #Class
+end  # Class

data/lib/blather/core_ext/nokogiri.rb

@@ -1,22 +1,25 @@
-module Nokogiri # :nodoc:
+module Nokogiri
 module XML
 
   class Node
+    # Alias #name to #element_name so we can use #name in an XMPP Stanza context
     alias_method :element_name, :name
     alias_method :element_name=, :name=
 
-    alias_method :attr_set, :[]=
+    alias_method :attr_set, :[]= # :nodoc:
+    # Override Nokogiri's attribute setter to add the ability to kill an attribute
+    # by setting it to nil and to be able to lookup an attribute by symbol
+    #
+    # @param [#to_s] name the name of the attribute
+    # @param [#to_s, nil] value the new value or nil to remove it
     def []=(name, value)
       name = name.to_s
       value.nil? ? remove_attribute(name) : attr_set(name, value.to_s)
     end
 
-#    alias_method :attr_get, :[]
-#    def [](name)
-#      attr_get name.to_s
-#    end
-
     alias_method :nokogiri_xpath, :xpath
+    # Override Nokogiri's #xpath method to add the ability to use symbols for lookup
+    # and namespace designation
     def xpath(*paths)
       paths[0] = paths[0].to_s
       if paths.size > 1 && (namespaces = paths.pop).is_a?(Hash)
@@ -26,6 +29,8 @@ module XML
     end
     alias_method :find, :xpath
 
+    # Return the first element at a specified xpath
+    # @see #xpath
     def find_first(*paths)
       xpath(*paths).first
     end

data/lib/blather/errors.rb

@@ -1,41 +1,50 @@
 module Blather
   # Main error class
+  # This starts the error hierarchy
+  #
+  # @handler :error
   class BlatherError < StandardError
-    class_inheritable_array :handler_heirarchy
-    self.handler_heirarchy ||= []
+    class_inheritable_array :handler_hierarchy
+    self.handler_hierarchy ||= []
 
+    # @private
     @@handler_list = []
 
-    ##
     # Register the class's handler
+    #
+    # @param [Symbol] handler the handler name
     def self.register(handler)
       @@handler_list << handler
-      self.handler_heirarchy.unshift handler
+      self.handler_hierarchy.unshift handler
     end
 
-    ##
     # The list of registered handlers
+    #
+    # @return [Array<Symbol>] a list of currently registered handlers
     def self.handler_list
       @@handler_list
     end
 
     register :error
 
+    # @private
     # HACK!! until I can refactor the entire Error object model
-    def id # :nodoc:
+    def id
       nil
     end
-  end
+  end  # BlatherError
 
-  ##
   # Used in cases where a stanza only allows specific values for its attributes
   # and an invalid value is attempted.
+  #
+  # @handler :argument_error
   class ArgumentError < BlatherError
     register :argument_error
-  end
+  end  # ArgumentError
 
-  ##
   # The stream handler received a response it didn't know how to handle
+  #
+  # @handler :unknown_response_error
   class UnknownResponse < BlatherError
     register :unknown_response_error
     attr_reader :node
@@ -43,10 +52,11 @@ module Blather
     def initialize(node)
       @node = node
     end
-  end
+  end  # UnknownResponse
 
-  ##
   # Something bad happened while parsing the incoming stream
+  #
+  # @handler :parse_error
   class ParseError < BlatherError
     register :parse_error
     attr_reader :message
@@ -54,5 +64,6 @@ module Blather
     def initialize(msg)
       @message = msg.to_s
     end
-  end
-end
+  end  # ParseError
+
+end  # Blather

data/lib/blather/errors/sasl_error.rb

@@ -1,25 +1,43 @@
 module Blather
 
+# General SASL Errors
+# Check #name for the error name
+#
+# @handler :sasl_error
 class SASLError < BlatherError
   SASL_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-sasl'
 
   class_inheritable_accessor :err_name
+  # @private
   @@registrations = {}
 
   register :sasl_error
 
+  # Import the stanza
+  #
+  # @param [Blather::XMPPNode] node the error node
+  # @return [Blather::SASLError]
   def self.import(node)
     self.new node
   end
 
+  # Create a new SASLError
+  #
+  # @param [Blather::XMPPNode] node the error node
   def initialize(node)
     super()
     @node = node
   end
 
+  # The actual error name
+  #
+  # @return [Symbol] a symbol representing the error name
   def name
-    @node.find_first('err_ns:*', :err_ns => SASL_ERR_NS).element_name.gsub('-', '_').to_sym if @node
+    if @node
+      name = @node.find_first('ns:*', :ns => SASL_ERR_NS).element_name
+      name.gsub('-', '_').to_sym
+    end
   end
-end #SASLError
+end  # SASLError
 
-end #Blather
+end  # Blather

data/lib/blather/errors/stanza_error.rb

@@ -1,19 +1,21 @@
 module Blather
 
-##
 # Stanza errors
 # RFC3920 Section 9.3 (http://xmpp.org/rfcs/rfc3920.html#stanzas-error)
+#
+# @handler :stanza_error
 class StanzaError < BlatherError
   STANZA_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-stanzas'
-  VALID_TYPES = [:cancel, :continue, :modify, :auth, :wait]
+  VALID_TYPES = [:cancel, :continue, :modify, :auth, :wait].freeze
 
   register :stanza_error
 
   attr_reader :original, :name, :type, :text, :extras
 
-  ##
-  # Factory method for instantiating the proper class
-  # for the error
+  # Factory method for instantiating the proper class for the error
+  #
+  # @param [Blather::XMPPNode] node the error node to import
+  # @return [Blather::StanzaError]
   def self.import(node)
     original = node.copy
     original.remove_child 'error'
@@ -30,12 +32,14 @@ class StanzaError < BlatherError
     self.new original, name, type, text, extras
   end
 
-  ##
-  # <tt>original</tt> An original node must be provided for stanza errors. You can't declare
-  # a stanza error on without a stanza.
-  # <tt>type</tt> is the error type specified in RFC3920 (http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
-  # <tt>text</tt> is an option error description
-  # <tt>extras</tt> an array of application specific nodes to add to the error. These should be properly namespaced.
+  # Create a new StanzaError
+  #
+  # @param [Blather::XMPPNode] original the original stanza
+  # @param [String] name the error name
+  # @param [#to_s] type the error type as specified in
+  # [RFC3920](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
+  # @param [String, nil] text additional text for the error
+  # @param [Array<Blather::XMPPNode>] extras an array of extra nodes to add
   def initialize(original, name, type, text = nil, extras = [])
     @original = original
     @name = name
@@ -44,20 +48,29 @@ class StanzaError < BlatherError
     @extras = extras
   end
 
-  ##
-  # Set the error type (see RFC3920 Section 9.3.2 (http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2))
+  # Set the error type
+  #
+  # @param [#to_sym] type the new error type. Must be on of
+  # Blather::StanzaError::VALID_TYPES
+  # @see [RFC3920 Section 9.3.2](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
   def type=(type)
     type = type.to_sym
-    raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if !VALID_TYPES.include?(type)
+    if !VALID_TYPES.include?(type)
+      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
+    end
     @type = type
   end
 
+  # The error name
+  #
+  # @return [Symbol]
   def name
     @name.gsub('-','_').to_sym
   end
 
-  ##
   # Creates an XML node from the error
+  #
+  # @return [Blather::XMPPNode]
   def to_node
     node = self.original.reply
     node.type = 'error'
@@ -76,16 +89,19 @@ class StanzaError < BlatherError
     node
   end
 
-  ##
-  # Turns the object into XML fit to be sent over the stream
+  # Convert the object to a proper node then convert it to a string
+  #
+  # @return [String]
   def to_xml
     to_node.to_s
   end
 
-  def inspect # :nodoc:
+  # @private
+  def inspect
     "Stanza Error (#{@name}): #{self.text} [#{self.extras}]"
   end
-  alias_method :to_s, :inspect # :nodoc:
-end #StanzaError
+  # @private
+  alias_method :to_s, :inspect
+end  # StanzaError
 
-end #Blather
+end  # Blather

data/lib/blather/errors/stream_error.rb

@@ -1,8 +1,9 @@
 module Blather
 
-##
 # Stream Errors
-# RFC3920 Section 9.3 (http://xmpp.org/rfcs/rfc3920.html#streams-error-rules)
+# [RFC3920 Section 9.3](http://xmpp.org/rfcs/rfc3920.html#streams-error-rules)
+#
+# @handler :stream_error
 class StreamError < BlatherError
   STREAM_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-streams'
 
@@ -10,9 +11,9 @@ class StreamError < BlatherError
 
   attr_reader :text, :extras
 
-  ##
-  # Factory method for instantiating the proper class
-  # for the error
+  # Factory method for instantiating the proper class for the error
+  #
+  # @param [Blather::XMPPNode] node the importable node
   def self.import(node)
     name = node.find_first('descendant::*[name()!="text"]', STREAM_ERR_NS).element_name
 
@@ -24,23 +25,29 @@ class StreamError < BlatherError
     self.new name, text, extras
   end
 
-  ##
-  # <tt>text</tt> is the (optional) error message.
-  # <tt>extras</tt> should be an array of nodes to attach to the error
-  # each extra should be in an application specific namespace
-  # see RFC3920 Section 4.7.2 (http://xmpp.org/rfcs/rfc3920.html#rfc.section.4.7.2)
+  # Create a new Stream Error
+  # [RFC3920 Section 4.7.2](http://xmpp.org/rfcs/rfc3920.html#rfc.section.4.7.2)
+  #
+  # @param [String] name the error name
+  # @param [String, nil] text optional error text
+  # @param [Array<Blather::XMPPNode>] extras an array of extras to attach to the
+  # error
   def initialize(name, text = nil, extras = [])
     @name = name
     @text = text
     @extras = extras
   end
 
+  # The error name
+  #
+  # @return [Symbol]
   def name
     @name.gsub('-','_').to_sym
   end
 
-  ##
   # Creates an XML node from the error
+  #
+  # @return [Blather::XMPPNode]
   def to_node
     node = XMPPNode.new('stream:error')
 
@@ -57,16 +64,19 @@ class StreamError < BlatherError
     node
   end
 
-  ##
-  # Turns the object into XML fit to be sent over the stream
+  # Convert the object to a proper node then convert it to a string
+  #
+  # @return [String]
   def to_xml
     to_node.to_s
   end
 
-  def inspect # :nodoc:
+  # @private
+  def inspect
     "Stream Error (#{@name}): #{self.text}" + (self.extras.empty? ? '' : " [#{self.extras}]")
   end
-  alias_method :to_s, :inspect # :nodoc:
-end #StreamError
+  # @private
+  alias_method :to_s, :inspect
+end  # StreamError
 
-end #Blather
+end  # Blather

data/lib/blather/jid.rb

@@ -1,7 +1,48 @@
 module Blather
 
-  ##
-  # This is a simple modification of the JID class from XMPP4R
+  # Jabber ID or JID
+  #
+  # See [RFC 3920 Section 3 - Addressing](http://xmpp.org/rfcs/rfc3920.html#addressing)
+  #
+  # An entity is anything that can be considered a network endpoint (i.e., an
+  # ID on the network) and that can communicate using XMPP. All such entities
+  # are uniquely addressable in a form that is consistent with RFC 2396 [URI].
+  # For historical reasons, the address of an XMPP entity is called a Jabber
+  # Identifier or JID. A valid JID contains a set of ordered elements formed
+  # of a domain identifier, node identifier, and resource identifier.
+  #
+  # The syntax for a JID is defined below using the Augmented Backus-Naur Form
+  # as defined in [ABNF]. (The IPv4address and IPv6address rules are defined
+  # in Appendix B of [IPv6]; the allowable character sequences that conform to
+  # the node rule are defined by the Nodeprep profile of [STRINGPREP] as
+  # documented in Appendix A of this memo; the allowable character sequences
+  # that conform to the resource rule are defined by the Resourceprep profile
+  # of [STRINGPREP] as documented in Appendix B of this memo; and the
+  # sub-domain rule makes reference to the concept of an internationalized
+  # domain label as described in [IDNA].)
+  #
+  #     jid             = [ node "@" ] domain [ "/" resource ]
+  #     domain          = fqdn / address-literal
+  #     fqdn            = (sub-domain 1*("." sub-domain))
+  #     sub-domain      = (internationalized domain label)
+  #     address-literal = IPv4address / IPv6address
+  #
+  # All JIDs are based on the foregoing structure. The most common use of this
+  # structure is to identify an instant messaging user, the server to which
+  # the user connects, and the user's connected resource (e.g., a specific
+  # client) in the form of <user@host/resource>. However, node types other
+  # than clients are possible; for example, a specific chat room offered by a
+  # multi-user chat service could be addressed as <room@service> (where "room"
+  # is the name of the chat room and "service" is the hostname of the
+  # multi-user chat service) and a specific occupant of such a room could be
+  # addressed as <room@service/nick> (where "nick" is the occupant's room
+  # nickname). Many other JID types are possible (e.g., <domain/resource>
+  # could be a server-side script or service).
+  #
+  # Each allowable portion of a JID (node identifier, domain identifier, and
+  # resource identifier) MUST NOT be more than 1023 bytes in length, resulting
+  # in a maximum total size (including the '@' and '/' separators) of 3071
+  # bytes.
   class JID
     include Comparable
 
@@ -11,19 +52,27 @@ module Blather
                 :domain,
                 :resource
 
-    ##
-    # Create a new JID. If called as new('a@b/c'), parse the string and split (node, domain, resource).
-    # * +node+ - can be any of the following:
-    #   * a string representing the JID ("node@domain.tld/resource")
-    #   * a JID. in which case nothing will be done and the original JID will be passed back
-    #   * a string representing the node
-    # * +domain+ - the domain of the JID
-    # * +resource+ - the resource the connection should be bound to
     def self.new(node, domain = nil, resource = nil)
       node.is_a?(JID) ? node : super
     end
 
-    def initialize(node, domain = nil, resource = nil) # :nodoc:
+    # Create a new JID object
+    #
+    # @overload initialize(jid)
+    #   Passes the jid object right back out
+    #   @param [Blather::JID] jid a jid object
+    # @overload initialize(jid)
+    #   Creates a new JID parsed out of the provided jid
+    #   @param [String] jid a jid in the standard format
+    #   ("node@domain/resource")
+    # @overload initialize(node, domain = nil, resource = nil)
+    #   Creates a new JID
+    #   @param [String] node the node of the JID
+    #   @param [String, nil] domian the domain of the JID
+    #   @param [String, nil] resource the resource of the JID
+    # @raise [ArgumentError] if the parts of the JID are too large (1023 bytes)
+    # @return [Blather::JID] a new jid object
+    def initialize(node, domain = nil, resource = nil)
       @resource = resource
       @domain = domain
       @node = node
@@ -35,18 +84,20 @@ module Blather
       @node.downcase!   if @node
       @domain.downcase! if @domain
 
-      raise ArgumentError, 'Node too long'      if (@node || '').length > 1023
-      raise ArgumentError, 'Domain too long'    if (@domain || '').length > 1023
-      raise ArgumentError, 'Resource too long'  if (@resource || '').length > 1023
+      raise ArgumentError, 'Node too long' if (@node || '').length > 1023
+      raise ArgumentError, 'Domain too long' if (@domain || '').length > 1023
+      raise ArgumentError, 'Resource too long' if (@resource || '').length > 1023
     end
 
-    ##
-    # Returns a string representation of the JID
+    # Turn the JID into a string
+    #
     # * ""
     # * "domain"
     # * "node@domain"
     # * "domain/resource"
     # * "node@domain/resource"
+    #
+    # @return [String] the JID as a string
     def to_s
       s = @domain
       s = "#{@node}@#{s}" if @node
@@ -54,34 +105,38 @@ module Blather
       s
     end
 
-    ##
     # Returns a new JID with resource removed.
+    #
+    # @return [Blather::JID] a new JID without a resource
     def stripped
       dup.strip!
     end
 
-    ##
     # Removes the resource (sets it to nil)
+    #
+    # @return [Blather::JID] the JID without a resource
     def strip!
       @resource = nil
       self
     end
 
-    ##
-    # Compare two JIDs,
-    # helpful for sorting etc.
+    # Compare two JIDs, helpful for sorting etc.
     #
     # String representations are compared, see JID#to_s
+    #
+    # @param [#to_s] other a JID to comare against
+    # @return [Fixnum<-1, 0, 1>]
     def <=>(other)
       to_s <=> other.to_s
     end
     alias_method :eql?, :==
 
-    ##
     # Test if JID is stripped
+    #
+    # @return [true, false]
     def stripped?
       @resource.nil?
     end
-  end
+  end  # JID
 
-end
+end  # Blather