mojodna-xmpp4r 0.4.0.2

data/lib/xmpp4r/xmpp4r.rb

@@ -0,0 +1,18 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+##
+# The Jabber module is the root namespace of the library.
+module Jabber
+  # XMPP4R Version number.  This is the ONLY place where the version number
+  # should be specified.  This constant is used to determine the version of
+  # package tarballs and generated gems.
+  XMPP4R_VERSION = '0.4.0.2'
+end
+
+require 'xmpp4r/client'
+require 'xmpp4r/component'
+require 'xmpp4r/debuglog'
+require 'xmpp4r/errors'
+

data/lib/xmpp4r/xmppelement.rb

@@ -0,0 +1,168 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/rexmladdons'
+
+module Jabber
+
+  ##
+  # This class represents an XML element and provides functionality
+  # for automatic casting of XML element classes according to their
+  # element name and namespace.
+  #
+  # Deriving classes must met these criteria:
+  # * The element name and namespace must be specified by calling
+  #   the name_xmlns class method
+  # * The class constructor must be callable with no mandatory parameter
+  class XMPPElement < REXML::Element
+    @@name_xmlns_classes = {}
+    @@force_xmlns = false
+
+    ##
+    # Specify XML element name and xmlns for a deriving class,
+    # this pair and the class will be added to a global pool
+    #
+    # If the namespace is nil the class is a "wildcard class"
+    # matching elements with any xmlns if no other class with
+    # that namespace was defined
+    def self.name_xmlns(name, xmlns=nil)
+      @@name_xmlns_classes[[name, xmlns]] = self
+    end
+
+    ##
+    # Set whether this element is always built with an xmlns attribute
+    def self.force_xmlns(force)
+      @@force_xmlns = force
+    end
+
+    ##
+    # Whether this element is always built with an xmlns attribute
+    def self.force_xmlns?
+      @@force_xmlns
+    end
+
+    ##
+    # Find the name and namespace for a given class.
+    # This class must have registered these two values
+    # by calling name_xmlns at definition time.
+    #
+    # Raises an exception if none was found
+    # klass:: [Class]
+    # result:: [String, String] name and namespace
+    def self.name_xmlns_for_class(klass)
+      klass.ancestors.each do |klass1|
+        @@name_xmlns_classes.each do |name_xmlns,k|
+          if klass1 == k
+            return name_xmlns
+          end
+        end
+      end
+
+      raise NoNameXmlnsRegistered.new(klass)
+    end
+
+    ##
+    # Find a class for given name and namespace
+    # name:: [String]
+    # xmlns:: [String]
+    # result:: A descendant of XMPPElement or REXML::Element
+    def self.class_for_name_xmlns(name, xmlns)
+      if @@name_xmlns_classes.has_key? [name, xmlns]
+        @@name_xmlns_classes[[name, xmlns]]
+      elsif @@name_xmlns_classes.has_key? [name, nil]
+        @@name_xmlns_classes[[name, nil]]
+      else
+        REXML::Element
+      end
+    end
+
+    ##
+    # Import another REXML::Element descendant to:
+    # * Either an element class that registered with
+    #   name and xmlns before
+    # * Or if none was found to the class itself
+    #   (you may call this class method on a deriving class)
+    def self.import(element)
+      klass = class_for_name_xmlns(element.name, element.namespace)
+      if klass != self and klass.ancestors.include?(self)
+        klass.new.import(element)
+      else
+        self.new.import(element)
+      end
+    end
+
+    ##
+    # Initialize this element, which will then be initialized
+    # with the name registered with name_xmlns.
+    def initialize(*arg)
+      if arg.empty?
+        name, xmlns = self.class::name_xmlns_for_class(self.class)
+        super(name)
+        if self.class::force_xmlns?
+          add_namespace(xmlns)
+        end
+      else
+        super
+      end
+    end
+
+    ##
+    # Add a child element which will be imported according to the
+    # child's name and xmlns
+    # element:: [REXML::Element] Child
+    # result:: [REXML::Element or descendant of XMPPElement] New child
+    def typed_add(element)
+      if element.kind_of? REXML::Element
+        element_ns = (element.namespace.to_s == '') ? namespace : element.namespace
+
+        klass = XMPPElement::class_for_name_xmlns(element.name, element_ns)
+        if klass != element.class
+          element = klass.import(element)
+        end
+      end
+
+      super(element)
+    end
+
+    def parent=(new_parent)
+      if parent and parent.namespace('') == namespace('') and attributes['xmlns'].nil?
+        add_namespace parent.namespace('')
+      end
+
+      super
+
+      if new_parent and new_parent.namespace('') == namespace('')
+        delete_namespace
+      end
+    end
+
+    def clone
+      cloned = self.class.new
+      cloned.add_attributes self.attributes.clone
+      cloned.context = @context
+      cloned
+    end
+
+    ##
+    # Generic XML attribute 'xml:lang'
+    # (REXML provides no shortcut)
+    def xml_lang
+      attributes['xml:lang']
+    end
+
+    ##
+    # Set XML language attribute
+    def xml_lang=(l)
+      attributes['xml:lang'] = l
+    end
+
+    ##
+    # Set XML language attribute (chainable)
+    def set_xml_lang(l)
+      self.xml_lang = l
+      self
+    end
+
+  end
+end

data/lib/xmpp4r/xmppstanza.rb

@@ -0,0 +1,162 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/xmppelement'
+require 'xmpp4r/errors'
+require 'xmpp4r/jid'
+
+module Jabber
+  ##
+  # root class of all Jabber XML elements
+  class XMPPStanza < XMPPElement
+    ##
+    # Compose a response by doing the following:
+    # * Create a new XMPPStanza of the same subclass
+    #   with the same element-name
+    # * Import xmppstanza if import is true
+    # * Swap 'to' and 'from'
+    # * Copy 'id'
+    # * Does not take care about the type
+    #
+    # *Attention*: Be careful when answering to stanzas with
+    # <tt>type == :error</tt> - answering to an error may generate
+    # another error on the other side, which could be leading to a
+    # ping-pong effect quickly!
+    #
+    # xmppstanza:: [XMPPStanza] source
+    # import:: [true or false] Copy attributes and children of source
+    # result:: [XMPPStanza] answer stanza
+    def XMPPStanza.answer(xmppstanza, import=true)
+      x = xmppstanza.class.new
+      if import
+        x.import(xmppstanza)
+      end
+      x.from = xmppstanza.to
+      x.to = xmppstanza.from
+      x.id = xmppstanza.id
+      x
+    end
+
+    ##
+    # Return the first <tt><error/></tt> child
+    def error
+      first_element('error')
+    end
+
+    ##
+    # Compose a response of this XMPPStanza
+    # (see XMPPStanza.answer)
+    # result:: [XMPPStanza] New constructed stanza
+    def answer(import=true)
+      XMPPStanza.answer(self, import)
+    end
+
+    ##
+    # Makes some changes to the structure of an XML element to help
+    # it respect the specification. For example, in a message, we should
+    # have <subject/> < <body/> < { rest of tags }
+    def normalize
+    end
+
+    ##
+    # get the to attribute
+    #
+    # return:: [String] the element's to attribute
+    def to
+      (a = attribute('to')).nil? ? a : JID.new(a.value)
+    end
+
+    ##
+    # set the to attribute
+    #
+    # v:: [String] the value to set
+    def to= (v)
+      add_attribute('to', v ? v.to_s : nil)
+    end
+
+    ##
+    # set the to attribute (chaining-friendly)
+    #
+    # v:: [String] the value to set
+    def set_to(v)
+      self.to = v
+      self
+    end
+
+    ##
+    # get the from attribute
+    #
+    # return:: [String] the element's from attribute
+    def from
+      (a = attribute('from')).nil? ? a : JID.new(a.value)
+    end
+
+    ##
+    # set the from attribute
+    #
+    # v:: [String] the value from set
+    def from= (v)
+      add_attribute('from', v ? v.to_s : nil)
+    end
+
+    ##
+    # set the from attribute (chaining-friendly)
+    #
+    # v:: [String] the value from set
+    def set_from(v)
+      add_attribute('from', v ? v.to_s : nil)
+      self
+    end
+
+    ##
+    # get the id attribute
+    #
+    # return:: [String] the element's id attribute
+    def id
+      (a = attribute('id')).nil? ? a : a.value
+    end
+
+    ##
+    # set the id attribute
+    #
+    # v:: [String] the value id set
+    def id= (v)
+      add_attribute('id', v.to_s)
+    end
+
+    ##
+    # set the id attribute (chaining-friendly)
+    #
+    # v:: [String] the value id set
+    def set_id(v)
+      add_attribute('id', v.to_s)
+      self
+    end
+
+    ##
+    # get the type attribute
+    #
+    # return:: [String] the element's type attribute
+    def type
+      (a = attribute('type')).nil? ? a : a.value
+    end
+
+    ##
+    # set the type attribute
+    #
+    # v:: [String] the value type set
+    def type= (v)
+      add_attribute('type', v)
+    end
+
+    ##
+    # set the type attribute (chaining-friendly)
+    #
+    # v:: [String] the value type set
+    def set_type(v)
+      add_attribute('type', v)
+      self
+    end
+  end
+end

data/lib/xmpp4r.rb

@@ -0,0 +1,116 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+#
+# ==Introduction
+#
+# XMPP4R is a XMPP/Jabber library for Ruby. It can be used to build scripts
+# using Jabber, full-featured Jabber clients, and components. It is written
+# with extensibility in mind.
+#
+# ==XML management
+#
+# All the XML parsing is REXML's, and XML stanzas like <message/> (class
+# <tt>Jabber::Message</tt>) or <iq/> (class <tt>Jabber::Iq</tt>) are indirect
+# derivatives from REXML's Element class. This provide a maximum flexibity:
+# the user can access attributes and childs using either the XMPP4R's helpers
+# or directly using REXML's methods.
+#
+# ===Automatic element casting
+#
+# Because there are special classes derived from REXML::Element to ease
+# development on the protocol level, Elements must be cast to them. This is
+# done via REXML::Element.import. This method is also used in import class
+# methods of some Element classes.
+#
+# The first occurance of this feature is in Jabber::Stream::receive:
+# * <tt><message/></tt> stanzas are cast to Jabber::Message class
+# * <tt><presence/></tt> stanzas are cast to Jabber::Presence class
+# * <tt><iq/></tt> stanzas are cast to Jabber::Iq class
+#
+# This is not only useful for stanzas but all other XML processing, too:
+# * <tt><x/></tt> children elements of <tt><message/></tt> and <tt><presence/></tt> are converted to Jabber::X
+# * <tt><error/></tt> children elements of all three stanzas are converted to Jabber::ErrorResponse
+# * <tt><query/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqQuery
+# * <tt><vCard/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqVcard
+#
+# The following conversion facilities are only executed if the respective
+# library parts are loaded. See below for more details on Non-basic features.
+# * Jabber::IqQuery elements are converted to Jabber::Roster::IqQueryRoster if their
+#   namespace is 'jabber:iq:roster'
+# * Jabber::IqQuery elements are converted to Jabber::Version::IqQueryVersion if their
+#   namespace is 'jabber:iq:version'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoInfo if their
+#   namespace is 'http://jabber.org/protocol/disco#info'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoItems if their
+#   namespace is 'http://jabber.org/protocol/disco#items'
+# * <tt><item/></tt> children elements of Jabber::Roster::IqQueryRoster are converted
+#   to Jabber::Roster::RosterItem
+# * <tt><identity/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoIdentity
+# * <tt><feature/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoFeature
+# * <tt><item/></tt> children elements of Jabber::IqQueryDiscoItems are converted
+#   to Jabber::Discovery::DiscoItem
+#
+# To use this, don't check for:
+# <tt>iq.queryns == 'http://jabber.org/protocol/disco#info'</tt>
+#
+# But instead check for the query's class:
+# <tt>iq.query.kind_of?(Jabber::IqQueryDiscoInfo)</tt>
+#
+# ==Where to begin?
+#
+# Because it is built in an extensible way, it might be hard for newcomers to
+# understand where to look at documentation for a specific method. For example,
+# Client inherits from Connection, which itself inherits from Stream.
+#
+# A newcomer should have a look at the <tt>Jabber::Client</tt> and
+# <tt>Jabber::Component</tt> classes, and their parent classes
+# <tt>Jabber::Connection</tt> and <tt>Jabber::Stream</tt>.  The best way to
+# understand how to use them is probably to look at the examples in the
+# <tt>examples/</tt> dir.
+#
+# ==Non-basic features
+#
+# <tt>require 'xmpp4r'</tt> only includes basic functionality for
+# Connections, Authentication, Stream processing, Callbacks, Stanza handling
+# and Debugging to keep the library's footprint small.
+#
+# There is code for features that aren't required by a *basic* client. These
+# must be additionally included to use them.
+#
+# ===Protocol-level features
+#
+# You're highly advised to read the according RFCs and JEPs if you intend to
+# use them. The benefit will be that you'll understand the protocols and be
+# going to be more efficient when programming with them.
+#
+# * Jabber::Bytestreams, Jabber::FileTransfer: <tt>require 'xmpp4r/bytestreams'</tt>
+# * Jabber::Dataforms: <tt>require 'xmpp4r/dataforms'</tt>
+# * Jabber::Delay: <tt>require 'xmpp4r/delay'</tt>
+# * Jabber::Discovery: <tt>require 'xmpp4r/discovery'</tt>
+# * Jabber::FeatureNegotiation: <tt>require 'xmpp4r/feature_negotiation'</tt>
+# * Jabber::MUC: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Roster: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::Vcard: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::Version: <tt>require 'xmpp4r/version'</tt>
+#
+# ===Helpers
+#
+# Helpers are intended to give more simplistic interfaces to various tasks
+# of Jabber clients at the cost of flexibility. But you won't need that
+# level of flexibility in most cases.
+#
+# * Jabber::Roster::Helper: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::MUC::MUCBrowser, Jabber::MUC::MUCClient, Jabber::MUC::SimpleMUCClient: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Version::SimpleResponder, Jabber::Version::Responder: <tt>require 'xmpp4r/version'</tt>
+# * Jabber::Vcard::Helper: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::FileTransfer::Helper, Jabber::Bytestreams::SOCKS5BytestreamsServer: <tt>require 'xmpp4r/bytestreams'</tt>
+#
+# ==Debugging
+#
+# Dumping your Jabber stream can be enabled this way:
+#   Jabber::debug = true
+
+require 'xmpp4r/xmpp4r'