butler 1.8.0 → 1.8.1

data/lib/dialogline.rb

@@ -12,6 +12,18 @@ begin
 	require 'readline'
 rescue LoadError; warn "DialogLine starts without readline support." end
 
+# == Indexing
+# Author:  Stefan Rusterholz
+# Contact: apeiros@gmx.net>
+# Version: 1.0.0
+# Date:    2007-10-12
+#
+# == About
+# Abstract command line dialogs with multilingualization.
+# 
+# == Synopsis
+# 
+# 
 class DialogLine
 	module VERSION
 		MAJOR  = 0

data/lib/event.rb

@@ -114,7 +114,8 @@ class Event
 		end
 	end
 
-	def initialize(options={}, &block)
+	# Don't use directly, use the creation methods.
+	def initialize(options={}, &block) # :nodoc:
 		@block    = block
 		@start    = options.delete(:start) || Time.now
 		@stop     = options.delete(:stop)
@@ -128,6 +129,7 @@ class Event
 		@count    = 0
 	end
 	
+	# Invoke the event
 	def call(*args)
 		@block.call(*args)
 	end
@@ -264,7 +266,8 @@ class Event
 	def to_f
 		seconds_left.to_f
 	end
-	
+
+	# Stop current thread until this event is finished.	
 	def join
 		@wakeup << Thread.current
 		sleep unless finished?

data/lib/installer.rb

@@ -1,5 +1,29 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
 require 'rbconfig'
 
+
+
+# == Indexing
+# Author:  Stefan Rusterholz
+# Contact: apeiros@gmx.net>
+# Version: 1.0.0
+# Date:    2007-10-12
+#
+# == About
+# Tools to install stuff. At the moment that means mostly suggest
+# where stuff might go.
+# 
+# == Synopsis
+#   x = Iterator.new { |iter| [1,2,3].each { |e| iter.yield(e) } }
+#   p x.map { |e| e*2 }
+# 
 class Installer
 	def initialize(app_name)
 		@app_name = app_name
@@ -13,43 +37,47 @@ class Installer
 		end
 	end
 	
-	def user_data_suggestions
+	def home(user=nil)
+		File.expand_path("~#{user}")
+	end
+	
+	def user_data_suggestions(user=nil)
 		{
-			:osx     => ["#{ENV['HOME']}/Library/Application Support/#{@app_name}", "#{ENV['HOME']}/.#{@app_name}"],
-			:windows => ["#{ENV['HOME']}/.#{@app_name}"],
-			:nix     => ["#{ENV['HOME']}/.#{@app_name}"],
+			:osx     => ["#{home(user)}/Library/Application Support/#{@app_name}", "#{home(user)}/.#{@app_name}"],
+			:windows => ["#{home(user)}/.#{@app_name}"],
+			:nix     => ["#{home(user)}/.#{@app_name}"],
 		}[os_class]
 	end
 
-	def user_config_suggestions
+	def user_config_suggestions(user=nil)
 		{
-			:osx     => ["#{ENV['HOME']}/Library/Preferences/#{@app_name}", "#{ENV['HOME']}/.#{@app_name}/etc"],
-			:windows => ["#{ENV['HOME']}/.#{@app_name}/etc"],
-			:nix     => ["#{ENV['HOME']}/.#{@app_name}/etc"],
+			:osx     => ["#{home(user)}/Library/Preferences/#{@app_name}", "#{home(user)}/.#{@app_name}/etc"],
+			:windows => ["#{home(user)}/.#{@app_name}/etc"],
+			:nix     => ["#{home(user)}/.#{@app_name}/etc"],
 		}[os_class]
 	end
 
-	def user_documents_suggestions
+	def user_documents_suggestions(user=nil)
 		{
-			:osx     => ["#{ENV['HOME']}/Documents"],
+			:osx     => ["#{home(user)}/Documents"],
 			:windows => [
-				"#{ENV['HOME']}/My Documents",
-				"#{ENV['HOME']}/#{ENV['USER']}'s Documents",
-				"#{ENV['HOME']}/#{ENV['USER'].downcase}'s documents"
+				"#{home(user)}/My Documents",
+				"#{home(user)}/#{ENV['USER']}'s Documents",
+				"#{home(user)}/#{ENV['USER'].downcase}'s documents"
 				].select { |path| File.directory?(path) },
-			:nix     => ["#{ENV['HOME']}/"],
+			:nix     => ["#{home(user)}/"],
 		}[os_class]
 	end
 	
-	def user_pid_suggestions
+	def user_pid_suggestions(user=nil)
 		{
-			:osx     => ["#{ENV['HOME']}/Library/Application Support/#{@app_name}/run", "#{ENV['HOME']}/.#{@app_name}/run"],
-			:windows => ["#{ENV['HOME']}/.#{@app_name}/run"],
-			:nix     => ["#{ENV['HOME']}/.#{@app_name}/run"],
+			:osx     => ["#{home(user)}/Library/Application Support/#{@app_name}/run", "#{home(user)}/.#{@app_name}/run"],
+			:windows => ["#{home(user)}/.#{@app_name}/run"],
+			:nix     => ["#{home(user)}/.#{@app_name}/run"],
 		}[os_class]
 	end
 
-	def shared_data_suggestions
+	def shared_data_suggestions(user=nil)
 		{
 			:osx     => ["/Library/Application Support/#{@app_name}", "#{Config::CONFIG['datadir']}/#{@app_name}"],
 			:windows => ["#{Config::CONFIG['datadir']}/#{@app_name}"],
@@ -57,19 +85,19 @@ class Installer
 		}[os_class]
 	end
 	
-	def cli_binary_suggestions
+	def cli_binary_suggestions(user=nil)
 		{
 			:osx     => [Config::CONFIG['bindir']],
 			:windows => [Config::CONFIG['bindir']],
-			:nix     => [Config::CONFIG['bindir'], "#{ENV['HOME']}/bin"],
+			:nix     => [Config::CONFIG['bindir'], "#{home(user)}/bin"],
 		}[os_class]
 	end
 
-	def gui_binary_suggestions
+	def gui_binary_suggestions(user=nil)
 		{
-			:osx     => ["/Applications", ENV['HOME']+"/Applications"],
+			:osx     => ["/Applications", home(user)+"/Applications"],
 			:windows => [Config::CONFIG['bindir']],
-			:nix     => [Config::CONFIG['bindir'], "#{ENV['HOME']}/bin"],
+			:nix     => [Config::CONFIG['bindir'], "#{home(user)}/bin"],
 		}[os_class]
 	end
 end

data/lib/iterator.rb

@@ -6,10 +6,23 @@
 
 
 
+# == Indexing
+# Author:  Stefan Rusterholz
+# Contact: apeiros@gmx.net>
+# Version: 1.0.0
+# Date:    2007-10-12
+#
+# == About
+# Similar like Enumarator, enables to create an Enumerable.
+# 
+# == Synopsis
+#   x = Iterator.new { |iter| [1,2,3].each { |e| iter.yield(e) } }
+#   p x.map { |e| e*2 }
+# 
 class Iterator
 	include Enumerable
 
-	class Iteration
+	class Iteration # :nodoc:
 		def initialize(&block)
 			@block = block
 		end
@@ -18,17 +31,14 @@ class Iterator
 		end
 	end
 
+	# Determine how to iterate, the block most contain the code that
+	# is executed to iterate.
 	def initialize(&iterator)
 		@iterator = iterator
 	end
 	
+	# Will iterate as defined in Iterator::new
 	def each(&block)
 		@iterator.call(Iteration.new(&block))
 	end
 end
-
-if __FILE__ == $0 then
-	#Iterator.new { |iter| File.open(path) { |fh| while buf = fh.read(8192); iter.yield(buf); end } }
-	x = Iterator.new { |iter| [1,2,3].each { |e| iter.yield(e) } }
-	p x.map { |e| e*2 }
-end

data/lib/log.rb

@@ -18,6 +18,24 @@
 #     $stdout.puts(exception) # same as Log::File#log(exception)
 #   end
 #
+# == Use-cases
+# === Daemon
+# Since a daemon should not output anything at all, the advice is to create a
+# logger (Log::File e.g.) and assign a Log::Forward to each, $stdout and $stderr.
+# It's suggested to use :info as the default level for $stdout and :warn for
+# $stderr.
+#
+# === Application
+# If you use Log with your application, you most likely want to log to a file.
+# The advice for that is to simply assign a Log::File to $stderr, anything that
+# prints to $stderr is now logged as :warn.
+#
+# === Library
+# With a library you most likely just want Log::Comfort. It adds logging methods
+# and convenience methods to your class. It uses @logger if set, else $stderr to
+# puts a Log::Entry. That way your library has decent logging even if the
+# employing app doesn't use a logger.
+#
 # == Notes
 # require 'log/kernel' to get convenience methods in Kernel
 # it isn't required via 'log' alone to avoid accidental method name clashes.
@@ -50,6 +68,8 @@ module Log
 	end
 end
 
+
+
 require 'log/comfort'
 require 'log/converter'
 require 'log/entry'
@@ -59,10 +79,17 @@ require 'log/file'
 require 'log/nolog'
 
 
+
 if __FILE__ == $0 then
-lf = StringIO.new
-log = Log::File.new(lf)
-$stderr = Log::Forward.new(log, :warn)
-warn "foo"
-Log::Entry.deserialize(lf.string.split("\n").first)
+	begin
+		require 'stringio'
+		lf = StringIO.new
+		log = Log::File.new(lf)
+		$stderr = Log::Forward.new(log, :warn)
+		warn "foo"
+		p Log::Entry.deserialize(lf.string.split("\n").first)
+		puts "end"
+	rescue => e
+		puts e, *e.backtrace
+	end
 end

data/lib/log/comfort.rb

@@ -22,52 +22,69 @@ require 'log/entry'
 module Log
 	module Comfort
 		# where data is logged to
-		attr_accessor :log_device
+		attr_accessor :logger
+		
+		# Used for the origin-field in the log
+		alias log_origin class
 
 		# See Log::Message.new
 		# Module::log(*args) is simply: $stderr.puts(Log::Message.new(*args))
-		def log(text, severity=:info, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, severity, *args))
+		def log(text, severity=:info, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, severity, origin||log_origin, data=nil, *flags)
+			)
 		end
 	
 		# See Log::Entry.new to see what arguments are valid.
 		# Module::debug(text, *args) is the same as:
 		#   $stderr.puts(Log::Message.new(text, :debug, *args))
-		def debug(text, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, :debug, *args))
+		def debug(text, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, :debug, origin||log_origin, data=nil, *flags)
+			)
 		end
-	
+
 		# See Log::Entry.new to see what arguments are valid.
 		# Module::info(text, *args) is the same as:
 		#   $stderr.puts(Log::Message.new(text, :info, *args))
-		def info(text, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, :info, *args))
+		def info(text, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, :info, origin||log_origin, data=nil, *flags)
+			)
 		end
 	
 		# See Log::Entry.new to see what arguments are valid.
 		# Module::warn(text, *args) is the same as:
 		#   $stderr.puts(Log::Message.new(text, :warn, *args))
-		def warn(text, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, :warn, *args))
+		def warn(text, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, :warn, origin||log_origin, data=nil, *flags)
+			)
 		end
 	
 		# See Log::Entry.new to see what arguments are valid.
 		# Module::error(text, *args) is the same as:
 		#   $stderr.puts(Log::Message.new(text, :error, *args))
-		def error(text, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, :error, *args))
+		def error(text, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, :error, origin||log_origin, data=nil, *flags)
+			)
 		end
 	
 		# See Log::Entry.new to see what arguments are valid.
 		# Module::fail(text, *args) is the same as:
 		#   $stderr.puts(Log::Message.new(text, :fail, *args))
-		def fail(text, *args)
-			(@log_device || $stderr).puts(Log::Entry.new(text.to_str, :fail, *args))
+		def fail(text, origin=nil, data=nil, *flags)
+			(@logger || $stderr).puts(
+				Log::Entry.new(text.to_str, :fail, origin||log_origin, data=nil, *flags)
+			)
 		end
 
-		# 
+		# Exception is special cased, if @logger || $stderr responds to 'exception',
+		# the exception is just forwarded, else it uses puts and prints
+		# the exception and the backtrace
 		def exception(e)
-			log = @log_device || $stderr
+			log = @logger || $stderr
 			if log.respond_to?(:exception) then
 				log.exception(e)
 			else

data/lib/log/entry.rb

@@ -20,20 +20,31 @@ module Log
 		"%s#{RecordSeparator}" \
 		"%s#{RecordSeparator}" \
 		"%s#{RecordSeparator}" \
+		"%s#{RecordSeparator}" \
 		"%s"
 
 	class Entry
+		# the value used by #to_s if no format is given
+		DefaultFormat = "%{time:%FT%T} [%{severity}]: %{text} in %{origin}"
+
 		class <<self
 			attr_accessor :time_format
 			
 			def deserialize(line)
-				time, severity, text, flagstr, data = line.chomp(RecordTerminator).split(RecordSeparator)
+				time, severity, origin, text, flagstr, data = line.chomp(RecordTerminator).split(RecordSeparator)
 				flags = {}
 				flagstr.split(UnitSeparator).each_cons(2) { |key, value|
 					flagstr[key] = value
 				}
 				severity = Integer(severity) rescue severity
-				new(text, InvSeverity[severity], Marshal.load(Log.unescape(data)), Time.at(time.to_i), flags)
+				new(
+					text,
+					InvSeverity[severity],
+					Log.unescape(origin),
+					Marshal.load(Log.unescape(data)),
+					Time.at(time.to_i),
+					flags
+				)
 			end
 
 			def formatter_for(entity, &formatter)
@@ -48,6 +59,10 @@ module Log
 				entry.time.strftime(format || @time_format)
 			end
 
+			def format_origin(entry)
+				entry.origin.to_s
+			end
+
 			def format_severity(entry)
 				entry.severity.to_s
 			end
@@ -72,6 +87,7 @@ module Log
 		@formatter = {
 			"time"     => method(:format_time),
 			"severity" => method(:format_severity),
+			"origin"   => method(:format_origin),
 			"flags"    => method(:format_flags),
 			"text"     => method(:format_text), #Log.method(:escape),
 		}
@@ -79,12 +95,14 @@ module Log
 		
 		attr_reader :time
 		attr_reader :severity
+		attr_reader :origin
 		attr_reader :text
 		attr_reader :flags
 		attr_reader :data
-		def initialize(text, severity=:info, data=nil, *flags)
+		def initialize(text, severity=:info, origin=nil, data=nil, *flags)
 			@time     = flags.first.kind_of?(Time) ? flags.shift : Time.now
 			@severity = severity
+			@origin   = origin.to_s
 			@text     = text
 			@data     = data
 			@flags    = flags.last.kind_of?(Hash) ? flags.pop : {}
@@ -120,6 +138,7 @@ module Log
 			Serialized %  [
 				@time,
 				Severity[@severity],
+				Log.escape(@origin),
 				Log.escape(@text),
 				@flags.map.join(UnitSeparator),
 				Log.escape(Marshal.dump(@data))
@@ -127,7 +146,7 @@ module Log
 		end
 	
 		def to_s(format=nil)
-			format ||= "%{time:%FT%T} [%{severity}]: %{text}"
+			format ||= DefaultFormat
 			format.gsub(/%(%|\{[^}]+\})/) { |match|
 				if match == "%%" then
 					"%"
@@ -139,10 +158,11 @@ module Log
 		end
 		
 		def inspect
-			"#<%s %s %s %s flags=%s data=%s>" %  [
+			"#<%s %s %s %s %s flags=%s data=%s>" %  [
 				self.class,
 				@time.strftime("%FT%T"),
 				@severity,
+				@origin,
 				@text.inspect,
 				@flags.inspect,
 				@data.inspect