shingara-blather 0.4.8

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

@@ -0,0 +1,53 @@
+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
+
+    # 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
+
+    # 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
+    # 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)
+      else
+        find_first('query')
+      end
+
+      unless q
+        (self << (q = XMPPNode.new('query', self.document)))
+        q.namespace = self.class.registered_ns
+      end
+      q
+    end
+  end #Query
+
+end #Iq
+end #Stanza
+end

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

@@ -0,0 +1,179 @@
+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'
+
+    # 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
+      super
+      # transmogrify nodes into RosterItems
+      items.each { |i| query << RosterItem.new(i); i.remove }
+      self
+    end
+
+    # The list of roster items
+    #
+    # @return [Array<Blather::Stanza::Iq::Roster::RosterItem>]
+    def items
+      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
+
+      # 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
+
+        case jid
+        when Nokogiri::XML::Node
+          new_node.inherit jid
+        when Hash
+          new_node.jid = jid[:jid]
+          new_node.name = jid[:name]
+          new_node.subscription = jid[:subscription]
+          new_node.ask = jid[:ask]
+        else
+          new_node.jid = jid
+          new_node.name = name
+          new_node.subscription = subscription
+          new_node.ask = ask
+        end
+        new_node
+      end
+
+      # Get the JID attached to the item
+      #
+      # @return [Blather::JID, nil]
+      def jid
+        (j = self[:jid]) ? JID.new(j) : nil
+      end
+
+      # 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
+
+      # 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
+      #
+      # @param [Array<#to_s>] new_groups an array of group names
+      def groups=(new_groups)
+        remove_children :group
+        if new_groups
+          new_groups.uniq.each do |g|
+            self << (group = XMPPNode.new(:group, self.document))
+            group.content = g
+          end
+        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
+    end #RosterItem
+  end #Roster
+
+end #Iq
+end #Stanza
+end

data/lib/blather/stanza/iq.rb

@@ -0,0 +1,138 @@
+module Blather
+class Stanza
+
+  # # Iq Stanza
+  #
+  # [RFC 3920 Section 9.2.3 - IQ Semantics](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.2.3)
+  #
+  # 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
+  #
+  # @handler :iq
+  class Iq < Stanza
+    VALID_TYPES = [:get, :set, :result, :error].freeze
+
+    register :iq
+
+    # @private
+    def self.import(node)
+      klass = nil
+      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)
+      else
+        new(node[:type]).inherit(node)
+      end
+    end
+
+    # Create a new Iq
+    #
+    # @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
+      node.to = to
+      node.id = id || self.next_id
+      node
+    end
+
+    # 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
+    #
+    # @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
+end

data/lib/blather/stanza/message.rb

@@ -0,0 +1,332 @@
+module Blather
+class Stanza
+
+  # # 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?
+  #
+  # 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 body'
+  #     msg.subject = 'message subject'
+  #     msg.subject  # => 'message 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'
+  #
+  # @handler :message
+  class Message < Stanza
+    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
+
+    # @private
+    def self.import(node)
+      klass = nil
+      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)
+      else
+        new(node[:type]).inherit(node)
+      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
+      node.type = type
+      node.body = body
+      node
+    end
+
+    # Check if the Message is of type :chat
+    #
+    # @return [true, false]
+    def chat?
+      self.type == :chat
+    end
+
+    # 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
+
+    # 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
+
+    # 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
+
+    # Get the parent thread
+    #
+    # @return [String, nil]
+    def parent_thread
+      n = find_first('thread')
+      n[:parent] if n
+    end
+
+    # 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
+end