opening_hours
, collection_times
, service_times
Technical:
The evaluation function is called with two arguments:
- time domain expression, a string containing the value of the corresponding attribute,
- the time the expression is to be evaluated for, as object with fields year, month, day, hour, minute; if ommited, now is assumed.
The evaluation function is (still) naive about the time zone; it assumes that time object and
time domain expression use the same timezone. If the time domain expressions time zone is known,
now
should be expressed in this timezone.
The evaluation function returns an object with six fields:
- Status:
Value Meaning true opened false closed null unknown - a list of the times of the next collections or services,
- informational messages (optional)
explaining uncommon evaluation steps. - a list of error messages (optional),
- a list of warning messages (optional),
- copy of the rule used for the decision.
Components of time domain expressions:
General:
- Case:
- is not significant (except in plain text comments of course);
- Blankspace:
-
is not significant, except if separating elements of the language:
is different to1234
.12 34
Elements:
- Years:
- are written using four digits and valid starting with 2000;
- Months:
- are written as english three letter abbreviations;
- Days of week:
- are written as english two letter abbreviations.
Dates:
- Calendar date:
-
A calendar date is written
(where year and month can be ommited).2010 Dec 25
If the year is missing, the current year is assumed.
Personally I prefer the ISO notation
(and would like to use it exclusively); what about including it?2010-12-25
- Moving holiday:
-
Currently only easter is implemented:
means easter sunday.easter
- Date as certain day of week in month:
-
is the first wednesday in september;Dec We[1]
is the last sunday of march in current year: in germany start of the summer time.Mar Su[-1]
- Date as day of week after or before another Date:
-
is the first christmasday,Dec 25
is the last sunday before the first christmasday: forth advent.Dec 25 - Su
- Date as fixed distance to another date:
-
is easter monday,easter + 1 days
is good friday,easter - 2 days
is carnival monday,easter - 48 days
is the first advent.Dec 25 - Su - 21 days
Periods:
- Period between two dates:
-
is the period of summer time.Mar Su[-1] - Oct Su[-1] - 1 days
Beware:
is not the same asOct Su[-1] - 1 days
!Oct Sa[-1]
is the period of winter time.Oct Su[-1] - Mar Su[-1] - 1 days
→ If the first date is later then the second one and no year is specified, the period stretches from begin of the year to the second date and from the first date until the end of the year.
is theNov 11 - easter-47 days
fifth season
(carnival in the area around Cologne).
- List of periods:
-
is the period of the Oktoberfest.Sep 15+Sa - Oct Su[1], Oct 1-3
→ Periods and single days can be combined using
. The list components may overlap.,
Calendar weeks:
- Weeks:
-
meansweek 2
in second calendar week
,
meansweek 10-12
in tenth, eleventh and twelfth calendar week
,
meansweek 2-52/2
all even calendar weeks
.
Days independent of a date:
- Day of week:
-
meansFr
every friday
,
meansFr-Mo
friday, saturday, sunday, monday
,
meansMo-We,Sa
monday, tuesday, wednesday, saturday
. - Day of week in month:
-
The first sunday in month is specified as
,Su[1]
first and second as
,Su[1,2]
first, second and third as
,Su[1-3]
first, third and all following as
.Su[1,3-5]
The last sunday in month is specified as
,Su[-1]
first and last as
.Su[1,-1]
- Day of month:
-
Day of month outside a calendar date are followed by a
.
; this notations prevents difficult to resolve ambiguities:
– the first of each month1.
– the first seven days of each month;1.-7.
– parking permitted only on even days.2.-30./2
→ thefrom - to /step
is a general notation, which ist used for calendar weeks and for repetitions atcollection_times
andservice_times
. - Holidays:
-
means public holidays,PH
means school holidays,SH
meansSu,PH
on public and school holidays
.
Times:
- Fixed times:
-
are written
H:MM
orHH:MM
. - Variable times:
-
The time of sunrise and sunset is written as (surprise!)
andsunrise
.sunset
This notation is quite popular for opening hours of parks and playing grounds. - Variable times with offset:
-
meanssunrise-0:30 hours
half an hour before sunrise
. - Timespans:
-
is the classical09:00-17:00
9 to 5
job.
is the21:00-05:00
9 to 5
job for kernel hackers.
→ if the second time is less than the first one, it is assumed to be on the next day.
←sunset-sunrise
From Dusk Till Dawn
→ beware of vampires!
Evaluation:
Rules:
Most opening hours can be specified as simple rules.
Rules consist of a sequence of time spans, in most cases qualified by a day of week,
and joined by ,
:
08:00-12:00
- On all days from 8 to 12.
Mo-Fr 08:00-12:00
- Monday until friday from 8 to 12.
Fr,Sa 22:00-05:00
- Friday and saturday evening from 10pm to 5am on next day.
Mo-Fr 08:00-12:00, Sa 10:00-12:00
- Monday until friday from 8 to 12, and saturdays from 10 to 12.
This indications are evaluated the way one intuitively reads opening hours at the doctors office, from left to right and additive, later timespans are joined to the former ones:
Mo-Fr 08:00-12:00, We 14:00-16:00
- Monday until friday from 8 to 12, on wednesdays additionally from 14 to 16.
Mo-Fr,Sa[1] 08:00-12:00
- Monday until friday and additionally on first saturday in months from 8 to 12.
Mo-Fr 08:00-12:00, Sa[1] 10:00-12:00
- Monday until friday from 8 to 12 and additionally on first saturday of months from 10 to 12.
Mo-Fr 08:00-12:00, Mo[1] 14:00-16:00
- Monday until friday from 8 to 12, additionally on first monday of months from 14 to 16 Uhr.
Mo-Fr 08:00-12:00, PH off
- Monday until friday from 8 to 12, except on public holidays.
The time indications can be followed by an opening status:
means opened (default),open
means closed,closed
represents conditional opening hours." ……Text…… "
The conditions can be external influences, users attributes, or represent incomplete knowlege. The evaluation function returns
Status=unknown + messages
. This models the (in reality quite common) answerit depends
to the questionis it open?
:Mo-Fr 08:00-16:00, Sa 10:00-14:00, Sa 14:00-18:00 "if weather permits "
- The public pool extends its opening hours on saturdays to 18:00, if the sun shines. (external influence)
Mo-Fr 18:00-22:00, We 18:00-20:00 "female only"
- Wednesday from 18:00 to 20:00 access to the saune is permitted to female only. (users attribute).
Mo-Fr 08:00-12:00, Sa 08:00-20:00 "on appointent (555 1234)"
- The pet doc will come in on saturdays from 8 to 20:00, too, but you have to phone him before. (users action required)
Su 14:00-15:00, Mo-Fr 08:00-16:00 "groups of at minimum 12 after appointment"
- On working days, the cave guide will appear only if it pays. (operators condition).
The evaluation function returns
unknown
together with the plain text message.
Fineprint regarding the rules:
andopen
can be followed by a comment. The comment does not change the status, but is returned together with it. It may contain a cause for a closing or additional information:closed
Mo-Sa 10:00-21:00 open "Hot meals from 11:30 to 13:30 and from 17:30 to 19:30"
- Days may be prepended by a holiday indication:
meansFr 10:00-14:00, SH Fr off
fridays from 10 to 14 Uhr, except on fridays during school holidays
. - Days may be prepended by a week indication:
meansweek 2-52/2 Sa 10:00-16:00
Flea market on saturdays of even weeks.
.
Extended indications for experts:
Rules can be combined using
. As long as the specified days are distinct,
the notation using a single rule is equivalent to the notation using multiple rules:
;
Mo-Fr 08:00-12:00; Sa 08:00-20:00
Mo-Fr 08:00-12:00, Sa 08:00-20:00
- Both have the same meaning.
But things change, if multiple rules compete
about one day:
in this case a all or nothing principle is applied: the last
rule appliable to a day has to take care of this day alone.
Mo-Fr 08:00-12:00, We 14:00-16:00
- On wednesdays opened additionally from 14:00 to 16:00.
Mo-Fr 08:00-12:00; We 14:00-16:00
- On wednesdays opened only from 14:00 to 16:00.
In my oppinion this is the most difficult to explain feature: ,
means a friendly together, ;
means competition. Both was part of the original proposal,
both is needed: additional opening hours on specific days are common,
while if defining exceptions for holidays one needs to redefine the whole day:
Mo-Fr 11:30-13:30, We 17:30-20:00; Su,PH 14:00-18:00
-
Monday to friday lunch menu, wednesday additionally dinner.
On Sundays and holidays only from 14:00 to 18:00 Uhr.
If the holiday is on a wednesday, the 14:00-18:00 rule applies.
An editor should display each rule on its own line to show their distinctness.
Calendar ranges:
Rules may be limited to certain periods of the year. The periods will be prepended followed by
a :
. A period indication is applied to the following rules upto the next period
indication. Rules without validity period are allways applicable:
Jul: Sa,Su 12:00-14:00
- On saturdays and sundays in july from noon to 14:00.
Oct-Mar: Su[1] 12:00-14:00
- From october to march the first sunday in month from noon to 14:00 (yearwrap allowed).
easter-sep 15: 12:00-14:00
- From easter until the fifteenth of september each day from noon to 14:00.
Jun: "from mid june"; Jul-Aug: open; Sep: "until mid september"
-
A mountain huts fuzzy opening hours: for the uncertain months
unknown
is returned together with an informational message, for the certain monthsopen
orclosed
is returned.
The evaluation of validity periods is easy to understand: all rules invalid for the particular time are ignored, than the remaining rules evaluated using the known all or nothing method.
Mo-Fr 10:00-12:00; Jul,Aug: Mo-Fr 14:00-16:00
- From 10:00 to 12:00, except in july and august, than from 14:00 to 16:00. The first rule is valid allways, the second one only from july to august. In july and august the second rule overwrites the first one.
Mar Su[-1]-Oct Su[-1]-1 days: sr1; sr2; …; Oct Su[-1]-Mar Su[-1]-1 days: wr1; wr2; …;
- Different sets of rules for summer and winter.
Some calendar ranges cannot be expressed formally, i.e. during asparagus season
. In this
case one writes the description as comment followed by a :
:
"During asparagus season": Mo-Fr 08:00-18:00
Evaluation: this calendar range
is valid allways, but in rules following this
indication open
is evaluated as unknown
with the plain text calendar range as
comment. This kind of calendar range should only be used if inavoidable and only standalone,
because the interaction with with the all-or-nothing
and fallback groups is weird.
Fallback groups:
Multiple rulesets can be concatenated using ||
. They are evaluated from left to right,
until on ruleset returns open
or the last one is reached.
Mo-Fr 08:00-12:00, 14:00-18:00, Sa 09:00-13:00, PH off || Tu 06:00-06:00 open "Emergency only"
- This pharmacy has normal opening hours, and additionally an emergency duty from tuesday 6:00 until wednesday 6:00. If both rulesets return open (i.e. on tuesday 9:00), the first one (normal open) is returned. On holidays, the normal opening hours do not apply, but the emergency rules do.
Mo-Fr 08:00-16:00, Sa 09:00-14:00, PH Off || "Outside office hours on appointment by phone"
- A customer friendly pet dog.
Open issues:
- Public holidays and school holidays depend on region:
-
The evaluation function accepts a parameter
region
, the interactive evaluation form provides an input field and the maps use the value of the key
. But the problem is still not solved:addr:country
- How fine grained should the region id be?
- How can I derive the region id (if no addr:country available) from coordinates (which are allways available)?
- How can I retrieve the definitions of public and school holidays for a certain region id?
Currently the countrywide public holidays for germany and austria are provided and activated by region ids “at” and “de”. Schoolholidays are not provided at all, because they depend on much smaller regions and change every year.
- Well defined conditions for opening hours:
-
There was a suggestion to define a list of ids for commonly used conditions (“on request”, “on appointment”, “if weather permits”, …), to enable providing translated messages.
Because there is no such list at the moment and because I dont like to clutter the syntax, I suggest writing such ids uppercase only as plain comments, i.e.:
"OR"
foron request
.This allows natural growth of the list without need for continuous adjustment of the evaluation software.
- Documentation:
-
If a developer tries to document his own development, the knowledge of the internals stand in his way. The documentation will follow the internal processing insted of being focused to the users needs.
Who can write a tutorial from users for users, possibly plundering this text?