blather 0.4.1 → 0.4.2

data/lib/blather/errors.rb

@@ -2,16 +2,27 @@ module Blather
   # Main error class
   class BlatherError < StandardError
     class_inheritable_array :handler_heirarchy
-
     self.handler_heirarchy ||= []
-    self.handler_heirarchy << :error
 
+    @@handler_list = []
+
+    ##
+    # Register the class's handler
     def self.register(handler)
+      @@handler_list << handler
       self.handler_heirarchy.unshift handler
     end
 
+    ##
+    # The list of registered handlers
+    def self.handler_list
+      @@handler_list
+    end
+
+    register :error
+
     # HACK!! until I can refactor the entire Error object model
-    def id
+    def id # :nodoc:
       nil
     end
   end

data/lib/blather/jid.rb

@@ -7,29 +7,23 @@ module Blather
 
     PATTERN = /^(?:([^@]*)@)??([^@\/]*)(?:\/(.*?))?$/.freeze
 
-    ##
-    # Get the JID's node
-    attr_reader :node
-
-    ##
-    # Get the JID's domain
-    attr_reader :domain
+    attr_reader :node,
+                :domain,
+                :resource
 
     ##
-    # Get the JID's resource
-    attr_reader :resource
-
-    ##
-    # If a JID is passed in just return it. 
-    # No need to copy out all the values
+    # 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
 
-    ##
-    # Create a new JID. If called as new('a@b/c'), parse the string and
-    # split (node, domain, resource)
-    def initialize(node, domain = nil, resource = nil)
+    def initialize(node, domain = nil, resource = nil) # :nodoc:
       @resource = resource
       @domain = domain
       @node = node
@@ -62,14 +56,12 @@ module Blather
 
     ##
     # Returns a new JID with resource removed.
-    # return:: [JID]
     def stripped
-      self.class.new @node, @domain
+      dup.strip!
     end
 
     ##
     # Removes the resource (sets it to nil)
-    # return:: [JID] self
     def strip!
       @resource = nil
       self
@@ -80,8 +72,8 @@ module Blather
     # helpful for sorting etc.
     #
     # String representations are compared, see JID#to_s
-    def <=>(o)
-      to_s <=> o.to_s
+    def <=>(other)
+      to_s <=> other.to_s
     end
     alias_method :eql?, :==
 

data/lib/blather/stanza.rb

@@ -34,22 +34,6 @@ module Blather
       'blather%04x' % @@last_id
     end
 
-    ##
-    # Creates a new stanza with the same name as the node
-    # then inherits all the node's attributes and properties
-    def self.import(node)
-      self.new(node.element_name).inherit(node)
-    end
-
-    ##
-    # Automatically set the stanza's ID
-    # and attach it to a document so XPath searching works
-    def self.new(name = nil)
-      node = super
-      node.name = name.to_s if name
-      node
-    end
-
     ##
     # Helper method to generate stanza guard methods
     #

data/lib/blather/stanza/iq.rb

@@ -1,14 +1,50 @@
 module Blather
 class Stanza
 
-  ##
-  # Base 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).
+  #
+  # == ID Attribute
+  #
+  # Iq Stanzas require the ID attribute be set. Blather will handle this automatically when a new Iq is created.
+  #
+  # == 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?
+  #
+  # 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.type = :invalid    # => RuntimeError
+  #
   class Iq < Stanza
-    VALID_TYPES = [:get, :set, :result, :error]
+    VALID_TYPES = [:get, :set, :result, :error] # :nodoc:
 
     register :iq
 
-    def self.import(node)
+    def self.import(node) # :nodoc:
       klass = nil
       node.children.each { |e| break if klass = class_from_registration(e.element_name, (e.namespace.href if e.namespace)) }
 
@@ -19,6 +55,11 @@ 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
     def self.new(type = nil, to = nil, id = nil)
       node = super :iq
       node.type = type || :get
@@ -31,7 +72,7 @@ class Stanza
 
     ##
     # Ensures type is :get, :set, :result or :error
-    def type=(type)
+    def type=(type) # :nodoc:
       raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
       super
     end

data/lib/blather/stanza/message.rb

@@ -1,14 +1,136 @@
 module Blather
 class Stanza
 
-  ##
-  # Base Message stanza
+  # Exchanging messages is a basic use of XMPP and occurs when a user generates a message stanza
+  # that is addressed to another entity. The sender's server is responsible for delivering the
+  # message to the intended recipient (if the recipient is on the same local server) or for routing
+  # the message to the recipient's server (if the recipient is on a remote server). Thus a message
+  # stanza is used to "push" information to another entity.
+  #
+  # == To Attribute
+  #
+  # An instant messaging client specifies an intended recipient for a message by providing the JID
+  # of an entity other than the sender in the +to+ attribute of the Message stanza. If the message
+  # is being sent outside the context of any existing chat session or received message, the value
+  # of the +to+ address SHOULD be of the form "user@domain" rather than of the form "user@domain/resource".
+  #
+  #   msg = Message.new 'user@domain.tld/resource'
+  #   msg.to == 'user@domain.tld/resource'
+  #
+  #   msg.to = 'another-user@some-domain.tld/resource'
+  #   msg.to == 'another-user@some-domain.tld/resource'
+  #
+  # The +to+ attribute on a Message stanza works like any regular ruby object attribute
+  #
+  # == Type Attribute
+  #
+  # Common uses of the message stanza in instant messaging applications include: single messages;
+  # messages sent in the context of a one-to-one chat session; messages sent in the context of a
+  # multi-user chat room; alerts, notifications, or other information to which no reply is expected;
+  # and errors. These uses are differentiated via the +type+ attribute. If included, the +type+
+  # attribute MUST have one of the following values:
+  #
+  # * +:chat+ -- The message is sent in the context of a one-to-one chat session. Typically a receiving 
+  #   client will present message of type +chat+ in an interface that enables one-to-one chat between
+  #   the two parties, including an appropriate conversation history.
+  # * +:error+ -- The message is generated by an entity that experiences an error in processing a message
+  #   received from another entity. A client that receives a message of type +error+ SHOULD present an
+  #   appropriate interface informing the sender of the nature of the error.
+  # * +:groupchat+ -- The message is sent in the context of a multi-user chat environment (similar to that
+  #   of [IRC]). Typically a receiving client will present a message of type +groupchat+ in an interface
+  #   that enables many-to-many chat between the parties, including a roster of parties in the chatroom
+  #   and an appropriate conversation history.
+  # * +:headline+ -- The message provides an alert, a notification, or other information to which no reply
+  #   is expected (e.g., news headlines, sports updates, near-real-time market data, and syndicated content).
+  #   Because no reply to the message is expected, typically a receiving client will present a message of
+  #   type "headline" in an interface that appropriately differentiates the message from standalone messages,
+  #   chat messages, or groupchat messages (e.g., by not providing the recipient with the ability to reply).
+  # * +:normal+ -- The message is a standalone message that is sent outside the context of a one-to-one
+  #   conversation or groupchat, and to which it is expected that the recipient will reply. Typically a receiving
+  #   client will present a message of type +normal+ in an interface that enables the recipient to reply, but
+  #   without a conversation history. The default value of the +type+ attribute is +normal+.
+  #
+  # Blather provides a helper for each possible type:
+  #
+  #   Message#chat?
+  #   Message#error?
+  #   Message#groupchat?
+  #   Message#headline?
+  #   Message#normal?
+  #
+  # Blather treats the +type+ attribute like a normal ruby object attribute providing a getter and setter.
+  # The default +type+ is +chat+.
+  #
+  #   msg = Message.new
+  #   msg.type              # => :chat
+  #   msg.chat?             # => true
+  #   msg.type = :normal
+  #   msg.normal?           # => true
+  #   msg.chat?             # => false
+  #
+  #   msg.type = :invalid   # => RuntimeError
+  #
+  # == Body Element
+  #
+  # The +body+ element contains human-readable XML character data that specifies the textual contents of the message;
+  # this child element is normally included but is optional.
+  #
+  # Blather provides an attribute-like syntax for Message +body+ elements.
+  #
+  #   msg = Message.new 'user@domain.tld', 'message body'
+  #   msg.body  # => 'message body'
+  #
+  #   msg.body = 'other message'
+  #   msg.body  # => 'other message'
+  #
+  # == Subject Element
+  #
+  # The +subject+ element contains human-readable XML character data that specifies the topic of the message.
+  #
+  # Blather provides an attribute-like syntax for Message +subject+ elements.
+  #
+  #   msg = Message.new 'user@domain.tld', 'message subject'
+  #   msg.subject  # => 'message subject'
+  #
+  #   msg.subject = 'other subject'
+  #   msg.subject  # => 'other subject'
+  #
+  # == Thread Element
+  #
+  # The primary use of the XMPP +thread+ element is to uniquely identify a conversation thread or "chat session"
+  # between two entities instantiated by Message stanzas of type +chat+. However, the XMPP thread element can
+  # also be used to uniquely identify an analogous thread between two entities instantiated by Message stanzas
+  # of type +headline+ or +normal+, or among multiple entities in the context of a multi-user chat room instantiated
+  # by Message stanzas of type +groupchat+. It MAY also be used for Message stanzas not related to a human
+  # conversation, such as a game session or an interaction between plugins. The +thread+ element is not used to
+  # identify individual messages, only conversations or messagingg sessions. The inclusion of the +thread+ element
+  # is optional. 
+  #
+  # The value of the +thread+ element is not human-readable and MUST be treated as opaque by entities; no semantic
+  # meaning can be derived from it, and only exact comparisons can be made against it. The value of the +thread+
+  # element MUST be a universally unique identifier (UUID) as described in [UUID].
+  #
+  # The +thread+ element MAY possess a 'parent' attribute that identifies another thread of which the current
+  # thread is an offshoot or child; the value of the 'parent' must conform to the syntax of the +thread+ element itself.
+  #
+  # Blather provides an attribute-like syntax for Message +thread+ elements.
+  # 
+  #   msg = Message.new
+  #   msg.thread = '12345'
+  #   msg.thread                                  # => '12345'
+  #
+  # Parent threads can be set using a hash:
+  #
+  #   msg.thread = {'parent-id' => 'thread-id'}
+  #   msg.thread                                  # => 'thread-id'
+  #   msg.parent_thread                           # => 'parent-id'
+  #
   class Message < Stanza
-    VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal]
+    VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal] # :nodoc:
 
     register :message
 
-    def self.import(node)
+    def self.import(node) # :nodoc:
       klass = nil
       node.children.each { |e| break if klass = class_from_registration(e.element_name, (e.namespace.href if e.namespace)) }
 
@@ -20,7 +142,7 @@ class Stanza
     end
 
     def self.new(to = nil, body = nil, type = :chat)
-      node = super(:message)
+      node = super :message
       node.to = to
       node.type = type
       node.body = body
@@ -29,16 +151,26 @@ class Stanza
 
     attribute_helpers_for :type, VALID_TYPES
 
-    ##
-    # Ensures type is :chat, :error, :groupchat, :headline or :normal
-    def type=(type)
+    def type=(type) # :nodoc:
       raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
       super
     end
 
     content_attr_accessor :body
     content_attr_accessor :subject
-    content_attr_accessor :thread
+
+    content_attr_reader :thread
+
+    def parent_thread # :nodoc:
+      n = find_first('thread')
+      n[:parent] if n
+    end
+
+    def thread=(thread) # :nodoc:
+      parent, thread = thread.to_a.flatten if thread.is_a?(Hash)
+      set_content_for :thread, thread
+      find_first('thread')[:parent] = parent
+    end
   end
 
 end #Stanza

data/lib/blather/stanza/presence.rb

@@ -1,10 +1,54 @@
 module Blather
 class Stanza
 
-  ##
-  # Base Presence stanza
+  # = Presence Stanza
+  #
+  # Within Blather most of the interaction with Presence stanzas will be through one of its child classes: Status or Subscription.
+  #
+  # Presence stanzas are used to express an entity's current network availability (offline or online, along with
+  # various sub-states of the latter and optional user-defined descriptive text), and to notify other entities of
+  # that availability. Presence stanzas are also used to negotiate and manage subscriptions to the presence of other entities.
+  #
+  # == Type Attribute
+  #
+  # The +type+ attribute of a presence stanza is optional. A presence stanza that does not possess a +type+ attribute
+  # is used to signal to the server that the sender is online and available for communication. If included, the +type+
+  # attribute specifies a lack of availability, a request to manage a subscription to another entity's presence, a
+  # request for another entity's current presence, or an error related to a previously-sent presence stanza. If included,
+  # the +type+ attribute must have one of the following values:
+  #
+  # * +:unavailable+ -- Signals that the entity is no longer available for communication
+  # * +:subscribe+ -- The sender wishes to subscribe to the recipient's presence.
+  # * +:subscribed+ -- The sender has allowed the recipient to receive their presence.
+  # * +:unsubscribe+ -- The sender is unsubscribing from another entity's presence.
+  # * +:unsubscribed+ -- The subscription request has been denied or a previously-granted subscription has been cancelled.
+  # * +:probe+ -- A request for an entity's current presence; should be generated only by a server on behalf of a user.
+  # * +:error+ -- An error has occurred regarding processing or delivery of a previously-sent presence stanza.
+  #
+  # Blather provides a helper for each possible type:
+  #
+  #   Presence#unavailabe?
+  #   Presence#unavailable?
+  #   Presence#subscribe?
+  #   Presence#subscribed?
+  #   Presence#unsubscribe?
+  #   Presence#unsubscribed?
+  #   Presence#probe?
+  #   Presence#error?
+  #
+  # Blather treats the +type+ attribute like a normal ruby object attribute providing a getter and setter.
+  # The default +type+ is nil.
+  #
+  #   presence = Presence.new
+  #   presence.type                # => nil
+  #   presence.type = :unavailable
+  #   presence.unavailable?        # => true
+  #   presence.error?              # => false
+  #
+  #   presence.type = :invalid   # => RuntimeError
+  #
   class Presence < Stanza
-    VALID_TYPES = [:unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe, :error]
+    VALID_TYPES = [:unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe, :error] # :nodoc:
 
     register :presence
 
@@ -13,7 +57,7 @@ class Stanza
     # either a Status or Subscription object is created based
     # on the type attribute.
     # If neither is found it instantiates a Presence object
-    def self.import(node)
+    def self.import(node) # :nodoc:
       klass = case node['type']
       when nil, 'unavailable' then Status
       when /subscribe/        then Subscription
@@ -32,7 +76,7 @@ class Stanza
 
     ##
     # Ensures type is one of :unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe or :error
-    def type=(type)
+    def type=(type) # :nodoc:
       raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
       super
     end