butler 1.8.0

data/lib/dialogline.rb

@@ -0,0 +1,296 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'erb'
+require 'dialogline/localizations'
+begin
+	require 'readline'
+rescue LoadError; warn "DialogLine starts without readline support." end
+
+class DialogLine
+	module VERSION
+		MAJOR  = 0
+		MINOR  = 0
+		TINY   = 1
+		STRING = "#{MAJOR}.#{MINOR}.#{TINY}"
+	end
+
+	class EndOfInput < RuntimeError; end
+	
+	class Variables
+		def initialize(data, fallback=nil)
+			@fallback = fallback
+			@data     = (@fallback ? Hash.new { |h,k| @fallback.send(k) } : {}).merge(data)
+		end
+		
+		def __keys__(include_fallback=true)
+			@data.keys + ((include_fallback && @fallback)? @fallback.__keys__ : [])
+		end
+		
+		def has_key?(key)
+			@data.has_key?(key) || (@fallback && @fallback.has_key?(key))
+		end
+		
+		def method_missing(m, *args)
+			case args.length
+				when 0: return @data[m] if has_key?(m)
+				when 1: return @data[m.to_s[0..-1].to_sym] = args.first if m.to_s =~ /=\z/
+			end			
+			super
+		end
+		
+		def binding
+			super
+		end
+		
+		def inspect
+			"#<%s:0x%08x @data=%s @fallback=%s>" %  [
+				self.class,
+				object_id,
+				@data.inspect,
+				@fallback ? "#<%s:0x%08x ...>" %  [@fallback.class, @fallback.object_id] : "nil"
+			]
+		end
+	end
+
+	attr_reader :language
+	attr_reader :dir
+	attr_reader :variables
+	
+	def initialize(dir, lang=nil, variables={})
+		@dir       = dir
+		@language  = lang
+		@in        = $stdin
+		@out       = $stdout
+		@variables = Variables.new(variables)
+	end
+
+	def puts(*args)
+		@out.puts(*args)
+	end
+	
+	def print(*args)
+		@out.print(*args)
+		@out.flush
+	end
+
+	def printf(*args)
+		@out.printf(*args)
+		@out.flush
+	end
+	
+	def localized(index)
+		Localized[index][@language]
+	end
+		
+	def request(string, default=nil, term=": ")
+		if default then
+			print("#{string} [#{default}]#{term}")
+		else
+			print("#{string}#{term}")
+		end
+	end
+
+	def gets(chomp=true)
+		raise EndOfInput unless response = @in.gets
+		response.chomp! if chomp
+		response
+	end
+
+	def in_context(name)
+		Context.new([@in,@out],@language,@dir,name,false)
+	end
+
+	def singleton_def(name, &code)
+		singleton = class<<self;self;end
+		singleton.send(:define_method, name, &code)
+	end
+	
+	def discuss(file, use_ostruct=false, variables={}, &stuff)
+		instance_eval(&stuff) if stuff
+		Context.run(self, file, use_ostruct, variables)
+	end
+
+	class Context
+		(DialogLine.public_instance_methods(false) & Context.private_instance_methods(true)).each { |m|
+			undef_method(m)
+		}
+
+		attr_reader :result
+		attr_reader :variables
+
+		def self.run(*args)
+			context = new(*args)
+			context.result
+		end
+		
+		def initialize(dialog, file, use_ostruct=false, variables={})
+			@dialog      = dialog
+			@file        = file
+			@use_ostruct = use_ostruct
+			dir, lang    = dialog.dir, dialog.language
+			@variables   = Variables.new(variables, dialog.variables)
+
+			qfile        = "#{dir}/#{lang}/#{file}.yaml"
+			dfile        = "#{dir}/#{file}.rb"
+			@result      = use_ostruct ? OpenStruct.new : {}
+			@questions   = Hash.new { |h,k| raise "No Question for #{k} in #{file}" }.merge(
+				File.exist?(qfile) ? YAML.load_file(qfile) : {}
+			)
+			
+			run_file(dfile)
+		end
+		
+		def run_file(__file__)
+			instance_eval(File.read(__file__), __file__)
+		end
+		private :run_file
+
+		def response(method, name, *args)
+			@result[name] = send(method, name, *args)
+		end
+		
+		def store(name, value)
+			@result[name] = value
+		end
+
+		def string(name, variables={})
+			if variables.empty? then
+				variables = @variables
+			else
+				variables = Variables.new(variables, @variables)
+			end
+			ERB.new(@questions[name]).result(variables.binding)
+		end
+
+		def prompt(question, default=nil, vars={}, *args)
+			valid = false
+			yes   = localized(:yes)
+			no    = localized(:no)
+			until valid
+				default_answer = default ? "#{yes.upcase}/#{no}" : "#{no.upcase}/#{yes}"
+				request("#{string(question, vars)} [#{default_answer}]")
+				response, valid  = validate(gets.downcase, default, String, :one_of => [yes, no])
+				puts localized(:invalid) unless valid
+			end
+			response == yes or response == true
+		end
+	
+		def say(message, vars={})
+			puts(string(message, vars))
+		end
+		
+		def ask(question, default=nil, klass=String, *args)
+			valid = false
+			until valid
+				request(string(question), default)
+				response, valid  = validate(gets, default, klass, *args)
+				puts localized(:invalid) unless valid
+			end
+			response
+		end
+		
+		# like option, but allows custom entry
+		def suggestion(question, suggestions, default=nil, klass=String, *args)
+			valid = false
+			until valid
+				request(string(question), default, ":\n")
+				suggestions.each_with_index { |opt,i| printf "%2d) %s\n", i+1, opt }
+				response, valid = validate(gets, default, klass, *args)
+				pos             = Integer(response) rescue -1
+				response, valid = suggestions[pos-1], true if pos.between?(1, suggestions.length)
+				puts localized(:invalid) unless valid
+			end
+			response
+		end
+		
+		def option(question, options, default=nil, klass=String, *args)
+			valid = false
+			until valid
+				request(string(question), default, ":\n")
+				options.each_with_index { |opt,i| printf "%2d) %s\n", i+1, opt }
+				if args.last.kind_of?(Hash) then
+					args.last.merge!(:one_of => options)
+				else
+					args.push(:one_of => options)
+				end
+				response, valid  = validate(gets, default, klass, *args)
+				if !valid && (pos = Integer(response) rescue false) then
+					response, valid = options[pos-1], true if pos.between?(1, options.length)
+				end
+				puts localized(:invalid) unless valid
+			end
+			response
+		end
+		
+		def context(file, variables={})
+			Context.run(@dialog, file, @use_ostruct, variables)
+		end
+
+		def validate(response, default, klass, *args) # FIXME, use Validator class here
+			return [default, true] if !default.nil? and response.empty?
+	
+			case [klass]
+				when [String]:  validate_string(response, *args)
+				when [Integer]: validate_integer(response, *args)
+				when [Array]:   validate_array(response, *args)
+			end
+		end
+
+		def validate_array(response, klass, *args)
+			response = response.split(/,\s*/)
+			valid    = response.all? { |item| validate(item, nil, klass, *args) }
+			return [response, valid]
+		end
+	
+		def validate_string(response, opts={})
+			valid = opts.all? { |test, param|
+				case test
+					when :matching:      response =~ param
+					when :not_matching:  response !~ param
+					when :max:           response.length <= param
+					when :min:           response.length >= param
+					when :max_exclusive: response.length < param
+					when :min_exclusive: response.length > param
+					when :between:       response.length.between?(*param)
+					when :one_of:        param.include?(response)
+					when :case_one_of:   param.include?(response.downcase)
+				end
+			}
+			return [response, valid]
+		end
+
+		def validate_integer(response, opts={})
+			return [response, false] unless response = Integer(response) rescue nil
+			valid = opts.all? { |test, param|
+				case test
+					when :greater_than:     response > param
+					when :less_than:        response < param
+					when :greater_or_equal: response >= param
+					when :less_or_equal:    response <= param
+					when :between:          response.between?(*param)
+					when :one_of:           param.include?(response)
+				end
+			}
+			return [response, valid]
+		end
+		
+		def method_missing(m, *args, &block)
+			super unless @dialog.respond_to?(m)
+			@dialog.send(m, *args, &block)
+		end
+		
+		def to_s
+			"#<%s:0x%X %s>" %  [
+				self.class,
+				object_id << 1,
+				@file
+			]
+		end
+	end
+end

data/lib/dialogline/localizations.rb

@@ -0,0 +1,24 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+class DialogLine
+	Localized = {
+		:invalid => {
+			"de" => "Ungültige Antwort.",
+			"en" => "Invalid response.",
+		},
+		:yes => {
+			"de" => "ja",
+			"en" => "yes",
+		},
+		:no  => {
+			"de" => "nein",
+			"en" => "no",
+		},
+	}
+end

data/lib/durations.rb

@@ -0,0 +1,57 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+class Numeric
+	# == Synopsis
+	#   45.seconds # => 45
+	def seconds(*args)
+		args.inject(self) { |s,a| s+a }
+	end
+
+	# == Synopsis
+	#   15.minutes # => 900
+	#   15.minutes 45.seconds # => 945
+	def minutes(*args)
+		args.inject(self*60) { |s,a| s+a }
+	end
+
+	# == Synopsis
+	#   5.hours # => 18000
+	#   5.hours 15.minutes, 45.seconds # => 18945
+	def hours(*args)
+		args.inject(self*3600) { |s,a| s+a }
+	end
+
+	# == Synopsis
+	#   2.days # => 172800
+	#   2.days 5.hours, 15.minutes, 45.seconds # => 191745
+	def days(*args)
+		args.inject(self*86400) { |s,a| s+a }
+	end
+	
+	# == Synopsis
+	#   1.week # => 604800
+	#   1.week 2.days, 5.hours, 15.minutes, 45.seconds # => 796545
+	def weeks(*args)
+		args.inject(self*604800) { |s,a| s+a }
+	end
+	
+	alias second seconds
+	alias minute minutes
+	alias hour   hours
+	alias day    days
+	alias week   weeks
+
+	def ago
+		Time.now-self
+	end
+
+	def from_now
+		Time.now+self
+	end
+end

data/lib/event.rb

@@ -0,0 +1,295 @@
+#--
+# Copyright 2007 by Stefan Rusterholz.
+# All rights reserved.
+# See LICENSE.txt for permissions.
+#++
+
+
+
+require 'ruby/range/stepped'
+require 'event/at'
+require 'event/every'
+require 'event/timed'
+
+
+
+#	== Description
+#	Allows to schedule things (furtherly called 'events') in one
+#	of several ways. Scheduled provides the methods to determine
+#	when this event will be executed next, when it was executed
+#	previuosly or how many seconds are left until the next execution.
+#	If a block is provided at creation it will execute that block
+#	everytime the event is due.
+#	
+#	== Synopsis
+#   # calls go_check_mails every 10 minutes, starting in 1h, ending 24h later
+#   check_mail_event	= Event.every(600, :start => Time.now+3600, :stop => Time.now+90000) { |event|
+#   	go_check_mails(...)
+#   }
+#   # deactivate it for the next 30 minutes
+#   # be aware only calling on/off will leave the Scheduled#next the same
+#   check_mail_event.off
+#   sleep(30*60)
+#
+#   # avoid that after 'on' the block get's called as many times as it was missed due to off
+#   check_mail_event.postpone
+#   # reactivate the check_mail_event
+#   check_mail_event.on
+#
+#   # let the mail checking be done 15s earlier this time
+#   check_mail_event.alter(-15)
+#   # see how many seconds are left to the next event
+#   puts check_mail_event.seconds_left.to_s
+#
+#   # let's the current thread sleep until check_mail_event is finished.
+#   check_mail_event.join
+#
+#   # this will be due? every hour, at minute 1, 2, 3, 4, 5, at seconds 0 and 30.
+#   # see Scheduled.timed for more information
+#   cron_like	= Scheduled.timed("*", (1..5), [0, 30]) { |event| ...do something... }
+#
+#   # this one will be due? every given
+#   specific_times	= Scheduled.at(Time.now+86400, Time.now+3600, Time.now+60)
+#
+#   # take a break at 09.15, 10.15, 11.15, 13.15, 14.15 and 15.15
+#   takeBreak	= Scheduled.timed([9,10,11,13,14,15], [15])
+#
+class Event
+	HOUR_DIVISORS   = [1, 2, 3, 4, 6, 8, 12, 24]
+	MINUTE_DIVISORS = [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60]
+	SECOND_DIVISORS = MINUTE_DIVISORS
+
+	include Comparable
+
+	# Time after which the event will be scheduled
+	attr_reader :start
+
+	# Time after which the event won't be scheduled anymore
+	attr_reader :stop
+
+	# Integer or nil, containing how many times the event will be due.
+	attr_reader :times
+
+	# Time object containing the time when the event is due next
+	# Will be nil if there's no next event possible to schedule (technically, not
+	# due to the event being finished, over stop or over times)
+	attr_reader :next
+
+	# Time object containing the time when the event was due the las time
+	attr_reader :previous
+
+	# Integer, counting how many times one_done was called.
+	attr_reader :count
+	
+	# :nodoc: FIXME, make it foolproof (no change of responsible scheduler)
+	attr_accessor :scheduler
+
+	class <<self
+		#private :new # FIXME I don't know what the fu* is going on but setting it public in descendants doesn't work here and I don't see why... :-S
+
+		# Creates a Schedule which is invoked in an interval, every <seconds> seconds.
+		# Postponing an every Schedule will set Schedule#next to Time.now+<seconds>.
+		def every(seconds, options={}, &block)
+			Every.new(seconds, options, &block)
+		end
+	
+		# Creates a Schedule which is invoked at specified hours, minutes
+		# and seconds of a day. Formats are:
+		# 	"*"		Every (hour, minute, second)
+		# 	4		Same as "0/4"
+		# 	"2/4"	Every 4 (hour, minutes, seconds), starting with 2
+		# 	[1,5]	Every specified (hour, minute, second) in the array
+		# 	0..5	Same as 0..5.to_a
+		# Postponing a timed Schedule will set @next to the next hour, minute, second-
+		# combination that gives a positive seconds_left.
+		def timed(hours=[0], minutes=[0], seconds=[0], options={}, &block)
+			Timed.new(hours, minutes, seconds, options, &block)
+		end
+	
+		# Creates a Schedule that is invoked at specified datetimes.
+		# Postponing an at Schedule will set @next to the first datetime that gives
+		# a positive seconds_left.
+		def at(*datetimes, &block)
+			At.new(datetimes, &block)
+		end
+	end
+
+	def initialize(options={}, &block)
+		@block    = block
+		@start    = options.delete(:start) || Time.now
+		@stop     = options.delete(:stop)
+		@times    = options.delete(:times)
+		@finished = false
+		@on       = true
+		@wakeup   = [] # threads to wakeup when finished
+
+		@previous = nil
+		@next     = nil
+		@count    = 0
+	end
+	
+	def call(*args)
+		@block.call(*args)
+	end
+
+	# Increment @count by one and return @next or nil if event is finished
+	def one_done(increment=true)
+		raise "no next" unless @next
+		raise "Cannot execute deactivated events." unless @on
+		@count += 1 if increment
+		@previous = @next
+		
+		return finished unless @next = calculate_next(@previous)
+		return finished if @times && @count >= @times
+		return finished	if @stop && @next > @stop
+		@next
+	end
+
+	# Will reinitalize the Scheduled event with start time beeing
+	# the current time. This results in seconds_left beeing the next
+	# positive amount (or nil if not postpone_stop and next event would
+	# be after @stop)
+	# Useful together with Scheduled#off, Scheduled#on
+	def reschedule(by_seconds=0, postpone_stop=true)
+		raise "Cannot postpone finished events." if @finished
+		@next	= calculate_first(Time.now+by_seconds)
+		finished if !@next || (!postpone_stop && @stop && @next > @stop)
+
+		update_scheduler
+		@next
+	end
+	alias postpone reschedule
+
+	# alterates the next-time exactly by "by_seconds",
+	# doesn't influence anything else.
+	def alter(by_seconds=0)
+		@next	+= by_seconds
+		update_scheduler
+		@next
+	end
+
+	# Switch the Scheduled event on.
+	# seconds_left will return seconds again.
+	# See Scheduled#off, Scheduled#on?, Scheduled#off?
+	def on
+		@on	= true
+		update_scheduler
+		self
+	end
+
+	# Switch the Scheduled event off.
+	# seconds_left will return nil.
+	# See Scheduled#on, Scheduled#on?, Scheduled#off?
+	def off
+		@on	= false
+		update_scheduler
+		self
+	end
+
+	# Define the Event as finished and remove it from the scheduler (if scheduled).
+	# seconds_left will return nil, <=> will be 1 or 0 (0 for other finished events)
+	def finished
+		@finished	= true
+		@wakeup.each { |thread| thread.wakeup }
+		nil
+	end
+	
+	# returns seconds left until next Timed
+	# returns nil if event is past @stop-datetime
+	# returns nil if event has been processed the specified amount of times
+	def seconds_left(time=nil)
+		(!@finished && @on && @next) && @next - (time||Time.now)
+	end
+
+	# returns how many times the event still has to be executed
+	def times_left
+		@times && @times-@count
+	end
+
+	# Whether Scheduled event is due now.
+	# A finished or off? event is never due?.
+	def due?(time=nil)
+		@on && !@finished && seconds_left(time) <= 0
+	end
+
+	# Whether an event has been declared as finished or not.
+	# Events that have any kind of limit (:stop, :times) can
+	# become automatically finished.
+	# Finished events are never due?.
+	def finished?
+		@finished
+	end
+
+	# Whether an event has been switched on (default).
+	def on?
+		@on
+	end
+
+	# Whether an event has been switched off (see Scheduled#off).
+	# Off? events are never due?.
+	def off?
+		!@on
+	end
+
+
+	# returns -1, 0 or 1 (smaller, equal to, bigger then other)
+	# nil-values for seconds_left are treaded like +INF
+	# <=> is overloaded, returning for
+	# * Event:   self.seconds_left <=> other.seconds_left (anything responding to .seconds_left)
+	# * Time:    self.next <=> other (only instances of Time, not Date nor DateTime)
+	# * Numeric: self.to_f <=> other.to_f (anything responding to .to_f)
+	def <=>(other)
+		return @next ? @next <=> other : 1 if other.kind_of?(Time)
+		if other.respond_to?(:seconds_left)
+			me    = seconds_left
+			other = other.seconds_left
+		else
+			me    = to_f
+			other = other.to_f
+		end
+		return me <=> other if me and other
+		return -1 if me
+		return  1 if other
+		0
+	end
+
+	# The left time to next due? as integer.
+	# IGNORES ON/OFF STATUS, use seconds_left for that.
+	def to_i
+		seconds_left.to_i
+	end
+
+	# The left time to next due? as float.
+	# IGNORES ON/OFF STATUS, use seconds_left for that.
+	def to_f
+		seconds_left.to_f
+	end
+	
+	def join
+		@wakeup << Thread.current
+		sleep unless finished?
+	end
+
+	# Normalizes inputs like "*", "1/12", 12, [1, 13], (1..5)
+	# to an array of all corresponding integers.
+	def extract_time_range(range, rangeEnd, divisors)
+		if range == "*" then
+			(0..rangeEnd).to_a
+		elsif (range.kind_of?(Integer) && divisors.include?(range)) then
+			(0..rangeEnd).stepped(range)
+		elsif (range.kind_of?(String) && !/^\d+\/\d+$/.match(range).nil?) then
+			a,b = *range.match(/(\d+)\/(\d+)/).captures
+			(a.to_i..rangeEnd).stepped(b.to_i)
+		elsif (range.kind_of?(Range) && range.begin >= 0 && range.end <= rangeEnd)
+			return range.to_a
+		elsif (range.kind_of?(Array))
+			return range
+		else
+			raise ArgumentError, "Invalid range #{range} (#{rangeEnd})"
+		end
+	end
+	
+	def update_scheduler
+		@scheduler.reschedule(self) if @scheduler
+	end
+end