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
  def self.run
    client.run
  end

  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

EM.run { Echo.run }

Create a class out of it


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

echo = Echo.new
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.client.run }

Defined Under Namespace

Classes: PubSub

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (Object) append_features(o)



86
87
88
89
90
91
# File 'lib/blather/client/dsl.rb', line 86

def self.append_features(o)
  Blather::Stanza.handler_list.each do |handler_name|
    o.__send__ :remove_method, handler_name if !o.is_a?(Class) && o.method_defined?(handler_name)
  end
  super
end

+ (Blather::Client) client

The actual client connection



96
97
98
# File 'lib/blather/client/dsl.rb', line 96

def client
  @client ||= Client.new
end

Instance Method Details

- (self) <<(stanza)

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

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


114
115
116
117
# File 'lib/blather/client/dsl.rb', line 114

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

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

Setup an after filter

run after against

Yields:



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

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

- (Object) before(handler = nil, *guards) {|Blather::Stanza| ... }

Setup a before filter

run before against

Yields:



144
145
146
# File 'lib/blather/client/dsl.rb', line 144

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

- (Object) disconnected(&block)

Wrapper for "handle :disconnected"

This is run after the connection has been shut down.

Examples:

Reconnect after a disconnection

disconnected { client.run }


182
183
184
# File 'lib/blather/client/dsl.rb', line 182

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

- (Object) discover(what, who, where, &callback)

Request items or info from an entity

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


274
275
276
277
278
279
280
281
# File 'lib/blather/client/dsl.rb', line 274

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

- (Object) halt

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 }


251
252
253
# File 'lib/blather/client/dsl.rb', line 251

def halt
  throw :halt
end

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

Set handler for a stanza type

against

Yields:



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

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

- (Blather::JID) jid

The JID according to the server



240
241
242
# File 'lib/blather/client/dsl.rb', line 240

def jid
  client.jid
end

- (Object) join(room_jid, nickname) - (Object) join(room_jid, nickname)

Helper method to join a MUC room



218
219
220
221
222
223
224
225
226
# File 'lib/blather/client/dsl.rb', line 218

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

- (Blather::Roster) my_roster

Direct access to the roster



198
199
200
# File 'lib/blather/client/dsl.rb', line 198

def my_roster
  client.roster
end

- (Object) pass

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



267
268
269
# File 'lib/blather/client/dsl.rb', line 267

def pass
  throw :pass
end

- (Blather::PubSub) pubsub

A pubsub helper



104
105
106
# File 'lib/blather/client/dsl.rb', line 104

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

- (Object) say(to, msg, using = :chat)

Helper method to make sending basic messages easier



233
234
235
# File 'lib/blather/client/dsl.rb', line 233

def say(to, msg, using = :chat)
  client.write Blather::Stanza::Message.new(to, msg, using)
end

- (Object) send_caps

Send capabilities to the server



295
296
297
298
299
300
301
302
303
# File 'lib/blather/client/dsl.rb', line 295

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

- (Object) set_caps(node, identities, features)

Set the capabilities of the client



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

def set_caps(node, identities, features)
  client.caps.node = node
  client.caps.identities = identities
  client.caps.features = features
end

- (Object) set_status(state = nil, msg = nil)

Set current status

state



191
192
193
# File 'lib/blather/client/dsl.rb', line 191

def set_status(state = nil, msg = nil)
  client.status = state, msg
end

- (Object) setup(jid, password, host = nil, port = nil, certs = nil, connection_timeout = nil)

Prepare server settings

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



127
128
129
# File 'lib/blather/client/dsl.rb', line 127

def setup(jid, password, host = nil, port = nil, certs = nil, connection_timeout = nil)
  client.setup(jid, password, host, port, certs, connection_timeout)
end

- (Object) shutdown

Shutdown the connection. Flushes the write buffer then stops EventMachine



133
134
135
# File 'lib/blather/client/dsl.rb', line 133

def shutdown
  client.close
end

- (Object) when_ready(&block)

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

This is run after the connection has been completely setup



172
173
174
# File 'lib/blather/client/dsl.rb', line 172

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

- (Object) write_to_stream(stanza)

Write data to the stream



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

def write_to_stream(stanza)
  client.write stanza
end