symphony-metronome 0.2.2 → 0.3.0

data/lib/symphony/metronome/intervalexpression.rl

@@ -1,599 +0,0 @@
-# vim: set noet nosta sw=4 ts=4 ft=ragel :
-
-%%{
-	#
-	# Generate the actual code like so:
-	#    ragel -R -T1 -Ls inputfile.rl
-	#
-
-	machine interval_expression;
-
-	########################################################################
-	### A C T I O N S
-	########################################################################
-
-	action set_mark { mark = p }
-
-	action set_valid   { event.instance_variable_set( :@valid, true ) }
-	action set_invalid { event.instance_variable_set( :@valid, false ) }
-	action recurring   { event.instance_variable_set( :@recurring, true ) }
-
-	action start_time {
-		time = event.send( :extract, mark, p - mark )
-		event.send( :set_starting, time, :time )
-	}
-
-	action start_interval {
-		interval = event.send( :extract, mark, p - mark )
-		event.send( :set_starting, interval, :interval )
-	}
-
-	action execute_time {
-		time = event.send( :extract, mark, p - mark )
-		event.send( :set_interval, time, :time )
-	}
-
-	action execute_interval {
-		interval = event.send( :extract, mark, p - mark )
-		event.send( :set_interval, interval, :interval )
-	}
-
-	action execute_multiplier {
-		multiplier = event.send( :extract, mark, p - mark ).sub( / times/, '' )
-		event.instance_variable_set( :@multiplier, multiplier.to_i )
-	}
-
-	action ending_time {
-		time = event.send( :extract, mark, p - mark )
-		event.send( :set_ending, time, :time )
-	}
-
-	action ending_interval {
-		interval = event.send( :extract, mark, p - mark )
-		event.send( :set_ending, interval, :interval )
-	}
-
-	
-	########################################################################
-	### P R E P O S I T I O N S
-	########################################################################
-
-	recur_preposition    = ( 'every' | 'each' | 'per' | 'once' ' per'? ) @recurring;
-	time_preposition     = 'at' | 'on';
-	interval_preposition = 'in';
-
-	
-	########################################################################
-	### K E Y W O R D S
-	########################################################################
-
-	interval_times = 
-		( 'milli'? 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year' ) 's'?;
-
-	start_identifiers  = ( 'start' | 'begin' 'n'? ) 'ing'?;
-	exec_identifiers   = ('run' | 'exec' 'ute'? | 'do' );
-	ending_identifiers = ( ('for' | 'until' | 'during') | ('end'|'finish'|'stop'|'complet' 'e'?) 'ing'? );
-
-
-	########################################################################
-	### T I M E  S P E C S
-	########################################################################
-
-	# 1st
-	# 202nd
-	# 2015th
-	# ...
-	#
-	ordinals = (
-			( (digit+ - '1')? '1' 'st' ) |
-			( digit+?
-				( '1' digit 'th' ) |  # all '11s'
-				( '2' 'nd' )       |
-				( '3' 'rd' )       |
-				( [0456789] 'th' )
-			)
-		);
-
-	# 2014-05-01
-	# 2014-05-01 15:00
-	# 2014-05-01 15:00:30
-	#
-	fulldate = digit{4} '-' digit{2} '-' digit{2}
-		( space digit{2} ':' digit{2} ( ':' digit{2} )? )?;
-
-	# 10am
-	# 2:45pm
-	#
-	time = digit{1,2} ( ':' digit{2} )? ( 'am' | 'pm' );
-
-	# union of the above
-	date_or_time = fulldate | time;
-
-	# 20 seconds
-	# 5 hours
-	# 1 hour
-	# 2.5 hours
-	# an hour
-	# a minute
-	# other minute
-	#
-	interval = (
-			(( 'a' 'n'? | [1-9][0-9]* ( '.' [0-9]+ )? ) | 'other' | ordinals ) space
-		)? interval_times;
-
-
-	########################################################################
-	### A C T I O N   C H A I N S
-	########################################################################
-
-	start_time = date_or_time                         >set_mark %start_time;
-	start_interval = interval                     >set_mark %start_interval;
-
-	start_expression = ( (time_preposition space)? start_time ) |
-		( (interval_preposition space)? start_interval );
-
-	execute_time = date_or_time                     >set_mark %/execute_time;
-	execute_interval = interval                  >set_mark %execute_interval;
-	execute_multiplier = ( digit+ space 'times' )
-		>set_mark %execute_multiplier @recurring;
-
-	execute_expression = (
-		# regular dates and intervals
-			( time_preposition space execute_time ) |
-			( ( interval_preposition | recur_preposition ) space execute_interval )
-		) | (
-		# count + interval (10 times every minute)
-			execute_multiplier space ( recur_preposition space )? execute_interval
-		) |
-		# count for 'timeboxed' intervals
-			execute_multiplier;
-
-
-	ending_time = date_or_time                       >set_mark %ending_time;
-	ending_interval = interval                   >set_mark %ending_interval;
-
-	ending_expression = ( (time_preposition space)? ending_time ) |
-		( (interval_preposition space)? ending_interval );
-
-
-	########################################################################
-	### M A C H I N E S
-	########################################################################
-
-	Start = (
-		start:      start_identifiers space                   -> StartTime,
-		StartTime:  start_expression                          -> final
-	);
-
-	Interval = (
-		start:
-		Decorators: ( exec_identifiers space )?              -> ExecuteTime,
-		ExecuteTime: execute_expression                      -> final
-	);
-
-	Ending = (
-		start: space ending_identifiers space                -> EndingTime,
-		EndingTime: ending_expression                        -> final
-	);
-
-
-	main := (
-				( Start space Interval Ending? )   |
-				( Interval ( space Start )? Ending? ) |
-				( Interval Ending space Start )
-			) %set_valid @!set_invalid;
-}%%
-
-
-require 'symphony' unless defined?( Symphony )
-require 'symphony/metronome'
-require 'symphony/metronome/mixins'
-
-using Symphony::Metronome::TimeRefinements
-
-
-### Parse natural English expressions of times and intervals.
-###
-###  in 30 minutes
-###  once an hour
-###  every 15 minutes for 2 days
-###  at 2014-05-01
-###  at 2014-04-01 14:00:25
-###  at 2pm
-###  starting at 2pm once a day
-###  start in 1 hour from now run every 5 seconds end at 11:15pm
-###  every other hour
-###  once a day ending in 1 week
-###  run once a minute for an hour starting in 6 days
-###  run each hour starting at 2010-01-05 09:00:00
-###  10 times a minute for 2 days
-###  run 45 times every hour
-###  30 times per day
-###  start at 2010-01-02 run 12 times and end on 2010-01-03
-###  starting in an hour from now run 6 times a minute for 2 hours
-###  beginning a day from now, run 30 times per minute and finish in 2 weeks
-###  execute 12 times during the next 2 minutes
-###
-class Symphony::Metronome::IntervalExpression
-	include Comparable,
-	        Symphony::Metronome::TimeFunctions
-	extend Loggability
-
-	log_to :symphony
-
-	# Ragel accessors are injected as class methods/variables for some reason.
-	%% write data;
-
-	# Words/phrases in the expression that we'll strip/ignore before parsing.
-	COMMON_DECORATORS = [ 'and', 'then', /\s+from now/, 'the next' ];
-
-
-	########################################################################
-	### C L A S S   M E T H O D S
-	########################################################################
-
-	### Parse a schedule expression +exp+.
-	###
-	### Parsing defaults to Time.now(), but if passed a +time+ object,
-	### all contexual times (2pm) are relative to it.  If you know when
-	### an expression was generated, you can 'reconstitute' an interval
-	### object this way.
-	###
-	def self::parse( exp, time=nil )
-
-		# Normalize the expression before parsing
-		#
-		exp = exp.downcase.
-			gsub( /(?:[^[a-z][0-9][\.\-:]\s]+)/, '' ).   # . : - a-z 0-9 only
-			gsub( Regexp.union(COMMON_DECORATORS), '' ). # remove common decorator words
-			gsub( /\s+/, ' ' ).                          # collapse whitespace
-			gsub( /([:\-])+/, '\1' ).                    # collapse multiple - or : chars
-			gsub( /\.+$/, '' )                           # trailing periods
-
-		event = new( exp, time || Time.now )
-		data  = event.instance_variable_get( :@data )
-
-		# Ragel interface variables
-		#
-		key    = ''
-		mark   = 0
-		%% write init;
-		eof = pe
-		%% write exec;
-
-		# Attach final time logic and sanity checks.
-		event.send( :finalize )
-
-		return event
-	end
-
-
-	########################################################################
-	### I N S T A N C E   M E T H O D S
-	########################################################################
-
-	### Instantiate a new TimeExpression, provided an +expression+ string
-	### that describes when this event will take place in natural english,
-	### and a +base+ Time to perform calculations against.
-	###
-	private_class_method :new
-	def initialize( expression, base ) # :nodoc:
-		@exp  = expression
-		@data = expression.to_s.unpack( 'c*' )
-		@base = base
-
-		@valid      = false
-		@recurring  = false
-		@starting   = nil
-		@interval   = nil
-		@multiplier = nil
-		@ending     = nil
-	end
-
-
-	######
-	public
-	######
-
-	# Is the schedule expression parsable?
-	attr_reader :valid
-
-	# Does this event repeat?
-	attr_reader :recurring
-
-	# The valid start time for the schedule (for recurring events)
-	attr_reader :starting
-
-	# The valid end time for the schedule (for recurring events)
-	attr_reader :ending
-
-	# The interval to wait before the event should be acted on.
-	attr_reader :interval
-
-	# An optional interval multipler for expressing counts.
-	attr_reader :multiplier
-
-
-	### If this interval is on a stack somewhere and ready to
-	### fire, is it okay to do so based on the specified
-	### expression criteria?
-	###
-	### Returns +true+ if it should fire, +false+ if it should not
-	### but could at a later attempt, and +nil+ if the interval has
-	### expired.
-	###
-	def fire?
-		now = Time.now
-
-		# Interval has expired.
-		return nil if self.ending && now > self.ending
-
-		# Interval is not yet in its current time window.
-		return false if self.starting - now > 0
-
-		# Looking good.
-		return true
-	end
-
-
-	### Just return the original event expression.
-	###
-	def to_s
-		return @exp
-	end
-
-
-	### Inspection string.
-	###
-	def inspect
-		return ( "<%s:0x%08x valid:%s recur:%s expression:%p " +
-					"starting:%p interval:%p ending:%p>" ) % [
-			self.class.name,
-			self.object_id * 2,
-			self.valid,
-			self.recurring,
-			self.to_s,
-			self.starting,
-			self.interval,
-			self.ending
-		]
-	end
-
-
-	### Comparable interface, order by interval, 'soonest' first.
-	###
-	def <=>( other )
-		return self.interval <=> other.interval
-	end
-
-
-	#########
-	protected
-	#########
-
-	### Given a +start+ and +ending+ scanner position,
-	### return an ascii representation of the data slice.
-	###
-	def extract( start, ending )
-		slice = @data[ start, ending ]
-		return '' unless slice
-		return slice.pack( 'c*' )
-	end
-
-
-	### Parse and set the starting attribute, given a +time_arg+
-	### string and the +type+ of string (interval or exact time)
-	###
-	def set_starting( time_arg, type )
-		@starting_args ||= []
-		@starting_args << time_arg
-
-		# If we already have seen a start time, it's possible the parser
-		# was non-deterministic and this action has been executed multiple
-		# times. Re-parse the complete date string, overwriting any previous.
-		time_arg = @starting_args.join( ' ' )
-
-		start = self.get_time( time_arg, type )
-		@starting = start
-
-		# If start time is expressed as a post-conditional (we've
-        # already got an end time) we need to recalculate the end
-		# as an offset from the start.  The original parsed ending
-		# arguments should have already been cached when it was
-		# previously set.
-		#
-		if self.ending && self.recurring
-			self.set_ending( *@ending_args )
-		end
-
-		return @starting
-	end
-
-
-	### Parse and set the interval attribute, given a +time_arg+
-	### string and the +type+ of string (interval or exact time)
-	###
-	### Perform consistency and sanity checks before returning an
-	### integer representing the amount of time needed to sleep before
-	### firing the event.
-	###
-	def set_interval( time_arg, type )
-		interval = nil
-		if self.starting && type == :time
-			raise Symphony::Metronome::TimeParseError, "That doesn't make sense, just use 'at [datetime]' instead"
-		else
-			interval = self.get_time( time_arg, type )
-			interval = interval - @base
-		end
-
-		@interval = interval
-		return @interval
-	end
-
-
-	### Parse and set the ending attribute, given a +time_arg+
-	### string and the +type+ of string (interval or exact time)
-	###
-	### Perform consistency and sanity checks before returning a
-	### Time object.
-	###
-	def set_ending( time_arg, type )
-		ending = nil
-
-		# Ending dates only make sense for recurring events.
-		#
-		if self.recurring
-			@ending_args = [ time_arg, type ] # squirrel away for post-set starts
-
-			# Make the interval an offset of the start time, instead of now.
-			#
-			# This is the contextual difference between:
-			#   every minute until 6 hours from now (ending based on NOW)
-			#   and
-			#   starting in a year run every minute for 1 month (ending based on start time)
-			#
-			if self.starting && type == :interval
-				diff = self.parse_interval( time_arg )
-				ending = self.starting + diff
-
-			# (offset from now)
-			#
-			else
-				ending = self.get_time( time_arg, type )
-			end
-
-			# Check the end time is after the start time.
-			#
-			if self.starting && ending < self.starting
-				raise Symphony::Metronome::TimeParseError, "recurring event ends before it begins"
-			end
-
-		else
-			self.log.debug "Ignoring ending date, event is not recurring."
-		end
-
-		@ending = ending
-		return @ending
-	end
-
-
-	### Perform finishing logic and final sanity checks before returning
-	### a parsed object.
-	###
-	def finalize
-		raise Symphony::Metronome::TimeParseError, "unable to parse expression" unless self.valid
-
-		# Ensure start time is populated.
-		#
-		unless self.starting
-			if self.recurring
-				@starting = @base
-			else
-				raise Symphony::Metronome::TimeParseError, "non-deterministic expression" if self.interval.nil?
-				@starting = @base + self.interval
-			end
-		end
-
-		# Alter the interval if a multiplier was specified.
-		#
-		if self.multiplier
-			if self.ending
-
-				# Regular 'count' style multipler with end date.
-				# (run 10 times a minute for 2 days)
-				# Just divide the current interval by the count.
-				#
-				if self.interval
-					@interval = self.interval.to_f / self.multiplier
-
-				# Timeboxed multiplier (start [date] run 10 times end [date])
-				# Evenly spread the interval out over the time window.
-				#
-				else
-					diff = self.ending - self.starting
-					@interval = diff.to_f / self.multiplier
-				end
-
-			# Regular 'count' style multipler (run 10 times a minute)
-			# Just divide the current interval by the count.
-			#
-			else
-				raise Symphony::Metronome::TimeParseError, "An end date or interval is required" unless self.interval
-				@interval = self.interval.to_f / self.multiplier
-			end
-		end
-	end
-
-
-	### Given a +time_arg+ string and a type (:interval or :time),
-	### dispatch to the appropriate parser.
-	###
-	def get_time( time_arg, type )
-		time = nil
-
-		if type == :interval
-			secs = self.parse_interval( time_arg )
-			time = @base + secs if secs
-		end
-
-		if type == :time
-			time = self.parse_time( time_arg )
-		end
-
-		raise Symphony::Metronome::TimeParseError, "unable to parse time" if time.nil?
-		return time
-	end
-
-
-	### Parse a +time_arg+ string (anything parsable buy Time.parse())
-	### into a Time object.
-	###
-	def parse_time( time_arg )
-		time = Time.parse( time_arg, @base ) rescue nil
-
-		# Generated date is in the past.
-		#
-		if time && @base > time
-
-			# Ensure future dates for ambiguous times (2pm)
-			time = time + 1.day if time_arg.length < 8
-
-			# Still in the past, abandon all hope.
-			raise Symphony::Metronome::TimeParseError, "attempt to schedule in the past" if @base > time
-		end
-
-		self.log.debug "Parsed %p (time) to: %p" % [ time_arg, time ]
-		return time
-	end
-
-
-	### Parse a +time_arg+ interval string ("30 seconds") into an
-	### Integer.
-	###
-	def parse_interval( interval_arg )
-		duration, span = interval_arg.split( /\s+/ )
-
-		# catch the 'a' or 'an' case (ex: "an hour")
-		duration = 1 if duration.index( 'a' ) == 0
-
-		# catch the 'other' case, ie: 'every other hour'
-		duration = 2 if duration == 'other'
-
-		# catch the singular case (ex: "hour")
-		unless span
-			span = duration
-			duration = 1
-		end
-
-		use_milliseconds = span.sub!( 'milli', '' )
-		interval = calculate_seconds( duration.to_f, span.to_sym )
-
-		# milliseconds
-		interval = duration.to_f / 1000 if use_milliseconds
-
-		self.log.debug "Parsed %p (interval) to: %p" % [ interval_arg, interval ]
-		return interval
-	end
-
-end # class TimeExpression
-