herald 0.1 → 0.2

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2011 Luke Duncalfe
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,9 +1,9 @@
 Herald
 ====
 
-Herald is a simple notifier for Twitter, RSS, or email. 
+Herald is a simple notifier for Twitter and RSS.
 
-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.
+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
 ------------
@@ -16,34 +16,34 @@ Installation
 
     git clone git://github.com/lukes/herald.git
     gem build herald.gemspec
-    gem install herald-<version>.gem
+    gem install herald-0.2.gem
 
 Usage
 -----
 
-First step is `require` Herald into your Ruby project:
+First step is to `require` Herald into your Ruby project
 
     require 'rubygems'
     require 'herald'
 
-Then, to watch for tweets containing "soundofmusic":
+Then, to watch for tweets containing "soundofmusic"
 
     Herald.watch do
       check :twitter
       _for "soundofmusic"
     end
 
-Or an RSS feed:
+Or an RSS feed
 
     Herald.watch do
       check :rss, :from => "http://example.com/.rss"
       _for "soundofmusic"
     end
-
-Or an email inbox: [Not Implemented]
+    
+Or text in a website
 
     Herald.watch do
-      check :inbox, :imap => "imap.server.com", :user => "username", :pass => "supersecret"
+      check :website, :from => "http://example.com"
       _for "soundofmusic"
     end
 
@@ -78,7 +78,7 @@ Swap in another action by passing Herald one of the following `action` parameter
 
 [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`:
+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"
@@ -87,25 +87,25 @@ To use Growl, enable "Listen for incoming notifications" and "Allow remote appli
 
 #### Ping
 
-To ping a URI, pass Herald `action :ping, :uri => "http://address.to.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"
+      _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"`:
+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"
+      _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:
+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"
@@ -113,55 +113,31 @@ If you'd like to do your own thing entirely each time a keyword appears, pass a
         `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:
+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 "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"
+      _for "revolution"
+      action do |item|
+        puts item.data # full Hash of all data
+      end
     end
-    
-### Callback Scope and Herald Metaprogramming
 
-Callbacks allow a great deal of reflection into the internals of Herald.
+### Timer
 
-If the callback is passed with the scope of `Herald`, it will have access to the `Herald` methods and instance variables:
+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 "#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
+      _for "soundofmusic"
+      every 30 => "seconds" # or "minutes", "hours", or "days"
     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
@@ -173,7 +149,7 @@ Edit your herald instance while it's working
     herald.watchers.first.keywords << "cats"
     herald.watchers.first.action { puts "callback" }
 
-Stop and start herald
+Stop and start the herald
 
     herald.stop
     herald.alive? # => false
@@ -183,15 +159,52 @@ Start a second herald
 
     herald_the_second = Herald.watch_twitter { _for "#herald" }
 
-Use `Herald` class methods to inspect and edit heralds as a batch
+Use the `Herald` class methods to inspect and edit your heralds as a batch
 
-    Herald.heralds # prints both running heralds
-    Herald.heralds.to_s # print in English
-    Herald.stop # both heralds stopped
+    Herald.heralds # prints all running heralds
+    Herald.stop # all heralds stopped
     Herald.alive? # => false
-    Herald.start # both heralds restarted
+    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 `check`ing), 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 binary [Not Implemented]
 
     herald -watch twitter -for #eqnz
     herald -once twitter -for #herald

data/Rakefile

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

data/TODO.txt

@@ -2,11 +2,13 @@
 
 - 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
+  - Show dependency on ruby-growl if installed for mac
+  
+- Growl icon
+
+- Custom Error classes

data/herald.gemspec

@@ -10,15 +10,25 @@ Gem::Specification.new do |s|
   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.description = %q{A simple and flexible notifier for Twitter, RSS, or email}
 
-  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.required_rubygems_version = ">= 1.3.6" # TODO test earliest dependency
+  s.add_development_dependency("minitest")
+  s.add_dependency("crack")
+  s.add_dependency("hpricot", "~> 0.8")
+  # if gem is being installed on a mac, add a dependency on ruby-growl.
+  # note, this is not a fool-proof method of detecting the OS,
+  # apparently if return "java" if platform is JRuby
+  if RUBY_PLATFORM.downcase.include?("darwin")
+    s.add_dependency("ruby-growl", "~> 3.0")
+  end
+
+  s.rubyforge_project = "herald"
+  s.extra_rdoc_files = ["README.md", "LICENSE"]
 
   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.default_executable = "herald"
   s.require_paths = ["lib"]
 end

data/lib/herald.rb

@@ -1,7 +1,4 @@
 require 'rubygems'
-#require 'json'
-gem 'crack'
-require 'crack'
 
 require 'herald/watcher'
 require 'herald/notifier'
@@ -11,6 +8,7 @@ require 'herald/item'
 class Herald
 
   @@heralds = []
+  
   attr_accessor :watchers, :keep_alive, :subprocess
 
   def self.watch(&block)
@@ -31,6 +29,9 @@ class Herald
   def self.watch_rss(options = {}, &block)
     watch() { check(:rss, options, &block) }
   end
+  def self.watch_website(options = {}, &block)
+    watch() { check(:website, options, &block) }
+  end
 
   # batch methods
   def self.start
@@ -88,7 +89,9 @@ class Herald
   
   # create a new Watcher
   def check(type, options = {}, &block)
-    @watchers << Herald::Watcher.new(type, @keep_alive, options, &block)
+    options[:keep_alive] ||= @keep_alive
+    @watchers << Herald::Watcher.new(type, options, &block)
+    self
   end
 
   # send keywords to Watchers
@@ -96,6 +99,7 @@ class Herald
     @watchers.each do |watcher|
       watcher._for(*keywords)
     end
+    self
   end
 
   # send instructions to Watchers
@@ -103,6 +107,7 @@ class Herald
     @watchers.each do |watcher|
       watcher.action(type, options, &block)
     end
+    self
   end
     
   # send sleep time to Watchers
@@ -110,6 +115,7 @@ class Herald
     @watchers.each do |watcher|
       watcher.every(time)
     end
+    self
   end
   
   # start Watchers
@@ -134,9 +140,18 @@ class Herald
     if @keep_alive
       Process.detach(@subprocess)
     else
-      # wait before the end of this script
-      # for all watchers to finish their jobs
-      Process.waitpid(@subprocess)
+      begin
+        # wait before the end of this script
+        # for all watchers to finish their jobs
+        Process.waitpid(@subprocess)
+      # if @subprocess PID does not exist, it will
+      # be due to an error in the subprocess
+      # which has terminated it and waitpid()
+      # will throw an exception
+      rescue Errno::ECHILD => e
+        # do nothing
+      end
+      @subprocess = nil # signal unalive state
     end
     self # return instance object
   end
@@ -145,7 +160,16 @@ class Herald
   # or have watchers do cleanup tasks on exit?
   # look at GOD
   def stop
-    Process.kill("TERM", @subprocess) if @subprocess
+    if @subprocess
+      begin
+        Process.kill("TERM", @subprocess)
+      # if @subprocess PID does not exist, 
+      # this will be due to an error in the subprocess
+      # which has terminated it
+      rescue Errno::ESRCH => e
+        # do nothing
+      end
+    end
     @subprocess = nil
     self
   end
@@ -155,10 +179,6 @@ class Herald
   def alive?
     !!@subprocess
   end
-  
-  def to_s
-    "#{alive? ? 'Alive' : 'Stopped'}Alive"
-  end
     
 private
   

data/lib/herald/notifiers/callback.rb

@@ -14,7 +14,11 @@ class Herald
         def test; true; end
 
         def notify(item)
-          @proc.call
+          if @proc.arity == 1
+            @proc.call(item)
+          else
+            @proc.call
+          end
         end
 
       end

data/lib/herald/notifiers/growl.rb

@@ -4,27 +4,31 @@ class Herald
 
       module Growl
 
-        # no options to parse for Growl
-        def parse_options(options); end
+        @@notification_type = "Herald Notification"
         
-        # 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"
+        def self.extended(base)
+          Herald.lazy_load('ruby-growl')
+          class << base
+            attr_accessor :growl, :sticky
           end
         end
 
+        def parse_options(options)
+          @sticky = options.delete(:sticky) || false
+          @priority = options.delete(:priority) || 1
+          host = options.delete(:host) || "localhost"
+          pass = options.delete(:pass) || nil
+          @growl = ::Growl.new(host, "Herald", [@@notification_type], [@@notification_type], pass)
+        end
+
+        # no tests for Growl
+        def test; 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}'")
+          begin
+            @growl.notify(@@notification_type, item.title, item.message, @priority, @sticky)
+          rescue Errno::ECONNREFUSED => e
             # 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