Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simonpoole/openinghoursparser
Parser for string values according to the OSM opening hours specification
https://github.com/simonpoole/openinghoursparser
openstreetmap
Last synced: 5 days ago
JSON representation
Parser for string values according to the OSM opening hours specification
- Host: GitHub
- URL: https://github.com/simonpoole/openinghoursparser
- Owner: simonpoole
- License: mit
- Created: 2015-08-19T11:53:47.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-09-09T11:52:50.000Z (3 months ago)
- Last Synced: 2024-09-09T14:06:57.332Z (3 months ago)
- Topics: openstreetmap
- Language: Java
- Homepage:
- Size: 39.5 MB
- Stars: 32
- Watchers: 4
- Forks: 12
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/simonpoole/OpeningHoursParser/actions) [](https://sonarcloud.io/dashboard?id=OpeningHoursParser) [](https://sonarcloud.io/dashboard?id=OpeningHoursParser) [](https://sonarcloud.io/component_measures?id=OpeningHoursParser&metric=bugs) [](https://sonarcloud.io/component_measures?id=OpeningHoursParser&metric=Maintainability) [](https://sonarcloud.io/component_measures?id=OpeningHoursParser&metric=Security) [](https://sonarcloud.io/component_measures?id=OpeningHoursParser&metric=Reliability) [](https://liberapay.com/SimonPoole/donate)
# OpeningHoursParser
This is a very simplistic parser for string values according to the [OSM opening hours specification][opening-hours-specification]. It is used in a number of OpenStreetMap projects, for example
in [Vespucci](https://github.com/MarcusWolschon/osmeditor4android). As the opening hours specification is currently reasonably stable you shouldn't expect lots of activity in this repository.
It parses 147'209 (91%) of 161'265 unique test strings in non-strict mode. The remaining 14'056 are likely valid errors, spot checking shows that they have obvious issues. In strict mode a further 15'993 fail (total 30'072).
"in the wild" there are currently 3.4 million opening hour values in OSM, of these we successfully parse 99.1%, leaving 31'000 that fail (in non-strict mode). Parsing a single value successfully on a 15 year old PC (slower than a modern mobile phone for these kind of workloads) takes on average 0.05 ms, or put differently we can easily parse 20'000 values per second in a single thread. Parsing a non-compliant value takes 0.1 ms on average, this is somewhat slower as we restart parsing, potentially multiple times, to determine as many issues as possible in one go. This could certainly be sped up by not using a parser generator and manually coding, however given that it takes just 3 minutes to parse all above mentioned 3.4 million values, and in real life scenarios many other factors will dominate the run time, this would be a substantial waste of time.
Deviations from the grammar as of [this version of the opening hours specification][opening-hours-grammar-specification] in all modes:
* case-insensitive
* leading 0s in times optional
* unicode EN DASH (U+2013) EM DASH (U+2014) characters are allowed for hyphen
* various unicode whitespace characters are ignored
In strict mode time ranges that have a numerically earlier ending time than start and
do not use the _extended time_ format will cause a parse exception to be thrown, this
can be overridden when calling the parser.
In non-strict mode the following further differences are allowed:
* three-character weekday abbreviations
* German two-letter weekday abbreviations
* single 0 for minutes
* minutes in times optional
* ignore spaces and more than one leading zeros in minutes
* "." and "h" as minutes separators
* AM and PM time specifications are allowed (plus A.M. and P.M.)
* holidays in weekday range
* superfluous ":" after weekday range
* 24/7 rules with preceding year, week and date selectors are corrected to 00:00-24:00 time spans
* single digit month day numbers (Jan 1 instead of Jan 01)
* list of month days after months ( Jan 1,4,5 )
* " to " and some translations of it in lieu of a hyphen for ranges
* date ranges that do not have the month day specified are corrected (Jan - Feb 15 -> Jan 1 - Feb 15)
Converting the data structures generated by parsing back to strings will result in correct data according to the specification.
## Usage
``` java
try {
OpeningHoursParser parser = new OpeningHoursParser(
new ByteArrayInputStream(line.getBytes()));
List rules = parser.rules(strict, strictTime);
// ...
} catch(OpeningHoursParseException e) {
// ...
// e.getExceptions() will return a List
// containing more than one Exception if more than one issue was found
}
```
Detailed documentation can be found in the [JavaDoc](http://www.javadoc.io/doc/ch.poole/OpeningHoursParser/0.28.2).
## Including in your project
We publish releases to [Maven Central](https://repo1.maven.org/maven2/ch/poole/OpeningHoursParser/).
The following snippets for `build.gradle` will make OpeningHoursParser available in your Gradle project:
``` groovy
repositories {
mavenCentral()
}
```
``` groovy
dependencies {
compile "ch.poole:OpeningHoursParser:0.28.2"
}
```
[opening-hours-specification]: http://wiki.openstreetmap.org/wiki/Key:opening_hours/specification
[opening-hours-grammar-specification]: http://wiki.openstreetmap.org/w/index.php?title=Key:opening_hours/specification&oldid=1075290
## Tests
Besides unit tests, we run the parser on ~160'000 opening hours values from the
OSM database and compare with previous output to detect any changes in behaviour. If you are running these on windows, you may need to add
``org.gradle.jvmargs=-Dfile.encoding=UTF-8``
to your gradle.properties to force correct use of the UTF-8 encoded test input.
## Building
The project uses [gradle](https://gradle.org/) for building. Standard gradle tasks for the java plugin can be found here [https://docs.gradle.org/current/userguide/java_plugin.html](https://docs.gradle.org/current/userguide/java_plugin.html). They can be invoked on the command line by running ``gradlew`` or ``gradlew.bat`` with the name of the task, for example
``gradlew jar`` to create the jar archive.
Note: the project has no runtime dependencies, and the jar file resulting from the build process is self-sufficient.
## Contributing
Pull requests are welcome.
As this library is used in a number of Android projects please restrict the use of Java 8 features and APIs to the Android supported subset see https://developer.android.com/studio/write/java8-support. Check that any APIs used are supported on all Android platform API versions 10 and later, this is mainly an issue for APIs that were introduced with Java 7. This restriction will likely be relaxed for future versions.
Currently, the library is self-contained and doesn't have any runtime dependencies outside of basic Java support, it would be nice if we can keep it like that.
## Translation
The error messages produced by the library are translated on [transifex](https://transifex.com/), see [https://www.transifex.com/openstreetmap/openinghoursparser/](https://www.transifex.com/openstreetmap/openinghoursparser/).