Explanation of time domain value evaluation

opening_hours, collection_times, service_times

Technical:

The evaluation function is called with two arguments:

  1. time domain expression, a string containing the value of the corresponding attribute,
  2. 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:

  1. Status:
    Value Meaning
    true opened
    false closed
    null unknown
  2. a list of the times of the next collections or services,
  3. informational messages (optional)
    explaining uncommon evaluation steps.
  4. a list of error messages (optional),
  5. a list of warning messages (optional),
  6. 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:
1234 is different to 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 2010 Dec 25 (where year and month can be ommited).
If the year is missing, the current year is assumed.
Personally I prefer the ISO notation 2010-12-25 (and would like to use it exclusively); what about including it?
Moving holiday:
Currently only easter is implemented: easter means easter sunday.
Date as certain day of week in month:
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.
Date as day of week after or before another Date:
Dec 25 is the first christmasday, Dec 25 - Su is the last sunday before the first christmasday: forth advent.
Date as fixed distance to another date:
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.

Periods:

Period between two dates:
Mar Su[-1] - Oct Su[-1] - 1 days is the period of summer time.
Beware: 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.
→ 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.
Nov 11 - easter-47 days is the fifth season (carnival in the area around Cologne).
List of periods:
Sep 15+Sa - Oct Su[1], Oct 1-3 is the period of the Oktoberfest.
→ Periods and single days can be combined using ,. The list components may overlap.

Calendar weeks:

Weeks:
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.

Days independent of a date:

Day of week:
Fr means every friday,
Fr-Mo means friday, saturday, sunday, monday,
Mo-We,Sa means 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:
1. – the first of each month
1.-7. – the first seven days of each month;
2.-30./2 – parking permitted only on even days.
→ the from - to /step is a general notation, which ist used for calendar weeks and for repetitions at collection_times and service_times.
Holidays:
PH means public holidays,
SH means school holidays,
Su,PH means on public and school holidays.

Times:

Fixed times:
are written H:MM or HH:MM.
Variable times:
The time of sunrise and sunset is written as (surprise!) sunrise and sunset.
This notation is quite popular for opening hours of parks and playing grounds.
Variable times with offset:
sunrise-0:30 hours means half an hour before sunrise.
Timespans:
09:00-17:00 is the classical 9 to 5 job.
21:00-05:00 is the 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-sunriseFrom 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:

  • 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 "
    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:

  • 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"
  • Days may be prepended by a holiday indication:
    Fr 10:00-14:00, SH Fr off means fridays from 10 to 14 Uhr, except on fridays during school holidays.
  • Days may be prepended by a week indication:
    week 2-52/2 Sa 10:00-16:00 means 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 months open or closed 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 addr:country. But the problem is still not solved:

  • 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" for on 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?

Dieser Text in deutscher Sprache