Blather

An evented XMPP library

Features

• evented architecture
• uses libxml
• simplified starting point

Project Pages

Author

Jeff Smick <sprsquish@gmail.com>

Usage

Installation

  sudo gem install blather

Example

See the /examples directory for more advanced examples.

This will auto-accept any subscription requests and echo back any chat messages.

  require 'rubygems'
  require 'blather/client'

  setup 'echo@jabber.local', 'echo'

  # Auto approve subscription requests
  subscription :request? do |s|
    write s.approve!
  end

  # Echo back what was said
  message :chat?, :body do |m|
    write m.reply
  end

Handlers

Setup handlers by calling their names as methods.

  # Will only be called for messages where #chat? responds positively
  # and #body == 'exit'
  message :chat?, :body => 'exit'

Handler Guards

Guards act like AND statements. Each condition must be met if the handler is to be used.

  # Equivalent to saying (stanza.chat? && stanza.body)
  message :chat?, :body

The different types of guards are:

  # Symbol
  #   Checks for a non-false reply to calling the symbol on the stanza
  #   Equivalent to stanza.chat?
  message :chat?

  # Hash with value (:body => 'exit')
  #   Calls the key on the stanza and checks for equality
  #   Equivalent to stanza.body == 'exit'
  message :body => 'exit'

  # Hash with regular expression (:body => /exit/)
  #   Calls the key on the stanza and checks for a match
  #   Equivalent to stanza.body.match /exit/
  message :body => /exit/

  # Hash with array (:name => [:gone, :forbidden])
  #   Calls the key on the stanza and check for inclusion in the array
  #   Equivalent to [:gone, :forbidden].include?(stanza.name)
  stanza_error :name => [:gone, :fobidden]

  # Proc
  #   Calls the proc passing in the stanza
  #   Checks that the ID is modulo 3
  message proc { |m| m.id % 3 == 0 }

  # Array
  #   Use arrays with the previous types effectively turns the guard into
  #   an OR statement.
  #   Equivalent to stanza.body == 'foo' || stanza.body == 'baz'
  message [{:body => 'foo'}, {:body => 'baz'}]

On the Command Line:

Default usage is:

  [blather_script] [options] node@domain.com/resource password [host] [port]

Command line options:

  -D, --debug                      Run in debug mode (you will see all XMPP communication)
  -d, --daemonize                  Daemonize the process
      --pid=[PID]                  Write the PID to this file
      --log=[LOG]                  Write to the [LOG] file instead of stdout/stderr
  -h, --help                       Show this message
  -v, --version                    Show version

TODO

• Add XPath guard that passes the result to the handler
• Add Disco the the DSL
• PubSub (XEP-0060: xmpp.org/extensions/xep-0060.html)
• More examples (Re-write XMPP4R examples into Blather)

License

Please see LICENSE