Zh-hans:Key:opening hours/specification
opening_hours 取值语法
本规范是基于 netzwolf.info 上的原始规范（镜像）的增强版本。
它是对标签 opening_hours=* 所用语法的一次形式化描述——该语法由社区多年来逐步形成，目的是作为标注者与开发者的参考。本规范最完善的实现是 opening_hours.js，也可以用它来检验你的 opening_hours 取值是否符合本规范。
为便于标注者查阅本规范，评估工具 会链向本规范。请查看其中的 „prettified opening_hours value for displaying“ 一节，取值的各组成部分都从那里链向本页的相应文档。
请注意，该语法最初是为描述设施的营业时间而引入的，但由于它已变得灵活而强大，如今也用于 OSM 中许多其他与时间相关的标签，这些标签在此列出。
语法总体结构概述
每个 opening_hours 取值（由语法符号 <time_domain> 描述）由一条或多条规则（符号 <rule_sequence>）组成，各规则之间由规则分隔符（<any_rule_separator>）分隔。
每条规则指定一组日期（使用 <wide_range_selectors>）、一组星期（<weekday_selectors>）和一组时段（<time_selector>），它们适用于给定日期范围内的那些星期。若未给出日期范围，则该规则适用于所有日期；若未给出星期集合，则该规则适用于所有星期。
默认情况下，规则所指定的时段表示设施开放，但可以通过附加规则修饰符（<rule_modifier>）来改变，例如改为 关闭。规则修饰符还可以包含用双引号括起来的自然语言注释。
若有多条规则适用于某一天，则规则分隔符的类型决定这些规则所指定的时段应如何合并。
已知问题
图例
- "|" 分隔可选方案。
- "[" 和 "]" 表示可选成分。
- "{" 和 "}" 表示可选且可重复的成分。
- 同一符号的多个产生式表示可选方案。
- 以 粗体 显示的字符或单词是语法中的关键字（或 词法单元）。
- 示例取值以 强调显示。
- 语法图中的符号按如下方式引用：
<selector_sequence>
语法图
Specification version 0.7.4. 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> | 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> | 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> |
[ |
|
<comment>:
|
Explanation | |
| <small_range_selectors> |
[ |
|
| <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> | ||
| <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> ] <month> <wday> [ [-]<nth> ]
|
||
[ <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> |
|
|
| <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 | |
|
| <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 | |
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> | " " | |
说明
| time_domain | ||
|---|---|---|
| 符号 | 说明 | |
| <time_domain> ↑ | 这是一个规则列表，每条规则都是 <rule_sequence> 的一个实例。
第一条规则以及所有由 规则按从左到右的顺序求值。如果指定了开放时段的普通规则适用于某一天，那么这些时段就是该天唯一开放的时段。如果附加规则适用于某一天，那么这些时段在该天也开放，并且是在此前所有规则所指定的时段之外追加的。 示例：
| |
| <rule_sequence> ↑ | 请注意，<rule_sequence> 当然不能为空。只有当 <selector_sequence> 与 <rule_modifier> 均非空时，才插入 <space>。
| |
| <additional_rule_separator> ↑ | 关于附加规则（含若干示例）的更多内容，请参阅 github 上的这个议题。
由于
| |
| <fallback_rule_separator> ↑ | 紧跟在该分隔符（标记）之后的规则将匹配此前规则未涵盖的每一个时间段。 | |
| <rule_modifier> (empty) ↑ | 默认为开放状态（就单条规则而言）。若未指定 <rule_modifier>，则 <rule_sequence> 被解释为开放。
| |
| <rule_modifier> (closed) ↑ | 带有 closed 或 off 修饰符的规则会截断其所匹配的时段。请注意，它们不会像带其他 <rule_modifier> 的规则那样覆盖别的东西。更多细节请参阅 github 上的这个议题。
| |
| <selector_sequence> (empty) ↑ | 含义为「始终」。该选择器会在任意时间匹配。 | |
| <wide_range_selectors> (no syntax) ↑ | 有时你无法（尚未能）精确指定有效的日历日期。 这种情况下，你可以在注释中使用纯文本，并在其后加上 ：。 | |
| <separator_for_readability> ↑ | 可选。它不会以任何方式改变含义。引入它是为了提升可读性。有些实现可能仍依赖它。如果你要实现此语法，请将 <separator_for_readability> 视为可选。
| |
| <timespan> (point in time) ↑ | 这仅在时间点模式下有效（例如 collection_times=* 或 service_times=* 这类标签）。
| |
| <timespan> (open end) ↑ | 开放时间在给定时刻开始，且没有定义关闭时间。
这类写法相当常见；但显然无法逐字求值。 求值方式在[此处](https://github.com/opening-hours/opening_hours.js#time-ranges)有说明。
| |
| <timespan> (shortcut for pattern points in time) ↑ | 这种写法描述一个重复发生的事件：
10:00-16:00/90 和 10:00-16:00/01:30 都被解释为「从上午十点到下午四点，每 1½ 小时一次」。 这种写法尤其适合用来非常简洁紧凑地书写发车时间。 "/" 之后的间隔时间在语法上有效，但会被 opening_hours 忽略。 这仅在时间点模式下有效（例如 | |
| <weekday_selector> ↑ | 符号（此处为 <holiday_sequence> 或 <weekday_sequence>）之间用 <space> 分隔时是[与](https://en.wikipedia.org/wiki/Logical_conjunction)关系，意思是两部分都必须匹配，该规则才适用。
以逗号分隔的符号则如常是[或](https://en.wikipedia.org/wiki/Logical_disjunction)关系，意思是至少有一部分匹配即可。 | |
| <weekday_range> (n-th weekday in month) ↑ | Su 表示所有周日，Su[1] 表示当月第一个周日，Su[-1] 表示当月最后一个周日。 | |
| <holiday> ↑ | 目前仅定义了在一天前后偏移一天（± 1 天）。 | |
| <school_holiday> ↑ | 可用于按[此处](https://github.com/opening-hours/opening_hours.js#holidays)或 键页面 中的说明来表达假日。讨论页 上还讨论了其他一些快捷写法，但它们尚未纳入本规范。给非英语母语者的提示：这也包括暑假，因此并不限于学年期间的假日。 | |
| <week> ↑ | 这种写法借鉴自 cron，可用于表达「在双周内」或「在奇数日」。 | |
| <monthday_range> ↑ | 当待检查的日期等于该日时求值为 true，否则为 false。
| |
| <monthday_range> (plus) ↑ | 「直至另行通知」：日历范围从该日期开始，没有上限。 | |
| <monthday_range> (range) ↑ | 若 from-date ≤ day-to-check ≤ to-date 成立，则求值为 true。
若 from-date > to-date 成立、未指定年份，且 day-to-check ≤ from-date 或 day-to-check ≧ to-date 成立，则求值为 | |
| <date_offset> ↑ | 给定任意日历日，写法 +Su 选出该日之后的第一个周日，写法 -Su 选出该日之前的最后一个周日。
运算符与星期之间不得有空格，因为一旦允许空格，任何解析器都无法区分 Jul 01 +Su（=七月的第一个周日）与 Jul 01 + Su（=自七月一日起的每个周日）。 | |
| <date_to> (daynum) ↑ | 缺少月份的日期被假定为指向前一个找到的月份。因此 Jan 23-25 会被解释为 Jan 23-Jan 25。 | |
| <variable_date> ↑ | 可能还有更多值得加入的 <variable_date>，但到目前为止仅支持 easter。如有缺失，请提出。
| |
| <extended_hour_minutes> ↑ | 可用于表达跨午夜延续的营业时间。跨午夜的营业时间也可以这样表达：第二个时间（如 04:00）小于第一个时间（如 22:00），例如 Fr,Sa 22:00-04:00；这种方式可能更容易阅读，在第二个时间更大时尤其如此（比较 Fr,Sa 22:00-20:00 与 Fr,Sa 22:00-44:00）。 | |
| <weeknum> ↑ | ISO 8601 对 week 01 的定义是：与 1 月 4 日处于同一周，也就是（等价地）包含该年第一个星期四的那个 ISO 周（从星期一开始）。参见维基百科。一年中第一个和最后一个 ISO 周最多可能有 3 天落在下一个或上一个公历年里：每个 ISO 周始终包含连续 7 天，同一「ISO 年」内的 ISO 周编号从 01 到 52 或 53。 美国还常用另一种商务周编号，它同样把 week 01 定义为与 1 月 4 日处于同一周，但它指的是包含该年第一个星期三的第一个美国周（从星期日开始）。 每当 1 月 4 日落在星期日时，商务周编号在全年（星期日除外）内相对 ISO 周历都会偏移 1。 在两种情况下，week 01 都不一定包含 1 月 1 日至 3 日，这几天可能被计入上一年的最后一周。 还有一种较少使用的周编号，它把 week 01 定义为与 1 月 1 日处于同一周。 | |
| <comment> ↑ | 注释可用于向用户提供额外信息或限制说明。当营业时间因依赖某些主观信息（例如天气）而无法由软件可靠确定时，也可使用注释。所用语言应为营业时间所属地区的母语。
示例：
| |
外部链接
- opening-hours/opening_hours_grammar GitHub – ANTLR 语法
- Peggy 语法
- "Is this a typo in the Opening Hours Specification?" - 讨论了该规范在某些情况下未提及空格
Warning: Default sort key "opening_hours/specification" overrides earlier default sort key "Key:opening hours/specification".