Accept callback for formatting tokens

Added a formatToken option to compile, getWayName, and tokenize that gives the client an opportunity to manipulate a road name or other token value after any transformations built into this library but before the value is inserted into the overall instruction string.

Author: 1ec5

.eslintrc.json

@@ -82,7 +82,12 @@
         "max-len": "off",
         "max-lines": "off",
         "max-nested-callbacks": "error",
-        "max-params": "error",
+        "max-params": [
+            "error",
+            {
+                "max": 4
+            }
+        ],
         "max-statements": "off",
         "max-statements-per-line": "off",
         "multiline-ternary": "off",

CHANGELOG.md

@@ -1,6 +1,10 @@
 # Change Log
 All notable changes to this project will be documented in this file. For change log formatting, see http://keepachangelog.com/
 
+## master
+
+- Added a `formatToken` option to `compile`, `getWayName`, and `tokenize` that allows you to manipulate any token value after any grammar or capitalization rules are applied but before the value is inserted into the instruction. [#170](https://github.com/Project-OSRM/osrm-text-instructions/pull/170)
+
 ## 0.9.0 2017-10-05
 
 - Added `getBestMatchingLanguage` for determining the closest available language. Pass a user locale into this method before passing the return value into `compile`. [#168](https://github.com/Project-OSRM/osrm-text-instructions/pull/168)

Readme.md

@@ -50,7 +50,22 @@ parameter | required? | values | description
 ---|----|----|---
 `language` | required | `en` `de` `zh-Hans` `fr` `nl` `ru` [and more](https://github.com/Project-OSRM/osrm-text-instructions/tree/master/languages/translations/) | Compiling instructions for the selected language code.
 `step` | required | [OSRM route step object](https://github.com/Project-OSRM/osrm-backend/blob/master/docs/http.md#routestep-object) | The RouteStep as it comes out of OSRM
-`options` | optional | Object with 2 keys: `legIndex` and `legCount`, both having integer values. Used for giving instructions for arriving at waypoints.
+`options` | optional | Object | See [below](#options)
+
+##### Options
+
+key | type | description
+---|----|----|---
+`legCount` | integer | Number of legs in the route
+`legIndex` | integer | Zero-based index of the leg containing the step; together with `legIndex`, this option determines whether an arrival instruction indicates which waypoint the user has arrived at
+`formatToken` | function | Function that formats the given token value after grammaticalization and capitalization but before the value is inserted into the instruction string
+
+`formatToken` takes two parameters:
+
+* `token`: A string that indicates the kind of token, such as `way_name` or `direction`
+* `value`: A grammatical string for this token, capitalized if the token appears at the beginning of the instruction
+
+and returns a string.
 
 ### Development
 #### Architecture

index.js

@@ -98,7 +98,7 @@ module.exports = function(version, _options) {
                 wayName = this.tokenize(language, phrase, {
                     name: name,
                     ref: ref
-                });
+                }, options);
             } else if (name && ref && wayMotorway && (/\d/).test(ref)) {
                 wayName = ref;
             } else if (!name && ref) {
@@ -204,7 +204,7 @@ module.exports = function(version, _options) {
                 'nth': nthWaypoint
             };
 
-            return this.tokenize(language, instruction, replaceTokens);
+            return this.tokenize(language, instruction, replaceTokens, options);
         },
         grammarize: function(language, name, grammar) {
             if (!language) throw new Error('No language code provided');
@@ -226,22 +226,36 @@ module.exports = function(version, _options) {
 
             return name;
         },
-        tokenize: function(language, instruction, tokens) {
+        tokenize: function(language, instruction, tokens, options) {
             if (!language) throw new Error('No language code provided');
             // Keep this function context to use in inline function below (no arrow functions in ES4)
             var that = this;
-            var output = instruction.replace(/\{(\w+):?(\w+)?\}/g, function(token, tag, grammar) {
-                var name = tokens[tag];
-                if (typeof name !== 'undefined') {
-                    return that.grammarize(language, name, grammar);
-                }
+            var startedWithToken = false;
+            var output = instruction.replace(/\{(\w+)(?::(\w+))?\}/g, function(token, tag, grammar, offset) {
+                var value = tokens[tag];
 
                 // Return unknown token unchanged
-                return token;
+                if (typeof value === 'undefined') {
+                    return token;
+                }
+
+                value = that.grammarize(language, value, grammar);
+
+                // If this token appears at the beginning of the instruction, capitalize it.
+                if (offset === 0 && instructions[language].meta.capitalizeFirstLetter) {
+                    startedWithToken = true;
+                    value = that.capitalizeFirstLetter(language, value);
+                }
+
+                if (options && options.formatToken) {
+                    value = options.formatToken(tag, value);
+                }
+
+                return value;
             })
             .replace(/ {2}/g, ' '); // remove excess spaces
 
-            if (instructions[language].meta.capitalizeFirstLetter) {
+            if (!startedWithToken && instructions[language].meta.capitalizeFirstLetter) {
                 return this.capitalizeFirstLetter(language, output);
             }
 

test/index_test.js

@@ -1,3 +1,4 @@
+/* eslint max-lines: "off" */
 var path = require('path');
 var fs = require('fs');
 var tape = require('tape');
@@ -34,6 +35,47 @@ tape.test('v5 tokenize', function(assert) {
     });
     assert.equal(missingSecond, 'Can osrm {second}', 'does not replace tokens which are not provided');
 
+    var formatsTokens = v5Compiler.tokenize('en', 'Take me {destination}, {way_name}', {
+        destination: 'home',
+        'way_name': 'Country Road'
+    }, {
+        formatToken: function (token, value) {
+            if (token === 'destination') {
+                return '<prosody rate="slow">' + value + '</prosody>';
+            }
+            if (token === 'name' || token === 'way_name' || token === 'rotary_name') {
+                return value.replace('Road', '<prosody rate="slow">Road</prosody>');
+            }
+
+            return value;
+        }
+    });
+    assert.equal(formatsTokens, 'Take me <prosody rate="slow">home</prosody>, Country <prosody rate="slow">Road</prosody>',
+                 'Formats tokens');
+
+    var capitalizesTokens = v5Compiler.tokenize('en', '{modifier} turns are prohibited here', {
+        modifier: 'left'
+    }, {
+        formatToken: function (token, value) {
+            if (token === 'modifier') {
+                return '<strong>' + value + '</strong>';
+            }
+
+            return value;
+        }
+    });
+    assert.equal(capitalizesTokens, '<strong>Left</strong> turns are prohibited here',
+                 'Capitalizes tokens before formatting');
+
+    var formatsGrammaticalTokens = v5Compiler.tokenize('ru', 'Плавно поверните налево на {way_name:accusative}', {
+        'way_name': 'Бармалеева улица'
+    }, {
+        formatToken: function (token, value) {
+            return token === 'way_name' ? value.toLocaleUpperCase('ru') : value;
+        }
+    });
+    assert.equal(formatsGrammaticalTokens, 'Плавно поверните налево на БАРМАЛЕЕВУ УЛИЦУ',
+                 'Formats tokens after grammaticalization but before insertion');
 
     assert.end();
 });