Introduction

XMPP4R is an XMPP/Jabber library for Ruby. Its goal is to provide a complete framework to develop Jabber-related applications or scripts in Ruby.

Features

• Fully object-oriented
• Aims at being XMPP compliant
• Threaded, events-based
• Well unit-tested and documented code
• Uses well-known and well-tested software like REXML, instead of reinventing the wheel
• Very easy to extend
• Released under Ruby's license, which is compatible with the GNU GPL via an explicit dual-licensing clause.

Current status

You can basically do everything you want with XMPP4R. It fully supports XMPP, and also a wide range of extensions (XEPs). Also, it's very easy to extend.

A lot of examples are shipped with XMPP4R (If you installed from a linux package see /usr/share/doc/xmpp4r/examples/ or /usr/local/share/doc/xmpp4r/examples/, or take a look in the data/doc dir if you have a copy of the source code).

Download and Installation

The latest stable XMPP4R release is XMPP4R 0.5.

From a tarball

Releases are available here: http://download.gna.org/xmpp4r/. Untar the archive and run ./setup.rb

Using RubyGems

gem install xmpp4r

Using a package for your distribution

There's a package available in Debian and Ubuntu. Just apt-get install libxmpp4r-ruby. With Gentoo, XMPP4R can be installed via emerge dev-ruby/xmpp4r.

Using RubyGems to install from GitHub (development version)

You should be using RubyGems version 1.2.0+ to use this method

gem sources -a http://gems.github.com (you only need to do this once!)
gem install ln-xmpp4r

Using Git to install the development version

git clone git://github.com/ln/xmpp4r.git (see GitHub)

Related Projects

Alternative Jabber libraries for Ruby

• Jabber4R (projet homepage at Rubyforge): Not maintained anymore. XMPP4R is slightly based on, but far more advanced than Jabber4R.
• Net::XMPP: was a Google SoC 2005 project by Yuki Mitsui (aka Silphire). He later contributed code to XMPP4R resulting in TLS & SASL support.

Libraries on top of XMPP4R

• Jabber::Simple: An easy-to-use Jabber client library. Hide some complexity, at some cost.
• Action Messenger: a Ruby on Rails convenience framework like Action Mailer, only for instant messaging.

Applications

• iBota is a plugin-capable bot using XMPP4R by Vojtech Vobr. A homepage doesn't exist yet, but you may browse or check out the source code.
• RbIRC-t is an IRC gateway based upon XMPP4R. It is already documented and has features, but needs some refactorization for more flexibility. It will be released once this has been done. RbIRC-t is hosted within XMPP4R: Source Browser & Repository.
• Jabberhole is for Jabber what MouseHole is for the Web. It serves as a connection proxy and loaded scripts may rewrite trespassing XMPP stanzas instead of web pages. It is experimental and old, but feel free to have fun with it: Source Browser & Repository.
• rabber was born out of the idea to have a Jabber client utilizing Gtk and XMPP4R. The project is still before its infancy due to lack of time and knowledge of Gtk. A SVN repository exists, contact Lars Strojny if you want to help.
• Jabber Disk is a very cool service, providing online file storage via Jabber. Look at the project homepage or just try it at disk.jabbim.cz.

Developers

Discussions take place on the xmpp4r-devel at gna dot org mailing list.

• xmpp4r-devel Info Page (to subscribe/unsubscribe, etc)
• xmpp4r-devel archives

Bugs can be reported to the mailing list or on the GNA project page.

When reporting bugs, please provide as much information as possible:

• Contact information
• XMPP4R version or Git SHA1 commit
• Use Jabber::debug = true but remove any sensitive information
• Describe your environment (Ruby version, OS, server software)
• Cool hackers send test cases

The main development branch is hosted on Github. We encourage contributors to get familiarized with Git, as Git makes it very easy to get patches into the project, not just for the maintainer but also for the contributor himself. A few typical questions are answered on the GitHub FAQ Page. Feel free to make a GitHub 'fork' of the project and send us pull requests or patches to the xmpp4r-devel mailing list.

The SVN repository isn't updated anymore, but is still accessible at svn co svn://svn.gna.org/svn/xmpp4r/trunk/xmpp4r for historical reasons.

The RDOC source code documentation is browseable here. It might not be completely up-to-date (but we try hard to make it be). If you have the source code you can generate your own using docs using rake rdoc

Articles about developing with XMPP4R

Famundo Dev Blog has a series of introductory articles about XMPP4R:

• Ruby and XMPP/Jabber - a Multi Posts Series, Part 1
• Ruby and XMPP/Jabber Part 2: Logging in and sending simple messages
• Ruby and XMPP/Jabber Part 3: Adding html to the messages

Another two-part Tutorial can be found at Ruby Fleebie:

• IM Integration With XMPP4r
• IM Integration With XMPP4r : Part 2

A German tutorial is available at the BSD-Crew Wiki: Jabberbots mit XMPP4R