dock_driver 0.1.0 → 0.1.1

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.1.1 / 2012-05-20
+
+* 2 minor enhancements
+  * logging
+  * bug fixes
+
 === 0.1.0 / 2012-05-15
 
 * 3 minor enhancements

data/Ideas.txt

@@ -4,7 +4,6 @@
 
 * Graphing
 * Automatic Coloring (with definable syntax)
-* Logging
 
 == With Dependencies
 

data/Manifest.txt

@@ -8,7 +8,7 @@ Rakefile
 bin/dock_driver
 data/example.dock_driver.yml
 lib/dock_driver.rb
-lib/dock_driver/laika_hashutils.rb
+lib/dock_driver/hashutils.rb
 lib/dock_driver/poll.rb
 lib/dock_driver/data_rate_poll.rb
 lib/dock_driver/dock.rb

data/README.txt

@@ -16,28 +16,42 @@ started. It's located in this gem's data directory, which is usually:
 === Features:
 
 * easy, flexible configuration
+* sholud the configuration change, the dock will be automatically restarted
 * field extraction with +scan_regex+ (no grep or pipes necessary)
+* automatic running average of data rates
+
+See 'Ideas' for more info on what's planned for the future.
 
 === Problems:
 
 * undiscovered bugs
-* unwritten test cases
+* more RSpec examples needed
 * cleanup
 
 == SYNOPSIS:
 
 There really isn't an API or interface other than the YAML config file.
 
+See the +--help+ option for more information on how to use the
++dock_config+ binary.
+
 == REQUIREMENTS:
 
-* This gem proudly has zero dependencies besides ruby and rubygems.
+* This gem proudly has zero dependencies.
 
 == INSTALL:
 
-* sudo gem install dock_driver
-* copy <gemdir>/etc/example.dock_driver.yml to ~/.dock_driver.yml
-* edit ~/.dock_driver.yml to taste
-* run dock_driver from your xsession or ~/.i3/config file. 
+	sudo gem install dock_driver
+
+After that you might want to copy +example.dock_driver.yml+ from the
+gem's data directory to ~/.dock_driver.yml and edit it to taste. You can
+test your config by running +dock_driver+ directly without arguments.
+
+Finally, you'll probably want run dock_driver from your .xsession or
+~/.i3/config file. See the documentation for either on how to do that.
+
+You'll find a log file called ~/.dock_driver.log that can give you
+more information should something go horribly wrong.
 
 == DEVELOPERS:
 
@@ -50,25 +64,68 @@ and generate the RDoc.
 
 == LICENSE:
 
-(The MIT License)
+(The BSD 2-Clause License)
+
+Copyright (c) 2012, Michael B. Hix
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+This software includes one or more mixins under the following license:
+
+	Copyright (c) 2008-2011, Michael Granger and Mahlon E. Smith
+	All rights reserved.
+
+	Redistribution and use in source and binary forms, with or without
+	modification, are permitted provided that the following conditions are met:
+
+	* Redistributions of source code must retain the above copyright notice,
+	  this list of conditions and the following disclaimer.
+
+	* Redistributions in binary form must reproduce the above copyright notice,
+	  this list of conditions and the following disclaimer in the documentation
+	  and/or other materials provided with the distribution.
+
+	* Neither the name of the author/s, nor the names of the project's
+	  contributors may be used to endorse or promote products derived from this
+	  software without specific prior written permission.
 
-Copyright (c) 2012 Michael Hix
+	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+	DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+	FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+	DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+	SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+	CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+	OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+	OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-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:
+=== Authors
 
-The above copyright notice and this permission notice shall be included
-in all copies or substantial portions of the Software.
+* Michael Hix <mike@musl.org>
 
-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/bin/dock_driver

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+#
 
 require 'optparse'
 require 'dock_driver/dock'
@@ -11,11 +14,31 @@ parser = OptionParser.new do |p|
 	p.on(
 		'-c',
 		'--conf FILE',
-		'Specify an alternate config file. (Default: ~/.dock_driver.yml)'
+		"Specify an alternate config file. (Default: #{DockDriver::Dock::DEFAULT_CONFIG_FILE})"
 	) do |file|
+		unless File.exists? file
+			$stderr.puts "That config file doesn't exist." % file
+			$stderr.puts
+			$stderr.puts p
+			exit
+		end
 		opts[:conf] = file
 	end
 
+	p.on(
+		'-l',
+		'--log FILE',
+		"Specify an alternate log file. (Default: #{DockDriver::Dock::DEFAULT_LOG_FILE})"
+	) do |log|
+		if File.exists? log
+			$stderr.puts "That log file exists, and I'm cowardly refusing to overwrite it." % log
+			$stderr.puts
+			$stderr.puts p
+			exit
+		end
+		opts[:log] = log
+	end
+
 	p.on(
 		'-d',
 		'--dock COMMAND',
@@ -28,29 +51,39 @@ parser = OptionParser.new do |p|
 
 	p.on( '-h', '--help', 'Print this help text.' ) do
 		cmd = File.basename( $0 )
-		puts "\n%s\n%s\n\nVersion: %s\n%s\n\n" % [
+		$stderr.puts "\n%s\n%s\n\nVersion: %s\n%s\n\n" % [
 			cmd,
 			'=' * cmd.length,
 			DockDriver::VERSION,
 			DockDriver::REVISION,
 		]
-		puts p
-		puts "\nAuthors:\n\t%s\n\n" % [
+		$stderr.puts p
+		$stderr.puts "\nAuthors:\n\t%s\n\n" % [
 			DockDriver::AUTHORS.join( '\n\t' ),
 		]
 		exit
 	end
 
-end.parse!
+end
+
+# Handle invalid options.
+#
+begin
+	parser.parse!
+rescue => e
+	$stderr.puts "\n%s\n\n%s\n" % [e, parser]
+	exit
+end
 
-puts "Options: %p" % opts if $DEBUG
+$stderr.puts "Options: %p" % opts if $DEBUG
 
-dock = DockDriver::Dock.new( opts[:conf], opts[:dock] )
+dock = DockDriver::Dock.new( opts[:conf], opts[:log], opts[:dock] )
 
+# Respond to ^C.
+#
 trap 'INT' do
-	dock.kill
-	puts "\nKilled!" if $DEBUG
+	dock.stop
 end
 
-dock.run
+dock.start
 

data/data/example.dock_driver.yml

@@ -19,62 +19,129 @@ time_format:
 # Processed by +ERB+. +Poll+ objects as defined by the 'commands' section are
 # available. Since +Poll+ objects respond to to_s intelligently, it's usually
 # sufficient to just specify the object name. Since they're also subclasses of
-# +OpenStruct+, you can also reference any method or member here.
+# +OpenStruct+, you can also use any attribute defined on the poll here too.
 #
 # See the dzen2 documentation.
 #
 template:
-    ^fg(white)rx ^fg(gray60)<%= eth0_rx %> ^fg(gray30)<%= eth0_rx.unit %> ·
-    ^fg(white)tx ^fg(gray60)<%= eth0_tx %> ^fg(gray30)<%= eth0_tx.unit %> ·
-    ^fg(white)cpu0 ^fg(gray60)<%= cpu0_temp %>^fg(gray30) C ·
-    ^fg(white)cpu1 ^fg(gray60)<%= cpu1_temp %>^fg(gray30) C ·
-    ^fg(white)gpu ^fg(gray60)<%= gpu_temp %>^fg(gray30) C ·
-    ^fg(white)mail <%= mail %>^fg(gray30) ·
-    ^fg(gray60)<%= time %>^fg(gray30) ·
+    <%= time %>
+    <%= load %>
+    ^fg(white)eth0
+    <%= eth0_rx %>^fg(gray30) <%= eth0_tx %>^fg(gray30) <%= eth0_rx.unit %>/s
+    <%= cpu0_temp %>
+    <%= cpu1_temp %>
+    <%= gpu_temp %>
+    ^fg(black)
 
-# Commands to poll. Each command will be polled every second, but specifying a
-# +delay+ greater than one will cache the value and only run the command every
-# +delay+ seconds. This defaults to evaluating a string with a shell, but if
-# your YAML fu is strong enough, you can specify a Proc here too.
-#
-# To narrow down the output, you may use +scan_regex+. A single-quoted regex
-# without forward slashes works great. Since scan returns an array, using one
-# or more capture groups will allow you to pull multiple values from a single
-# command's output - the values returned will be joined with single spaces.
-#
-# To change the class used to poll the command, you can specify a +type+.
-# Right now, only 'rate' is recognized. It uses a separate class that expects
-# a string containing a single number. Best to use +scan_regex+ here. It
-# calculates a running average based on the changes in the value over time.
-# A unit of measurement (b, kb, mb, gb, tb, pb, eb, zb, yb) or its full name
-# (bits, kibibits, mebibits, ...) is also useful here. You may also specify a
-# +number_format+ here if you don't like the default. See +sprintf+ for details
-# on the format string.
+# Provides a list of commands to poll.
+#
+# The key commands needs to be a hash of hashes. The example below shows
+# some interesting examples. Here's the basic structure:
+#
+#   commands:
+#       name:
+#           cmd: 'whoami'
+#       frob:
+#           cmd: 'byte_frobber'
+#           type: 'rate'
+#           scan_regex: 'bytes_frobbed: (\d+)'
+#           format: '%0.3f bits per second'
+#
+# You'd refer to the above commands in your template like so:
+#
+#   User '<%= name %>' is frobbing <%= frob %>!
+#
+# Which would yield something like the following on your dock.
+#
+#   User 'mike' is frobbing 0.321 bits per second!
+#
+# Standard options for commands are as follows:
+#
+#
+# cmd:
+#
+# A required string that will get executed by a shell. If you're comfortable enough with YAML,
+# this can be a ruby Proc too.
+#
+#
+# scan_regex:
+#
+# This optional key provides a way to extract values from command
+# output. The value should be a regular expression without forward
+# slashes, and you'll probably want to put it in single quotes. The best
+# way to use it is to define one capture group with parenthasees. If you
+# define more than one capture group, they'll be joined up with spaces and
+# returned as a single string.
+#
+#
+# format:
+#
+# A string that allows you to wrap the output from your command in
+# another string. You can prepend a label, append a unit, convert the
+# data type in a limited fashion, or whatever you like.
+#
+# See: Kernel#format
+#
+#
+# delay:
+#
+# How long to cache the command output for. If delay is set to 60, even
+# if the bar is refreshed every second, the command will only be run every
+# 60 seconds or so. Timing isn't guaranteed, but it's good enough to
+# estimate data rates.
+#
+#
+# type:
+#
+# This optional key allows you to specify the type of poll to use. If
+# you don't specify a type, the default 'text' is used. It simply runs the
+# command, applies any scan_regex or format specified, and returns the
+# resulting text.
+#
+# If you specify 'rate', the command and scan_regex are expected
+# to return a number. This number will be interpereted as a total in
+# bytes. For example the number of bits that your network adapter has
+# sent. A history of how that value changes over time is kept, and the
+# output from this poll is the average of that history.
+#
+#
+# history_length:
+#
+# This only applies to the 'rate' type. The history length is the number
+# of samples to keep and allows you to control how long of a running
+# average to keep. The larger this number is, the more the average will
+# lag behind the actual rate of change.
+#
 #
 commands:
-    mail:
-        cmd: '/home/joeuser/bin/dockmail'
-        delay: 5
+    load:
+        cmd: 'uptime'
+        scan_regex: '(\d+\.\d+)$'
+        format: '^fg(white)load ^fg(gray60)%s^fg(gray30)/15'
+        delay: 60
     cpu0_temp:
         cmd: 'sensors'
         scan_regex: 'Core 0:\s+\+(\d+\.\d+)'
+        format: '^fg(white)cpu0 ^fg(gray60)%s^fg(gray30)°C'
         delay: 30
     cpu1_temp:
         cmd: 'sensors'
         scan_regex: 'Core 1:\s+\+(\d+\.\d+)'
+        format: '^fg(white)cpu1 ^fg(gray60)%s^fg(gray30)°C'
         delay: 30
     gpu_temp:
         cmd: 'nvidia-smi -q -d TEMPERATURE'
         scan_regex: '(\d+) C'
+        format: '^fg(white)gpu ^fg(gray60)%s^fg(gray30)°C'
         delay: 30    
     eth0_rx:
         cmd: 'ifconfig eth0'
         scan_regex: 'RX bytes:(\d+)'
-        type: rate
-        unit: mb
+        format: '^fg(#208020)%0.3f'
+        type: 'rate'
     eth0_tx:
         cmd: 'ifconfig eth0'
         scan_regex: 'TX bytes:(\d+)'
-        type: rate
-        unit: mb
+        format: '^fg(#802020)%0.3f'
+        type: 'rate'
 

data/lib/dock_driver.rb

@@ -1,13 +1,17 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+#
 
 # A namespace for the project.
 #
 module DockDriver
 
 	# Version Constant
-	VERSION = '0.1.0'
+	VERSION = '0.1.1'
 
 	# Revision Constant
-    REVISION = %q$Revision: d17549778789 $
+    REVISION = %q$Revision: 196ad604d0de $
 
 	# Behold the author(s) responsible for this mess.
 	AUTHORS = [ 'Mike Hix <mike@musl.org>' ]

data/lib/dock_driver/data_rate_poll.rb

@@ -1,11 +1,14 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'ostruct'
 
 require 'dock_driver' unless defined? DockDriver
 require 'dock_driver/poll'
 
-# A class to provide simple, periodic command execution, caching, and a
-# running average in changes in a value.
+# A class to provide periodic command execution, caching, and a
+# running average of changes in the output of the command.
 #
 class DockDriver::DataRatePoll < DockDriver::Poll
 
@@ -14,7 +17,7 @@ class DockDriver::DataRatePoll < DockDriver::Poll
 	DEFAULTS = {
 		:unit => :mb,
 		:history_size => 2,
-		:number_format => '%0.3f',
+		:format => '%0.3f',
 	}.freeze
 
 	# Create a new DataRatePoll.
@@ -27,26 +30,18 @@ class DockDriver::DataRatePoll < DockDriver::Poll
 	#
 	# === Options:
 	#
-	# +:delay+ - Determines the minimum amount of time to let elapse between executions.
-	#
-	# +:cmd+ - A string or block to execute.
-	#
-	# +:scan_regex+ - A bare string to be interpreted as a regex for use with +scan+. Any
-	# capture group matches will be joined with single spaces.
+	# Everything accepted by from Poll, plus:
 	#
 	# +:history_size+ - How many samples to keep
 	#
 	# +:unit+ - The unit to use. See the methods and aliases available.
 	# (b, kb, mb, gb, tb, pb, eb, zb, yb, and full names: bits, kibibits, mebibits, ...)
 	#
-	# +:number_format+ - The format used by +to_s+ to turn a number into a string. See: +printf+ 
-	#
 	def initialize( opts = {} )
 		super DEFAULTS.merge( opts )
 
 		@last_sample = nil
-		@history = Array.new( @table[:history_size] ) { 0 }
-		@average = 0
+		@history = Array.new( self.history_size ) { 0 }
 	end
 
 	# Runs the command if enough time has elapsed since the last
@@ -56,13 +51,12 @@ class DockDriver::DataRatePoll < DockDriver::Poll
 	def poll
 		return false unless super
 
-		@sample = @sample.to_s.to_f unless @sample.is_a? Float
+		@sample = @sample.to_f
 		@last_sample ||= @sample
 		sample = 8 * ( @sample - @last_sample )
-		@history.shift if @history.length >= @table[:history_size]
+		@history.shift if @history.length >= self.history_size
 		@history.push sample
 		@last_sample = @sample
-		@average = @table[:number_format] % send( @table[:unit] )
 
 		true
 	end
@@ -130,11 +124,12 @@ class DockDriver::DataRatePoll < DockDriver::Poll
 	end
 	alias :yb :yobibits
 
-	# Returns the output of the command this Poll runs, formated as per the
-	# option :number_format.
+	# Returns a string representing the data rate this poll tracks.
 	#
 	def to_s
-		@average
+		value = self.unit ? send( self.unit ) : bits
+		return value.to_s if self.format.nil?
+		self.format % value
 	end
 
 end

data/lib/dock_driver/dock.rb

@@ -1,10 +1,14 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
 
 require 'erb'
 require 'yaml'
 require 'ostruct'
+require 'logger'
 
 require 'dock_driver' unless defined? DockDriver
-require 'dock_driver/laika_hashutils'
+require 'dock_driver/hashutils'
 require 'dock_driver/poll'
 require 'dock_driver/data_rate_poll'
 
@@ -13,15 +17,27 @@ require 'dock_driver/data_rate_poll'
 #
 class DockDriver::Dock < OpenStruct
 
-	include LAIKA::HashUtilities
+	include HashUtilities
+
+	# The *normal* place people keep user-specific configuration data for this program.
+	DEFAULT_CONFIG_FILE = '~/.dock_driver.yml'.freeze
+
+	# The usual place to put user-specific diagnostic information pertaining to this program.
+	DEFAULT_LOG_FILE = '~/.dock_driver.log'.freeze
 
 	# Default values to populate this OpenStruct with.
 	#
 	DEFAULTS = {
 		:polls => {},
 		:time_format => '%Y-%m-%d %H:%M:%S %Z',
-		:config_file => File.expand_path( '~/.dock_driver.yml' ),
-		:template => '',
+	}.freeze
+
+	# A map of poll Classes/types to kewords for config.
+	#
+	POLL_TYPES = {
+		nil => DockDriver::Poll,
+		'text' => DockDriver::Poll,
+		'rate' => DockDriver::DataRatePoll,
 	}.freeze
 
 	# Create and start a new Dock.
@@ -33,94 +49,120 @@ class DockDriver::Dock < OpenStruct
 	#
 	# +:dock_command+ - Override the dock command from the config file.
 	#
-	def initialize( config_file = nil, dock_command = nil )
+	def initialize( config_file = nil, log_file = nil, dock_command = nil )
 		super DEFAULTS
-		@worker = nil
-		@table[:config_file] = config_file if config_file
-		load_config
-		@table[:dock_command] = dock_command if dock_command
-	end
 
-	# Returns the result of the template.
-	#
-	def to_s()
-		# Poll everything.
-		@table[:polls].values.map( &:poll )
+		@log_file = File.expand_path( log_file || DEFAULT_LOG_FILE )
+		@log = Logger.new( @log_file )
+		@log.level = $DEBUG ? Logger::DEBUG : Logger::WARN
+
+		@config_file_mtime = nil
+		@config_file = File.expand_path( config_file || DEFAULT_CONFIG_FILE )
 
-		# Prepare a binding and render the ERB template.
-		vbind = OpenStruct.new( @table[:polls] ).send( :binding )
-		@table[:template].result( vbind ).gsub( /\s+/, ' ' )
+		load_config
+
+		@running = false
+		if dock_command
+			self.dock_command = dock_command
+		end
 	end
 
-	# Start thiis Dock if it isn't already running, does nothing otherwise.
+	# Start the dock. Repeatedly calls Dock#drive until it's time to stop. See Dock#stop.
 	#
-	def run
-		@worker ||= Thread.new do
-			while true
-				File.popen( @table[:dock_command], 'w' ) do |pipe|
-					while true
-						pipe.puts self
-						pipe.flush
-						sleep 1
-						break if load_config
-					end
-				end
-			end
+	def start
+		return if @running
+		@running = true
+		while @running
+			drive
 		end
-		@worker.run unless @worker.status
-		@worker.join
 	end
 
-	# Forcibly stops this Dock if it is running, does nothing otherwise.
+	# Signal that it's time to stop the dock.
 	#
-	def kill
-		@worker.kill if @worker.status
+	def stop
+		@running = false
 	end
 
 	#########
 	protected
 	#########
 
-	# Loads the configuration file defined by the option +:config_file+ if it has
-	# changed since this method was last called. If not, returns false.
+	# Drives the dock program by IO#popen. This method provides a main
+	# loop that repeatedly checks the mtime of the config file, polls all of
+	# the polls, updates and delivers the template or any errors that
+	# happened along the way.
 	#
-	# === Arguments:
-	#
-	# +force+ - If true, force a reload, even if the config file hasn't changed.
-	#
-	def load_config( force = false )
-
-		mtime = File.mtime @table[:config_file]
-		return false if not force and mtime == @table[:config_mtime]
-
-		@table.delete :template
-		hash = symbolify_keys( YAML.load_file( @table[:config_file] ) )
-		hash.delete :config_file
-		@table.merge! hash
-		@table[:config_mtime] = mtime
-
-		@table[:polls] = {}
+	def drive
+		pipe = File.popen( self.dock_command, 'w' )
+		pipe.sync = true
+
+		while true
+
+			begin
+				break if load_config
+			rescue Exception => e
+				@log.error e
+				pipe.puts "Couldn't load your config: %s " % e
+				sleep 10
+				next
+			end
 
-		if @table[:commands] and @table[:commands].is_a? Hash
-			@table[:commands].each do |name,hash|
-				klass = DockDriver::Poll
-				case hash[:type]
-				when /rate/i
-					klass = DockDriver::DataRatePoll
+			self.polls.each do |name,p|
+				begin
+					p.poll
+				rescue Exception => e
+					@log.error e
 				end
-				@table[:polls][name] = klass.new( hash )
 			end
+
+			begin
+				vbind = OpenStruct.new( self.polls ).send( :binding )
+				pipe.puts @template.result( vbind ).gsub( /\s+/, ' ' )
+			rescue SyntaxError => e
+				@log.error e
+				pipe.puts "ERB didn't like your template. Check #{@log_file} to see why."
+				sleep 30
+			rescue Exception
+				break
+			end
+
+			sleep 1
 		end
 
-		if @table[:polls]['time'].nil?
-			@table[:polls]['time'] = DockDriver::Poll.new( { :delay => 1 } ) do
-				Time.now.strftime( @table[:time_format] )
+		pipe.close
+	rescue => e
+		puts e
+		puts e.backtrace
+		exit
+	end
+
+	# Loads the configuration file defined by the option +:config_file+ if it has
+	# changed since this method was last called. If not, returns false.
+	#
+	def load_config
+		mtime = File.mtime @config_file
+		return false if mtime == @config_file_mtime
+
+		@table.merge! symbolify_keys YAML.load_file @config_file
+		@config_file_mtime = mtime
+
+		self.polls = {}
+		if self.commands and self.commands.is_a? Hash
+			self.commands.each do |name,hash|
+				hash[:name] = name
+				self.polls[name] = POLL_TYPES[hash[:type]].new( hash )
 			end
 		end
 
-		@table[:template] = ERB.new( @table[:template] )
+		if self.polls[:time].nil?
+			self.polls[:time] = DockDriver::Poll.new( {
+				:cmd => Proc.new { Time.now.strftime( self.time_format ) },
+			} )
+		end
 
-		return true
+		@template = ERB.new( self.template )
+		true
 	end
 
 end
+

data/lib/dock_driver/hashutils.rb

@@ -0,0 +1,79 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+#
+# Copyright (c) 2007-2012, Michael Granger and Mahlon E. Smith
+# All rights reserved.
+#
+
+### A collection of utilities for working with Hashes.
+#
+module HashUtilities
+
+	###############
+	module_function
+	###############
+
+	### Return a version of the given +hash+ with its keys transformed
+	### into Strings from whatever they were before.
+	def stringify_keys( hash )
+		newhash = {}
+
+		hash.each do |key,val|
+			if val.is_a?( Hash )
+				newhash[ key.to_s ] = stringify_keys( val )
+			else
+				newhash[ key.to_s ] = val
+			end
+		end
+
+		return newhash
+	end
+
+
+	### Return a duplicate of the given +hash+ with its identifier-like keys
+	### transformed into symbols from whatever they were before.
+	def symbolify_keys( hash )
+		newhash = {}
+
+		hash.each do |key,val|
+			keysym = key.to_s.dup.untaint.to_sym
+
+			if val.is_a?( Hash )
+				newhash[ keysym ] = symbolify_keys( val )
+			else
+				newhash[ keysym ] = val
+			end
+		end
+
+		return newhash
+	end
+	alias_method :internify_keys, :symbolify_keys
+
+
+	# Recursive hash-merge function
+	def merge_recursively( key, oldval, newval )
+		case oldval
+		when Hash
+			case newval
+			when Hash
+				oldval.merge( newval, &method(:merge_recursively) )
+			else
+				newval
+			end
+
+		when Array
+			case newval
+			when Array
+				oldval | newval
+			else
+				newval
+			end
+
+		else
+			newval
+		end
+	end
+
+end # HashUtilities
+

data/lib/dock_driver/poll.rb

@@ -1,9 +1,13 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+#
 
 require 'ostruct'
 
 require 'dock_driver' unless defined? DockDriver
 
-# A class to provide simple, periodic command execution and caching.
+# A class to provide periodic command execution and caching.
 #
 class DockDriver::Poll < OpenStruct
 
@@ -30,42 +34,56 @@ class DockDriver::Poll < OpenStruct
 	# +:scan_regex+ - A bare string to be interpreted as a regex for use with +scan+. Any
 	# capture group matches will be joined with single spaces.
 	#
+	# +:format+ - A format string. See: Kernel#format
+	#
 	def initialize( opts = {}, &block )
 		super DEFAULTS.merge( opts )
+
 		@sample = nil
 
 		if block_given?
-			@table[:cmd] = block
+			self.cmd = block
 		end
 	end
 
-	# Runs the command if enough time has elapsed since the last poll. "Enough Time" is
-	# defined by the :delay option.
+	# Runs the command if enough time has elapsed since the last
+	# poll. "Enough Time" is defined by the :delay option. If the command
+	# fails to run, it is disabled and the format and output string are set
+	# to nil.
 	#
 	def poll
-		return false if @sample and (Time.now - (@table[:last_poll] || 0 )) < @table[:delay]
+		return false if @sample and (Time.now - (self.last_poll || 0 )) < self.delay
 
-		@table[:last_poll] = Time.now
+		self.last_poll = Time.now
 
-		case @table[:cmd]
+		case self.cmd
 		when Proc
-			@sample = @table[:cmd].call
+			@sample = self.cmd.call.to_s.chomp
 		else
-			@sample = `#{@table[:cmd].to_s}`
+			output = `#{self.cmd.to_s} 2>&1`.chomp
+			if $? == 0
+				@sample = output
+			else
+				self.format = nil
+				@sample = '[%s: Error!] ' % self.name
+				raise output
+			end
 		end
 
-		if @table[:scan_regex]
-			extract = @sample.scan( Regexp.new( @table[:scan_regex] ) ).flatten
+		if self.scan_regex
+			extract = @sample.scan( Regexp.new( self.scan_regex ) ).flatten
 			@sample = extract.join( ' ' ) unless extract.empty?
 		end
 
 		true
 	end
 
-	# Returns the output of the command this Poll runs.
+	# Returns the output of the command this Poll runs. It will return a formatted string if
+	# the +:format+ option is correctly specified.
 	#
 	def to_s
-		@sample
+		return @sample.to_s if self.format.nil?
+		self.format % @sample
 	end
 
 end

data/spec/dock_driver/dock_spec.rb

@@ -6,35 +6,31 @@ require 'dock_driver/dock'
 describe DockDriver::Dock do
 
 	subject do
-		conf = Pathname( __FILE__ ).parent.parent.parent + 'data'
-		conf += 'example.dock_driver.yml'
-		dock = Dock.new conf, 'cat'
+		@conf = Pathname( __FILE__ ).parent.parent.parent
+		@conf += 'data/example.dock_driver.yml'
+
+		# Use very common binaries that are all but guaranteed to be in the
+		# user's path so that we can maintain a meaningful example config file.
+		#
+		dock = Dock.new( @conf.to_s, nil, 'cat' )
+		dock.polls.values.each { |p| p.cmd = 'echo test' }
 		dock
 	end
 
-	it 'should be able to load a config file properly' do
+	it 'should load a config file' do
 		subject.dock_command.should_not be nil
 		subject.template.should_not be nil
 		subject.polls.should have_at_least( 2 ).things
 		subject.polls.values.each { |p| p.should be_a_kind_of Poll }
 	end
 
-	it 'should only attempt to reload a config file with a more recent mtime' do
+	it 'should only reload a config file with a more recent mtime' do
 		subject.send( :load_config ).should be false
-		FileUtils.touch subject.config_file
+		sleep 0.1
+		FileUtils.touch @conf
 		subject.send( :load_config ).should be true
 		subject.send( :load_config ).should be false
 	end
 
-	it 'should produce a string properly' do
-
-		# make sure we don't fail if a particular binary for an example doesn't exist.
-		subject.polls.values.each { |p| p.cmd = 'echo' }
-
-		string = subject.to_s
-		string.should be_a_kind_of String
-		string.should_not be ''
-	end
-
 end
 

data/spec/dock_driver/poll_spec.rb

@@ -4,48 +4,42 @@ require 'dock_driver/data_rate_poll'
 
 include DockDriver
 
-shared_examples 'Poll' do |klass|
+shared_examples 'a poll' do
 
-	it 'should be able to execute shell commands' do
-		p = Poll.new( :cmd => "echo" )
-		lambda { p.poll }.should_not raise_error
+	subject do
+		described_class.new( :cmd => 'echo test' )
 	end
 
-	it 'should be able to execute blocks' do
-		p = Poll.new do; end
-		lambda { p.poll }.should_not raise_error
+	it 'should execute shell commands' do
+		lambda do
+			subject.poll.should == true
+		end.should_not raise_error
 	end
 
-	it 'should return the same object if polled quickly' do
-		p = Poll.new( :cmd => "echo" )
-		p.poll
-		a = p.to_s
-		p.poll
-		b = p.to_s
-		a.object_id.should == b.object_id
+	it 'should execute blocks' do
+		subject.cmd = lambda {}
+		lambda do
+			subject.poll.should == true
+		end.should_not raise_error
 	end
 
-	it 'should return a different object if polled slowly' do
-		p = Poll.new( :cmd => "echo", :delay => 0.1 )
-		p.poll
-		a = p.to_s
-		sleep 0.5
-		p.poll
-		b = p.to_s
-		a.object_id.should_not == b.object_id
+	it 'should cache command output' do
+		subject.delay = 10
+		subject.poll.should == true
+		subject.poll.should == false
+
+		subject.delay = 0
+		subject.poll.should == true
+		subject.poll.should == true
 	end
 
 end
 
 describe Poll do
-
-	include_examples 'Poll', Poll
-
+	it_behaves_like 'a poll'
 end
 
 describe DataRatePoll do
-
-	include_examples 'Poll', DataRatePoll
-
+	it_behaves_like 'a poll'
 end
 

data/spec/dock_driver_spec.rb

@@ -3,12 +3,12 @@ require 'dock_driver'
 
 describe DockDriver do
 
-	it 'should have a standard version number' do
+	it 'should define a standard version number' do
 		defined?( VERSION ).should == 'constant'
 		VERSION.should =~ /^\d+\.\d+\.\d+$/
 	end
 
-	it 'should have a mercurial revision' do
+	it 'should define a mercurial revision' do
 		defined?( REVISION ).should == 'constant'
 		REVISION.should =~ /^Revision: [[:xdigit:]]+ $/
 	end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: dock_driver
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Michael Hix
@@ -35,7 +35,7 @@ cert_chain:
   Edc7ShBTME9+u6K/HFwVxTOH8WJVxkwGTmxKgCevr5mZzbINH/C6LbkmfEA=
   -----END CERTIFICATE-----
 
-date: 2012-05-16 00:00:00 Z
+date: 2012-05-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: hoe-mercurial
@@ -112,7 +112,7 @@ files:
 - bin/dock_driver
 - data/example.dock_driver.yml
 - lib/dock_driver.rb
-- lib/dock_driver/laika_hashutils.rb
+- lib/dock_driver/hashutils.rb
 - lib/dock_driver/poll.rb
 - lib/dock_driver/data_rate_poll.rb
 - lib/dock_driver/dock.rb

data/lib/dock_driver/laika_hashutils.rb

@@ -1,74 +0,0 @@
-# A module borrowed from my coworkers at LAIKA. 
-#
-module LAIKA
-
-	### A collection of utilities for working with Hashes.
-	module HashUtilities
-
-		###############
-		module_function
-		###############
-
-		### Return a version of the given +hash+ with its keys transformed
-		### into Strings from whatever they were before.
-		def stringify_keys( hash )
-			newhash = {}
-
-			hash.each do |key,val|
-				if val.is_a?( Hash )
-					newhash[ key.to_s ] = stringify_keys( val )
-				else
-					newhash[ key.to_s ] = val
-				end
-			end
-
-			return newhash
-		end
-
-
-		### Return a duplicate of the given +hash+ with its identifier-like keys
-		### transformed into symbols from whatever they were before.
-		def symbolify_keys( hash )
-			newhash = {}
-
-			hash.each do |key,val|
-				keysym = key.to_s.dup.untaint.to_sym
-
-				if val.is_a?( Hash )
-					newhash[ keysym ] = symbolify_keys( val )
-				else
-					newhash[ keysym ] = val
-				end
-			end
-
-			return newhash
-		end
-		alias_method :internify_keys, :symbolify_keys
-
-
-		# Recursive hash-merge function
-		def merge_recursively( key, oldval, newval )
-			case oldval
-			when Hash
-				case newval
-				when Hash
-					oldval.merge( newval, &method(:merge_recursively) )
-				else
-					newval
-				end
-
-			when Array
-				case newval
-				when Array
-					oldval | newval
-				else
-					newval
-				end
-
-			else
-				newval
-			end
-		end
-
-	end # HashUtilities
-end