module Blather::DSL

# Blather DSL

The DSL is a set of methods that enables you to write cleaner code. Being a module means it can be included in or extend any class you may want to create.

Every stanza handler is registered as a method on the DSL.

@example Include the DSL in the top level namespace.

require 'blather/client'
when_ready { puts "Connected ! send messages to #{jid.stripped}." }

subscription :request? do |s|
  write_to_stream s.approve!
end

message :chat?, :body => 'exit' do |m|
  say m.from, 'Exiting ...'
  shutdown
end

message :chat?, :body do |m|
  say m.from, "You sent: #{m.body}"
end

@example Set the DSL to its own namespace.

require 'blather/client/dsl'
module Echo
  extend Blather::DSL

  when_ready { puts "Connected ! send messages to #{jid.stripped}." }

  subscription :request? do |s|
    write_to_stream s.approve!
  end

  message :chat?, :body => 'exit' do |m|
    say m.from, 'Exiting ...'
    shutdown
  end

  message :chat?, :body do |m|
    say m.from, "You sent: #{m.body}"
  end
end

Echo.setup 'foo@bar.com', 'foobar'

EM.run { Echo.run }

@example Create a class out of it

require 'blather/client/dsl'
class Echo
  include Blather::DSL
end

echo = Echo.new
echo.setup 'foo@bar.com', 'foobar'
echo.when_ready { puts "Connected ! send messages to #{jid.stripped}." }

echo.subscription :request? do |s|
  write_to_stream s.approve!
end

echo.message :chat?, :body => 'exit' do |m|
  say m.from, 'Exiting ...'
  shutdown
end

echo.message :chat?, :body do |m|
  say m.from, "You sent: #{m.body}"
end

EM.run { echo.run }

Public Class Methods

append_features(o) click to toggle source
Calls superclass method
# File lib/blather/client/dsl.rb, line 87
def self.append_features(o)
  # Generate a method for every stanza handler that exists.
  Blather::Stanza.handler_list.each do |handler_name|
    o.__send__ :define_method, handler_name do |*args, &callback|
      handle handler_name, *args, &callback
    end
  end
  super
end
client() click to toggle source

The actual client connection

@return [Blather::Client]

# File lib/blather/client/dsl.rb, line 112
def client
  @client ||= Client.new
end
extended(o) click to toggle source
Calls superclass method
# File lib/blather/client/dsl.rb, line 97
    def self.extended(o)
      # Generate a method for every stanza handler that exists.
      Blather::Stanza.handler_list.each do |handler_name|
        module_eval <<-METHOD, __FILE__, __LINE__
          def #{handler_name}(*args, &callback)
            handle :#{handler_name}, *args, &callback
          end
        METHOD
      end
      super
    end

Public Instance Methods

<<(stanza) click to toggle source

Push data to the stream This works such that it can be chained:

self << stanza1 << stanza2 << "raw data"

@param [#to_xml, to_s] stanza data to send down the wire @return [self]

# File lib/blather/client/dsl.rb, line 130
def <<(stanza)
  client.write stanza
  self
end
after(handler = nil, *guards, &block) click to toggle source

Setup an after filter

@param [Symbol] handler (optional) the stanza handler the filter should run after @param [guards] guards (optional) a set of guards to check the stanza against @yield [Blather::Stanza] stanza

# File lib/blather/client/dsl.rb, line 177
def after(handler = nil, *guards, &block)
  client.register_filter :after, handler, *guards, &block
end
before(handler = nil, *guards, &block) click to toggle source

Setup a before filter

@param [Symbol] handler (optional) the stanza handler the filter should run before @param [guards] guards (optional) a set of guards to check the stanza against @yield [Blather::Stanza] stanza

# File lib/blather/client/dsl.rb, line 166
def before(handler = nil, *guards, &block)
  client.register_filter :before, handler, *guards, &block
end
disconnected(&block) click to toggle source

Wrapper for “handle :disconnected”

This is run after the connection has been shut down.

@example Reconnect after a disconnection

disconnected { client.run }
# File lib/blather/client/dsl.rb, line 204
def disconnected(&block)
  handle :disconnected, &block
end
discover(what, who, where, &callback) click to toggle source

Request items or info from an entity

discover (items|info), [jid], [node] do |response|
end
# File lib/blather/client/dsl.rb, line 296
def discover(what, who, where, &callback)
  stanza = Blather::Stanza.class_from_registration(:query, "http://jabber.org/protocol/disco##{what}").new
  stanza.to = who
  stanza.node = where

  client.register_tmp_handler stanza.id, &callback
  client.write stanza
end
halt() click to toggle source

Halt the handler chain

Use this to stop the propogation of the stanza though the handler chain.

@example Ignore all IQ stanzas

before(:iq) { halt }
# File lib/blather/client/dsl.rb, line 273
def halt
  throw :halt
end
handle(handler, *guards, &block) click to toggle source

Set handler for a stanza type

@param [Symbol] handler the stanza type it should handle @param [guards] guards (optional) a set of guards to check the stanza against @yield [Blather::Stanza] stanza

# File lib/blather/client/dsl.rb, line 187
def handle(handler, *guards, &block)
  client.register_handler handler, *guards, &block
end
jid() click to toggle source

The JID according to the server

@return [Blather::JID]

# File lib/blather/client/dsl.rb, line 262
def jid
  client.jid
end
join(room, service, nickname = nil) click to toggle source

Helper method to join a MUC room

@overload join(room_jid, nickname)

@param [Blather::JID, #to_s] room the JID of the room to join
@param [#to_s] nickname the nickname to join the room as

@overload join(room_jid, nickname)

@param [#to_s] room the name of the room to join
@param [Blather::JID, #to_s] service the service domain the room is hosted at
@param [#to_s] nickname the nickname to join the room as
# File lib/blather/client/dsl.rb, line 240
def join(room, service, nickname = nil)
  join = Blather::Stanza::Presence::MUC.new
  join.to = if nickname
    "#{room}@#{service}/#{nickname}"
  else
    "#{room}/#{service}"
  end
  client.write join
end
my_roster() click to toggle source

Direct access to the roster

@return [Blather::Roster]

# File lib/blather/client/dsl.rb, line 220
def my_roster
  client.roster
end
pass() click to toggle source

Pass responsibility to the next handler

Use this to jump out of the current handler and let the next registered handler take care of the stanza

@example Pass a message to the next handler

This is contrive and should be handled with guards, but pass a message to the next handler based on the content

message { |s| puts "message caught" }
message { |s| pass if s.body =~ /pass along/ }
# File lib/blather/client/dsl.rb, line 289
def pass
  throw :pass
end
pubsub() click to toggle source

A pubsub helper

@return [Blather::PubSub]

# File lib/blather/client/dsl.rb, line 120
def pubsub
  @pubsub ||= PubSub.new client, jid.domain
end
run() click to toggle source

Connect to the server. Must be run in the EventMachine reactor

# File lib/blather/client/dsl.rb, line 149
def run
  client.run
end
say(to, msg, using = :chat) click to toggle source

Helper method to make sending basic messages easier

@param [Blather::JID, to_s] to the JID of the message recipient @param [#to_s] msg the message to send @param [#to_sym] the stanza method to use

# File lib/blather/client/dsl.rb, line 255
def say(to, msg, using = :chat)
  client.write Blather::Stanza::Message.new(to, msg, using)
end
send_caps() click to toggle source

Send capabilities to the server

# File lib/blather/client/dsl.rb, line 317
def send_caps
  client.register_handler :disco_info, :type => :get, :node => client.caps.node do |s|
    r = client.caps.dup
    r.to = s.from
    r.id = s.id
    client.write r
  end
  client.write client.caps.c
end
set_caps(node, identities, features) click to toggle source

Set the capabilities of the client

@param [String] node the URI @param [Array<Hash>] identities an array of identities @param [Array<Hash>] features an array of features

# File lib/blather/client/dsl.rb, line 310
def set_caps(node, identities, features)
  client.caps.node = node
  client.caps.identities = identities
  client.caps.features = features
end
set_status(state = nil, msg = nil) click to toggle source

Set current status

@param [Blather::Stanza::Presence::State::VALID_STATES] state the current state @param [#to_s] msg the status message to use

# File lib/blather/client/dsl.rb, line 213
def set_status(state = nil, msg = nil)
  client.status = state, msg
end
setup(jid, password, host = nil, port = nil, certs = nil, connection_timeout = nil, options = {}) click to toggle source

Prepare server settings

@param [#to_s] jid the JID to authenticate with @param [#to_s] password the password to authenticate with @param [String] host (optional) the host to connect to (can be an IP). If this is `nil` the domain on the JID will be used @param [Fixnum, String] (optional) port the port to connect on @param [Fixnum] (optional) connection_timeout the time to wait for connection to succeed before timing out @param [Hash] (optional) options

# File lib/blather/client/dsl.rb, line 144
def setup(jid, password, host = nil, port = nil, certs = nil, connection_timeout = nil, options = {})
  client.setup(jid, password, host, port, certs, connection_timeout, options)
end
shutdown() click to toggle source

Shutdown the connection. Flushes the write buffer then stops EventMachine

# File lib/blather/client/dsl.rb, line 155
def shutdown
  client.close
end
when_ready(&block) click to toggle source

Wrapper for “handle :ready” (just a bit of syntactic sugar)

This is run after the connection has been completely setup

# File lib/blather/client/dsl.rb, line 194
def when_ready(&block)
  handle :ready, &block
end
write_to_stream(stanza) click to toggle source

Write data to the stream

@param [#to_xml, to_s] stanza the data to send down the wire.

# File lib/blather/client/dsl.rb, line 227
def write_to_stream(stanza)
  client.write stanza
end

Private Instance Methods

client() click to toggle source

The actual client connection

@return [Blather::Client]

# File lib/blather/client/dsl.rb, line 112
def client
  @client ||= Client.new
end