tp-blather 0.8.2

data/lib/blather/stanza/presence/status.rb

@@ -0,0 +1,218 @@
+module Blather
+class Stanza
+class Presence
+
+  # # Status Stanza
+  #
+  # [RFC 3921 Section 2.2.2 - Presence Child Elements](http://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2)
+  #
+  # 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.
+  #
+  # ## "State" Attribute
+  #
+  # The `state` attribute determains the availability of the entity and can be
+  # one of the following:
+  #
+  # * `:available` -- The entity or resource is available
+  #
+  # * `:away` -- The entity or resource is temporarily away.
+  #
+  # * `:chat` -- The entity or resource is actively interested in chatting.
+  #
+  # * `:dnd` -- The entity or resource is busy (dnd = "Do Not Disturb").
+  #
+  # * `:xa` -- The entity or resource is away for an extended period (xa =
+  #   "eXtended Away").
+  #
+  # Blather provides a helper for each possible state:
+  #
+  #     Status#available?
+  #     Status#away?
+  #     Status#chat?
+  #     Status#dnd?
+  #     Status#xa?
+  #
+  # Blather treats the `type` attribute like a normal ruby object attribute
+  # providing a getter and setter. The default `type` is `available`.
+  #
+  #     status = Status.new
+  #     status.state              # => :available
+  #     status.available?         # => true
+  #     status.state = :away
+  #     status.away?              # => true
+  #     status.available?         # => false
+  #     status
+  #     status.state = :invalid   # => RuntimeError
+  #
+  # ## "Type" Attribute
+  #
+  # The `type` attribute is inherited from Presence, but limits the value to
+  # either `nil` or `:unavailable` as these are the only types that relate to
+  # Status.
+  #
+  # ## "Priority" Attribute
+  #
+  # The `priority` attribute sets the priority of the status for the entity
+  # and must be an integer between -128 and 127.
+  #
+  # ## "Message" Attribute
+  #
+  # The optional `message` element contains XML character data specifying a
+  # natural-language description of availability status. It is normally used
+  # in conjunction with the show element to provide a detailed description of
+  # an availability state (e.g., "In a meeting").
+  #
+  # Blather treats the `message` attribute like a normal ruby object attribute
+  # providing a getter and setter. The default `message` is nil.
+  #
+  #     status = Status.new
+  #     status.message            # => nil
+  #     status.message = "gone!"
+  #     status.message            # => "gone!"
+  #
+  # @handler :status
+  class Status < Presence
+    # @private
+    VALID_STATES = [:away, :chat, :dnd, :xa].freeze
+    VALID_TYPES = [:unavailable].freeze
+
+    include Comparable
+
+    register :status, :status
+
+    # Create a new Status stanza
+    #
+    # @param [<:away, :chat, :dnd, :xa>] state the state of the status
+    # @param [#to_s] message a message to send with the status
+    def self.new(state = nil, message = nil)
+      node = super()
+      node.state = state
+      node.message = message
+      node
+    end
+
+    module InstanceMethods
+
+      # Check if the state is available
+      #
+      # @return [true, false]
+      def available?
+        self.state == :available
+      end
+
+      # Check if the state is away
+      #
+      # @return [true, false]
+      def away?
+        self.state == :away
+      end
+
+      # Check if the state is chat
+      #
+      # @return [true, false]
+      def chat?
+        self.state == :chat
+      end
+
+      # Check if the state is dnd
+      #
+      # @return [true, false]
+      def dnd?
+        self.state == :dnd
+      end
+
+      # Check if the state is xa
+      #
+      # @return [true, false]
+      def xa?
+        self.state == :xa
+      end
+
+      # Set the state
+      # Ensure state is one of :available, :away, :chat, :dnd, :xa or nil
+      #
+      # @param [<:available, :away, :chat, :dnd, :xa, nil>] state
+      def state=(state) # :nodoc:
+        state = state.to_sym if state
+        state = nil if state == :available
+        if state && !VALID_STATES.include?(state)
+          raise ArgumentError, "Invalid Status (#{state}), use: #{VALID_STATES*' '}"
+        end
+
+        set_content_for :show, state
+      end
+
+      # Get the state of the status
+      #
+      # @return [<:available, :away, :chat, :dnd, :xa>]
+      def state
+        state = type || content_from(:show)
+        state = :available if state.blank?
+        state.to_sym
+      end
+
+      # Set the priority of the status
+      # Ensures priority is between -128 and 127
+      #
+      # @param [Fixnum<-128...127>] new_priority
+      def priority=(new_priority) # :nodoc:
+        if new_priority && !(-128..127).include?(new_priority.to_i)
+          raise ArgumentError, 'Priority must be between -128 and +127'
+        end
+        set_content_for :priority, new_priority
+      end
+
+      # Get the priority of the status
+      #
+      # @return [Fixnum<-128...127>]
+      def priority
+        read_content(:priority).to_i
+      end
+
+      # Get the status message
+      #
+      # @return [String, nil]
+      def message
+        read_content :status
+      end
+
+      # Set the status message
+      #
+      # @param [String, nil] message
+      def message=(message)
+        set_content_for :status, message
+      end
+
+      # Compare status based on priority and state:
+      # unavailable status is always less valuable than others
+      # Raises an error if the JIDs aren't the same
+      #
+      # @param [Blather::Stanza::Presence::Status] o
+      # @return [true,false]
+      def <=>(o)
+        if self.from || o.from
+          unless self.from.stripped == o.from.stripped
+            raise ArgumentError, "Cannot compare status from different JIDs: #{[self.from, o.from].inspect}"
+          end
+        end
+
+        if (self.type.nil? && o.type.nil?) || (!self.type.nil? && !o.type.nil?)
+          self.priority <=> o.priority
+        elsif self.type.nil? && !o.type.nil?
+          1
+        elsif !self.type.nil? && o.type.nil?
+          -1
+        end
+      end
+    end
+
+    include InstanceMethods
+
+  end #Status
+
+end #Presence
+end #Stanza
+end #Blather

data/lib/blather/stanza/presence/subscription.rb

@@ -0,0 +1,100 @@
+module Blather
+class Stanza
+class Presence
+
+  # # Subscription Stanza
+  #
+  # [RFC 3921 Section 8 - Integration of Roster Items and Presence Subscriptions](http://xmpp.org/rfcs/rfc3921.html#rfc.section.8)
+  #
+  # Blather handles subscription request/response through this class. It
+  # provides a set of helper methods to quickly transform the stanza into a
+  # response.
+  #
+  # @handler :subscription
+  class Subscription < Presence
+    register :subscription, :subscription
+
+    # Create a new Subscription stanza
+    #
+    # @param [Blather::JID, #to_s] to the JID to subscribe to
+    # @param [Symbol, nil] type the subscription type
+    def self.new(to = nil, type = nil)
+      node = super()
+      node.to = to
+      node.type = type
+      node
+    end
+
+    module InstanceMethods
+
+      # Set the to value on the stanza
+      #
+      # @param [Blather::JID, #to_s] to a JID to subscribe to
+      def to=(to)
+        super JID.new(to).stripped
+      end
+
+      # Transform the stanza into an approve stanza
+      # makes approving requests simple
+      #
+      # @example approve an incoming request
+      #   subscription(:request?) { |s| write_to_stream s.approve! }
+      # @return [self]
+      def approve!
+        self.type = :subscribed
+        reply_if_needed!
+      end
+
+      # Transform the stanza into a refuse stanza
+      # makes refusing requests simple
+      #
+      # @example refuse an incoming request
+      #   subscription(:request?) { |s| write_to_stream s.refuse! }
+      # @return [self]
+      def refuse!
+        self.type = :unsubscribed
+        reply_if_needed!
+      end
+
+      # Transform the stanza into an unsubscribe stanza
+      # makes unsubscribing simple
+      #
+      # @return [self]
+      def unsubscribe!
+        self.type = :unsubscribe
+        reply_if_needed!
+      end
+
+      # Transform the stanza into a cancel stanza
+      # makes canceling simple
+      #
+      # @return [self]
+      def cancel!
+        self.type = :unsubscribed
+        reply_if_needed!
+      end
+
+      # Transform the stanza into a request stanza
+      # makes requests simple
+      #
+      # @return [self]
+      def request!
+        self.type = :subscribe
+        reply_if_needed!
+      end
+
+      # Check if the stanza is a request
+      #
+      # @return [true, false]
+      def request?
+        self.type == :subscribe
+      end
+    end
+
+    include InstanceMethods
+
+  end #Subscription
+
+end #Presence
+end #Stanza
+end

data/lib/blather/stanza/pubsub.rb

@@ -0,0 +1,119 @@
+module Blather
+class Stanza
+
+  # # Pubsub Stanza
+  #
+  # [XEP-0060 - Publish-Subscribe](http://xmpp.org/extensions/xep-0060.html)
+  #
+  # The base class for all PubSub nodes. This provides helper methods common to
+  # all PubSub nodes.
+  #
+  # @handler :pubsub_node
+  class PubSub < Iq
+    register :pubsub_node, :pubsub, 'http://jabber.org/protocol/pubsub'
+
+    # @private
+    def self.import(node)
+      klass = nil
+      if pubsub = node.document.find_first('//ns:pubsub', :ns => self.registered_ns)
+        pubsub.children.detect do |e|
+          ns = e.namespace ? e.namespace.href : nil
+          klass = class_from_registration(e.element_name, ns)
+        end
+      end
+      (klass || self).new(node[:type]).inherit(node)
+    end
+
+    # Overwrites the parent constructor to ensure a pubsub node is present.
+    # Also allows the addition of a host attribute
+    #
+    # @param [<Blather::Stanza::Iq::VALID_TYPES>] type the IQ type
+    # @param [String, nil] host the host the node should be sent to
+    def self.new(type = nil, host = nil)
+      new_node = super type
+      new_node.to = host
+      new_node.pubsub
+      new_node
+    end
+
+    # Overrides the parent to ensure the current pubsub node is destroyed before
+    # inheritting the new content
+    #
+    # @private
+    def inherit(node)
+      remove_children :pubsub
+      super
+    end
+
+    # Get or create the pubsub node on the stanza
+    #
+    # @return [Blather::XMPPNode]
+    def pubsub
+      p = find_first('ns:pubsub', :ns => self.class.registered_ns) ||
+          find_first('pubsub', :ns => self.class.registered_ns)
+
+      unless p
+        self << (p = XMPPNode.new('pubsub', self.document))
+        p.namespace = self.class.registered_ns
+      end
+      p
+    end
+  end  # PubSub
+
+  # # PubSubItem Fragment
+  #
+  # This fragment is found in many places throughout the pubsub spec
+  # This is a convenience class to attach methods to the node
+  class PubSubItem < XMPPNode
+    # Create a new PubSubItem
+    #
+    # @param [String, nil] id the id of the stanza
+    # @param [#to_s, nil] payload the payload to attach to this item.
+    # @param [XML::Document, nil] document the document the node should be
+    # attached to. This should be the document of the parent PubSub node.
+    def self.new(id = nil, payload = nil, document = nil)
+      new_node = super 'item', document
+      new_node.id = id
+      new_node.payload = payload if payload
+      new_node
+    end
+
+    # Get the item's ID
+    #
+    # @return [String, nil]
+    def id
+      read_attr :id
+    end
+
+    # Set the item's ID
+    #
+    # @param [#to_s] id the new ID
+    def id=(id)
+      write_attr :id, id
+    end
+
+    alias_method :payload_node, :child
+
+    # Get the item's payload
+    #
+    # @return [String, nil]
+    def payload
+      children.empty? ? nil : children.to_s
+    end
+
+    # Set the item's payload
+    #
+    # @param [String, XMPPNode, nil] payload the payload
+    def payload=(payload)
+      children.map &:remove
+      return unless payload
+      if payload.is_a?(String)
+        self.content = payload
+      else
+        self << payload
+      end
+    end
+  end  # PubSubItem
+
+end  # Stanza
+end  # Blather

data/lib/blather/stanza/pubsub/affiliations.rb

@@ -0,0 +1,79 @@
+module Blather
+class Stanza
+class PubSub
+
+  # # PubSub Affiliations Stanza
+  #
+  # [XEP-0060 Section 8.9 - Manage Affiliations](http://xmpp.org/extensions/xep-0060.html#owner-affiliations)
+  #
+  # @handler :pubsub_affiliations
+  class Affiliations < PubSub
+    register :pubsub_affiliations, :affiliations, self.registered_ns
+
+    include Enumerable
+    alias_method :find, :xpath
+
+    # Overrides the parent to ensure an affiliation node is created
+    # @private
+    def self.new(type = nil, host = nil)
+      new_node = super
+      new_node.affiliations
+      new_node
+    end
+
+    # Kill the affiliations node before running inherit
+    # @private
+    def inherit(node)
+      affiliations.remove
+      super
+    end
+
+    # Get or create the affiliations node
+    #
+    # @return [Blather::XMPPNode]
+    def affiliations
+      aff = pubsub.find_first('ns:affiliations', :ns => self.class.registered_ns)
+      unless aff
+        self.pubsub << (aff = XMPPNode.new('affiliations', self.document))
+      end
+      aff
+    end
+
+    # Convenience method for iterating over the list
+    #
+    # @see #list for the format of the yielded input
+    def each(&block)
+      list.each &block
+    end
+
+    # Get the number of affiliations
+    #
+    # @return [Fixnum]
+    def size
+      list.size
+    end
+
+    # Get the hash of affilations as affiliation-type => [nodes]
+    #
+    # @example
+    #
+    #     { :owner => ['node1', 'node2'],
+    #       :publisher => ['node3'],
+    #       :outcast => ['node4'],
+    #       :member => ['node5'],
+    #       :none => ['node6'] }
+    #
+    # @return [Hash<String => Array<String>>]
+    def list
+      items = affiliations.find('//ns:affiliation', :ns => self.class.registered_ns)
+      items.inject({}) do |hash, item|
+        hash[item[:affiliation].to_sym] ||= []
+        hash[item[:affiliation].to_sym] << item[:node]
+        hash
+      end
+    end
+  end  # Affiliations
+
+end  # PubSub
+end  # Stanza
+end  # Blather