Adding release checksum.
Signing v0.5.0
Added tag v0.5.0 for changeset ad66e8787738
home : https://hg.sr.ht/~ged/Schedulability
code : https://hg.sr.ht/~ged/Schedulability
docs : https://deveiate.org/code/schedulability
github : https://github.com/ged/schedulability
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.
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.
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 ...]}]
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):
Scale | Scale | Valid Range Values
| Code |
-------+-------+------------------------------------------------------
year | yr | n where n is a 4-digit integer
month | mo | 1-12 or jan, feb, mar, apr, may, jun, jul,
| | aug, sep, oct, nov, dec
week | wk | 1-6
yday | yd | 1-366
mday | md | 1-31
wday | wd | 1-7 or sun, mon, tue, wed, thu, fri, sat
hour | hr | 0-23 or 12am 1am-11am 12noon 12pm 1pm-11pm
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.
A range
is specified in the form:
<range value>
or
<range value>-<range value>
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}
.
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 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 and months can be abbreviated to three characters
(Wednesday
== Wed
, September
== Sep
).
wd {Mon-Fri} hr {9am-4pm}
wd {Mon Wed Fri} hr {9am-4pm}, wd{Tue Thu} hr {9am-2pm}
wk {1 3 5} wd {Mon-Fri} hr {9am-5pm}
month {Jan-Feb Nov-Dec}
mo {Nov-Feb}
not mo {Mar-Oct}
mo {jan feb nov dec}
mo {Jan Feb}, mo {Nov Dec}
mo {Jan Feb} mo {Nov Dec}
minute { 0-29 }
hour { 12am - 12pm }
sec {0-4 10-14 20-24 30-34 40-44 50-54}
wd {mon wed fri} hr {8am - 5pm}, except day {1}
wd {1 3 5 7} min {0-29}, wd {2 4 6} min {30-59}
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:
weekend = Schedulability::Schedule.parse( "wd {Sat - Sun}" )
weekdays = Schedulability::Schedule.parse( "wd {Mon - Fri}" )
work_hours = Schedulability::Schedule.parse( "hour {9am - 5pm}" )
off_hours = Schedulability::Schedule.parse( "hour {5pm - 9am}" )
### Boolean operators
on_duty = weekdays | work_hours
off_duty = weekend + ( weekdays | off_hours )
# -or-
off_duty = ~on_duty
### Exclusivity predicates
on_duty.overlaps?( off_duty )
# => false
on_duty.exclusive?( off_duty )
# => true
### Time predicates
Time.now
# => 2015-12-22 12:05:44 -0800
on_duty.include?( Time.now )
# => true
on_duty.now?
# => true
off_duty.now?
# => false
### Case equality (=== operator)
case Time.now
when on_duty
send_sms( "Stuff happened." )
when off_duty
send_email( "Stuff happened." )
end
$ gem install schedulability
You can check out the current development source with Mercurial, or if you prefer Git, via its Github mirror.
After checking out the source, run:
$ rake newb
This task will install any missing dependencies, run the tests/specs, and generate the API documentation.
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.
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-2020, 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.
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.