Herald

Herald is a simple notifier for Twitter and RSS.

Pass Herald some keywords and sources to watch, and Herald will notify you using Growl, pinging or posting to a site, or running Ruby code as soon as those keywords appear.

Installation

Rubygems

gem install herald

GitHub

git clone git://github.com/lukes/herald.git
gem build herald.gemspec
gem install herald-0.2.gem

Usage

First step is to require Herald into your Ruby project

require 'rubygems'
require 'herald'

Then, to watch for tweets containing "soundofmusic"

Herald.watch do
  check :twitter
  _for "soundofmusic"
end

Or an RSS feed

Herald.watch do
  check :rss, :from => "http://example.com/.rss"
  _for "soundofmusic"
end

Or text in a website

Herald.watch do
  check :website, :from => "http://example.com"
  _for "soundofmusic"
end

Watching multiple sources, or for multiple keywords

Watching two RSS feeds and Twitter for two keywords

Herald.watch do
  check :rss, :from => ["http://earthquakes.gov/.rss", "http://livenews.com/.rss"]
  check :twitter
  _for "christchurch", "earthquake"
end

Or, if sources should have different keywords

Herald.watch do    
  check :rss, :from => "http://earthquake.usgs.gov/earthquakes/catalogs/eqs1day-M0.xml"
    _for "christchurch"
  end
  check :twitter do
    _for "#eqnz", "#chch", "#quake"
  end
end

Actions

By default Herald will use Ruby's $stdout and simply prints what it finds.

Swap in another action by passing Herald one of the following action parameters:

Growl

Growl is a notification system for Mac OS X.

To use Growl, enable "Listen for incoming notifications" and "Allow remote application registration" on the Network tab of the Growl Preference Panel, and pass Herald action :growl

Herald.watch_twitter do
  _for "nz", "#election"
  action :growl
end

Ping

To ping a URI, pass Herald action :ping, :uri => "http://address.to.ping"

Herald.watch_twitter do
  _for "#fundamentalists", "#in", "#space"
  action :ping, :uri => "http://armageddon-clock.com/+1"
end

Post

To post information about what Herald finds to a URI, pass Herald action :post, :uri => "http://address.to.post.to"

Herald.watch_twitter do
  _for "vanity", "tweeting"
  action :post, :uri => "http://twitter-loves-me.com/post"
end

Callbacks

If you'd like to do your own thing entirely each time a keyword appears, pass a callback in the form of a Ruby block

Herald.watch_twitter do
  _for "revolution"
  action do
    `say "Viva!"`
  end
end

Pass the callback a parameter to be given a Herald::Item object within your block. The object makes available everything Herald could find in the source.

Herald.watch_twitter do
  _for "revolution"
  action do |item|
    puts item.data # full Hash of all data
  end
end

Timer

By default Herald will sleep for 1 minute after checking each of the sources independently. To set a different sleep time

Herald.watch_twitter do
  _for "soundofmusic"
  every 30 => "seconds" # or "minutes", "hours", or "days"
end

For inquisitive minds

Assign the herald watcher to a variable

herald = Herald.watch_rss :from => "http://www.reddit.com/r/pics/new/.rss" do
  _for "imgur"
end

Edit your herald instance while it's working

herald.watchers
herald.watchers.to_s # in English
herald.watchers.first.keywords << "cats"
herald.watchers.first.action { puts "callback" }

Stop and start the herald

herald.stop
herald.alive? # => false
herald.start

Start a second herald

herald_the_second = Herald.watch_twitter { _for "#herald" }

Use the Herald class methods to inspect and edit your heralds as a batch

Herald.heralds # prints all running heralds
Herald.stop # all heralds stopped
Herald.alive? # => false
Herald.start # all heralds restarted

Look once

Rather than watching, if you just want to get a single poll of keywords, use once(). All the same parameters as with watch() can be used (every will be ignored)

herald = Herald.once do
  check :twitter
  _for "#herald"
end

As with watching, Herald will fork a new process (or one for every source you're checking), but unlike with watching, Herald will block and wait for the process to finish

herald.start # waiting ... process ends at the same time you receive your notifications
herald.alive? # => false

A bit about callback scope and Herald metaprogramming

Callbacks allow a great deal of reflection into the internals of Herald.

If the callback is passed with the scope of Herald, it will have access to the Herald methods and instance variables

Herald.watch_twitter do
  _for "#breaking", "news"
  action do
    puts instance_variables
  end
end

If passed in within the scope of Herald::Watcher (action agents), it will have access to the particular Watcher's methods and instance variables

Herald.watch do
  check :twitter do
    _for "#breaking", "news"
    action do
      puts instance_variables
    end
  end
end

Herald binary [Not Implemented]

herald -watch twitter -for #eqnz
herald -once twitter -for #herald
herald -show-heralds
herald -modify 1 -watch rss -from http://example.com/.rss
herald -pause 1
herald -kill 1