FR:Key:opening hours/specification

From OpenStreetMap Wiki
Jump to navigation Jump to search

En cours de traduction!

Syntaxe à utiliser pour les horaires d'ouvertures

Cette spécification est une description complète de la syntaxe utilisée pour la balise opening_hours=* que la communauté a défini au fur et à mesure des années et qui sert de référence pour les cartographes et les développeurs. L'implémentation la plus sophistiquée de cette spécification est disponible sur le projet opening_hours.js qui permet également de tester la chaîne de valeur que les cartographes souhaitent intègrer dans la clé opening_hours=*.

Pour plus de simplicité cet outil d'évalution fait le lien avec cette spécification. Reportez vous à la section prettified opening_hours value for displaying dont toutes les catégories de valeurs sont liés à la documentation incluse sur cette page.

Initialement cette syntaxe a été introduit pour décrire les heures d'ouverture des installations, Elle est désormais également utilisé pour de nombreuses autres balises temporelles liées à l'OSM qui sont énumérés ici .

Aperçu général sur la construction syntaxique

La balise opening_hours est composée d'une ou plusieurs règles séparées par des séparateurs de règles. Une règle est composée d'un ou plusieurs sélecteurs (voir <selector_sequence>) et d'aucune, une ou plusieurs règles modificatrices (voir <rule_modifier>).

Exemple: Définition d'une période de fermeture du lundi au vendredi

La règle est Mo-Fr closed

Ainsi, le sélecteur Mo-Fr est une période (date ou heure) et la règle modificatrice est closed pour l'état de fermée (cela modifie donc l'état par défaut correspondant à un horaire d'ouverture en définissant, à l'inverse, une fermeture)

Légende

  • "|" sépare des solutions alternatives.
  • "[" Et "]" représente un composant optionnel.
  • "{" Et "}" représente un composant reproductible optionnel.
  • Les productions multiples pour un symbole évoquent des solutions alternatives.
  • Les caractère(s) ou mot(s) en gras sont des mots-clés (ou des jetons) syntaxique.
  • Les exemples de valeurs cette manière.
  • Les symboles dans le diagramme de syntaxe sont référencés comme ceci: < selector_sequence >
  • Les couleurs permettent renvoyer à la catégorie de symboles.

Diagramme syntaxique

Specification version 0.7.3. The specification versioning complies with Semantic Versioning. Increase the version accordingly when updating the specification.

Note that the English version of the specification is considered the official documentation. Translations of the specification might not be up-to-date or in compliance with the latest version yet.

time_domain
Symbol Definition Comment
<time_domain> <rule_sequence> { <any_rule_separator> <rule_sequence> } Explanation
<rule_sequence>

<selector_sequence> <space> <rule_modifier>

Limitations and Explanation
Rule separators
<any_rule_separator> <normal_rule_separator> | <additional_rule_separator> | <fallback_rule_separator>
<normal_rule_separator> ; <space>
<additional_rule_separator> , <space> Limitations and Explanation
<fallback_rule_separator>

<space> || <space>

Explanation
Rule modifiers
<rule_modifier> → open (Explanation)
open [ <space> <comment> ] → open
closed | off [ <space> <comment> ] → closed (Explanation)
unknown [ <space> <comment> ] → unknown
<comment>
Selectors
<selector_sequence> 24/7 Explanation
<wide_range_selectors> <small_range_selectors>
<wide_range_selectors>

[ <year_selector> ] [ <monthday_selector> ] [ <week_selector> ] [ <separator_for_readability> ]

<comment>: Explanation
<small_range_selectors>

[ <weekday_selector> ] [ <time_selector> ]

<separator_for_readability> : Explanation
Time selector
<time_selector> <timespan> { , <timespan> }
<timespan>
<time> Limitations and Explanation
<time> + Explanation
<time> - <extended_time> +
<time> - <extended_time>
<time> - <extended_time> / <positive_number> Limitations and Explanation
<time> - <extended_time> / <hour_minutes>
<time> <hour_minutes> | <variable_time>
<extended_time>

<extended_hour_minutes> | <variable_time>

<variable_time> <event>
( <event> <plus_or_minus> <hour_minutes> )
<event>

dawn | sunrise | sunset | dusk

Weekday selector
<weekday_selector> <weekday_sequence> Explanation
<holiday_sequence>
<holiday_sequence> , <weekday_sequence>
<weekday_sequence> , <holiday_sequence>
<holiday_sequence> <space> <weekday_sequence>
<weekday_sequence> <weekday_range> { , <weekday_range> }
<weekday_range> <wday>
<wday> - <wday>
<wday> [ <nth_entry> { , <nth_entry> } ] Explanation
<wday> [ <nth_entry> { , <nth_entry> } ] <day_offset>
<holiday_sequence> <holiday> { , <holiday> }
<holiday> <public_holiday> [ <day_offset> ] Limitations and Explanation
<school_holiday>
<public_holiday> PH
<school_holiday> SH Explanation
<nth_entry> <nth>
<nth> - <nth>
- <nth>
<nth> 1 | 2 | 3 | 4 | 5
<day_offset> <space> <plus_or_minus> <positive_number> <space> day[s]
Week selector
<week_selector> week <week> { , <week> }
<week> <weeknum>
<weeknum> - <weeknum>
<weeknum> - <weeknum> / <positive_number> Explanation
Month selector
<monthday_selector> <monthday_range> { , <monthday_range> }
<monthday_range> [ <year> ] <month>
[ <year> ] <month> - <month>
<date_from> [ <date_offset> ] Explanation
<date_from> [ <date_offset> ] + Explanation
<date_from> [ <date_offset> ] - <date_to> [ <date_offset> ] Explanation
<date_offset> [ <plus_or_minus> <wday> ] [ <day_offset> ] Explanation
<date_from> [ <year> ] <month> <daynum>
[ <year> ] <variable_date>
<date_to> <date_from>
<daynum> Explanation
<variable_date> easter Explanation
Year selector
<year_selector> <year_range> { , <year_range> }
<year_range> <year>
<year> - <year>
<year> - <year> / <positive_number>
<year> +
Basic elements
<plus_or_minus>

+ | -

<hour>

00 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24

<extended_hour>

<hour> | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48

<minute>

00 | 01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 |
30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59

<hour_minutes> <hour>:<minute>
<extended_hour_minutes> <extended_hour>:<minute> Explanation
<wday>

Su | Mo | Tu | We | Th | Fr | Sa

<daynum>

01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31

<weeknum>

01 | 02 | 03 | 04 | 05 | 06 | 07 | 08 | 09 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53

Explanation
<month>

Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec

<year> Four digit number greater than 1900.
<positive_number> Integer greater than zero (not zero padded).
<comment> " <comment_character> { <comment_character> } " Explanation
<comment_character> Any character except ".
<space> " "

Explication du diagramme

time_domain
Symbol Explanations
<time_domain> Un sélecteur <selector_sequence> de période s'applique sur base du «tout ou rien».

Le résultat de l’évaluation provient de la dernière règle utilisé sur période précise. Ce qui signifie que si plusieurs règles correspondent à une même période, ce sera la dernière règle qui remplacera toutes les précédentes. Cependant vous pouvez ajouter des règles additionnelles <additional_rule_separator> pour éviter ce comportement.

<rule_sequence> Notez qu'un <rule_sequence> ne peut être vide. Ajoutez <space> seulement si ni <selector_sequence> ni <rule_modifier> sont vides.
<additional_rule_separator> A additional rule is treated exactly the same as a normal rule, except that a additional rule does not overwrite the day for which it applies (unlike the normal separator which starts always with a new, empty day, deleting any pervious rules applying the given day). Note that a additional rule does not use any data from previous or from following rules. If time wraps over midnight are involved then you will probably also need to use additional rules to not overwrite the part which wraps into the next day. It can also be used to specify different comments for one day. Read more (including some examples) in this issue on github.

Because of the peskiness that the <additional_rule_separator> is the same token as the token to separate lists (e.g. <timespan> { , <timespan> }) the , (comma) is only interpreted as <additional_rule_separator> if it follows after one of those symbols:

<fallback_rule_separator> Rules are evaluated from left to right, until one rule evaluates to "open".

In discussion "!" was proposed as "not" operator; obviously intended was a "shortcut-or".
Tentatively Netzwolf introduced || because one will not type it by chance, it exhibits the cut very good, and every programmer will understand it immediately. For those how don’t understand it immediately: It is meant as an or. The rule which follows after this separator (token) will match every time frame not covered by previous rules.

<rule_modifier> (empty) Default state is open (for one rule). If no <rule_modifier> is specified, then the <rule_sequence> is interpreted as open.
<rule_modifier> (closed) Rules with the closed or off modifier will cut of the times they match. Note that they will not overwrite anything else as rules with other <rule_modifier> would do. See this issue on github for more details.
<selector_sequence> (empty) Meant as "always". This selector will match anytime.
<wide_range_selectors> (no syntax) Sometimes you cannot (yet) specify exactly the valid calendar days.

In this case you can use plain text in a comment followed by :.

<separator_for_readability> Optional. Does not change the meaning in any way. Was introduced to enhance the readability. Some implementations might still rely on this. If you implement this syntax, consider the <separator_for_readability> as optional.
<timespan> (point in time) This is only valid in point in time mode (tags like collection_times=*.
<timespan> (open end) The opening time starts at the given time without defined closing time.

This kind of indication is used quite often; but of course it is impossible to evaluate it verbatim. The evaluations is described here.

<timespan> (wrapping over midnight) If the second time is earlier then the first one, it is assumed to be on the next day.

The condition evaluates to true, if first timeparticular time < last time holds.

<timespan> (shortcut for pattern points in time) This notation describes a repeated event:

10:00-16:00/90 and 10:00-16:00/1:30 are evaluated as "from ten am to four pm every 1½ hours". Especially departure times can be written very concise and compact using this notation. The interval time following the "/" is valid but ignored for opening_hours.

This is only valid in point in time mode (tags like collection_times=*.

<weekday_range> (n-te weekday in month) Su represents all Sundays,

Su[1] represents the first Sunday of a month, Su[-1] represents the last Sunday of a month.

<holiday> Only a day shift around one day (± 1 day) is currently defined.
<plural_day_holiday> Can be used to express holidays as explained here or on the Key page. There are other short cuts used as discussed on the talk page but they are not yet included in the specification.
<week> This notation is borrowed from cron

and enables to express "in even weeks" or "on odd days".

<monthday_range> Evaluates to true of the date to check equals this day, to false otherwise.
<monthday_range> (plus) "Until further notice": the calendar range starts at this date and has no upper limit.
<monthday_range> (range) Evaluates to true, if from-dateday-to-checkto-date holds.

Evaluates to true, if from-date > to-date holds, year is not specified and either day-to-checkfrom-date or day-to-checkto-date holds. Evaluates to false otherwise.

<date_offset> Given any calendar day,

the notation + Su selects the first Sunday after this calendar day, the notation - Su selects the last Sunday before this calendar day.

<date_to> (daynum) A day missing a month is assumed to refer to the last month found before. So Jan 23-25 is evaluated as Jan 23-Jan 25.
<variable_date> There may be more <variable_date> s which are worth adding but until now only easter is supported. If something is missing please yell.
<extended_hour_minutes> Can be used to express opening hours wrapping over midnight. Opening hours wrapping over midnight can also be expressed if the second time (e.g. 04:00) is less than the first time (e.g. 22:00) for a value like Fr,Sa 22:00-04:00 which is probably easier to read especially if the second time is greater (compare Fr,Sa 22:00-20:00 with Fr,Sa 22:00-44:00).
<weeknum> The ISO 8601 definition for week 01 is the week with the year's first Thursday in it. See wikipedia.