Timer strings are used in both
refresh.timer stetting and timer services as the
timer: .. app property. See Refresh scheduling on specific days of the month for details on how the syntax conceived and evolved over time.
eventlist = eventset *( ",," eventset ) eventset = wdaylist / timelist / wdaylist "," timelist wdaylist = wdayset *( "," wdayset ) wdayset = wday / wdayspan wday = ( "mon" / "tue" / "wed" / "thu" / "fri" / "sat" / "sun" ) [ wspec ] wdayspan = wday "-" wday wspec = ( "1" / "2" / "3" / "4" / "5" ) timelist = timeset *( "," timeset ) timeset = time / timespan time = 2DIGIT ":" 2DIGIT timespan = time ( "-" / "~" ) time [ "/" count ] count = n*DIGIT
Clock times are always specified in 24H format.
Every hour on the hour
Every 30 minutes
Every 15 mintues
Every 5 minutes from 12:00 to 13:10
Every day at 23:00
More specific timer examples:
Mondays at 10:00, Fridays at 15:10
Mondays at 10:00 and 15:00, Fridays at 10:00 and 15:00
Monday to Wednesday and on Friday, twice between 9:00 and 11:00
Mondays, some time between 9:00 and 11:00, and on Wednesdays, some time between 22:00 and 23:00
Monday and on Wednesday, at 0:00
Monday through Wednesday on the 2nd week of the month, between 23:00 and 24:00
Last Friday of the month, from 23:00 to 1:00 the next day
A timer string is composed of one or more event sets, which are combined by using commas (
,,) as separators.
Each event set defines the weekdays and the time windows in which events may occur. The next event will be scheduled inside the soonest opportunity that matches both one of the provided weekdays and one of the provided time windows. If no weekdays are provided, the default is every day. If no time windows are provided, the default is an arbitrary time in the day.
For example, consider the timer:
Assuming today is Sunday, the next 5 events are, in order:
Monday 10:00 Monday 15:00 Friday 10:00 Friday 15:00 Monday 10:00
Consider the following timer:
The next 3 events in this case are:
Monday 10am Friday 15pm Monday 10am
All of these examples work on a weekly basis, but certain events are better scheduled on a monthly basis. To support that, weekdays may be suffixed by
wspec entry that defines the week number inside the month. As an example, the following timer defines two events every month, on the first and third Mondays at 15:00:
As a special case, the 5th week is considered the last one to hold the given day, so that specifying an event on the last Friday of the month, for instance, is done simply as:
In addition to specifying precise weekdays, an interval may be used to define a larger span:
This represents an event per day at 15:00, Monday through Friday, every week.
The same interval syntax also works to define time spans, but the meaning is slightly different. For instance, consider this time span:
It defines an event every Monday that will take place at the earliest chance between 14:100 and 16:00.
Weekday spans define an event every day within the span. In contrast, time spans define a single event inside the defined span.
That latter aspect may be changed via an explicit divisor, which may be specified as a
count. For instance, consider this time span:
This represents two events every day, one in the morning between 8:00 and 12:00, and another one between 12:00 and 16:00.
While the following represents an hourly event, every day of the week:
All of the time spans defined so far work similarly in the sense that the start of the span defines the earliest chance in which the event may start, and the end of the span defines the latest chance for the event to have started. For various reasons, though, it’s often useful to introduce some level of randomization inside the time span so that events won’t all start at exactly the same time. This may be achieved by replacing the time span dash character (
-) by a tilde (
~). Consider the following time span:
It represents 4 events that will take place at a random time inside time windows of 6 hours each.