Module: Blather::DSL

Defined in:
lib/blather/client/dsl.rb,
lib/blather/client/dsl/pubsub.rb

Overview

# 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.

Examples:

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

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 '[email protected]', 'foobar'

EM.run { Echo.run }

Create a class out of it


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

echo = Echo.new
echo.setup '[email protected]', '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 }

Defined Under Namespace

Classes: PubSub

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.append_features(o) ⇒ Object 



87
88
89
90
91
92
93
94
95
 
# 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 ⇒ Blather::Client

The actual client connection

Returns:



112
113
114
 
# File 'lib/blather/client/dsl.rb', line 112

def client
  @client ||= Client.new
end

.extended(o) ⇒ Object 



97
98
99
100
101
102
103
104
105
106
107
 
# 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

Instance Method Details

#<<(stanza) ⇒ self

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

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

Parameters:

  • stanza (#to_xml, #to_s) —

    data to send down the wire

Returns:

  • (self) 


130
131
132
133
 
# File 'lib/blather/client/dsl.rb', line 130

def <<(stanza)
  client.write stanza
  self
end

#after(handler = nil, *guards) {|Blather::Stanza| ... } ⇒ Object

Setup an after filter

run after against

Parameters:

  • handler (Symbol) (defaults to: nil) —

    (optional) the stanza handler the filter should

  • guards (guards) —

    (optional) a set of guards to check the stanza

Yields:



177
178
179
 
# 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) {|Blather::Stanza| ... } ⇒ Object

Setup a before filter

run before against

Parameters:

  • handler (Symbol) (defaults to: nil) —

    (optional) the stanza handler the filter should

  • guards (guards) —

    (optional) a set of guards to check the stanza

Yields:



166
167
168
 
# File 'lib/blather/client/dsl.rb', line 166

def before(handler = nil, *guards, &block)
  client.register_filter :before, handler, *guards, &block
end

#disconnected(&block) ⇒ Object

Wrapper for “handle :disconnected”

This is run after the connection has been shut down.

Examples:

Reconnect after a disconnection

disconnected { client.run }


204
205
206
 
# File 'lib/blather/client/dsl.rb', line 204

def disconnected(&block)
  handle :disconnected, &block
end

#discover(what, who, where, &callback) ⇒ Object

Request items or info from an entity

discover (items|info), [jid], [node] do |response|
end



296
297
298
299
300
301
302
303
 
# 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 ⇒ Object

Halt the handler chain

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

Examples:

Ignore all IQ stanzas


before(:iq) { halt }


273
274
275
 
# File 'lib/blather/client/dsl.rb', line 273

def halt
  throw :halt
end

#handle(handler, *guards) {|Blather::Stanza| ... } ⇒ Object

Set handler for a stanza type

against

Parameters:

  • handler (Symbol) —

    the stanza type it should handle

  • guards (guards) —

    (optional) a set of guards to check the stanza

Yields:



187
188
189
 
# File 'lib/blather/client/dsl.rb', line 187

def handle(handler, *guards, &block)
  client.register_handler handler, *guards, &block
end

#jid ⇒ Blather::JID

The JID according to the server

Returns:



262
263
264
 
# File 'lib/blather/client/dsl.rb', line 262

def jid
  client.jid
end

#join(room_jid, nickname) ⇒ Object #join(room_jid, nickname) ⇒ Object

Helper method to join a MUC room

Overloads:

  • #join(room_jid, nickname) ⇒ Object

    Parameters:

    • room (Blather::JID, #to_s) —

      the JID of the room to join

    • nickname (#to_s) —

      the nickname to join the room as

  • #join(room_jid, nickname) ⇒ Object

    Parameters:

    • room (#to_s) —

      the name of the room to join

    • service (Blather::JID, #to_s) —

      the service domain the room is hosted at

    • nickname (#to_s) —

      the nickname to join the room as



240
241
242
243
244
245
246
247
248
 
# 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 ⇒ Blather::Roster

Direct access to the roster

Returns:



220
221
222
 
# File 'lib/blather/client/dsl.rb', line 220

def my_roster
  client.roster
end

#pass ⇒ Object

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

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/ }

Examples:

Pass a message to the next handler



289
290
291
 
# File 'lib/blather/client/dsl.rb', line 289

def pass
  throw :pass
end

#pubsub ⇒ Blather::PubSub

A pubsub helper

Returns:

  • (Blather::PubSub) 


120
121
122
 
# File 'lib/blather/client/dsl.rb', line 120

def pubsub
  @pubsub ||= PubSub.new client, jid.domain
end

#run ⇒ Object

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



149
150
151
 
# File 'lib/blather/client/dsl.rb', line 149

def run
  client.run
end

#say(to, msg, using = :chat) ⇒ Object

Helper method to make sending basic messages easier

Parameters:

  • to (Blather::JID, #to_s) —

    the JID of the message recipient

  • msg (#to_s) —

    the message to send

  • the (#to_sym) —

    stanza method to use



255
256
257
 
# 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 ⇒ Object

Send capabilities to the server



317
318
319
320
321
322
323
324
325
 
# 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) ⇒ Object

Set the capabilities of the client

Parameters:

  • node (String) —

    the URI

  • identities (Array<Hash>) —

    an array of identities

  • features (Array<Hash>) —

    an array of features



310
311
312
313
314
 
# 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) ⇒ Object

Set current status

state

Parameters:

  • state (Blather::Stanza::Presence::State::VALID_STATES) (defaults to: nil) —

    the current

  • msg (#to_s) (defaults to: nil) —

    the status message to use



213
214
215
 
# 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 = {}) ⇒ Object

Prepare server settings

this is ‘nil` the domain on the JID will be used

Parameters:

  • jid (#to_s) —

    the JID to authenticate with

  • password (#to_s) —

    the password to authenticate with

  • host (String) (defaults to: nil) —

    (optional) the host to connect to (can be an IP). If

  • (optional) (Fixnum, String) —

    port the port to connect on

  • (optional) (Fixnum) —

    connection_timeout the time to wait for connection to succeed before timing out

  • (optional) (Hash) —

    options



144
145
146
 
# 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 ⇒ Object

Shutdown the connection. Flushes the write buffer then stops EventMachine



155
156
157
 
# File 'lib/blather/client/dsl.rb', line 155

def shutdown
  client.close
end

#when_ready(&block) ⇒ Object

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

This is run after the connection has been completely setup



194
195
196
 
# File 'lib/blather/client/dsl.rb', line 194

def when_ready(&block)
  handle :ready, &block
end

#write_to_stream(stanza) ⇒ Object

Write data to the stream

Parameters:

  • stanza (#to_xml, #to_s) —

    the data to send down the wire.



227
228
229
 
# File 'lib/blather/client/dsl.rb', line 227

def write_to_stream(stanza)
  client.write stanza
end