blather 0.4.7 → 0.4.8

data/lib/blather/stanza/presence.rb

@@ -1,58 +1,85 @@
 module Blather
 class Stanza
 
-  # = Presence Stanza
+  # # Presence Stanza
   #
-  # Within Blather most of the interaction with Presence stanzas will be through one of its child classes: Status or Subscription.
+  # [RFC 3921 Section 2.2 - Presence Syntax](http://xmpp.org/rfcs/rfc3921.html#stanzas-presence)
   #
-  # 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.
+  # Within Blather most of the interaction with Presence stanzas will be
+  # through one of its child classes: Status or Subscription.
   #
-  # == Type Attribute
+  # 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.
   #
-  # 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:
+  # ## "Type" Attribute
   #
-  # * +: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.
+  # 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?
+  #     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.
+  # 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 = Presence.new
+  #     presence.type                # => nil
+  #     presence.type = :unavailable
+  #     presence.unavailable?        # => true
+  #     presence.error?              # => false
   #
-  #   presence.type = :invalid   # => RuntimeError
+  #     presence.type = :invalid   # => RuntimeError
   #
+  # @handler :presence
   class Presence < Stanza
-    VALID_TYPES = [:unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe, :error] # :nodoc:
+    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.
@@ -66,18 +93,67 @@ class Stanza
       klass.new.inherit(node)
     end
 
-    ##
     # Ensure element_name is "presence" for all subclasses
     def self.new
       super :presence
     end
 
-    attribute_helpers_for(:type, VALID_TYPES)
+    # Check if the IQ is of type :unavailable
+    #
+    # @return [true, false]
+    def unavailable?
+      self.type == :unavailable
+    end
 
-    ##
-    # Ensures type is one of :unavailable, :subscribe, :subscribed, :unsubscribe, :unsubscribed, :probe or :error
-    def type=(type) # :nodoc:
-      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
+    # 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
 

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

@@ -2,73 +2,89 @@ module Blather
 class Stanza
 class Presence
 
-  # = Status Stanza
+  # # Status Stanza
   #
-  # 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.
+  # [RFC 3921 Section 2.2.2 - Presence Child Elements](http://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2)
   #
-  # == State Attribute
+  # 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.
   #
-  # The +state+ attribute determains the availability of the entity and can be one of the following:
+  # ## "State" Attribute
   #
-  # * +: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").
+  # 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?
+  #     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`.
   #
-  # 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
   #
-  #   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
   #
-  # == 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.
   #
-  # 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
   #
-  # == Priority Attribute
+  # The `priority` attribute sets the priority of the status for the entity
+  # and must be an integer between -128 and 127.
   #
-  # The +priority+ attribute sets the priority of the status for the entity and must be an integer between
-  # -128 and 127. 
+  # ## "Message" Attribute
   #
-  # == 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").
   #
-  # 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.
+  # 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!"
+  #     status = Status.new
+  #     status.message            # => nil
+  #     status.message = "gone!"
+  #     status.message            # => "gone!"
   #
+  # @handler :status
   class Status < Presence
-    VALID_STATES = [:away, :chat, :dnd, :xa] # :nodoc:
+    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
@@ -76,48 +92,112 @@ class Presence
       node
     end
 
-    attribute_helpers_for(:state, [:available] + VALID_STATES)
+    # 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
-    def type=(type) # :nodoc:
-      raise ArgumentError, "Invalid type (#{type}). Must be nil or unavailable" if type && type.to_sym != :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
-      raise ArgumentError, "Invalid Status (#{state}), use: #{VALID_STATES*' '}" if state && !VALID_STATES.include?(state)
+      if state && !VALID_STATES.include?(state)
+        raise ArgumentError, "Invalid Status (#{state}), use: #{VALID_STATES*' '}"
+      end
 
       set_content_for :show, state
     end
 
-    ##
-    # :available if state is nil
-    def state # :nodoc:
+    # 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
 
-    ##
-    # Ensure priority is between -128 and 127
+    # Set the priority of the status
+    # Ensures priority is between -128 and 127
+    #
+    # @param [Fixnum<-128...127>] new_priority
     def priority=(new_priority) # :nodoc:
-      raise ArgumentError, 'Priority must be between -128 and +127' if new_priority && !(-128..127).include?(new_priority.to_i)
+      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
 
-    content_attr_reader :priority, :to_i
+    # Get the priority of the status
+    #
+    # @return [Fixnum<-128...127>]
+    def priority
+      read_content(:priority).to_i
+    end
 
-    content_attr_accessor :message, nil, :status
+    # 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}"