README.md

OpeningHoursParser

This is a very simplistic parser for string values according to the OSM opening hours specification. It is used in a number of OpenStreetMap projects, for example in Vespucci. 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).

Deviations from the grammar as of this version of the opening hours 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 non-strict mode the following further differences are allowed:

• three-character weekday abbreviations
• German two-letter weekday abbreviations
• times extending in to the next day that are missing the extra 24 hours are corrected
• 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 selectors are corrected to 00:00-24:00 time spans
• 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

try {
	OpeningHoursParser parser = new OpeningHoursParser(
		new ByteArrayInputStream(line.getBytes()));
	List<Rule> rules = parser.rules(strict);
	// ...
} catch(OpeningHoursParseException e) {
	// ...
	// e.getExceptions() will return a List<OpeningHoursParseException> 
	// containing more than one Exception if more than one issue was found 
}

Detailed documentation can be found in the JavaDoc.

Including in your project

We publish releases to Maven Central. The following snippets for build.gradle will make OpeningHoursParser available in your Gradle project:

repositories {
    mavenCentral()
}

dependencies {
    compile "ch.poole:OpeningHoursParser:0.25.0"
}

Tests

Besides some unit tests, we run the parser on ~160'000 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 for building. Standard gradle tasks for the java plugin can be found here 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, see https://www.transifex.com/openstreetmap/openinghoursparser/.