herald 0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+.rvmrc
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in herald.gemspec
+gemspec

data/README.md

@@ -0,0 +1,201 @@
+Herald
+====
+
+Herald is a simple notifier for Twitter, RSS, or email. 
+
+Pass Herald some keywords and sources to watch, and Herald will notify you using Growl, email, pinging 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-<version>.gem
+
+Usage
+-----
+
+First step is `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 an email inbox: [Not Implemented]
+
+    Herald.watch do
+      check :inbox, :imap => "imap.server.com", :user => "username", :pass => "supersecret"
+      _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](http://growl.info/) 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](http://growl.info/documentation/exploring-preferences.php) 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 "#yaks", "#in", "#space"
+      action :ping, :uri => "http://counter.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 "#yaks", "#in", "#space"
+      action :post, :uri => "http://yakdb.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
+
+### 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
+        
+### 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 (except `every`).
+
+    Herald.once do
+      check :twitter
+      _for "#herald"
+    end
+    
+### 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`, 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
+
+### For inquisitive minds
+
+Assign the herald watcher to a variable
+
+    require 'herald'
+    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 herald
+
+    herald.stop
+    herald.alive? # => false
+    herald.start
+
+Start a second herald
+
+    herald_the_second = Herald.watch_twitter { _for "#herald" }
+
+Use `Herald` class methods to inspect and edit heralds as a batch
+
+    Herald.heralds # prints both running heralds
+    Herald.heralds.to_s # print in English
+    Herald.stop # both heralds stopped
+    Herald.alive? # => false
+    Herald.start # both heralds restarted
+
+### 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

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :test do
+  $LOAD_PATH.unshift './lib'
+  require 'herald'
+  require 'minitest/autorun'
+  Dir.glob("test/**/*_test.rb").each { |test| require "./#{test}" }
+end

data/TODO.txt

@@ -0,0 +1,12 @@
+- Catch and report on exceptions in @@subprocess, or thread, when exception has killed a @@subprocess, remove it from @@subprocess
+
+- Best way to require gems? Can I vendorise crack gem?
+
+- Suppress Growl text on test()
+
+- Comment in RDOC
+
+- Handle exceptions in processes, by reporting the error, then set the @subprocess to nil
+
+- Look at Gemspec
+  - Show dependency on ruby-growl if installed for mac

data/herald.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "herald/version"
+
+Gem::Specification.new do |s|
+  s.name        = "herald"
+  s.version     = Herald::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Luke Duncalfe"]
+  s.email       = ["lduncalfe@eml.cc"]
+  s.homepage    = "http://github.com/lukes/herald"
+  s.summary     = %q{A simple notifier for Twitter, RSS, or email}
+  s.description = %q{Pass Herald some keywords and sources to watch, and Herald will notify you using Growl, email, pinging a site, or running Ruby code as soon as those keywords appear}
+
+  s.required_rubygems_version = ">= 1.3.6" # TODO test earliest dependency
+  s.add_development_dependency "minitest"
+  s.add_dependency "crack"
+  s.rubyforge_project         = "herald"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+#  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/herald.rb

@@ -0,0 +1,178 @@
+require 'rubygems'
+#require 'json'
+gem 'crack'
+require 'crack'
+
+require 'herald/watcher'
+require 'herald/notifier'
+require 'herald/notifiers/stdout'
+require 'herald/item'
+
+class Herald
+
+  @@heralds = []
+  attr_accessor :watchers, :keep_alive, :subprocess
+
+  def self.watch(&block)
+    new(&block).start
+  end
+  
+  def self.once(&block)
+    herald = new()
+    herald.keep_alive = false
+    herald.send(:instance_eval, &block)
+    herald.start
+  end
+  
+  # shorthand methods
+  def self.watch_twitter(&block)
+    watch() { check(:twitter, &block) }
+  end
+  def self.watch_rss(options = {}, &block)
+    watch() { check(:rss, options, &block) }
+  end
+
+  # batch methods
+  def self.start
+    return false if @@heralds.empty?
+    @@heralds.each do |herald|
+      herald.start
+    end
+    true
+  end
+
+  def self.stop
+    return false unless Herald.alive?
+    @@heralds.each do |herald|
+      herald.stop
+    end
+    true
+  end
+  
+  # stop all heralds, and remove them
+  # from list of herald instances. mostly
+  # useful for clearing @@heralds when testing
+  def self.clear
+    stop()
+    @@heralds.clear
+    true
+  end
+  
+  # just walk away, leaving whatever strays to themselves
+  def self.demonize!
+    @@heralds.clear
+    true
+  end
+    
+  def self.alive?
+    @@heralds.any? { |h| h.alive? }
+  end
+  
+  def self.heralds
+    @@heralds
+  end
+  
+  #
+  # instance methods:
+  #
+  
+  def initialize(&block)
+    @watchers = []
+    @keep_alive = true
+    if block_given?
+      instance_eval(&block)
+    end
+    @@heralds << self
+    self
+  end
+  
+  # create a new Watcher
+  def check(type, options = {}, &block)
+    @watchers << Herald::Watcher.new(type, @keep_alive, options, &block)
+  end
+
+  # send keywords to Watchers
+  def _for(*keywords)
+    @watchers.each do |watcher|
+      watcher._for(*keywords)
+    end
+  end
+
+  # send instructions to Watchers
+  def action(type = nil, options = {}, &block)
+    @watchers.each do |watcher|
+      watcher.action(type, options, &block)
+    end
+  end
+    
+  # send sleep time to Watchers
+  def every(time)
+    @watchers.each do |watcher|
+      watcher.every(time)
+    end
+  end
+  
+  # start Watchers
+  def start
+    if @watchers.empty?
+      raise "No watchers assigned"
+    end
+    # if herald is already running, first stop
+    stop() if alive?
+    # start watching as a @subprocess
+    @subprocess = fork {
+      @watchers.each do |watcher|
+        watcher.start
+      end
+      # all watchers do their tasks in a new thread.
+      # join all thread in this @subprocess
+      Thread.list.each do |thread| 
+        thread.join unless thread == Thread.main
+      end
+    }
+    # if herald process is persistant
+    if @keep_alive
+      Process.detach(@subprocess)
+    else
+      # wait before the end of this script
+      # for all watchers to finish their jobs
+      Process.waitpid(@subprocess)
+    end
+    self # return instance object
+  end
+
+  # is there a gentler way of doing it?
+  # or have watchers do cleanup tasks on exit?
+  # look at GOD
+  def stop
+    Process.kill("TERM", @subprocess) if @subprocess
+    @subprocess = nil
+    self
+  end
+  alias :end :stop
+  alias :kill :stop
+  
+  def alive?
+    !!@subprocess
+  end
+  
+  def to_s
+    "#{alive? ? 'Alive' : 'Stopped'}Alive"
+  end
+    
+private
+  
+  def self.lazy_load_module(module_path)
+    lazy_load("herald/#{module_path}")
+  end
+
+  def self.lazy_load(path)
+    require(path)
+  end
+
+end
+
+# queue a block to always stop all forked processes on exit
+at_exit do
+  Herald.stop 
+end

data/lib/herald/item.rb

@@ -0,0 +1,13 @@
+class Herald
+  class Item
+    
+    attr_accessor :title, :message, :data
+    
+    def initialize(title, message, data)
+      @title = title
+      @message = message
+      @data = data
+    end
+
+  end
+end

data/lib/herald/notifier.rb

@@ -0,0 +1,33 @@
+class Herald
+  class Watcher
+    
+    class Notifier
+    
+      # TODO, make this dynamic? to allow people to write
+      # their own and drop it into notifiers dir
+      @@notifier_types = [:callback, :growl, :ping, :post, :stdout]
+      DEFAULT_NOTIFIER = :stdout
+    
+      def initialize(type, options, &block)
+        type = type.to_sym
+        # check notifier type
+        unless @@notifier_types.include?(type)
+          raise ArgumentError, "#{type} is not a valid Notifier type"
+        end
+        Herald::lazy_load_module("notifiers/#{type}")
+        # extend class with module
+        send(:extend, eval(type.to_s.capitalize))
+        # each individual Notifier will handle their options
+        parse_options(options)
+        # if callback given
+        if block_given?
+          @proc = block
+        end
+        # call test() method of Notifier module
+        test()
+      end
+    
+    end
+
+  end
+end

data/lib/herald/notifiers/callback.rb

@@ -0,0 +1,24 @@
+class Herald
+  class Watcher
+    class Notifier
+
+      module Callback
+
+        attr_reader :proc
+
+        # no options for Callback
+        def parse_options(options); end
+        
+        # we can't sandbox the proc to test it out,
+        # so just return true
+        def test; true; end
+
+        def notify(item)
+          @proc.call
+        end
+
+      end
+
+    end
+  end  
+end

data/lib/herald/notifiers/growl.rb

@@ -0,0 +1,37 @@
+class Herald
+  class Watcher
+    class Notifier
+
+      module Growl
+
+        # no options to parse for Growl
+        def parse_options(options); end
+        
+        # test growl on system and throw exception if fail.
+        def test
+          # TODO suppress output
+          unless(system("growl --version"))
+            # TODO throw custom exception
+            raise "ruby-growl gem is not installed. Run:\n\tsudo gem install ruby-growl"
+          end
+        end
+
+        # send a Growl notification
+        def notify(item)
+          # response will be false if system() call exits with an error.
+          # presence of ruby-growl has already been tested in test(), so a false
+          # return is likely to be the user's Growl settings
+          # TODO escape characters in title and message
+          item.title.gsub!("'", '')
+          item.message.gsub!("'", '')
+          if !system("growl -H localhost -t '#{item.title}' -m '#{item.message}'")
+            # TODO throw custom exception
+            raise "Growl settings not configured to allow remote application registration. See Growl website docs: http://growl.info/documentation/exploring-preferences.php"
+          end
+        end
+
+      end
+
+    end
+  end  
+end

data/lib/herald/notifiers/ping.rb

@@ -0,0 +1,46 @@
+class Herald
+  class Watcher
+    class Notifier
+
+      module Ping
+
+        attr_reader :uri
+
+        # lazy-load net/http when this Module is used
+        def self.extended(base)
+          Herald.lazy_load('net/http')
+        end
+
+        # note: dupe between ping and post
+        def parse_options(options)
+          begin
+            @uri = URI.parse(options.delete(:uri) || options.delete(:url))
+            # if URI lib can't resolve a protocol (because it was missing from string)
+            if @uri.class == URI::Generic
+              @uri = URI.parse("http://#{@uri.path}")
+            end
+          rescue URI::InvalidURIError
+            raise ArgumentError, ":uri for :ping action not specified or invalid"
+          end
+        end
+        
+        def test
+          response = Net::HTTP.new(@uri.host).head('/')
+          return if response.kind_of?(Net::HTTPOK)
+          # TODO raise custom error types
+          if response.kind_of?(Net::HTTPFound)
+            raise "URI #{@uri} is being redirected to #{response.header['location']}"
+          else
+            raise "URI #{@uri} cannot be reached. Ping returned status code: #{response.code}"
+          end
+        end
+
+        def notify(item)
+          Net::HTTP.new(@uri.host).head('/')
+        end
+
+      end
+
+    end
+  end  
+end

data/lib/herald/notifiers/post.rb

@@ -0,0 +1,47 @@
+class Herald
+  class Watcher
+    class Notifier
+
+      # note most of this code is duplicated between ping and post
+      module Post
+
+        attr_reader :uri
+
+        # lazy-load net/http when this Module is used
+        def self.extended(base)
+          Herald.lazy_load('net/http')
+        end
+
+        def parse_options(options)
+          begin
+            @uri = URI.parse(options.delete(:uri) || options.delete(:url))
+            # if URI lib can't resolve a protocol (because it was missing from string)
+            if @uri.class == URI::Generic
+              @uri = URI.parse("http://#{@uri.path}")
+            end
+          rescue URI::InvalidURIError
+            raise ArgumentError, ":uri for :ping action not specified or invalid"
+          end
+        end
+
+        # test by pinging to URI throw exception if fail
+        def test
+          response = Net::HTTP.new(@uri.host).head('/')
+          return if response.kind_of?(Net::HTTPOK)
+          # TODO raise custom error types
+          if response.kind_of?(Net::HTTPFound)
+            raise "URI #{@uri} is being redirected to #{response.header['location']}"
+          else
+            raise "URI #{@uri} cannot be reached. Ping returned status code: #{response.code}"
+          end
+        end
+
+        def notify(item)
+          Net::HTTP.post_form(@uri.to_s, { "title" => item.title, "message" => item.message })
+        end
+
+      end
+
+    end
+  end  
+end

data/lib/herald/notifiers/stdout.rb

@@ -0,0 +1,27 @@
+class Herald
+  class Watcher
+    class Notifier
+
+      module Stdout
+
+        def parse_options(options)
+          # option to send stdout to file
+          if file = options.delete(:file)
+            $stdout = File.new(file, 'w')
+          end
+        end
+        
+        # is always working, so true
+        def test; true; end
+
+        # print to $stdout
+        def notify(item)
+          $stdout.puts item.data.inspect
+          $stdout.flush
+        end
+
+      end
+
+    end
+  end  
+end

data/lib/herald/version.rb

@@ -0,0 +1,3 @@
+class Herald
+  VERSION = "0.1"
+end

data/lib/herald/watcher.rb

@@ -0,0 +1,99 @@
+class Herald
+  
+  class Watcher
+    
+    @@watcher_types = [:rss, :twitter] # :imap
+    DEFAULT_TIMER = 60
+
+    attr_reader :type, :keep_alive, :thread, :items
+    attr_accessor :notifiers, :keywords, :timer
+    
+    def initialize(type, keep_alive, options, &block)
+      @type = type.to_sym
+      # TODO this is prepared to handle other protocols, but might not be necessary
+#      if @type == :inbox
+#        if options.key?(:imap)
+#          @type = :imap
+#          options[:host] = options[:imap]
+#        end
+#      end
+      # check watcher type
+      unless @@watcher_types.include?(@type)
+        raise ArgumentError, "#{@type} is not a valid Watcher type"
+      end
+      @keep_alive = keep_alive
+      @keywords = []
+      @notifiers = []
+      @items = []
+      @timer = Watcher::DEFAULT_TIMER
+      Herald.lazy_load_module("watchers/#{@type}")
+      # extend class with module
+      send(:extend, eval(@type.to_s.capitalize))
+      # each individual Watcher will handle their options
+      parse_options(options)
+      # eval the block, if given
+      if block_given?
+        instance_eval(&block)
+      end
+      # TODO implement a Watcher::test()?
+    end
+    
+    def _for(*keywords)
+      @keywords += keywords.flatten
+    end
+    
+    # assign the Notifier
+    def action(type = :callback, options = {}, &block)
+      @notifiers << Herald::Watcher::Notifier.new(type, options, &block)
+    end
+    
+    # parse a hash like { 120 => "seconds" }
+    def every(time); 
+      quantity = time.keys.first.to_i
+      unit = case time.values.first
+      when /^second/
+        1
+      when /^minute/
+        60
+      when /^hour/
+        3600
+      when /^day/
+        86400
+      else
+        raise ArgumentError, "Invalid time unit for every. (Use seconds, minutes, hours or days)"
+      end
+      @timer = quantity * unit
+    end
+    
+    # call the Notifier and pass it a message
+    def notify(item)
+      @notifiers.each do |notifier|
+        notifier.notify(item)
+      end
+    end
+    
+    def start
+      # set a default Notifier for this Watcher
+      action(Watcher::Notifier::DEFAULT_NOTIFIER) if @notifiers.empty?
+      # prepare() is defined in the individual Watcher modules.
+      # any pre-tasks are performed before
+      prepare()
+      # begin loop, which will execute at least once (like a do-while loop)
+      @thread = Thread.new {
+        begin
+          activities
+          sleep @timer if @keep_alive
+        end while @keep_alive
+      }
+    end
+        
+    def stop
+      # stop looping
+      @keep_alive = false
+      # cleanup() is defined in the individual Watcher modules
+      cleanup()
+    end
+    
+  end
+  
+end

data/lib/herald/watchers/imap.rb

@@ -0,0 +1,55 @@
+class Herald  
+  class Watcher
+
+    module Imap
+
+      attr_accessor :user, :pass, :host, :mailbox, :last_uid
+
+      # lazy-load net/imap when this Module is used
+      def self.extended(base)
+        Herald.lazy_load('net/imap')
+        Herald.lazy_load('date')
+      end
+
+      def parse_options(options)
+        @user = options.delete(:user)
+        @pass = options.delete(:pass)
+        @host = options.delete(:host)
+        @mailbox = options.delete(:mailbox) || "INBOX"
+        @mailbox.upcase!
+        # start looking a week ago unless option given
+        @start_date = options.delete(:start_date) || (Date.today - 7).strftime("%d-%b-%Y")
+      end
+
+      def prepare; end
+      def cleanup; end
+      
+      def to_s
+        "Herald IMAP Watcher, Host: #{@host}, Keywords: '#{@keywords}', Timer: #{@timer}, State: #{@keep_alive ? 'Watching' : 'Stopped'}"
+      end
+      
+    private
+
+      def activities
+        puts "u: #{@user}"
+        puts "p: #{@pass}"
+        puts "h: #{@host}"
+        imap = Net::IMAP.new(@host)
+        imap.login("LOGIN", @user, @pass)
+        imap.select(@mailbox)
+        @last_look = Time.now
+        # if we have the id of the last email looked at
+        if @last_uid
+          search_result = imap.search(["BODY", @keywords, "SINCE", @start_date])
+        else
+          search_result = imap.search(["BODY", @keywords, "SINCE", @start_date])
+        end  
+        puts search_result.inspect
+        imap.logout
+        imap.disconnect
+      end
+
+    end
+
+  end
+end

data/lib/herald/watchers/rss.rb

@@ -0,0 +1,64 @@
+class Herald
+  class Watcher
+
+    module Rss
+
+      attr_accessor :uris
+      
+      # lazy-load open-uri when this Module is used
+      def self.extended(base)
+        Herald.lazy_load('open-uri')
+      end
+      
+      def parse_options(options)
+        @uris = Array(options.delete(:from))
+        if @uris.empty?
+          raise ArgumentError, "RSS source not specified in :from Hash"
+        end
+      end
+
+      def prepare; end
+      def cleanup; end
+      
+      def to_s
+        "Herald RSS Watcher, URL: #{@uris}, Keywords: '#{@keywords}', Timer: #{@timer}, State: #{@keep_alive ? 'Watching' : 'Stopped'}"
+      end
+            
+    private
+    
+      def activities
+        @uris.each do |uri|
+          # return response as string and parse to RSS
+          begin
+            rss = Crack::XML.parse(open(uri).read)
+          rescue
+            return
+          end
+          # skip if rss variable is nil, or is missing
+          # rss elements in the expected nested format
+          next unless defined?(rss["rss"]["channel"]["item"])
+          # ignore items that have been part of a notification round
+          # or that don't contain the keywords being looked for
+          items = []
+          rss["rss"]["channel"]["item"].each do |item|
+            # if we've already seen this item, skip to next item
+            if @items.include?(item)
+              next
+            end
+            # keep this item if it contains keywords in the title or description
+            if "#{item["title"]}#{item["description"]}".match(/#{@keywords.join('|')}/i)
+              items << item
+            end
+          end
+          return if items.empty?
+          items.each do |item|
+            notify(Item.new(item["title"], item["description"], item))
+          end
+          @items += items
+        end
+      end
+
+    end
+
+  end
+end

data/lib/herald/watchers/twitter.rb

@@ -0,0 +1,54 @@
+class Herald  
+  class Watcher
+
+    # TODO, ignore retweets, if option passed
+    module Twitter
+
+      attr_accessor :uri, :last_tweet_id
+      TWITTER_API = "http://search.twitter.com/search.json"
+      
+      # lazy-load open-uri when this Module is used
+      def self.extended(base)
+        Herald.lazy_load('open-uri')
+      end
+
+      def parse_options(options); end
+      
+      # executed before Watcher starts
+      def prepare
+        # twitter doesn't allow you to query its api without
+        # providing a query string
+        if @keywords.empty?
+          raise ArgumentError, "Keywords are missing"
+        end
+        # initialise array, first element will be the Twitter API with search query string, 
+        # the second element will be a "since_id" extra query parameter, added at close of 
+        # activities() loop
+        @uri = ["#{TWITTER_API}?q=#{@keywords.join('+')}"]
+      end
+
+      def cleanup; end
+      
+      def to_s
+        "Herald Twitter Watcher, Keywords: '#{@keywords}', Timer: #{@timer}, State: #{@keep_alive ? 'Watching' : 'Stopped'}"
+      end
+      
+    private
+
+      def activities
+        # return response as string from Twitter and parse it to JSON
+        json = Crack::JSON.parse(open(@uri.join("&")).read)
+        # will be nil if there are no results
+        return if json["results"].nil?
+        @last_tweet_id = json["max_id"]
+        json["results"].each do |tweet|
+          @items << tweet
+          notify(Item.new("@#{tweet['from_user']}", tweet['text'], json['results']))
+        end
+        @uri = [@uri.first, "since_id=#{@last_tweet_id}"]
+      end
+
+    end
+
+  end
+end

data/test/herald_test.rb

@@ -0,0 +1,110 @@
+# start tests by 'rake test' on root path
+
+describe Herald do
+  before do
+    @herald = Herald.watch { check :twitter; _for "test" }
+  end
+  
+  after do
+    Herald.clear
+  end
+  
+  describe "initialisation with watchers" do
+    it "must throw an acception if no 'check' param is given" do
+      assert_raises(RuntimeError) do
+        Herald.watch {}
+      end
+    end
+    it "must assign a watcher" do
+      @herald.watchers.size.must_equal(1)
+    end
+    it "must allow assigning multiple watchers" do
+      herald = Herald.watch { check :rss, :from => "http://example.com"; check :twitter; _for "test" }
+      herald.watchers.size.must_equal(2)
+    end
+  end
+
+  describe "initialisation of twitter watcher" do
+    it "must throw an error if no keywords are given" do
+      skip("Test not working")
+      assert_raises(ArgumentError) do
+        Herald.watch { check :twitter }
+      end
+    end
+    it "must assign a twitter watcher" do
+      @herald.watchers.first.type.must_equal(:twitter)
+    end
+  end
+  
+  describe "initialisation of rss watcher" do
+    it "must throw an error if no rss url is given" do
+      assert_raises(ArgumentError) do
+        Herald.watch { check :rss }
+      end
+    end
+    it "must assign an rss watcher" do
+      herald = Herald.watch { check :rss, :from => "http://example.com" }
+      herald.watchers.first.type.must_equal(:rss)
+    end
+  end
+  
+  describe "initialisation with keywords" do
+    it "must assign keyword when passed as a string" do
+      @herald.watchers.first.keywords.must_be_kind_of(Array)
+      @herald.watchers.first.keywords.size.must_equal(1)
+      @herald.watchers.first.keywords.to_s.must_equal("test")
+    end
+    it "must slurp keywords when passed as a multiargument strings" do
+      keywords = ["test1", "test2"]
+      herald = Herald.watch { check :twitter; _for *keywords }
+      herald.watchers.first.keywords.size.must_equal(2)
+      herald.watchers.first.keywords.to_s.must_equal(keywords.to_s)
+    end
+    it "must assign keywords when passed as an array" do
+      keywords = ["test1", "test2"]
+      herald = Herald.watch { check :twitter; _for keywords }
+      herald.watchers.first.keywords.size.must_equal(2)
+      herald.watchers.first.keywords.to_s.must_equal(keywords.to_s)
+    end
+  end
+
+  describe "initialisation with actions" do
+    it "should assign stdout as the default Notifier" do
+      skip("@notifiers appears as empty, possible due to threading?")
+      @herald.watchers.first.notifiers.size.must_equal(1)
+    end
+  end
+  
+  describe "Herald class methods (stop, start, alive?) must allow batch operations" do
+    it "must return array of running heralds" do
+      Herald.heralds.must_be_kind_of(Array)
+      Herald.heralds.size.must_equal(1)
+      Herald.heralds.first.must_be_kind_of(Herald)
+      herald_2 = Herald.watch { check :twitter; _for "test" }
+      Herald.heralds.size.must_equal(2)
+    end
+    it "must report on if there are any heralds alive" do
+      Herald.alive?.must_equal(true)
+    end
+    it "must allow heralds to be stopped" do
+      Herald.stop.must_equal(true)
+    end
+    it "alive? must report false if heralds exist, but none are running" do
+      Herald.stop
+      Herald.heralds.size.must_equal(1)
+      Herald.alive?.must_equal(false)
+    end
+    it "must report false if heralds are told to stop, and no herald are alive" do
+      Herald.stop
+      Herald.stop.must_equal(false)
+    end
+    it "must allow heralds to be restarted" do
+      Herald.stop
+      Herald.start
+      Herald.alive?.must_equal(true)
+    end
+    
+  end
+
+  
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: herald
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- Luke Duncalfe
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-14 00:00:00 +12:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: crack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+description: Pass Herald some keywords and sources to watch, and Herald will notify you using Growl, email, pinging a site, or running Ruby code as soon as those keywords appear
+email: 
+- lduncalfe@eml.cc
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- TODO.txt
+- herald.gemspec
+- lib/herald.rb
+- lib/herald/item.rb
+- lib/herald/notifier.rb
+- lib/herald/notifiers/callback.rb
+- lib/herald/notifiers/growl.rb
+- lib/herald/notifiers/ping.rb
+- lib/herald/notifiers/post.rb
+- lib/herald/notifiers/stdout.rb
+- lib/herald/version.rb
+- lib/herald/watcher.rb
+- lib/herald/watchers/imap.rb
+- lib/herald/watchers/rss.rb
+- lib/herald/watchers/twitter.rb
+- test/herald_test.rb
+has_rdoc: true
+homepage: http://github.com/lukes/herald
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: herald
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: A simple notifier for Twitter, RSS, or email
+test_files: 
+- test/herald_test.rb