opening_hours
,
collection_times
,
service_times
The evaluation function is called with two arguments:
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:
Value | Meaning |
---|---|
true | opened |
false | closed |
null | unknown |
1234
is different to 12 34
.
2010 Dec 25
(where year and month can be ommited).2010-12-25
(and would like to
use it exclusively);
what about including it?
easter
means easter sunday.
Dec We[1]
is the first wednesday in september;Mar Su[-1]
is the last sunday of march in current year:
in germany start of the summer time.
Dec 25
is the first christmasday,
Dec 25 - Su
is the last sunday before the first christmasday: forth advent.
easter + 1 days
is easter monday,easter - 2 days
is good friday,easter - 48 days
is carnival monday,Dec 25 - Su - 21 days
is the first advent.
Mar Su[-1] - Oct Su[-1] - 1 days
is the period of summer time.
Oct Su[-1] - 1 days
is not the same as
Oct Sa[-1]
!
Oct Su[-1] - Mar Su[-1] - 1 days
is the period of winter time.Nov 11 - easter-47 days
is the fifth season(carnival in the area around Cologne).
Sep 15+Sa - Oct Su[1], Oct 1-3
is the period of the Oktoberfest.,
.
The list components may overlap.
week 2
means in second calendar week,
week 10-12
means in tenth, eleventh and twelfth calendar week,
week 2-52/2
means all even calendar weeks.
Fr
means every friday,
Fr-Mo
means friday, saturday, sunday, monday,
Mo-We,Sa
means monday, tuesday, wednesday, saturday.
Su[1]
,Su[1,2]
,Su[1-3]
,Su[1,3-5]
.Su[-1]
,Su[1,-1]
.
.; this notations prevents difficult to resolve ambiguities:
1.
– the first of each month1.-7.
– the first seven days of each month;2.-30./2
– parking permitted only on even days.from - to /stepis a general notation, which ist used for calendar weeks and for repetitions at
collection_times
and service_times
.
PH
means public holidays,SH
means school holidays,Su,PH
means on public and school holidays.
H:MMor
HH:MM.
sunrise
and sunset
.sunrise-0:30 hours
means half an hour before sunrise.
09:00-17:00
is the classical 9 to 5job.
21:00-05:00
is the 9 to 5job for kernel hackers.
sunset-sunrise
← From Dusk Till Dawn→ beware of vampires!
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
Mo-Fr 08:00-12:00
Fr,Sa 22:00-05:00
Mo-Fr 08:00-12:00, Sa 10:00-12:00
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
Mo-Fr,Sa[1] 08:00-12:00
Mo-Fr 08:00-12:00, Sa[1] 10:00-12:00
Mo-Fr 08:00-12:00, Mo[1] 14:00-16:00
Mo-Fr 08:00-12:00, PH off
The time indications can be followed by an opening status:
open
means opened (default),closed
means closed," ……Text…… "
represents conditional opening hours.
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) answer it depends
to the question is it open?
:
Mo-Fr 08:00-16:00, Sa 10:00-14:00, Sa 14:00-18:00 "if weather permits "
Mo-Fr 18:00-22:00, We 18:00-20:00 "female only"
Mo-Fr 08:00-12:00, Sa 08:00-20:00 "on appointent (555 1234)"
Su 14:00-15:00, Mo-Fr 08:00-16:00 "groups of at minimum 12 after appointment"
The evaluation function returns unknown
together with the plain text message.
open
and closed
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:
Mo-Sa 10:00-21:00 open "Hot meals from 11:30 to 13:30 and from 17:30 to 19:30"
Fr 10:00-14:00, SH Fr off
means
fridays from 10 to 14 Uhr, except on fridays during school holidays.
week 2-52/2 Sa 10:00-16:00
means
Flea market on saturdays of even weeks..
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
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
Mo-Fr 08:00-12:00;
We 14:00-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
An editor should display each rule on its own line to show their distinctness.
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
Oct-Mar: Su[1] 12:00-14:00
easter-sep 15: 12:00-14:00
Jun: "from mid june"; Jul-Aug: open; Sep: "until mid september"
unknownis returned together with an informational message, for the certain months
openor
closedis 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
Mar Su[-1]-Oct Su[-1]-1 days: sr1; sr2; …;
Oct Su[-1]-Mar Su[-1]-1 days: wr1; wr2; …;
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.
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"
Mo-Fr 08:00-16:00, Sa 09:00-14:00, PH Off || "Outside office hours on appointment by phone"
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
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.
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"
for on request
.
This allows natural growth of the list without need for continuous adjustment of the evaluation software.
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?