= Blather

An evented XMPP library

== Features

* evented architecture
* uses libxml
* simplified starting point

== Project Pages

GitHub:: https://github.com/sprsquish/blather

RubyForge:: http://rubyforge.org/projects/squishtech/

== 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

There are 5 different types of guards:

  # 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'}]

= TODO

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

= License

Please see LICENSE