shingara-blather 0.4.8

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

@@ -0,0 +1,212 @@
+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
+    VALID_STATES = [:away, :chat, :dnd, :xa].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
+
+    # 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 type attribute
+    # Ensures type is nil or :unavailable
+    #
+    # @param [<:unavailable, nil>] type the type
+    def type=(type)
+      if type && type.to_sym != :unavailable
+        raise ArgumentError, "Invalid type (#{type}). Must be nil or unavailable"
+      end
+      super
+    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
+    # raises an error if the JIDs aren't the same
+    #
+    # @param [Blather::Stanza::Presence::Status] o
+    # @return [true,false]
+    def <=>(o)
+      unless self.from && o.from && self.from.stripped == o.from.stripped
+        raise ArgumentError, "Cannot compare status from different JIDs: #{[self.from, o.from].inspect}"
+      end
+      self.priority <=> o.priority
+    end
+
+  end #Status
+
+end #Presence
+end #Stanza
+end #Blather

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

@@ -0,0 +1,101 @@
+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
+
+    # @private
+    def inherit(node)
+      inherit_attrs node.attributes
+      self
+    end
+
+    # 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 #Subscription
+
+end #Presence
+end #Stanza
+end

data/lib/blather/stanza/presence.rb

@@ -0,0 +1,163 @@
+module Blather
+class Stanza
+
+  # # Presence Stanza
+  #
+  # [RFC 3921 Section 2.2 - Presence Syntax](http://xmpp.org/rfcs/rfc3921.html#stanzas-presence)
+  #
+  # 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
+  #
+  # @handler :presence
+  class Presence < Stanza
+    VALID_TYPES = [ :unavailable,
+                    :subscribe,
+                    :subscribed,
+                    :unsubscribe,
+                    :unsubscribed,
+                    :probe,
+                    :error].freeze
+
+    register :presence
+
+    # Creates a class based on the presence type
+    # 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) # :nodoc:
+      klass = case node['type']
+      when nil, 'unavailable' then Status
+      when /subscribe/        then Subscription
+      else self
+      end
+      klass.new.inherit(node)
+    end
+
+    # Ensure element_name is "presence" for all subclasses
+    def self.new
+      super :presence
+    end
+
+    # Check if the IQ is of type :unavailable
+    #
+    # @return [true, false]
+    def unavailable?
+      self.type == :unavailable
+    end
+
+    # Check if the IQ is of type :subscribe
+    #
+    # @return [true, false]
+    def subscribe?
+      self.type == :subscribe
+    end
+
+    # Check if the IQ is of type :subscribed
+    #
+    # @return [true, false]
+    def subscribed?
+      self.type == :subscribed
+    end
+
+    # Check if the IQ is of type :unsubscribe
+    #
+    # @return [true, false]
+    def unsubscribe?
+      self.type == :unsubscribe
+    end
+
+    # Check if the IQ is of type :unsubscribed
+    #
+    # @return [true, false]
+    def unsubscribed?
+      self.type == :unsubscribed
+    end
+
+    # Check if the IQ is of type :probe
+    #
+    # @return [true, false]
+    def probe?
+      self.type == :probe
+    end
+
+    # Check if the IQ is of type :error
+    #
+    # @return [true, false]
+    def error?
+      self.type == :error
+    end
+
+    # Ensures type is one of Blather::Stanza::Presence::VALID_TYPES
+    #
+    # @param [#to_sym] type the Presence 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
+
+  end
+
+end #Stanza
+end

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

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

@@ -0,0 +1,65 @@
+module Blather
+class Stanza
+class PubSub
+
+  # # PubSub Create Stanza
+  #
+  # [XEP-0060 Section 8.1 - Create a Node](http://xmpp.org/extensions/xep-0060.html#owner-create)
+  #
+  # @handler :pubsub_create
+  class Create < PubSub
+    register :pubsub_create, :create, self.registered_ns
+
+    # Create a new Create Stanza
+    #
+    # @param [<Blather::Stanza::Iq::VALID_TYPES>] type the node type
+    # @param [String, nil] host the host to send the request to
+    # @param [String, nil] node the name of the node to create
+    def self.new(type = :set, host = nil, node = nil)
+      new_node = super(type, host)
+      new_node.create_node
+      new_node.configure_node
+      new_node.node = node
+      new_node
+    end
+
+    # Get the name of the node to create
+    #
+    # @return [String, nil]
+    def node
+      create_node[:node]
+    end
+
+    # Set the name of the node to create
+    #
+    # @param [String, nil] node
+    def node=(node)
+      create_node[:node] = node
+    end
+
+    # Get or create the actual create node on the stanza
+    #
+    # @return [Balther::XMPPNode]
+    def create_node
+      unless create_node = pubsub.find_first('ns:create', :ns => self.class.registered_ns)
+        self.pubsub << (create_node = XMPPNode.new('create', self.document))
+        create_node.namespace = self.pubsub.namespace
+      end
+      create_node
+    end
+
+    # Get or create the actual configure node on the stanza
+    #
+    # @return [Blather::XMPPNode]
+    def configure_node
+      unless configure_node = pubsub.find_first('ns:configure', :ns => self.class.registered_ns)
+        self.pubsub << (configure_node = XMPPNode.new('configure', self.document))
+        configure_node.namespace = self.pubsub.namespace
+      end
+      configure_node
+    end
+  end  # Create
+
+end  # PubSub
+end  # Stanza
+end  # Blather

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

@@ -0,0 +1,18 @@
+module Blather
+class Stanza
+
+  # # PusSub Error Stanza
+  #
+  # @private
+  class PubSubErrors < PubSub
+    def node
+      read_attr :node
+    end
+
+    def node=(node)
+      write_attr :node, node
+    end
+  end  # PubSubErrors
+
+end  # Stanza
+end  # Blather