schedulability 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 50fb75892fe34a90d09b2b053f07d7e60209aee6
-  data.tar.gz: fc229096b9d9395dbc2717194a4b6391440f6266
+  metadata.gz: 8eded0bd62f85e98614fb6f8c2f57300036be176
+  data.tar.gz: b7fc81a9f3bae2ed902bc6f123ed6d9537012675
 SHA512:
-  metadata.gz: 774433974b322f79241580ff4378173f009526cfad3b93a49bea994719fa8df0dbb15d0393bd9fe046c9a3a4ed6be9a842c1bc7abdd110449c763bb77276d2a5
-  data.tar.gz: 2cc54b3bfc288409a73eeea2c68881354766c7fde08c47aa77cfc41392fc104c402f131ea4efe3f3e2f4a706fecbecac652fdda05be4d17c6ca62400c57755c2
+  metadata.gz: 9e8d048d6cd378fc9b0b5532d1c7acc2ed667ea885eaec6cd1cdf6b0e8e59e7cc3a4e8f5e6d016d231b251b6d0b50c0659b921f0eff1a518128aa5ec408cc622
+  data.tar.gz: ca2bbea2c50b9fce77c3ff4b3d5ab2a2c0bf037ce278bde3fc6e5bf1dce60eed84f2f11c1789af515947e528116048c510de9bb1c293571352af1bafd173f704

data/ChangeLog

@@ -1,8 +1,47 @@
+2016-07-14  Jason Rogers  <jacaetevha@gmail.com>
+
+	* lib/schedulability/parser.rb, spec/schedulability/schedule_spec.rb:
+	[PATCH] bug fixes for the 0th second or minute, and the 59th second
+	From bc2864a832fa60bc39958b9aaa26e6f546936539 Mon Sep 17 00:00:00
+	2001 or minute
+	--- lib/schedulability/parser.rb | 8 +++---
+	spec/schedulability/schedule_spec.rb | 52
+	++++++++++++++++++++++++++++++++++++ 2 files changed, 57
+	insertions(+), 3 deletions(-)
+	[0f59486cf040] [github/master, tip]
+
+2016-07-15  Michael Granger  <ged@FaerieMUD.org>
+
+	* README.md, Rakefile, lib/schedulability/schedule.rb,
+	schedulability.gemspec, spec/schedulability/schedule_spec.rb:
+	Fix some README discrepancies and implement some missing stuff
+	[b99801aa4e3f]
+
+	* lib/schedulability.rb, lib/schedulability/mixins.rb,
+	lib/schedulability/parser.rb, lib/schedulability/schedule.rb,
+	spec/schedulability/mixins_spec.rb,
+	spec/schedulability/parser_spec.rb,
+	spec/schedulability/schedule_spec.rb:
+	Implement a simplistic Schedule#to_s, add some missing specs.
+	[eda686d951b7]
+
 2015-12-30  Michael Granger  <ged@FaerieMUD.org>
 
+	* .hgtags:
+	Added tag v0.1.0 for changeset 45f35fbd585b
+	[3e26b7e59243]
+
+	* .hgsigs:
+	Added signature for changeset 0f46dc0d8056
+	[45f35fbd585b] [v0.1.0]
+
+	* cert/ged.pem, cert/mahlon.pem:
+	Add gem certs.
+	[0f46dc0d8056]
+
 	* .hgtags:
 	Backed out tag for v0.1.0; trying again
-	[342ac3d0b6db] [tip]
+	[342ac3d0b6db]
 
 	* Rakefile, schedulability.gemspec:
 	Explicitly set urls in the Hoespec, since Hoe can't read Markdown.
@@ -38,7 +77,7 @@
 	lib/schedulability/schedule.rb,
 	spec/schedulability/schedule_spec.rb:
 	Implement negated periods; invert the meaning of empty schedule.
-	[9a401a820265] [github/master]
+	[9a401a820265]
 
 	* lib/schedulability/parser.rb, lib/schedulability/schedule.rb,
 	spec/schedulability/schedule_spec.rb:

data/History.md

@@ -1,3 +1,16 @@
+## v0.2.0 [2016-07-20] Michael Granger <ged@FaerieMUD.org>
+
+Bugfixes:
+- fixes for the 0th second or minute, and the 59th second
+  (thanks to Jason Rogers <jacaetevha@gmail.com> for the patch)
+- Make Schedule#empty? take negative periods into account
+
+Enhancements
+- Add missing Schedule#overlaps? and #exclusive predicate methods.
+- Add a Schedule#to_s that stringifies them back into schedule descriptions
+
+
+
 ## v0.1.0 [2015-12-30] Michael Granger <ged@FaerieMUD.org>
 
 First release.  Happy New Year!

data/Manifest.txt

@@ -11,5 +11,7 @@ lib/schedulability/mixins.rb
 lib/schedulability/parser.rb
 lib/schedulability/schedule.rb
 spec/helpers.rb
+spec/schedulability/mixins_spec.rb
+spec/schedulability/parser_spec.rb
 spec/schedulability/schedule_spec.rb
 spec/schedulability_spec.rb

data/README.md

@@ -15,28 +15,41 @@ github
 
 ## Description
 
-Schedulability is a library for describing scheduled time. You can specify one or more periods of time using a simple syntax, then combine them to describe more-complex schedules.
+Schedulability is a library for describing scheduled time. You can specify one
+or more periods of time using a simple syntax, then combine them to describe
+more-complex schedules.
 
 
 ## Usage
 
-Schedules are represented with Schedulability::Schedule objects, which are empty by default:
+Schedules are represented with Schedulability::Schedule objects, which are
+empty by default:
 
     schedule = Schedulability::Schedule.new
     # => #<Schedulability::Schedule:0x007ffcf2b982b8 (empty)>
 
 An empty Schedule has no time restrictions, and will match any time.
 
-To specify matching times, you'll need to construct a Schedule with one or more periods.
+To specify matching times, you'll need to construct a Schedule with one or more
+periods.
 
 
 ### Periods
 
-A schedule is specified as a String that contains a comma-separated list of period descriptions. The string `"never"` can be specified to explicitly create a schedule which will not match any time.
+A schedule is made up of zero or more positive periods, and zero or more
+negative periods. A time is within the schedule if at least one positive period
+and no negative periods match it.
+
+Periods are specified as a String that contains a comma-separated list of
+period descriptions. The string `"never"` can be specified to explicitly create
+a schedule which will not match any time.
 
 A period description is of the form
 
-    scale {range [range ...]} [scale {range [range ...]}]
+    [!] scale {range [range ...]} [scale {range [range ...]}]
+
+Negative periods begin with a `!`; you may also use `not` or `except` for
+readability.
 
 Scale must be one of nine different scales (or their equivalent codes):
 
@@ -54,25 +67,39 @@ Scale must be one of nine different scales (or their equivalent codes):
     minute |  min  | 0-59
     second |  sec  | 0-59
 
-The same scale type may be specified multiple times. Additional scales are unioned with the ranges defined by previous scales of the same type in the same sub-period.
+The same scale type may be specified multiple times. Additional scales are
+unioned with the ranges defined by previous scales of the same type in the same
+sub-period.
 
-A `range` is an exclusive Time range in the form:
+A `range` is specified in the form:
 
-    t
+    <range value>
 or
 
-    t1-t2
+    <range value>-<range value>
 
-For two-value ranges, the range is defined as the period between `t1` and `t2`. Scales which are in
-seconds granularity are exclusive of their end value, but the rest are inclusive. For example, `hr {9am-5pm}` means 9:00:00 AM until 4:59:59 PM, but `wd {Wed-Sat}` runs until one second before midnight on Saturday.
+For two-value ranges, the range is defined as the period between the first and
+second `range value`s. Scales which are in seconds granularity are exclusive of
+their end value, but the rest are inclusive. For example, `hr {9am-5pm}` means
+9:00:00 AM until 4:59:59 PM, but `wd {Wed-Sat}` runs until one second before
+midnight on Saturday.
 
-If the first value is larger than the second value (e.g. `min {20-10}`), the range wraps (except when the scale specification is `year`). For example, `month {9-2}` is the same as specifying `month {1-2 9-12}` or `month {1-2} month {9-12}` or even `month {Jan-Feb Sep-Dec}`.
+If the first value is larger than the second value (e.g. `min {20-10}`), the
+range wraps (except when the scale specification is `year`). For example,
+`month {9-2}` is the same as specifying `month {1-2 9-12}` or `month {1-2}
+month {9-12}` or even `month {Jan-Feb Sep-Dec}`.
 
-The range specified by the single-value specification is implicitly between the value of `t` and its next sequential whole value. For example, `hr {9}` is the same as specifying `hr {9-10}`, `mday {15}` is the same as `mday {15-16}`, etc.
+The range specified by the single-value specification is implicitly between the
+`range value` and its next sequential whole value. For example, `hr {9}` is the
+same as specifying `hr {9-10}`, `mday {15}` is the same as `mday {15-16}`, etc.
 
-Neither extra whitespace or case are significant in a period description. Scales must be specified either in long form (`year`, `month`, `week`, etc.) or in code form (`yr`, `mo`, `wk`, etc.). Scale forms may be mixed in a period statement.
+Neither extra whitespace nor case are significant in a period description.
+Scales must be specified either in long form (`year`, `month`, `week`, etc.) or
+in code form (`yr`, `mo`, `wk`, etc.). Scale forms may be mixed in a period
+statement.
 
-Values for week days can be abbreviated to two characters (`Wednesday` == `Wed` == `we`), and months can be abbreviated to three (`September` == `Sep`).
+Values for week days and months can be abbreviated to three characters
+(`Wednesday` == `Wed`, `September` == `Sep`).
 
 
 #### Period Examples
@@ -82,8 +109,8 @@ Values for week days can be abbreviated to two characters (`Wednesday` == `Wed`
 <dd>Monday through Friday, 9am to 5pm</dd>
 
 <dt><code>wd {Mon Wed Fri} hr {9am-4pm}, wd{Tue Thu} hr {9am-2pm}</code></dt>
-<dd>Monday through Friday, 9:00:00am to 3:59:59pm on Monday, Wednesday, and Friday, 
-  and 9:00:00am to 1:59:59pm on Tuesday and Thursday</dd>
+<dd>Monday through Friday, 9:00:00am to 3:59:59pm on Monday, Wednesday, and 
+	Friday, and 9:00:00am to 1:59:59pm on Tuesday and Thursday</dd>
 
 <dt><code>wk {1 3 5} wd {Mon-Fri} hr {9am-5pm}</code></dt>
 <dd>Mon-Fri 9:00:00am-4:59:59pm, on odd weeks in the month</dd>
@@ -94,6 +121,9 @@ Values for week days can be abbreviated to two characters (`Wednesday` == `Wed`
 <dt><code>mo {Nov-Feb}</code></dt>
 <dd>The same thing (Winter) as a wrapped range.</dd>
 
+<dt><code>not mo {Mar-Oct}</code></dt>
+<dd>The same thing (Winter) as a negative range.</dd>
+
 <dt><code>mo {jan feb nov dec}</code></dt>
 <dd>Northern Winter as single months</dd>
 
@@ -106,12 +136,16 @@ Values for week days can be abbreviated to two characters (`Wednesday` == `Wed`
 <dt><code>minute { 0-29 }</code></dt>
 <dd>The first half of every hour.</dd>
 
-<dt><code>hour { 12am-12pm }</code></dt>
+<dt><code>hour { 12am - 12pm }</code></dt>
 <dd>During the morning.</dd>
 
 <dt><code>sec {0-4 10-14 20-24 30-34 40-44 50-54}</code></dt>
 <dd>Alternating 5-second periods every hour.</dd>
 
+<dt><code>wd {mon wed fri} hr {8am - 5pm}, except day {1}</code></dt>
+<dd>Every Monday, Wednesday, and Friday from 8am until 4:59:59 PM, except on 
+	the first of the month.</dd>
+
 <dt><code>wd {1 3 5 7} min {0-29}, wd {2 4 6} min {30-59}</code></dt>
 <dd>Every first half-hour on alternating week days, and the second half-hour the
   rest of the week.</dd>
@@ -121,8 +155,8 @@ Values for week days can be abbreviated to two characters (`Wednesday` == `Wed`
 ### Schedule Objects
 
 Schedules are immutable after they're created, but they have mutator methods to
-allow you to compose the schedule you want by combining them, or by using mutator
-methods that return a changed copy of the original:
+allow you to compose the schedule you want by combining them, or by using
+mutator methods that return a changed copy of the original:
 
     weekend = Schedulability::Schedule( "wd {Sat - Sun}" )
     weekdays = Schedulability::Schedule( "wd {Mon - Fri}" )
@@ -159,14 +193,6 @@ methods that return a changed copy of the original:
         send_email( "Stuff happened." )
     end
 
-	### Enumerators
-	on_duty.each_minute
-	# => #<Enumerator: ...>
-	on_duty.each_hour
-	# => #<Enumerator: ...>
-	on_duty.each_day
-	# => #<Enumerator: ...>
-
 
 ## Prerequisites
 
@@ -194,18 +220,20 @@ and generate the API documentation.
 
 ## License
 
-This library borrows much of its schedule description syntax and several implementation strategies from the Time::Period Perl module by Patrick Ryan, used under the terms of the Perl Artistic License.
-
-  Patrick Ryan <perl@pryan.org> wrote it.
-  Paul Boyd <pboyd@cpan.org> fixed a few bugs.
+This library borrows much of its schedule description syntax and several
+implementation strategies from the Time::Period Perl module by Patrick Ryan,
+used under the terms of the Perl Artistic License.
 
-  Copyright (c) 1997 Patrick Ryan. All rights reserved. This Perl 
-  module uses the conditions given by Perl. This module may only
-  be distributed and or modified under the conditions given by Perl.
+> Patrick Ryan <perl@pryan.org> wrote it.
+> Paul Boyd <pboyd@cpan.org> fixed a few bugs.
+> 
+> Copyright (c) 1997 Patrick Ryan. All rights reserved. This Perl 
+> module uses the conditions given by Perl. This module may only
+> be distributed and or modified under the conditions given by Perl.
 
 The rest is:
 
-Copyright (c) 2015, Michael Granger and Mahlon E. Smith
+Copyright (c) 2015-2016, Michael Granger and Mahlon E. Smith
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/Rakefile

@@ -33,9 +33,9 @@ hoespec = Hoe.spec 'schedulability' do
 	self.dependency 'loggability',     '~> 0.11'
 
 	self.dependency 'timecop',         '~> 0.8', :developer
-	self.dependency 'hoe-deveiate',    '~> 0.4', :developer
-	self.dependency 'hoe-bundler',     '~> 1.2', :developer
-	self.dependency 'simplecov',       '~> 0.7', :developer
+	self.dependency 'rdoc',            '~> 4.2', :developer
+	self.dependency 'hoe-deveiate',    '~> 0.8', :developer
+	self.dependency 'simplecov',       '~> 0.12', :developer
 
 	self.license "BSD-3-Clause"
 	self.require_ruby_version( '>=2.2.0' )
@@ -67,7 +67,7 @@ if File.directory?( '.hg' )
 	RDoc::Task.new( 'docs' ) do |rdoc|
 	    rdoc.main = "README.md"
 	    rdoc.rdoc_files.include( "*.rdoc", "*.md", "ChangeLog", "lib/**/*.rb" )
-	    rdoc.generator = :sixfish
+	    rdoc.generator = :fivefish
 		rdoc.title = 'Schedulability'
 	    rdoc.rdoc_dir = 'doc'
 	end

data/lib/schedulability.rb

@@ -10,10 +10,10 @@ module Schedulability
 	extend Loggability
 
 	# Package version constant
-	VERSION = '0.1.0'
+	VERSION = '0.2.0'
 
 	# VCS revision
-	REVISION = %q$Revision: 39de155fb60f $
+	REVISION = %q$Revision: bd7566ac26d5 $
 
 
 	# Loggability API -- set up a logger for Schedulability objects
@@ -24,5 +24,9 @@ module Schedulability
 	autoload :Parser, 'schedulability/parser'
 	autoload :TimeRefinements, 'schedulability/mixins'
 
+	autoload :Error, 'schedulability/exceptions'
+	autoload :ParseError, 'schedulability/exceptions'
+	autoload :RangeError, 'schedulability/exceptions'
+
 end # module Schedulability
 

data/lib/schedulability/mixins.rb

@@ -120,6 +120,81 @@ module Schedulability
 			end
 
 		end # refine Numeric
+
+
+		refine Time do
+
+			# Approximate Time Constants (in seconds)
+			MINUTES = 60
+			HOURS   = 60  * MINUTES
+			DAYS    = 24  * HOURS
+			WEEKS   = 7   * DAYS
+			MONTHS  = 30  * DAYS
+			YEARS   = 365.25 * DAYS
+
+
+			### Returns +true+ if the receiver is a Time in the future.
+			def future?
+				return self > Time.now
+			end
+
+
+			### Returns +true+ if the receiver is a Time in the past.
+			def past?
+				return self < Time.now
+			end
+
+
+			### Return a description of the receiving Time object in relation to the current
+			### time.
+			###
+			### Example:
+			###
+			###    "Saved %s ago." % object.updated_at.as_delta
+			def as_delta
+				now = Time.now
+				if now > self
+					seconds = now - self
+					return "%s ago" % [ timeperiod(seconds) ]
+				else
+					seconds = self - now
+					return "%s from now" % [ timeperiod(seconds) ]
+				end
+			end
+
+
+			### Return a description of +seconds+ as the nearest whole unit of time.
+			def timeperiod( seconds )
+				return case
+					when seconds < MINUTES - 5
+						'less than a minute'
+					when seconds < 50 * MINUTES
+						if seconds <= 89
+							"a minute"
+						else
+							"%d minutes" % [ (seconds.to_f / MINUTES).ceil ]
+						end
+					when seconds < 90 * MINUTES
+						'about an hour'
+					when seconds < 18 * HOURS
+						"%d hours" % [ (seconds.to_f / HOURS).ceil ]
+					when seconds < 30 * HOURS
+						'about a day'
+					when seconds < WEEKS
+						"%d days" % [ (seconds.to_f / DAYS).ceil ]
+					when seconds < 2 * WEEKS
+						'about a week'
+					when seconds < 3 * MONTHS
+						"%d weeks" % [ (seconds.to_f / WEEKS).round ]
+					when seconds < 18 * MONTHS
+						"%d months" % [ (seconds.to_f / MONTHS).ceil ]
+					else
+						"%d years" % [ (seconds.to_f / YEARS).ceil ]
+					end
+			end
+
+		end # refine Time
+
 	end # module TimeRefinements
 
 end # module Schedulability

data/lib/schedulability/parser.rb

@@ -56,6 +56,35 @@ module Schedulability::Parser
 	module_function
 	###############
 
+	### Normalize an array of parsed periods into a human readable string.
+	def stringify( periods )
+		strings = []
+		periods.each do |period|
+			period_string = []
+			period.sort_by{|k, v| k}.each do |scale, ranges|
+				range_string = ""
+				range_string << "%s { " % [ scale.to_s ]
+
+				range_strings = ranges.each_with_object( [] ).each do |range, acc|
+					if range.min == range.max
+						acc << range.min
+					elsif range.exclude_end?
+						acc << "%d-%d" % [ range.min, range.max + 1 ]
+					else
+						acc << "%d-%d" % [ range.min, range.max ]
+					end
+				end
+
+				range_string << range_strings.join( ' ' ) << " }"
+				period_string << range_string
+			end
+			strings << period_string.join( ' ' )
+		end
+
+		return strings.join( ', ' )
+	end
+
+
 	### Scan +expression+ for periods and return them in an Array.
 	def extract_periods( expression )
 		positive_periods = []
@@ -64,7 +93,6 @@ module Schedulability::Parser
 		expression.strip.downcase.split( /\s*,\s*/ ).each do |subexpr|
 			hash, negative = self.extract_period( subexpr )
 			if negative
-				self.log.debug "Adding %p to the negative "
 				negative_periods << hash
 			else
 				positive_periods << hash
@@ -81,7 +109,6 @@ module Schedulability::Parser
 		scanner = StringScanner.new( expression )
 
 		negative = scanner.skip( /\s*(!|not |except )\s*/ )
-		self.log.debug "Period %p is %snegative!" % [ expression, negative ? "" : "not " ]
 
 		while scanner.scan( PERIOD_PATTERN )
 			ranges = scanner[:ranges].strip
@@ -187,7 +214,7 @@ module Schedulability::Parser
 
 	### Return an Array of Integer minute Ranges for the specified +ranges+ expression.
 	def extract_minute_ranges( ranges )
-		return self.extract_ranges( :minute, ranges, 0, 59 ) do |val|
+		return self.extract_ranges( :minute, ranges, 0, 60 ) do |val|
 			Integer( strip_leading_zeros(val) )
 		end
 	end
@@ -195,7 +222,7 @@ module Schedulability::Parser
 
 	### Return an Array of Integer second Ranges for the specified +ranges+ expression.
 	def extract_second_ranges( ranges )
-		return self.extract_ranges( :second, ranges, 0, 59 ) do |val|
+		return self.extract_ranges( :second, ranges, 0, 60 ) do |val|
 			Integer( strip_leading_zeros(val) )
 		end
 	end
@@ -233,7 +260,6 @@ module Schedulability::Parser
 
 		ints = ranges.split( /(?<!-)\s+(?!-)/ ).flat_map do |range|
 			min, max = range.split( /\s*-\s*/, 2 )
-			self.log.debug "Min = %p, max = %p" % [ min, max ]
 
 			min = yield( min )
 			raise Schedulability::ParseError, "invalid %s value: %p" % [ scale, min ] unless
@@ -243,10 +269,8 @@ module Schedulability::Parser
 			max = yield( max )
 			raise Schedulability::ParseError, "invalid %s value: %p" % [ scale, max ] unless
 				valid_range.cover?( max )
-			self.log.debug "Parsed min = %p, max = %p" % [ min, max ]
 
 			if min > max
-				self.log.debug "wrapped: %d-%d and %d-%d" % [ minval, max, min, maxval ]
 				Range.new( minval, max, exclude_end ).to_a +
 					Range.new( min, maxval, false ).to_a
 			else
@@ -261,8 +285,6 @@ module Schedulability::Parser
 	### Coalese an Array of non-contiguous Range objects from the specified +ints+ for +scale+.
 	def coalesce_ranges( ints, scale )
 		exclude_end = EXCLUSIVE_RANGED_SCALES.include?( scale )
-		self.log.debug "Coalescing %d ints to Ranges (%p, %s)" %
-			[ ints.size, ints, exclude_end ? "exclusive" : "inclusive" ]
 		ints.flatten!
 		return [] if ints.empty?
 
@@ -276,8 +298,6 @@ module Schedulability::Parser
 			last_val = values.last
 			last_val += 1 if exclude_end
 			Range.new( values.first, last_val, exclude_end )
-		end.tap do |ranges|
-			self.log.debug "Coalesced range integers to Ranges: %p" % [ ranges ]
 		end
 	end
 
@@ -302,8 +322,10 @@ module Schedulability::Parser
 
 
 	### Return a copy of the specified +val+ with any leading zeros stripped.
+	### If the resulting string is empty, return "0".
 	def strip_leading_zeros( val )
-		return val.sub( /\A0+/, '' )
+		return val.sub( /\A0+(?!$)/, '' )
 	end
 
 end # module Schedulability::Parser
+

data/lib/schedulability/schedule.rb

@@ -46,7 +46,7 @@ class Schedulability::Schedule
 
 	### Returns +true+ if the schedule doesn't have any time periods.
 	def empty?
-		return self.positive_periods.empty?
+		return self.positive_periods.empty? && self.negative_periods.empty?
 	end
 
 
@@ -62,7 +62,6 @@ class Schedulability::Schedule
 				time.to_time
 			else
 				time_obj = Time.parse( time.to_s )
-				self.log.debug "Parsed %p to time %p" % [ time, time_obj ]
 				time_obj
 			end
 
@@ -86,6 +85,22 @@ class Schedulability::Schedule
 	end
 
 
+	### Returns +true+ if the schedule has any times which overlap those of +other_schedule+.
+	def overlaps?( other_schedule )
+		return ! self.exclusive?( other_schedule )
+	end
+	alias_method :overlaps_with?, :overlaps?
+
+
+	### Returns +true+ if the schedule does not have any times which overlap those
+	### of +other_schedule+.
+	def exclusive?( other_schedule )
+		return ( self & other_schedule ).empty?
+	end
+	alias_method :exclusive_of?, :exclusive?
+	alias_method :is_exclusive_of?, :exclusive?
+
+
 	### Returns +true+ if the time periods for +other_schedule+ are the same as those for the
 	### receiver.
 	def ==( other_schedule )
@@ -125,6 +140,17 @@ class Schedulability::Schedule
 	end
 
 
+	### Return a string from previously parsed Schedule period objects.
+	def to_s
+		str = Schedulability::Parser.stringify( self.positive_periods )
+		unless self.negative_periods.empty?
+			str << ", not %s" % [ Schedulability::Parser.stringify(self.negative_periods) ]
+		end
+
+		return str
+	end
+
+
 	#######
 	private
 	#######
@@ -161,7 +187,6 @@ class Schedulability::Schedule
 		when :wk
 			return ( time.day / 7.0 ).ceil
 		when :yr
-			self.log.debug "Year match: %p" % [ time.year ]
 			return time.year
 		else
 			# If this happens, it's likely a bug in the parser.

data/spec/schedulability/mixins_spec.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../helpers'
+
+require 'schedulability/mixins'
+
+
+describe Schedulability, 'mixins' do
+
+
+	describe Schedulability::TimeRefinements do
+
+		using( described_class )
+
+
+		describe "used to extend Numeric objects" do
+
+			SECONDS_IN_A_MINUTE    = 60
+			SECONDS_IN_AN_HOUR     = SECONDS_IN_A_MINUTE * 60
+			SECONDS_IN_A_DAY       = SECONDS_IN_AN_HOUR * 24
+			SECONDS_IN_A_WEEK      = SECONDS_IN_A_DAY * 7
+			SECONDS_IN_A_FORTNIGHT = SECONDS_IN_A_WEEK * 2
+			SECONDS_IN_A_MONTH     = SECONDS_IN_A_DAY * 30
+			SECONDS_IN_A_YEAR      = Integer( SECONDS_IN_A_DAY * 365.25 )
+
+
+			it "can calculate the number of seconds for various units of time" do
+				expect( 1.second ).to eq( 1 )
+				expect( 14.seconds ).to eq( 14 )
+
+				expect( 1.minute ).to eq( SECONDS_IN_A_MINUTE )
+				expect( 18.minutes ).to eq( SECONDS_IN_A_MINUTE * 18 )
+
+				expect( 1.hour ).to eq( SECONDS_IN_AN_HOUR )
+				expect( 723.hours ).to eq( SECONDS_IN_AN_HOUR * 723 )
+
+				expect( 1.day ).to eq( SECONDS_IN_A_DAY )
+				expect( 3.days ).to eq( SECONDS_IN_A_DAY * 3 )
+
+				expect( 1.week ).to eq( SECONDS_IN_A_WEEK )
+				expect( 28.weeks ).to eq( SECONDS_IN_A_WEEK * 28 )
+
+				expect( 1.fortnight ).to eq( SECONDS_IN_A_FORTNIGHT )
+				expect( 31.fortnights ).to eq( SECONDS_IN_A_FORTNIGHT * 31 )
+
+				expect( 1.month ).to eq( SECONDS_IN_A_MONTH )
+				expect( 67.months ).to eq( SECONDS_IN_A_MONTH * 67 )
+
+				expect( 1.year ).to eq( SECONDS_IN_A_YEAR )
+				expect( 13.years ).to eq( SECONDS_IN_A_YEAR * 13 )
+			end
+
+
+			it "can calculate various time offsets" do
+				starttime = Time.now
+
+				expect( 1.second.after( starttime ) ).to eq( starttime + 1 )
+				expect( 18.seconds.from_now ).to be_within( 10.seconds ).of( starttime + 18 )
+
+				expect( 1.second.before( starttime ) ).to eq( starttime - 1 )
+				expect( 3.hours.ago ).to be_within( 10.seconds ).of( starttime - 10800 )
+			end
+
+		end
+
+
+		context "used to extend Time objects" do
+
+			it "makes them aware of whether they're in the future or not" do
+				Timecop.freeze do
+					time = Time.now
+					expect( time.future? ).to be_falsey
+
+					future_time = time + 1
+					expect( future_time.future? ).to be_truthy
+
+					past_time = time - 1
+					expect( past_time.future? ).to be_falsey
+				end
+			end
+
+
+			it "makes them aware of whether they're in the past or not" do
+				Timecop.freeze do
+					time = Time.now
+					expect( time.past? ).to be_falsey
+
+					future_time = time + 1
+					expect( future_time.past? ).to be_falsey
+
+					past_time = time - 1
+					expect( past_time.past? ).to be_truthy
+				end
+			end
+
+
+			it "adds the ability to express themselves as an offset in English" do
+				Timecop.freeze do
+					expect( 1.second.ago.as_delta ).to eq( 'less than a minute ago' )
+					expect( 1.second.from_now.as_delta ).to eq( 'less than a minute from now' )
+
+					expect( 1.minute.ago.as_delta ).to eq( 'a minute ago' )
+					expect( 1.minute.from_now.as_delta ).to eq( 'a minute from now' )
+					expect( 68.seconds.ago.as_delta ).to eq( 'a minute ago' )
+					expect( 68.seconds.from_now.as_delta ).to eq( 'a minute from now' )
+					expect( 2.minutes.ago.as_delta ).to eq( '2 minutes ago' )
+					expect( 2.minutes.from_now.as_delta ).to eq( '2 minutes from now' )
+					expect( 38.minutes.ago.as_delta ).to eq( '38 minutes ago' )
+					expect( 38.minutes.from_now.as_delta ).to eq( '38 minutes from now' )
+
+					expect( 1.hour.ago.as_delta ).to eq( 'about an hour ago' )
+					expect( 1.hour.from_now.as_delta ).to eq( 'about an hour from now' )
+					expect( 75.minutes.ago.as_delta ).to eq( 'about an hour ago' )
+					expect( 75.minutes.from_now.as_delta ).to eq( 'about an hour from now' )
+
+					expect( 2.hours.ago.as_delta ).to eq( '2 hours ago' )
+					expect( 2.hours.from_now.as_delta ).to eq( '2 hours from now' )
+					expect( 14.hours.ago.as_delta ).to eq( '14 hours ago' )
+					expect( 14.hours.from_now.as_delta ).to eq( '14 hours from now' )
+
+					expect( 22.hours.ago.as_delta ).to eq( 'about a day ago' )
+					expect( 22.hours.from_now.as_delta ).to eq( 'about a day from now' )
+					expect( 28.hours.ago.as_delta ).to eq( 'about a day ago' )
+					expect( 28.hours.from_now.as_delta ).to eq( 'about a day from now' )
+
+					expect( 36.hours.ago.as_delta ).to eq( '2 days ago' )
+					expect( 36.hours.from_now.as_delta ).to eq( '2 days from now' )
+					expect( 4.days.ago.as_delta ).to eq( '4 days ago' )
+					expect( 4.days.from_now.as_delta ).to eq( '4 days from now' )
+
+					expect( 1.week.ago.as_delta ).to eq( 'about a week ago' )
+					expect( 1.week.from_now.as_delta ).to eq( 'about a week from now' )
+					expect( 8.days.ago.as_delta ).to eq( 'about a week ago' )
+					expect( 8.days.from_now.as_delta ).to eq( 'about a week from now' )
+
+					expect( 15.days.ago.as_delta ).to eq( '2 weeks ago' )
+					expect( 15.days.from_now.as_delta ).to eq( '2 weeks from now' )
+					expect( 3.weeks.ago.as_delta ).to eq( '3 weeks ago' )
+					expect( 3.weeks.from_now.as_delta ).to eq( '3 weeks from now' )
+
+					expect( 1.month.ago.as_delta ).to eq( '4 weeks ago' )
+					expect( 1.month.from_now.as_delta ).to eq( '4 weeks from now' )
+					expect( 36.days.ago.as_delta ).to eq( '5 weeks ago' )
+					expect( 36.days.from_now.as_delta ).to eq( '5 weeks from now' )
+
+					expect( 6.months.ago.as_delta ).to eq( '6 months ago' )
+					expect( 6.months.from_now.as_delta ).to eq( '6 months from now' )
+					expect( 14.months.ago.as_delta ).to eq( '14 months ago' )
+					expect( 14.months.from_now.as_delta ).to eq( '14 months from now' )
+
+					expect( 6.year.ago.as_delta ).to eq( '6 years ago' )
+					expect( 6.year.from_now.as_delta ).to eq( '6 years from now' )
+					expect( 14.years.ago.as_delta ).to eq( '14 years ago' )
+					expect( 14.years.from_now.as_delta ).to eq( '14 years from now' )
+				end
+			end
+
+		end
+
+	end
+
+
+end
+

data/spec/schedulability/parser_spec.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env rspec -cfd
+
+require_relative '../helpers'
+
+require 'schedulability/parser'
+
+
+describe Schedulability::Parser do
+
+
+	it "can parse a single time period structure from a string" do
+		range, negative = described_class.extract_period( "min {25-35}" )
+
+		expect( range ).to be_a( Hash )
+		expect( range ).to include( min: [25...35] )
+		expect( negative ).to be_falsey
+	end
+
+
+	it "parses single values as one-unit ranges" do
+		range, _ = described_class.extract_period( "min {0 15 30 45}" )
+
+		expect( range ).to be_a( Hash )
+		expect( range ).to include( min: [0...1, 15...16, 30...31, 45...46] )
+	end
+
+
+	it "can parse a single negative time period structure from a string" do
+		range, negative = described_class.extract_period( "except hr {6-8}" )
+
+		expect( range ).to be_a( Hash )
+		expect( range ).to include( hr: [6...8] )
+		expect( negative ).to be_truthy
+	end
+
+
+	it "can parse multiple time period structures from string descriptions joined by commas" do
+		positive, negative = described_class.extract_periods( "wd {Mon-Fri}, except hr {6am-8pm}" )
+		expect( positive ).to eq( [{wd: [1..5]}] )
+		expect( negative ).to eq( [{hr: [6...20]}] )
+	end
+
+
+	it "can stringify an array of parsed time period structures" do
+		schedule_string = "wd { 1-5 }, hr { 6-19 }, min { 0 15 30 45 }"
+		periods, _ = described_class.extract_periods( schedule_string )
+
+		expect( described_class.stringify(periods) ).
+			to eq( schedule_string )
+	end
+
+
+	describe "can extract Range objects from expressions" do
+
+		describe "for years"
+		describe "for months"
+		describe "for weeks of the month"
+		describe "for days of the year"
+		describe "for days of the month"
+		describe "for hours"
+		describe "for minutes"
+		describe "for seconds"
+
+	end
+
+end
+

data/spec/schedulability/schedule_spec.rb

@@ -25,6 +25,13 @@ describe Schedulability::Schedule do
 	let( :testing_time ) { Time.iso8601('2015-12-15T12:00:00-00:00') }
 
 
+	RSpec::Matchers.define( :overlap ) do |other|
+		match do |schedule|
+			schedule.overlaps?( other )
+		end
+	end
+
+
 	context "with no periods" do
 
 		let( :schedule ) { described_class.new }
@@ -161,6 +168,13 @@ describe Schedulability::Schedule do
 			expect( schedule ).to include( 'Wed Dec 16 12:00:00 2015' )
 			expect( schedule ).to_not include( 'Wed Dec 16 15:05:00 2015' )
 		end
+
+
+		it "can be stringified" do
+			schedule = described_class.
+				parse( "wd {Mon Wed Fri} hr {8am-4pm}, wd {Tue Thu} hr {9am-5pm}, not hour { 3pm }" )
+			expect( schedule.to_s ).to eq( "hr { 8-16 } wd { 1 3 5 }, hr { 9-17 } wd { 2 4 }, not hr { 15 }" )
+		end
 	end
 
 
@@ -709,6 +723,32 @@ describe Schedulability::Schedule do
 		end
 
 
+		it "doesn't raise a parse error for second values equal to 59" do
+			expect {
+				described_class.parse( 'sec {1 5 10 59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'sec {59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'sec {0-59}' )
+			}.not_to raise_error
+		end
+
+
+		it "allows second values equal to 0" do
+			expect {
+				described_class.parse( 'sec {0 5 10 59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'sec {0}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'sec {0-59}' )
+			}.not_to raise_error
+		end
+
+
 		it "raises a parse error for minute values greater than 59" do
 			expect {
 				described_class.parse( 'min {09 28 68}' )
@@ -719,6 +759,32 @@ describe Schedulability::Schedule do
 		end
 
 
+		it "doesn't raise a parse error for minute values equal to 59" do
+			expect {
+				described_class.parse( 'min {1 5 10 59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'min {59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'min {0-59}' )
+			}.not_to raise_error
+		end
+
+
+		it "allows minute values equal to 0" do
+			expect {
+				described_class.parse( 'min {0 5 10 59}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'min {0}' )
+			}.not_to raise_error
+			expect {
+				described_class.parse( 'min {0-59}' )
+			}.not_to raise_error
+		end
+
+
 		it "raises a parse error for minute ranges with invalid values" do
 			expect {
 				described_class.parse( 'min {120-15}' )
@@ -784,6 +850,15 @@ describe Schedulability::Schedule do
 		end
 
 
+		it "treats scales present in one schedule as infinite in the other when intersecting" do
+			schedule1 = described_class.parse( 'hr {6am-8am}' )
+			schedule2 = described_class.parse( 'wday {Thu Sat}' )
+			schedule3 = schedule1 & schedule2
+
+			expect( schedule3 ).to be == described_class.parse( 'hr {6am-8am} wday {Thu Sat}' )
+		end
+
+
 		it "can calculate unions of schedules with negated periods" do
 			schedule1 = described_class.parse( '! wday { Mon-Fri }' )
 			schedule2 = described_class.parse( '! wday { Thu }' )
@@ -824,5 +899,31 @@ describe Schedulability::Schedule do
 
 	end
 
+
+	describe "predicates" do
+
+		it "can test if one schedule overlaps another" do
+			schedule1 = described_class.parse( "hr {8am - 5pm}" )
+			schedule2 = described_class.parse( "hr {5pm - 8am}" )
+			schedule3 = described_class.parse( "wd {Mon - Fri}" )
+
+			expect( schedule1 ).to_not overlap( schedule2 )
+			expect( schedule1 ).to overlap( schedule3 )
+			expect( schedule2 ).to overlap( schedule3 )
+		end
+
+
+		it "can test if one schedule is exclusive of another" do
+			schedule1 = described_class.parse( "hr {8am - 5pm}" )
+			schedule2 = described_class.parse( "hr {5pm - 8am}" )
+			schedule3 = described_class.parse( "wd {Mon - Fri}" )
+
+			expect( schedule1 ).to be_exclusive_of( schedule2 )
+			expect( schedule1 ).to_not be_exclusive_of( schedule3 )
+			expect( schedule2 ).to_not be_exclusive_of( schedule3 )
+		end
+
+	end
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schedulability
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Granger
@@ -11,9 +11,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIDbDCCAlSgAwIBAgIBATANBgkqhkiG9w0BAQUFADA+MQwwCgYDVQQDDANnZWQx
+  MIIDMDCCAhigAwIBAgIBAjANBgkqhkiG9w0BAQUFADA+MQwwCgYDVQQDDANnZWQx
   GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
-  HhcNMTUwNDAxMjEyNDEzWhcNMTYwMzMxMjEyNDEzWjA+MQwwCgYDVQQDDANnZWQx
+  HhcNMTYwNjAyMDE1NTQ2WhcNMTcwNjAyMDE1NTQ2WjA+MQwwCgYDVQQDDANnZWQx
   GTAXBgoJkiaJk/IsZAEZFglGYWVyaWVNVUQxEzARBgoJkiaJk/IsZAEZFgNvcmcw
   ggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDb92mkyYwuGBg1oRxt2tkH
   +Uo3LAsaL/APBfSLzy8o3+B3AUHKCjMUaVeBoZdWtMHB75X3VQlvXfZMyBxj59Vo
@@ -21,17 +21,16 @@ cert_chain:
   OkOzAscMwkfQxBkXDzjvAWa6UF4c5c9kR/T79iA21kDx9+bUMentU59aCJtUcbxa
   7kcKJhPEYsk4OdxR9q2dphNMFDQsIdRO8rywX5FRHvcb+qnXC17RvxLHtOjysPtp
   EWsYoZMxyCDJpUqbwoeiM+tAHoz2ABMv3Ahie3Qeb6+MZNAtMmaWfBx3dg2u+/WN
-  AgMBAAGjdTBzMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBSZ0hCV
-  qoHr122fGKelqffzEQBhszAcBgNVHREEFTATgRFnZWRARmFlcmllTVVELm9yZzAc
-  BgNVHRIEFTATgRFnZWRARmFlcmllTVVELm9yZzANBgkqhkiG9w0BAQUFAAOCAQEA
-  lUKo3NXePpuvN3QGsOLJ6QhNd4+Q9Rz75GipuMrCl296V8QFkd2gg9EG44Pqtk+9
-  Zac8TkKc9bCSR0snakp+cCPplVvZF0/gMzkSTUJkDBHlNV16z73CyWpbQQa+iLJ4
-  uisI6gF2ZXK919MYLn2bFJfb7OsCvVfyTPqq8afPY+rq9vlf9ZPwU49AlD8bPRic
-  0LX0gO5ykvETIOv+WgGcqp96ceNi9XVuJMh20uWuw6pmv/Ub2RqAf82jQSbpz09G
-  G8LHR7EjtPPmqCCunfyecJ6MmCNaiJCBxq2NYzyNmluPyHT8+0fuB5kccUVZm6CD
-  xn3DzOkDE6NYbk8gC9rTsA==
+  AgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBSZ0hCV
+  qoHr122fGKelqffzEQBhszANBgkqhkiG9w0BAQUFAAOCAQEAF2XCzjfTFxkcVvuj
+  hhBezFkZnMDYtWezg4QCkR0RHg4sl1LdXjpvvI59SIgD/evD1hOteGKsXqD8t0E4
+  OPAWWv/z+JRma72zeYsBZLSDRPIUvBoul6qCpvY0MiWTh496mFwOxT5lvSAUoh+U
+  pQ/MQeH/yC6hbGp7IYska6J8T4z5XkYqafYZ3eKQ8H+xPd/z+gYx+jd0PfkWf1Wk
+  QQdziL01SKBHf33OAH/p/puCpwS+ZDfgnNx5oMijWbc671UXkrt7zjD0kGakq+9I
+  hnfm736z8j1wvWddqf45++gwPpDr1E4zoAq2PgRl/WBNyR0hfoZLpi3TnHu3eC0x
+  uALKNA==
   -----END CERTIFICATE-----
-date: 2015-12-31 00:00:00.000000000 Z
+date: 2016-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -67,14 +66,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: hoe-highline
   requirement: !ruby/object:Gem::Requirement
@@ -117,50 +116,37 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: hoe-bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: hoe
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.14'
+        version: '3.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.14'
-description: Schedulability is a library for describing scheduled time. You can specify
-  one or more periods of time using a simple syntax, then combine them to describe
+        version: '3.15'
+description: |-
+  Schedulability is a library for describing scheduled time. You can specify one
+  or more periods of time using a simple syntax, then combine them to describe
   more-complex schedules.
 email:
 - ged@FaerieMUD.org
@@ -185,6 +171,8 @@ files:
 - lib/schedulability/parser.rb
 - lib/schedulability/schedule.rb
 - spec/helpers.rb
+- spec/schedulability/mixins_spec.rb
+- spec/schedulability/parser_spec.rb
 - spec/schedulability/schedule_spec.rb
 - spec/schedulability_spec.rb
 homepage: http://deveiate.org/projects/schedulability