rename d.remarks -> d.hints, parseRemark -> parseHint

HAFAS returns notes for journey legs, stopovers and departures.

There are two kinds of notes: "remarks" (in `remL`) and HAFAS
Information Manager (HIM) notes (in `himL`). The former describe
the regular operating situation, e.g. "bicycles allows", whereas
the latter describe cancellations, construction work, etc.

The planned naming scheme for hafas-client:
- hints: notes from `remL` for regular operation
- warnings: notes from `himL` for cancellations, construction, etc
- remarks: both "notes" and "warnings"

This commit prepares the new naming scheme by renaming the
existing parsing logic of `remL` to "hints". Follow-up commits
will add `parseWarning`.

index.js

@@ -51,7 +51,7 @@ const createClient = (profile, request = _request) => {
 		})
 		.then((d) => {
 			if (!Array.isArray(d.jnyL)) return [] // todo: throw err?
-			const parse = profile.parseDeparture(profile, d.locations, d.lines, d.remarks)
+			const parse = profile.parseDeparture(profile, d.locations, d.lines, d.hints)
 			return d.jnyL.map(parse)
 			.sort((a, b) => new Date(a.when) - new Date(b.when))
 		})
@@ -164,7 +164,7 @@ const createClient = (profile, request = _request) => {
 				if (!Array.isArray(d.outConL)) return []
 
 				const polylines = opt.polylines && d.common.polyL || []
-				const parse = profile.parseJourney(profile, d.locations, d.lines, d.remarks, polylines)
+				const parse = profile.parseJourney(profile, d.locations, d.lines, d.hints, polylines)
 
 				if (!journeys.earlierRef) journeys.earlierRef = d.outCtxScrB
 
@@ -310,7 +310,7 @@ const createClient = (profile, request = _request) => {
 		})
 		.then((d) => {
 			const polylines = opt.polyline && d.common.polyL || []
-			const parse = profile.parseJourneyLeg(profile, d.locations, d.lines, d.remarks, polylines)
+			const parse = profile.parseJourneyLeg(profile, d.locations, d.lines, d.hints, polylines)
 
 			const leg = { // pretend the leg is contained in a journey
 				type: 'JNY',
@@ -363,7 +363,7 @@ const createClient = (profile, request = _request) => {
 			if (!Array.isArray(d.jnyL)) return []
 
 			const polylines = opt.polyline && d.common.polyL || []
-			const parse = profile.parseMovement(profile, d.locations, d.lines, d.remarks, polylines)
+			const parse = profile.parseMovement(profile, d.locations, d.lines, d.hints, polylines)
 			return d.jnyL.map(parse)
 		})
 	}

lib/default-profile.js

@@ -10,7 +10,7 @@ const parsePolyline = require('../parse/polyline')
 const parseMovement = require('../parse/movement')
 const parseNearby = require('../parse/nearby')
 const parseOperator = require('../parse/operator')
-const parseRemark = require('../parse/remark')
+const parseHint = require('../parse/hint')
 const parseStopover = require('../parse/stopover')
 
 const formatAddress = require('../format/address')
@@ -47,7 +47,7 @@ const defaultProfile = {
 	parseMovement,
 	parseNearby,
 	parseOperator,
-	parseRemark,
+	parseHint,
 	parseStopover,
 
 	formatAddress,

lib/request.js

@@ -81,7 +81,7 @@ const request = (profile, data) => {
 		const c = d.common || {}
 
 		if (Array.isArray(c.remL)) {
-			d.remarks = c.remL.map(rem => profile.parseRemark(profile, rem))
+			d.hints = c.remL.map(hint => profile.parseHint(profile, hint))
 		}
 		if (Array.isArray(c.opL)) {
 			d.operators = c.opL.map(op => profile.parseOperator(profile, op))

lib/validate-profile.js

@@ -20,7 +20,7 @@ const types = {
 	parseMovement: 'function',
 	parseNearby: 'function',
 	parseOperator: 'function',
-	parseRemark: 'function',
+	parseHint: 'function',
 	parseStopover: 'function',
 
 	formatAddress: 'function',

p/db/index.js

@@ -34,8 +34,8 @@ const transformJourneysQuery = (query, opt) => {
 	return query
 }
 
-const createParseJourney = (profile, stations, lines, remarks, polylines) => {
-	const parseJourney = _createParseJourney(profile, stations, lines, remarks, polylines)
+const createParseJourney = (profile, stations, lines, hints, polylines) => {
+	const parseJourney = _createParseJourney(profile, stations, lines, hints, polylines)
 
 	// todo: j.sotRating, j.conSubscr, j.isSotCon, j.showARSLink, k.sotCtxt
 	// todo: j.conSubscr, j.showARSLink, j.useableTime

p/nahsh/index.js

@@ -36,8 +36,8 @@ const parseLocation = (profile, l, lines) => {
 	return res
 }
 
-const createParseJourney = (profile, stations, lines, remarks) => {
-	const parseJourney = _createParseJourney(profile, stations, lines, remarks)
+const createParseJourney = (profile, stations, lines, hints) => {
+	const parseJourney = _createParseJourney(profile, stations, lines, hints)
 
 	const parseJourneyWithTickets = (j) => {
 		const res = parseJourney(j)
@@ -78,8 +78,8 @@ const createParseJourney = (profile, stations, lines, remarks) => {
 	return parseJourneyWithTickets
 }
 
-const createParseMovement = (profile, locations, lines, remarks) => {
-	const _parseMovement = _createParseMovement(profile, locations, lines, remarks)
+const createParseMovement = (profile, locations, lines, hints) => {
+	const _parseMovement = _createParseMovement(profile, locations, lines, hints)
 	const parseMovement = (m) => {
 		const res = _parseMovement(m)
 		// filter out empty nextStops entries

p/oebb/index.js

@@ -44,8 +44,8 @@ const parseLocation = (profile, l, lines) => {
 	return res
 }
 
-const createParseMovement = (profile, locations, lines, remarks) => {
-	const _parseMovement = _createParseMovement(profile, locations, lines, remarks)
+const createParseMovement = (profile, locations, lines, hints) => {
+	const _parseMovement = _createParseMovement(profile, locations, lines, hints)
 	const parseMovement = (m) => {
 		const res = _parseMovement(m)
 		// filter out POIs

p/vbb/index.js

@@ -56,8 +56,8 @@ const parseLocation = (profile, l, lines) => {
 	return res
 }
 
-const createParseJourney = (profile, stations, lines, remarks, polylines) => {
-	const parseJourney = _createParseJourney(profile, stations, lines, remarks, polylines)
+const createParseJourney = (profile, stations, lines, hints, polylines) => {
+	const parseJourney = _createParseJourney(profile, stations, lines, hints, polylines)
 
 	const parseJourneyWithTickets = (j) => {
 		const res = parseJourney(j)
@@ -86,8 +86,8 @@ const createParseJourney = (profile, stations, lines, remarks, polylines) => {
 	return parseJourneyWithTickets
 }
 
-const createParseDeparture = (profile, stations, lines, remarks) => {
-	const parseDeparture = _createParseDeparture(profile, stations, lines, remarks)
+const createParseDeparture = (profile, stations, lines, hints) => {
+	const parseDeparture = _createParseDeparture(profile, stations, lines, hints)
 
 	const ringbahnClockwise = /^ringbahn s\s?41$/i
 	const ringbahnAnticlockwise = /^ringbahn s\s?42$/i

parse/departure.js

@@ -6,8 +6,8 @@
 // todo: d.stbStop.dProgType
 // todo: d.freq, d.freq.jnyL, see https://github.com/public-transport/hafas-client/blob/9203ed1481f08baacca41ac5e3c19bf022f01b0b/parse.js#L115
 
-const createParseDeparture = (profile, stations, lines, remarks) => {
-	const findRemark = rm => remarks[parseInt(rm.remX)] || null
+const createParseDeparture = (profile, stations, lines, hints) => {
+	const findHint = rm => hints[parseInt(rm.remX)] || null
 
 	const parseDeparture = (d) => {
 		const when = profile.parseDateTime(profile, d.date, d.stbStop.dTimeR || d.stbStop.dTimeS)
@@ -17,7 +17,7 @@ const createParseDeparture = (profile, stations, lines, remarks) => {
 			when: when.toISO(),
 			direction: profile.parseStationName(d.dirTxt),
 			line: lines[parseInt(d.prodX)] || null,
-			remarks: d.remL ? d.remL.map(findRemark) : [],
+			remarks: d.remL ? d.remL.map(findHint) : [],
 			trip: +d.jid.split('|')[1] // todo: this seems brittle
 		}
 		// todo: res.trip from rawLine.prodCtx.num?

parse/find-remark.js

@@ -0,0 +1,18 @@
+'use strict'
+
+// There are two kinds of notes: "remarks" (in `remL`) and HAFAS
+// Information Manager (HIM) notes (in `himL`). The former describe
+// the regular operating situation, e.g. "bicycles allows", whereas
+// the latter describe cancellations, construction work, etc.
+
+// hafas-client's naming scheme:
+// - hints: notes from `remL` for regular operation
+// - warnings: notes from `himL` for cancellations, construction, etc
+// - remarks: both "notes" and "warnings"
+
+const findRemark = (hints, ref) => {
+	// todo: `warnings[ref.himX]`
+	return hints[ref.remX] || null
+}
+
+module.exports = findRemark

parse/hint.js

@@ -74,39 +74,39 @@ const hints = Object.assign(Object.create(null), {
 })
 
 // todo: is passing in profile necessary?
-const parseRemark = (profile, r) => {
+const parseHint = (profile, h) => {
 	// todo: U "stop cancelled"?
 	// todo: C
 
 	// todo: find sth more reliable than this
-	if (r.type === 'P' && r.txtN.toLowerCase().trim() === 'journey cancelled') {
+	if (h.type === 'P' && h.txtN.toLowerCase().trim() === 'journey cancelled') {
 		return {
 			type: 'status',
 			code: 'journey-cancelled',
-			text: r.txtN
-			// todo: `r.sIdx`
+			text: h.txtN
+			// todo: `h.sIdx`
 		}
 	}
-	if (r.type === 'L') {
+	if (h.type === 'L') {
 		return {
 			type: 'status',
 			code: 'alternative-trip',
-			text: r.txtN,
-			journeyId: r.jid
+			text: h.txtN,
+			journeyId: h.jid
 		}
 	}
-	if (r.type === 'A') {
-		return hints[r.code && r.code.trim().toLowerCase()] || null
+	if (h.type === 'A') {
+		return hints[h.code && h.code.trim().toLowerCase()] || null
 	}
-	if (r.type === 'R') {
+	if (h.type === 'R') {
 		// todo: how can we identify the individual types?
 		return {
 			type: 'status',
-			code: r.code,
-			text: r.txtN || ''
+			code: h.code,
+			text: h.txtN || ''
 		}
 	}
 	return null
 }
 
-module.exports = parseRemark
+module.exports = parseHint

parse/index.js

@@ -4,7 +4,7 @@ module.exports = {
 	dateTime: require('./date-time'),
 	location: require('./location'),
 	line: require('./line'),
-	remark: require('./remark'),
+	hint: require('./hint'),
 	operator: require('./operator'),
 	stopover: require('./stopover'),
 	journeyLeg: require('./journey-leg'),

parse/journey-leg.js

@@ -4,10 +4,7 @@ const parseDateTime = require('./date-time')
 
 const clone = obj => Object.assign({}, obj)
 
-const createParseJourneyLeg = (profile, stations, lines, remarks, polylines) => {
-	// todo: finish parse/remark.js first
-	const applyRemark = (j, rm) => {}
-
+const createParseJourneyLeg = (profile, stations, lines, hints, polylines) => {
 	// todo: pt.sDays
 	// todo: pt.dep.dProgType, pt.arr.dProgType
 	// todo: what is pt.jny.dirFlg?
@@ -55,13 +52,12 @@ const createParseJourneyLeg = (profile, stations, lines, remarks, polylines) =>
 			if (pt.arr.aPlatfS) res.arrivalPlatform = pt.arr.aPlatfS
 
 			if (passed && pt.jny.stopL) {
-				const parse = profile.parseStopover(profile, stations, lines, remarks, j.date)
+				const parse = profile.parseStopover(profile, stations, lines, hints, j.date)
 				const passedStations = pt.jny.stopL.map(parse)
 				// filter stations the train passes without stopping, as this doesn't comply with fptf (yet)
 				res.passed = passedStations.filter((x) => !x.passBy)
-			}
-			if (Array.isArray(pt.jny.remL)) {
-				for (let remark of pt.jny.remL) applyRemark(j, remark)
+
+				// todo: pt.jny.remL, j.msgL
 			}
 
 			const freq = pt.jny.freq || {}

parse/journey.js

@@ -2,8 +2,8 @@
 
 const clone = obj => Object.assign({}, obj)
 
-const createParseJourney = (profile, stations, lines, remarks, polylines) => {
-	const parseLeg = profile.parseJourneyLeg(profile, stations, lines, remarks, polylines)
+const createParseJourney = (profile, stations, lines, hints, polylines) => {
+	const parseLeg = profile.parseJourneyLeg(profile, stations, lines, hints, polylines)
 
 	// todo: c.sDays
 	// todo: c.conSubscr

parse/movement.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const createParseMovement = (profile, locations, lines, remarks, polylines = []) => {
+const createParseMovement = (profile, locations, lines, hints, polylines = []) => {
 	// todo: what is m.dirGeo? maybe the speed?
 	// todo: what is m.stopL?
 	// todo: what is m.proc? wut?
@@ -8,7 +8,7 @@ const createParseMovement = (profile, locations, lines, remarks, polylines = [])
 	// todo: what is m.ani.dirGeo[n]? maybe the speed?
 	// todo: what is m.ani.proc[n]? wut?
 	const parseMovement = (m) => {
-		const pStopover = profile.parseStopover(profile, locations, lines, remarks, m.date)
+		const pStopover = profile.parseStopover(profile, locations, lines, hints, m.date)
 
 		const res = {
 			direction: profile.parseStationName(m.dirTxt),

parse/stopover.js

@@ -2,7 +2,7 @@
 
 // todo: arrivalDelay, departureDelay or only delay ?
 // todo: arrivalPlatform, departurePlatform
-const createParseStopover = (profile, stations, lines, remarks, date) => {
+const createParseStopover = (profile, stations, lines, hints, date) => {
 	const parseStopover = (st) => {
 		const res = {
 			station: stations[parseInt(st.locX)] || null,