xmpp4r 0.3.2 → 0.4

data/{ChangeLog → CHANGELOG}

@@ -1,3 +1,35 @@
+XMPP4R 0.4 (05/08/2008)
+=======================
+* Initial support for Ruby 1.9 (see README_ruby19.txt)
+* Complete PubSub API Change - more logical and better for 
+  childclasses, support for collection node creation
+* a Helper to assist with XEP-0115 Entity Capabilities 
+* SASL anonymous support
+* File transfer fixes
+* MUC room configuration fixes
+* initial support for XEP-0118 User Tune
+* fix for an xmlrpc exception-during-serialisation bug, which would cause
+  a hang
+* Support auto-gem generation on GitHub with improved and DRY'er RakeFile and
+  gemspec.
+* Add support for the old SSL protocol (needed to connect to GTalk)
+* Changed API for Client, Component, Connection, Stream to remove
+  need for antiquated 'threaded' param in the initializer.
+* Use a Logger instance instead of directly writing to stdout
+* Re-factored & consolidated Error classes.  See xmpp4r/errors.rb for all
+  custom errors that can be caught.  All inherit from Jabber::Error which
+  itself inherits from Ruby's StandardError. This is a first step in
+  re-factoring errors.  The next step will be to convert all 'raise' calls to
+  raise a custom Jabber::Error or one of its children instead of anonymous
+  RuntimeErrors.  This allows much more granularity in catching and handling
+  errors later.
+  If you were catching Jabber::ErrorException before you should probably
+  change that in your code to now catch Jabber::Error if you want to
+  catch everything or one of the custom children of Jabber::Error defined in
+  'lib/xmpp4r/errors.rb'.  Additionally, the Error class which encapsulated
+  the xmpp error response, has been renamed to ErrorResponse to reflect its
+  real usage.  This free's up 'Jabber::Error' for use as our base Error class.
+
 XMPP4R 0.3.2 (15/10/2007)
 =========================
 * Serious bug involving Ruby threading fixed (caused exceptions with
@@ -48,3 +80,4 @@ XMPP4R 0.2 (20/10/2005)
 XMPP4R 0.1 (12/09/2005)
 =======================
 * first public release.
+

data/LICENSE

@@ -1,5 +1,5 @@
 XMPP4R is copyrighted free software by Lucas Nussbaum
-<lucas@lucas-nussbaum.net>, Stephan Maka <astro@spaceboyz.net>, and others.
+<lucas@lucas-nussbaum.net>, Stephan Maka <stephan@spaceboyz.net>, and others.
 You can redistribute it and/or modify it under either the terms of the GPL (see
 COPYING file), or the conditions below:
 
@@ -12,14 +12,14 @@ COPYING file), or the conditions below:
 
        a) place your modifications in the Public Domain or otherwise
           make them Freely Available, such as by posting said
-	  modifications to Usenet or an equivalent medium, or by allowing
-	  the author to include your modifications in the software.
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
 
        b) use the modified software only within your corporation or
           organization.
 
        c) rename any non-standard executables so the names do not conflict
-	  with standard executables, which must also be provided.
+          with standard executables, which must also be provided.
 
        d) make other distribution arrangements with the author.
 
@@ -27,11 +27,11 @@ COPYING file), or the conditions below:
      form, provided that you do at least ONE of the following:
 
        a) distribute the executables and library files of the software,
-	  together with instructions (in the manual page or equivalent)
-	  on where to get the original distribution.
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
 
        b) accompany the distribution with the machine-readable source of
-	  the software.
+          the software.
 
        c) give non-standard executables non-standard names, with
           instructions on where to get the original software distribution.
@@ -46,9 +46,9 @@ COPYING file), or the conditions below:
      files under the ./missing directory.  See each file for the copying
      condition.
 
-  5. The scripts and library files supplied as input to or produced as 
+  5. The scripts and library files supplied as input to or produced as
      output from the software do not automatically fall under the
-     copyright of the software, but belong to whomever generated them, 
+     copyright of the software, but belong to whomever generated them,
      and may be sold commercially, and may be aggregated with this
      software.
 

data/README.rdoc

@@ -0,0 +1,110 @@
+= XMPP4R
+
+== Project Home
+
+You can find info about the xmpp4r project and how to contribute
+at the project home page:
+
+http://home.gna.org/xmpp4r/
+
+If you need to ask questions, or want feedback on proposed changes
+please feel free to ask them on the 'xmpp4r-devel@gna.org' mailing
+list.  You can join or view archives of the mailing list at:
+
+https://gna.org/mail/?group=xmpp4r
+
+If you are having a problem and would like to report it
+to the mailing list please include a protocol dump
+which can be enabled in your code with:
+
+  Jabber::debug = true
+
+
+== Contributors
+
+  Lucas Nussbaum <lucas@lucas-nussbaum.net>
+  Stephan Maka <stephan@spaceboyz.net>
+  Kirill A. Shutemov <k.shutemov@gmail.com>
+  Yuki Mitsui
+  Peter Schrammel
+  Olli
+  Vojtech Vobr
+  Andreas Wiese
+  Chris Zelenak
+  Matthew Wood
+  Sam Ruby
+  Glenn Rempe <glenn@rempe.us>
+  Tim Carey-Smith
+  Scott Lillibridge
+  Joshua Sierles
+
+
+== Source Code
+
+The source for xmpp4r is managed using the Git SCM and can be
+found in our GitHub.com project page:
+
+http://github.com/ln/xmpp4r/tree/master
+
+
+== Installation
+
+There are a number of ways that you can install xmpp4r depending
+on your needs and the methods you prefer.
+
+=== Install over the network using RubyGems
+
+You can install the current release of the xmpp4r library from a stable
+release gem on RubyForge using RubyGems:
+
+  sudo gem install xmpp4r
+
+=== Install over the network using a Debian package
+
+You can install the current release of the xmpp4r library from a stable release copy
+on your .deb friendly linux system (e.g. Debian or Ubuntu) using apt:
+
+  sudo apt-get install libxmpp4r-ruby
+
+=== Install from local source code (Developers Only)
+
+If you have a local Git clone of the source repository or a tarball
+you can install xmpp4r using several methods.  First you'll
+need to get a local copy.
+
+Clone the Git repository (recommended):
+
+  git clone git://github.com/ln/xmpp4r.git
+
+OR download a stable release tarball from:
+
+  http://download.gna.org/xmpp4r/xmpp4r-0.3.2.tgz
+
+OR download a snapshot of the latest source in .tar.gz format from:
+
+  http://github.com/ln/xmpp4r/tarball/master
+
+==== Install : Using Rake
+
+  # Show all available rake tasks
+  cd xmpp4r/
+  rake -T
+
+  # Package up the gem file and install it
+  rake gem:install
+
+==== Install : Using setup.rb
+
+This will install a copy of the library in your Ruby path and does not
+require RubyGems to be installed.
+
+  cd xmpp4r/
+  ./setup.rb
+
+
+== License
+
+XMPP4R is released under the Ruby license (see the LICENSE file), which is
+compatible with the GNU GPL (see the COPYING file) via an explicit
+dual-licensing clause.
+

data/README_ruby19.txt

@@ -0,0 +1,43 @@
+Ruby 1.9 is a development release in anticipation of Ruby 2.0, which has
+overall better performance, real threading, and character encoding support.
+Note: Ruby 1.9 is a development release, meaning that everything is
+subject to change without prior notice.  Among other things, this means
+that xmpp4r could stop working on Ruby 1.9 at any time.
+
+This version of xmpp4r has made a number of internal changes (nothing visible
+at the API) to remove depency on deprecated Ruby Kernel APIs, support the new
+encoding APIs, etc.
+
+At the present time, all tests pass except tc_helper.rb and tc_stream.rb.
+These tests themselves make assumptions about timinings of events,
+assumptions that are not guaranteed with true multi-tasking.  Initial
+analysis indicates that xmpp4r is operating correctly, it is the tests
+themselves that need to be corrected, but this could turn out to be
+incorrect.
+
+The executing of these two tests are disabled by a check in ts_xmpp4r.rb,
+which is marked as a TODO.
+
+A specific example: test_bidi in test/tc_stream.rb defines two threads,
+one pumps out requests, the other echoes them.  The receiver then verifies
+that it gets back what it sent.  With Ruby 1.8, these threads tend to
+alternate in lock step, and the test usually passes.  What happens in Ruby 1.9
+is that the first thread waits for a message, and the second one creates a
+callback block, generates a message, and then proceeds on to create a second
+callback block -- even before the first message has been responded to.
+The way xmpp4r works is that callbacks are saved on a pushdown stack.
+
+The net result is that the first response typically is processed first by 
+the second callback, which decides that the ids don't match, and the test fails.
+
+The way it is supposed to work is that the reply callback is supposed to
+only process requests destined for it (and return true) and ignore
+everything else (returning false).
+
+This is but one test.  Many of the tests in these two files are of this
+nature.
+
+The current status of the tests that are expected to pass on Ruby 1.9
+can generally be found here:
+
+http://intertwingly.net/projects/ruby19/logs/xmpp4r.html

data/Rakefile

@@ -1,101 +1,262 @@
+require 'rake'
+require "rake/clean"
 require 'rake/testtask'
-require 'rake/packagetask'
 require 'rake/rdoctask'
-require 'rake'
-require 'find'
 
-begin
-  require 'rubygems'
-  require 'rcov/rcovtask'
-  RCOV = true
-rescue LoadError
-  RCOV = false
-end
+$:.unshift 'lib'
+require "xmpp4r"
 
+##############################################################################
+# OPTIONS
+##############################################################################
 
-# Globals
+PKG_NAME      = 'xmpp4r'
+PKG_VERSION   = Jabber::XMPP4R_VERSION
+AUTHORS       = ['Lucas Nussbaum', 'Stephan Maka', 'Glenn Rempe']
+EMAIL         = "xmpp4r-devel@gna.org"
+HOMEPAGE      = "http://home.gna.org/xmpp4r/"
+SUMMARY       = "XMPP4R is an XMPP/Jabber library for Ruby."
 
-PKG_NAME = 'xmpp4r'
-PKG_VERSION = '0.3.2'
+# These are the common rdoc options that are shared between generation of
+# rdoc files using BOTH 'rake rdoc' and the installation by users of a
+# RubyGem version which builds rdoc's along with its installation.  Any
+# rdoc options that are ONLY for developers running 'rake rdoc' should be
+# added in the 'Rake::RDocTask' block below.
+RDOC_OPTIONS  = [
+                "--quiet",
+                "--title", SUMMARY,
+                "--opname", "index.html",
+                "--main", "lib/xmpp4r.rb",
+                "--line-numbers",
+                "--inline-source"
+                ]
 
-PKG_FILES = ['ChangeLog', 'README', 'COPYING', 'LICENSE', 'setup.rb', 'Rakefile', 'UPDATING']
-Find.find('lib/', 'data/', 'test/', 'tools/') do |f|
-	if FileTest.directory?(f) and f =~ /\.svn/
-		Find.prune
-	else
-		PKG_FILES << f
-	end
-end
+# Extra files outside of the lib dir that should be included with the rdocs.
+RDOC_FILES    = %w( README.rdoc README_ruby19.txt CHANGELOG LICENSE COPYING )
 
+# The full file list used for rdocs, tarballs, gems, and for generating the xmpp4r.gemspec.
+PKG_FILES     = %w( Rakefile setup.rb xmpp4r.gemspec ) + RDOC_FILES + Dir["{lib,test,data,tools}/**/*"]
 
-# Tasks
+##############################################################################
+# DEFAULT TASK
+##############################################################################
 
-task :default => [:package]
+# The task that will run when a simple 'rake' command is issued.
+# Default to running the test suite as that's a nice safe command
+# we should run frequently.
+task :default => [:test]
+
+##############################################################################
+# TESTING TASKS
+##############################################################################
 
 Rake::TestTask.new do |t|
-	t.libs << "test"
-	t.test_files = ['test/ts_xmpp4r.rb']
+  t.libs << "test"
+  t.test_files = ['test/ts_xmpp4r.rb']
 end
 
+##############################################################################
+# DOCUMENTATION TASKS
+##############################################################################
+
+# RDOC
+#######
 Rake::RDocTask.new do |rd|
-  f = []
-  require 'find'
-  Find.find('lib/') do |file|
-    # Skip hidden files (.svn/ directories and Vim swapfiles)
-    if file.split(/\//).last =~ /^\./
-      Find.prune
-    else
-      f << file if not FileTest.directory?(file)
-    end
-  end
-  f.delete('lib/xmpp4r.rb')
-  # hack to document the Jabber module properly
-  f.unshift('lib/xmpp4r.rb')
-  rd.rdoc_files.include(f)
-  rd.options << '--all'
-  rd.options << '--diagram'
-  rd.options << '--fileboxes'
-  rd.options << '--inline-source'
-  rd.options << '--line-numbers'
+
+  # which dir should rdoc files be installed in?
   rd.rdoc_dir = 'rdoc'
+
+  # the full list of files to be included
+  rd.rdoc_files.include(RDOC_FILES, "lib/**/*.rb")
+
+  # the full list of options that are common between gem build
+  # and 'rake rdoc' build of docs.
+  rd.options = RDOC_OPTIONS
+
+  # Devs Only : Uncomment to also document private methods in the rdocs
+  # Please don't check this change in to the source repo.
+  #rd.options << '--all'
+
+  # Devs Only : Uncomment to generate dot (graphviz) diagrams along with rdocs.
+  # This requires that graphiz (dot) be installed as a local binary and on your path.
+  # See : http://www.graphviz.org/
+  # Please don't check this change in to the source repo as it introduces a binary dependency.
+  #rd.options << '--diagram'
+  #rd.options << '--fileboxes'
+
 end
 
-task :doctoweb => [:rdoc] do |t|
-   # copies the rdoc to the CVS repository for xmpp4r website
-	# repository is in $CVSDIR (default: ~/dev/xmpp4r-web)
-   sh "tools/doctoweb.bash"
+
+# RCOV
+#######
+
+# Conditional require rcov/rcovtask if present
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.test_files = ['test/ts_xmpp4r.rb']
+    t.output_dir = "coverage"
+  end
+rescue Object
 end
 
-Rake::PackageTask.new(PKG_NAME, PKG_VERSION) do |p|
-	p.need_tar = true
-	p.package_files = PKG_FILES
+# DOT GRAPH
+############
+desc "Generate requires graph"
+task :gen_requires_graph do
+  sh %{cd tools; ./gen_requires.bash}
 end
 
-if RCOV
-	Rcov::RcovTask.new do |t|
-		t.test_files = ['test/ts_xmpp4r.rb']
-	end
+# UPDATE WEBSITE (for Lucas only)
+#################################
+desc "Update website (for Lucas only)"
+task :update_website do
+  sh %{cp website/* ~/dev/xmpp4r/website/ && cd ~/dev/xmpp4r/website/ && svn commit -m "website update"}
+end
+
+
+##############################################################################
+# SYNTAX CHECKING
+##############################################################################
+
+desc "Check syntax of all Ruby files."
+task :check_syntax do
+  `find . -name "*.rb" |xargs -n1 ruby -c |grep -v "Syntax OK"`
+  puts "* Done"
 end
 
-# "Gem" part of the Rakefile
+##############################################################################
+# PACKAGING & INSTALLATION
+##############################################################################
+
+# What files/dirs should 'rake clean' remove?
+CLEAN.include ["*.gem", "pkg", "rdoc", "coverage", "tools/*.png"]
+
+# Flag for RubyGems installation used to add rake package tasks conditionally.
+# Full gem + tarball on systems with RubyGems.  More limited on systems without.
+@rubygems = nil
+
 begin
-	require 'rake/gempackagetask'
-
-	spec = Gem::Specification.new do |s|
-		s.platform = Gem::Platform::RUBY
-		s.summary = "Ruby library for Jabber Instant-Messaging"
-		s.name = PKG_NAME
-		s.version = PKG_VERSION
-		s.requirements << 'none'
-		s.require_path = 'lib'
-		s.autorequire = 'xmpp4r'
-		s.files = PKG_FILES
-		s.description = "Ruby library for Jabber Instant-Messaging"
-	end
-
-	Rake::GemPackageTask.new(spec) do |pkg|
-		pkg.need_zip = true
-		pkg.need_tar = true
-	end
+  require 'rake/gempackagetask'
+
+  # RubyGems is installed, known since require 'rake/gempackagetask' succeeded.
+  @rubygems = true
+
+  spec = Gem::Specification.new do |s|
+    s.name = PKG_NAME
+    s.version = PKG_VERSION
+    s.authors = AUTHORS
+    s.email = EMAIL
+    s.homepage = HOMEPAGE
+    s.rubyforge_project = PKG_NAME
+    s.summary = SUMMARY
+    s.description = s.summary
+    s.platform = Gem::Platform::RUBY
+    s.require_path = 'lib'
+    s.executables = []
+    s.files = PKG_FILES
+    s.test_files = []
+    s.has_rdoc = true
+    s.extra_rdoc_files = RDOC_FILES
+    s.rdoc_options = RDOC_OPTIONS
+    s.required_ruby_version = ">= 1.8.4"
+  end
+
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.gem_spec = spec
+    pkg.need_tar = true
+  end
+
+  namespace :gem do
+
+    desc "Run :package and install the .gem locally"
+    task :install => [:update_gemspec, :package] do
+      sh %{sudo gem install --local pkg/#{PKG_NAME}-#{PKG_VERSION}.gem}
+    end
+
+    desc "Like gem:install but without ri or rdocs"
+    task :install_fast => [:update_gemspec, :package] do
+      sh %{sudo gem install --local pkg/#{PKG_NAME}-#{PKG_VERSION}.gem --no-rdoc --no-ri}
+    end
+
+    desc "Run :clean and uninstall the .gem"
+    task :uninstall => :clean do
+      sh %{sudo gem uninstall #{PKG_NAME}}
+    end
+
+    # Thanks to the Merb project for this code.
+    desc "Update Github Gemspec"
+    task :update_gemspec do
+      skip_fields = %w(new_platform original_platform date)
+      integer_fields = %w(specification_version)
+
+      result = "# WARNING : RAKE AUTO-GENERATED FILE.  DO NOT MANUALLY EDIT!\n"
+      result << "# RUN : 'rake gem:update_gemspec'\n\n"
+      result << "Gem::Specification.new do |s|\n"
+      spec.instance_variables.each do |ivar|
+        value = spec.instance_variable_get(ivar)
+        name  = ivar.split("@").last
+        next if skip_fields.include?(name) || value.nil? || value == "" || (value.respond_to?(:empty?) && value.empty?)
+        if name == "dependencies"
+          value.each do |d|
+            dep, *ver = d.to_s.split(" ")
+            result <<  "  s.add_dependency #{dep.inspect}, #{ver.join(" ").inspect.gsub(/[()]/, "")}\n"
+          end
+        else
+          case value
+          when Array
+            value =  name != "files" ? value.inspect : value.sort.uniq.inspect.split(",").join(",\n")
+          when String
+            value = value.to_i if integer_fields.include?(name)
+            value = value.inspect
+          else
+            value = value.to_s.inspect
+          end
+          result << "  s.#{name} = #{value}\n"
+        end
+      end
+      result << "end"
+      File.open(File.join(File.dirname(__FILE__), "#{spec.name}.gemspec"), "w"){|f| f << result}
+    end
+
+  end # namespace :gem
+
+  # also keep the gemspec up to date each time we package a tarball or gem
+  task :package => ['gem:update_gemspec']
+  task :gem => ['gem:update_gemspec']
+
 rescue LoadError
+  @rubygems = false
+  warning = <<EOF
+###
+  Packaging Warning : RubyGems is apparently not installed on this
+  system and any file add/remove/rename will not
+  be auto-updated in the 'xmpp4r.gemspec' when you run any
+  package tasks.  All such file changes are recommended
+  to be packaged on a system with RubyGems installed
+  if you intend to push commits to the Git repo so the
+  gemspec will also stay in sync for others.
+###
+EOF
+  puts warning
+end
+
+# we are apparently on a system that does not have RubyGems installed.
+# Lets try to provide only the basic tarball package tasks as a fallback.
+if @rubygems == false
+  begin
+    require 'rake/packagetask'
+    Rake::PackageTask.new(PKG_NAME, PKG_VERSION) do |p|
+      p.package_files = PKG_FILES
+      p.need_tar = true
+    end
+  rescue LoadError
+    warning = <<EOF
+###
+  Warning : Unable to require the 'rake/packagetask'. Is Rake installed?
+###
+EOF
+    puts warning
+  end
 end