sprsquish-blather 0.1 → 0.2.3

data/lib/blather/{core/roster.rb → roster.rb}

@@ -1,5 +1,8 @@
 module Blather
 
+  ##
+  # Local Roster 
+  # Takes care of adding/removing JIDs through the stream
   class Roster
     include Enumerable
 
@@ -9,6 +12,9 @@ module Blather
       stanza.items.each { |i| push i, false } if stanza
     end
 
+    ##
+    # Process any incoming stanzas adn either add or remove the
+    # corresponding RosterItem
     def process(stanza)
       stanza.items.each do |i|
         case i.subscription
@@ -18,11 +24,18 @@ module Blather
       end
     end
 
+    ##
+    # Pushes a JID into the roster
+    # then returns self to allow for chaining
     def <<(elem)
       push elem
       self
     end
 
+    ##
+    # Push a JID into the roster
+    # Will send the new item to the server
+    # unless overridden by calling #push(elem, false)
     def push(elem, send = true)
       jid = elem.respond_to?(:jid) ? elem.jid : JID.new(elem)
       @items[key(jid)] = node = RosterItem.new(elem)
@@ -31,20 +44,29 @@ module Blather
     end
     alias_method :add, :push
 
+    ##
+    # Remove a JID from the roster
+    # Sends a remove query stanza to the server
     def delete(jid)
       @items.delete key(jid)
       @stream.send_data Stanza::Iq::Roster.new(:set, Stanza::Iq::Roster::RosterItem.new(jid, nil, :remove))
     end
     alias_method :remove, :delete
 
+    ##
+    # Get a RosterItem by JID
     def [](jid)
       items[key(jid)]
     end
 
+    ##
+    # Iterate over all RosterItems
     def each(&block)
       items.each &block
     end
 
+    ##
+    # Returns a duplicate of all RosterItems
     def items
       @items.dup
     end

data/lib/blather/{core/roster_item.rb → roster_item.rb}

@@ -1,6 +1,11 @@
 module Blather
 
+  ##
+  # RosterItems hold internal representations of the user's roster
+  # including each JID's status.
   class RosterItem
+    VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to]
+
     attr_reader :jid,
                 :ask,
                 :statuses
@@ -8,50 +13,76 @@ module Blather
     attr_accessor :name,
                   :groups
 
+    ##
+    # item:: can be a JID, String (a@b) or a Stanza
     def initialize(item)
       @statuses = []
+      @groups = []
 
-      if item.is_a?(JID)
+      case item
+      when JID
         self.jid = item.stripped
-      elsif item.is_a?(XMPPNode)
-        self.jid          = JID.new(item['jid']).stripped
-        self.name         = item['name']
-        self.subscription = item['subscription']
-        self.ask          = item['ask']
+      when String
+        self.jid = JID.new(item).stripped
+      when XMPPNode
+        self.jid          = JID.new(item[:jid]).stripped
+        self.name         = item[:name]
+        self.subscription = item[:subscription]
+        self.ask          = item[:ask]
         item.groups.each { |g| self.groups << g }
       end
+
+      @groups = [nil] if @groups.empty?
     end
 
+    ##
+    # Set the jid
     def jid=(jid)
       @jid = JID.new(jid).stripped
     end
 
-    VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to].freeze
+    ##
+    # Set the subscription
+    # Ensures it is one of VALID_SUBSCRIPTION_TYPES
     def subscription=(sub)
       raise ArgumentError, "Invalid Type (#{sub}), use: #{VALID_SUBSCRIPTION_TYPES*' '}" if
         sub && !VALID_SUBSCRIPTION_TYPES.include?(sub = sub.to_sym)
       @subscription = sub ? sub : :none
     end
 
+    ##
+    # Get the current subscription
+    # returns:: :both, :from, :none, :remove, :to or :none
     def subscription
       @subscription || :none
     end
 
+    ##
+    # Set the ask value
+    # ask:: must only be nil or :subscribe
     def ask=(ask)
-      raise ArgumentError, "Invalid Type (#{ask}), use: #{VALID_SUBSCRIPTION_TYPES*' '}" if ask && (ask = ask.to_sym) != :subscribe
+      raise ArgumentError, "Invalid Type (#{ask}), can only be :subscribe" if ask && (ask = ask.to_sym) != :subscribe
       @ask = ask ? ask : nil
     end
 
+    ##
+    # Set the status then sorts them according to priority
+    # presence:: Status
     def status=(presence)
       @statuses.delete_if { |s| s.from == presence.from }
       @statuses << presence
       @statuses.sort!
     end
 
+    ##
+    # Return the status with the highest priority
+    # if resource is set find the status of that specific resource 
     def status(resource = nil)
       top = resource ? @statuses.detect { |s| s.from.resource == resource } : @statuses.first
     end
 
+    ##
+    # Translate the RosterItem into a proper stanza that can be sent over the stream
     def to_stanza(type = nil)
       r = Stanza::Iq::Roster.new type
       n = Stanza::Iq::Roster::RosterItem.new jid, name, subscription, ask

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

@@ -0,0 +1,11 @@
+module Blather
+class Stanza
+class Iq
+
+  class Disco < Query
+    attribute_accessor :node, :to_sym => false
+  end
+
+end #Iq
+end #Stanza
+end #Blather

data/lib/blather/stanza/iq/discos/disco_info.rb

@@ -0,0 +1,86 @@
+module Blather
+class Stanza
+class Iq
+
+  ##
+  # DiscoInfo object ()
+  # 
+  class DiscoInfo < Disco
+    register :disco_info, nil, 'http://jabber.org/protocol/disco#info'
+
+    def initialize(type = nil, identities = [], features = [], node = nil)
+      super type
+
+      [identities].flatten.each do |id|
+        query << (id.is_a?(Identity) ? id : Identity.new(id[:name], id[:type], id[:category]))
+      end
+
+      [features].flatten.each do |feature|
+        query << (feature.is_a?(Feature) ? feature : Feature.new(feature))
+      end
+
+      self.node = node
+    end
+
+    ##
+    # List of identity objects
+    def identities
+      identities = query.find('identity')
+      identities = query.find('query_ns:identity', :query_ns => self.class.ns) if identities.empty?
+      identities.map { |i| Identity.new i }
+    end
+
+    ##
+    # List of feature objects
+    def features
+     features = query.find('feature')
+     features = query.find('query_ns:feature', :query_ns => self.class.ns) if features.empty?
+     features.map { |i| Feature.new i }
+    end
+
+    class Identity < XMPPNode
+      attribute_accessor :category, :type
+      attribute_accessor :name, :to_sym => false
+
+      def initialize(name, type = nil, category = nil)
+        super :identity
+
+        if name.is_a?(XML::Node)
+          self.inherit name
+        else
+          self.name = name
+          self.type = type
+          self.category = category
+        end
+      end
+
+      def eql?(other)
+        other.kind_of?(self.class) &&
+        other.name == self.name &&
+        other.type == self.type &&
+        other.category == self.category
+      end
+    end
+
+    class Feature < XMPPNode
+      attribute_accessor :var, :to_sym => false
+
+      def initialize(var)
+        super :feature
+        if var.is_a?(XML::Node)
+          self.inherit var
+        else
+          self.var = var
+        end
+      end
+
+      def eql?(other)
+        other.kind_of?(self.class) &&
+        other.var == self.var
+      end
+    end
+  end
+
+end #Iq
+end #Stanza
+end #Blather

data/lib/blather/stanza/iq/discos/disco_items.rb

@@ -0,0 +1,61 @@
+module Blather
+class Stanza
+class Iq
+
+  class DiscoItems < Disco
+    register :disco_items, nil, 'http://jabber.org/protocol/disco#items'
+
+    def initialize(type = nil, node = nil, items = [])
+      super type
+      self.node = node
+      [items].flatten.each do |item|
+        query << (item.is_a?(Item) ? item : Item.new(item[:jid], item[:node], item[:name]))
+      end
+    end
+
+    def items
+      items = query.find('item')
+      items = query.find('query_ns:item', :query_ns => self.class.ns) if items.empty?
+      items.map { |i| Item.new i }
+    end
+
+    def node=(node)
+      query.attributes[:node] = node
+    end
+
+    def node
+      query.attributes[:node]
+    end
+
+    class Item < XMPPNode
+      def initialize(jid, node = nil, name = nil)
+        super :item
+
+        if jid.is_a?(XML::Node)
+          self.inherit jid
+        else
+          self.jid = jid
+          self.node = node
+          self.name = name
+        end
+      end
+
+      def jid
+        (j = attributes[:jid]) ? JID.new(j) : nil
+      end
+      attribute_writer :jid
+
+      attribute_accessor :node, :name, :to_sym => false      
+    end
+
+    def eql?(other)
+      other.kind_of?(self.class) &&
+      other.jid == self.jid &&
+      other.node == self.node &&
+      other.name == self.name
+    end
+  end
+
+end #Iq
+end #Stanza
+end #Blather

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

@@ -0,0 +1,51 @@
+module Blather
+class Stanza
+class Iq
+
+  class Query < Iq
+    register :query, :query
+
+    ##
+    # Ensure the namespace is set to the query node
+    def initialize(type = nil)
+      super()
+      query.namespace = self.class.ns
+    end
+
+    ##
+    # Kill the query node before running inherit
+    def inherit(node)
+      query.remove!
+      super
+    end
+
+    ##
+    # Query node accessor
+    # This will ensure there actually is a query node
+    def query
+      q = find_first('query')
+      q = find_first('//query_ns:query', :query_ns => self.class.ns) if !q && self.class.ns
+      (self << (q = XMPPNode.new('query'))) unless q
+      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
+end #Stanza
+end

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

@@ -0,0 +1,90 @@
+module Blather
+class Stanza
+class Iq
+
+  class Roster < Query
+    register :roster, nil, 'jabber:iq:roster'
+
+    ##
+    # Any new items are added to the query
+    def initialize(type = nil, item = nil)
+      super type
+      query << item if item
+    end
+
+    ##
+    # Inherit the XMPPNode to create a proper Roster object.
+    # Creates RosterItem objects out of each roster item as well.
+    def inherit(node)
+      # remove the current set of nodes
+      items.each { |i| i.remove! }
+      super
+      # transmogrify nodes into RosterItems
+      items.each { |i| query << RosterItem.new(i); i.remove! }
+      self
+    end
+
+    ##
+    # Roster items
+    def items
+      items = query.find('item')
+      items = query.find('query_ns:item', :query_ns => self.class.ns) if items.empty?
+      items.map { |i| RosterItem.new(i) }
+    end
+
+    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
+      def initialize(jid = nil, name = nil, subscription = nil, ask = nil)
+        super :item
+
+        if jid.is_a?(XML::Node)
+          self.inherit jid
+        else
+          self.jid = jid
+          self.name = name
+          self.subscription = subscription
+          self.ask = ask
+        end
+      end
+
+      ##
+      # Roster item's JID
+      def jid
+        (j = attributes[:jid]) ? JID.new(j) : nil
+      end
+      attribute_writer :jid
+
+      attribute_accessor :name, :to_sym => false
+
+      attribute_accessor :subscription, :ask
+
+      ##
+      # The groups roster item belongs to
+      def groups
+        find(:group).map { |g| g.content }
+      end
+
+      ##
+      # Set the roster item's groups
+      # must be an array
+      def groups=(new_groups)
+        find(:group).each { |g| g.remove! }
+        new_groups.uniq.each { |g| self << XMPPNode.new(:group, g) } if new_groups
+      end
+
+      ##
+      # Convert the roster item to a proper stanza all wrapped up
+      # This facilitates new subscriptions
+      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,38 @@
+module Blather
+class Stanza
+
+  ##
+  # Base Iq stanza
+  class Iq < Stanza
+    VALID_TYPES = [:get, :set, :result, :error]
+
+    register :iq
+
+    def self.import(node)
+      raise(ArgumentError, "Import missmatch #{[node.element_name, self.name].inspect}") if node.element_name != self.name.to_s
+      klass = nil
+      node.children.each { |e| break if klass = class_from_registration(e.element_name, e.namespace) }
+      (klass || self).new(node.attributes[:type]).inherit(node)
+    end
+
+    def initialize(type = nil, to = nil, id = nil)
+      super :iq
+      self.type = type || :get
+      self.to = to
+      self.id = id if id
+    end
+
+    VALID_TYPES.each do |valid_type|
+      define_method("#{valid_type}?") { self.type == valid_type }
+    end
+
+    ##
+    # Ensures type is :get, :set, :result or :error
+    def type=(type)
+      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
+      super
+    end
+  end
+
+end #Stanza
+end

data/lib/blather/stanza/message.rb

@@ -0,0 +1,58 @@
+module Blather
+class Stanza
+
+  ##
+  # Base Message stanza
+  class Message < Stanza
+    VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal]
+
+    register :message
+
+    def initialize(to = nil, body = nil, type = :chat)
+      super()
+      self.to = to
+      self.type = type
+      self.body = body
+    end
+
+    VALID_TYPES.each do |valid_type|
+      define_method("#{valid_type}?") { self.type == valid_type }
+    end
+
+    ##
+    # Ensures type is :chat, :error, :groupchat, :headline or :normal
+    def type=(type)
+      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if type && !VALID_TYPES.include?(type.to_sym)
+      super
+    end
+
+    def body=(body)
+      remove_child :body
+      self << XMPPNode.new('body', body) if body
+    end
+
+    def body
+      content_from :body
+    end
+
+    def subject=(subject)
+      remove_child :subject
+      self << XMPPNode.new('subject', subject) if subject
+    end
+
+    def subject
+      content_from :subject
+    end
+
+    def thread=(thread)
+      remove_child :thread
+      self << XMPPNode.new('thread', thread) if thread
+    end
+
+    def thread
+      content_from :thread
+    end
+  end
+
+end #Stanza
+end

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

@@ -0,0 +1,78 @@
+module Blather
+class Stanza
+class Presence
+
+  class Status < Presence
+    VALID_STATES = [:away, :chat, :dnd, :xa]
+
+    include Comparable
+
+    register :status, :status
+
+    def initialize(state = nil, message = nil)
+      super()
+      self.state = state
+      self.message = message
+    end
+
+    ##
+    # Ensures type is nil or :unavailable
+    def type=(type)
+      raise ArgumentError, "Invalid type (#{type}). Must be nil or unavailable" if type && type.to_sym != :unavailable
+      super
+    end
+
+    ##
+    # Ensure state is one of :away, :chat, :dnd, :xa or nil
+    def state=(state)
+      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)
+
+      remove_child :show
+      self << XMPPNode.new('show', state) if state
+    end
+
+    ##
+    # return:: :available if state is nil
+    def state
+      (type || content_from(:show) || :available).to_sym
+    end
+
+    ##
+    # Ensure priority is between -128 and 127
+    def priority=(new_priority)
+      raise ArgumentError, 'Priority must be between -128 and +127' if new_priority && !(-128..127).include?(new_priority.to_i)
+
+      remove_child :priority
+      self << XMPPNode.new('priority', new_priority) if new_priority
+    end
+
+    def priority
+      content_from(:priority).to_i
+    end
+
+    def message=(msg)
+      remove_child :status
+      self << XMPPNode.new('status', msg) if msg
+    end
+
+    def message
+      content_from :status
+    end
+
+    ##
+    # Compare status based on priority
+    # raises an error if the JIDs aren't the same
+    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,72 @@
+module Blather
+class Stanza
+class Presence
+
+  class Subscription < Presence
+    register :subscription, :subscription
+
+    def initialize(to = nil, type = nil)
+      super()
+      self.to = to
+      self.type = type
+    end
+
+    def inherit(node)
+      inherit_attrs node.attributes
+      self
+    end
+
+    def to=(to)
+      super JID.new(to).stripped
+    end
+
+    ##
+    # Create an approve stanza
+    def approve!
+      self.type = :subscribed
+      morph_to_reply
+    end
+
+    ##
+    # Create a refuse stanza
+    def refuse!
+      self.type = :unsubscribed
+      morph_to_reply
+    end
+
+    ##
+    # Create an unsubscribe stanza
+    def unsubscribe!
+      self.type = :unsubscribe
+      morph_to_reply
+    end
+
+    ##
+    # Create a cancel stanza
+    def cancel!
+      self.type = :unsubscribed
+      morph_to_reply
+    end
+
+    ##
+    # Create a request stanza
+    def request!
+      self.type = :subscribe
+      morph_to_reply
+    end
+
+    def request?
+      self.type == :subscribe
+    end
+
+  private
+    def morph_to_reply
+      self.to = self.from if self.from
+      self.from = nil
+      self
+    end
+  end #Subscription
+
+end #Presence
+end #Stanza
+end