Home

A servant runs in order to respond to orders by performing tasks. Orders are gathered from one or more listeners.

Creating a Servant

A servant is just a ruby script.

  #cuppa.rb
  require 'rubygems'
  require 'baldrick_serve'

  listen_to :feed, :at => 'http://search.twitter.com/search.atom?q=cup+of'

  on_hearing /cup of (.*?)[\.,]/ do |beverage, order|
    puts "#{order[:who]} would like a cup of #{beverage}"  
  end

Just run the script and the magic ruby fairies will take care of the rest:

  ruby cuppa.rb

Dismiss Baldrick with CTRL C.

Where to Listen

  listen_to :feed, :at => 'http://search.twitter.com/search.atom?q=cup+of'

The first argument is the name of a registered listener, the second is a Hash containing any options for that listener.

Tasks

A task defines what should be done and which orders should be acted apon.

Order

An order consists of:

• who – whoever issued the order
• what – the actual order
• where – where the order was issued from
• when – the time the order was issued

Individual listeners are responsible for mapping their source to this format. An order is passed into the body of a task as a Hash when it is executed.

Rule

  on_hearing /cup of (.*?)[\.,]/ do |beverage, order|
    .... 
  end

The rule is a regular expression. If the :what of the order matches the pattern then the task will be performed.

The contents of capturing groups (if any) will be passed to the task body, followed by the order.

Body

    puts "#{order[:who]} would like a cup of #{beverage}"

The body will be executed against the same task instance every time. This means you can use it to maintain state between executions:

    count ||= 0
    @count  += 1
    puts "I have been called #{count) times"

Other Configuration

There are also other configuration options.

Register a New Listener

  register_listener_type :morse, MorseCodeListener

You can register your own listener types, see the Listeners section for more details on creating your own listener.

Set Polling Period

  listen_every 1

You can control the number of seconds the servant will wait between trying to perform tasks. The servant will act on orders from all listeners, wait for the specified period and then attempt to act on all new orders again.

Listeners

A listener is responsible for

• converting its source into a number of orders
• returning only new orders (managing which orders have already been returned)

Injour Listener

  listen_to :injour

Obtains orders from injour[http://github.com/arunthampi/injour] statuses on the local network using the injour client. The injour listener converts the current status for each user into an order.

You will need the injour command available on the path before using this listener.

Feed Listener

  listen_to :feed, :at => 'http://search.twitter.com/search.atom?q=cup+of'

Obtains orders from a web feed (RSS 1.0/2.0 or Atom). Items or entries in the feed are converted into individual orders. You must also specify the URL of the feed using :at.

Please get in contact if you find any cases that this listener doesn’t meet.

Creating Your Own

Creating your own listeners is easy, for example:

class MyAwesomeListener
  def initialize options={}
  end

  def orders
    [{
      :who => 'some guy',
      :what => 'stuff',
      :where => 'behind the bike sheds',
      :when => Time.now
    }]
  end
end

Just follow these rules:

• provide an initializer that takes an options hash
• add an orders method that returns an Enumerable containing orders Hashes
• define a :who, :what, :where and :when in each order

Then register your new listener as described before.