blather 0.4.7 → 0.4.8

data/lib/blather/stanza/iq/query.rb

@@ -2,27 +2,37 @@ module Blather
 class Stanza
 class Iq
 
+  # # Query Stanza
+  #
+  # This is a base class for any query based Iq stanzas. It provides a base set
+  # of methods for working with query stanzas
+  #
+  # @handler :query
   class Query < Iq
     register :query, :query
 
-    ##
-    # Ensure the query node is created
+    # Overrides the parent method to ensure a query node is created
+    #
+    # @see Blather::Stanza::Iq.new
     def self.new(type = nil)
       node = super
       node.query
       node
     end
 
-    ##
-    # Kill the query node before running inherit
+    # Overrides the parent method to ensure the current query node is destroyed
+    #
+    # @see Blather::Stanza::Iq#inherit
     def inherit(node)
       query.remove
       super
     end
 
-    ##
     # Query node accessor
-    # This will ensure there actually is a query node
+    # If a query node exists it will be returned.
+    # Otherwise a new node will be created and returned
+    #
+    # @return [Balather::XMPPNode]
     def query
       q = if self.class.registered_ns
         find_first('query_ns:query', :query_ns => self.class.registered_ns)
@@ -36,22 +46,6 @@ class Iq
       end
       q
     end
-
-    ##
-    # A query reply should have type set to "result"
-    def reply
-      elem = super
-      elem.type = :result
-      elem
-    end
-
-    ##
-    # A query reply should have type set to "result"
-    def reply!
-      super
-      self.type = :result
-      self
-    end
   end #Query
 
 end #Iq

data/lib/blather/stanza/iq/roster.rb

@@ -2,20 +2,28 @@ module Blather
 class Stanza
 class Iq
 
+  # # Roster Stanza
+  #
+  # [RFC 3921 Section 7 - Roster Management](http://xmpp.org/rfcs/rfc3921.html#roster)
+  #
+  # @handler :roster
   class Roster < Query
     register :roster, nil, 'jabber:iq:roster'
 
-    ##
-    # Any new items are added to the query
+    # Create a new roster stanza and (optionally) load it with an item
+    #
+    # @param [<Blather::Stanza::Iq::VALID_TYPES>] type the stanza type
+    # @param [Blather::XMPPNode] item a roster item
     def self.new(type = nil, item = nil)
       node = super type
       node.query << item if item
       node
     end
 
-    ##
     # Inherit the XMPPNode to create a proper Roster object.
     # Creates RosterItem objects out of each roster item as well.
+    #
+    # @param [Blather::XMPPNode] node a node to inherit
     def inherit(node)
       # remove the current set of nodes
       remove_children :item
@@ -25,18 +33,41 @@ class Iq
       self
     end
 
-    ##
-    # Roster items
+    # The list of roster items
+    #
+    # @return [Array<Blather::Stanza::Iq::Roster::RosterItem>]
     def items
-      query.find('//ns:item', :ns => self.class.registered_ns).map { |i| RosterItem.new(i) }
+      query.find('//ns:item', :ns => self.class.registered_ns).map do |i|
+        RosterItem.new i
+      end
     end
 
+    # # RosterItem Fragment
+    #
+    # Individual roster items.
+    # This is a convenience class to attach methods to the node
     class RosterItem < XMPPNode
-      ##
-      # [jid] may be either a JID or XMPPNode. 
-      # [name] name alias of the given JID
-      # [subscription] subscription type
-      # [ask] ask subscription sub-state
+
+      # Create a new RosterItem
+      # @overload new(XML::Node)
+      #   Create a RosterItem by inheriting a node
+      #   @param [XML::Node] node an xml node to inherit
+      # @overload new(opts)
+      #   Create a RosterItem through a hash of options
+      #   @param [Hash] opts the options
+      #   @option opts [Blather::JID, String, nil] :jid the JID of the item
+      #   @option opts [String, nil] :name the alias to give the JID
+      #   @option opts [Symbol, nil] :subscription the subscription status of
+      #   the RosterItem must be one of
+      #   Blather::RosterItem::VALID_SUBSCRIPTION_TYPES
+      #   @option opts [:subscribe, nil] :ask the ask value of the RosterItem
+      # @overload new(jid = nil, name = nil, subscription = nil, ask = nil)
+      #   @param [Blather::JID, String, nil] jid the JID of the item
+      #   @param [String, nil] name the alias to give the JID
+      #   @param [Symbol, nil] subscription the subscription status of the
+      #   RosterItem must be one of
+      #   Blather::RosterItem::VALID_SUBSCRIPTION_TYPES
+      #   @param [:subscribe, nil] ask the ask value of the RosterItem
       def self.new(jid = nil, name = nil, subscription = nil, ask = nil)
         new_node = super :item
 
@@ -57,26 +88,72 @@ class Iq
         new_node
       end
 
-      ##
-      # Roster item's JID
+      # Get the JID attached to the item
+      #
+      # @return [Blather::JID, nil]
       def jid
         (j = self[:jid]) ? JID.new(j) : nil
       end
-      attribute_writer :jid
 
-      attribute_accessor :name
+      # Set the JID of the item
+      #
+      # @param [Blather::JID, String, nil] jid the new JID
+      def jid=(jid)
+        write_attr :jid, jid
+      end
+
+      # Get the item name
+      #
+      # @return [String, nil]
+      def name
+        read_attr :name
+      end
+
+      # Set the item name
+      #
+      # @param [#to_s] name the name of the item
+      def name=(name)
+        write_attr :name, name
+      end
+
+      # Get the subscription value of the item
+      #
+      # @return [<:both, :from, :none, :remove, :to>]
+      def subscription
+        read_attr :subscription, :to_sym
+      end
+
+      # Set the subscription value of the item
+      #
+      # @param [<:both, :from, :none, :remove, :to>] subscription
+      def subscription=(subscription)
+        write_attr :subscription, subscription
+      end
 
-      attribute_accessor :subscription, :ask, :call => :to_sym
+      # Get the ask value of the item
+      #
+      # @return [<:subscribe, nil>]
+      def ask
+        read_attr :ask, :to_sym
+      end
+
+      # Set the ask value of the item
+      #
+      # @param [<:subscribe, nil>] ask
+      def ask=(ask)
+        write_attr :ask, ask
+      end
 
-      ##
       # The groups roster item belongs to
+      #
+      # @return [Array<String>]
       def groups
         find('child::*[local-name()="group"]').map { |g| g.content }
       end
 
-      ##
       # Set the roster item's groups
-      # must be an array
+      #
+      # @param [Array<#to_s>] new_groups an array of group names
       def groups=(new_groups)
         remove_children :group
         if new_groups
@@ -87,9 +164,10 @@ class Iq
         end
       end
 
-      ##
       # Convert the roster item to a proper stanza all wrapped up
       # This facilitates new subscriptions
+      #
+      # @return [Blather::Stanza::Iq::Roster]
       def to_stanza
         Roster.new(:set, self)
       end

data/lib/blather/stanza/message.rb

@@ -1,138 +1,176 @@
 module Blather
 class 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+.
+  # # Message Stanza
+  #
+  # [RFC 3921 Section 2.1 - Message Syntax](http://xmpp.org/rfcs/rfc3921.html#rfc.section.2.1)
+  #
+  # 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?
+  #     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`.
   #
-  # 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 = Message.new
-  #   msg.type              # => :chat
-  #   msg.chat?             # => true
-  #   msg.type = :normal
-  #   msg.normal?           # => true
-  #   msg.chat?             # => false
+  #     msg.type = :invalid   # => RuntimeError
   #
-  #   msg.type = :invalid   # => RuntimeError
   #
-  # == Body Element
+  # ## "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.
+  # 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.
+  # Blather provides an attribute-like syntax for Message `body` elements.
   #
-  #   msg = Message.new 'user@domain.tld', 'message body'
-  #   msg.body  # => 'message body'
+  #     msg = Message.new 'user@domain.tld', 'message body'
+  #     msg.body  # => 'message body'
   #
-  #   msg.body = 'other message'
-  #   msg.body  # => 'other message'
+  #     msg.body = 'other message'
+  #     msg.body  # => 'other message'
   #
-  # == Subject Element
+  # ## "Subject" Element
   #
-  # The +subject+ element contains human-readable XML character data that specifies the topic of the message.
+  # 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.
+  # Blather provides an attribute-like syntax for Message `subject` elements.
   #
-  #   msg = Message.new 'user@domain.tld', 'message subject'
-  #   msg.subject  # => 'message subject'
+  #     msg = Message.new 'user@domain.tld', 'message body'
+  #     msg.subject = 'message subject'
+  #     msg.subject  # => 'message subject'
   #
-  #   msg.subject = 'other subject'
-  #   msg.subject  # => 'other subject'
+  # ## "Thread" Element
   #
-  # == 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 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 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.
   #
-  # 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.
   #
-  # Blather provides an attribute-like syntax for Message +thread+ elements.
-  # 
-  #   msg = Message.new
-  #   msg.thread = '12345'
-  #   msg.thread                                  # => '12345'
+  #     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'
+  #     msg.thread = {'parent-id' => 'thread-id'}
+  #     msg.thread                                  # => 'thread-id'
+  #     msg.parent_thread                           # => 'parent-id'
   #
+  # @handler :message
   class Message < Stanza
-    VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal] # :nodoc:
+    VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal].freeze
+
+    HTML_NS = 'http://jabber.org/protocol/xhtml-im'.freeze
+    HTML_BODY_NS = 'http://www.w3.org/1999/xhtml'.freeze
 
     register :message
 
-    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)
@@ -141,6 +179,11 @@ class Stanza
       end
     end
 
+    # Create a new Message stanza
+    #
+    # @param [#to_s] to the JID to send the message to
+    # @param [#to_s] body the body of the message
+    # @param [Symbol] type the message type. Must be one of VALID_TYPES
     def self.new(to = nil, body = nil, type = :chat)
       node = super :message
       node.to = to
@@ -149,29 +192,141 @@ class Stanza
       node
     end
 
-    attribute_helpers_for :type, VALID_TYPES
+    # Check if the Message is of type :chat
+    #
+    # @return [true, false]
+    def chat?
+      self.type == :chat
+    end
 
-    def type=(type) # :nodoc:
-      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
+    # Check if the Message is of type :error
+    #
+    # @return [true, false]
+    def error?
+      self.type == :error
+    end
+
+    # Check if the Message is of type :groupchat
+    #
+    # @return [true, false]
+    def groupchat?
+      self.type == :groupchat
+    end
+
+    # Check if the Message is of type :headline
+    #
+    # @return [true, false]
+    def headline?
+      self.type == :headline
+    end
+
+    # Check if the Message is of type :normal
+    #
+    # @return [true, false]
+    def normal?
+      self.type == :normal
+    end
+
+    # Ensures type is :get, :set, :result or :error
+    #
+    # @param [#to_sym] type the Message 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
 
-    content_attr_accessor :body
-    content_attr_accessor :subject
+    # Get the message body
+    #
+    # @return [String]
+    def body
+      read_content :body
+    end
+
+    # Set the message body
+    #
+    # @param [#to_s] body the message body
+    def body=(body)
+      set_content_for :body, body
+    end
+
+    # Get the message xhtml node
+    # This will create the node if it doesn't exist
+    #
+    # @return [XML::Node]
+    def xhtml_node
+      unless h = find_first('ns:html', :ns => HTML_NS)
+        self << (h = XMPPNode.new('html', self.document))
+        h.namespace = HTML_NS
+      end
+
+      unless b = h.find_first('ns:body', :ns => HTML_BODY_NS)
+        h << (b = XMPPNode.new('body', self.document))
+        b.namespace = HTML_BODY_NS
+      end
+
+      b
+    end
+
+    # Get the message xhtml
+    #
+    # @return [String]
+    def xhtml
+      self.xhtml_node.content.strip
+    end
+
+    # Set the message xhtml
+    # This will use Nokogiri to ensure the xhtml is valid
+    #
+    # @param [#to_s] valid xhtml
+    def xhtml=(xhtml_body)
+      self.xhtml_node.content = Nokogiri::XML(xhtml_body).to_xhtml
+    end
 
-    content_attr_reader :thread
+    # Get the message subject
+    #
+    # @return [String]
+    def subject
+      read_content :subject
+    end
+
+    # Set the message subject
+    #
+    # @param [#to_s] body the message subject
+    def subject=(subject)
+      set_content_for :subject, subject
+    end
+
+    # Get the message thread
+    #
+    # @return [String]
+    def thread
+      read_content :thread
+    end
 
-    def parent_thread # :nodoc:
+    # Get the parent thread
+    #
+    # @return [String, nil]
+    def parent_thread
       n = find_first('thread')
       n[:parent] if n
     end
 
-    def thread=(thread) # :nodoc:
+    # Set the thread
+    #
+    # @overload thread=(hash)
+    #   Set a thread with a parent
+    #   @param [Hash<parent-id => thread-id>] thread
+    # @overload thread=(thread)
+    #   Set a thread id
+    #   @param [#to_s] thread the new thread id
+    def thread=(thread)
       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
+end
 end