writing a profile guide: part 1

docs/index.md

@@ -7,3 +7,7 @@
 - [`location(id)`](location.md) – get details about a location
 - [`nearby(location, [opt])`](nearby.md) – show stations & POIs around
 - [`radar(north, west, south, east, [opt])`](radar.md) – find all vehicles currently in a certain area
+
+## Writing a profile
+
+Check [the guide](writing-a-profile.md).

docs/writing-a-profile.md

@@ -0,0 +1,57 @@
+# Writing a profile
+
+**Per endpoint, there is an endpoint-specific customisation called *profile*** which may for example do the following:
+
+- handle the additional requirements of the endpoint (e.g. authentication),
+- extract additional information from the data provided by the endpoint,
+- guard against triggering bugs of certain endpoints (e.g. time limits).
+
+**This guide is about writing such a profile.** If you just want to use an already supported endpoint, refer to the [API documentation](index.md) instead.
+
+*Note*: You can always ask for help by creating an issue! We're motivated to help people expand the scope of this library.
+
+## 0. How does it work?
+
+A profile contains two things:
+
+- **mandatory details about the HAFAS endpoint**
+	- `endpoint`: The protocol, host and path of the endpoint.
+	- `locale`: The [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) [locale](https://en.wikipedia.org/wiki/Locale_(computer_software)) of your endpoint (or the area that your endpoint covers).
+	- `timezone`: An [IANA-time-zone](https://www.iana.org/time-zones)-compatible [timezone](https://en.wikipedia.org/wiki/Time_zone) of your endpoint.
+- **flags indicating that features are supported by the endpoint** – e.g. `journeyRef`
+- **methods overriding the [default profile](../lib/default-profile.js)**
+
+As an example, let's say that our endpoint `https://example.org/bin/mgate.exe` has the timezone `Europe/Vienna` and locale `de-AT`. It also returns all lines names prefixed with `foo `. We can strip them like this:
+
+```js
+// get the default line parser
+const createParseLine = require('hafas-client/parse/line')
+
+const createParseLineWithoutFoo = (profile, operators) => {
+	const parseLine = createParseLine(profile, operators)
+
+	// wrapper function with additional logic
+	const parseLineWithoutFoo = (l) => {
+		const line = parseLine(l)
+		line.name = line.name.replace(/foo /g, '')
+		return line
+	}
+	return parseLineWithoutFoo
+}
+```
+
+Our profile will look like this:
+
+```js
+const myProfile = {
+	endpoint: 'https://example.org/bin/mgate.exe',
+	parseLine: createParseLineWithoutFoo
+}
+```
+
+If you pass this profile into `hafas-client`, the `parseLine` method will override [the default one](../parse/line.js).
+
+```js
+const createClient = require('hafas-client')
+const client = createClient(myProfile) // create a client with our profile
+```