add function to allow users to register their own parser hooks

README.md

@@ -218,6 +218,30 @@ The original wiki links markup is elaborate, but here we only support simple syn
 * Internal links:  `[[pageTitle]]`  or `[[pageTitle|displayText]]`. For example `[[Apple]]` gives `<a href="./Apple" title="Apple">Apple</a>`.
 * External links: `[https://example.com]` or `[https://example.com display text]`
 
+## Extending the parser
+
+Following example illustrates extending the parser to support more parser plugins
+
+```js
+const banana = new Banana('en');
+banana.registerParserPlugin('sitename', () => {
+  return 'Wikipedia';
+});
+banana.registerParserPlugin('link', (nodes) => {
+  return '<a href="' + nodes[1] + '">' + nodes[0] + '</a>';
+});
+```
+
+This will parse the message
+```js
+banana.i18n('{{link:{{SITENAME}}|https://en.wikipedia.org}}');
+```
+to
+
+```
+<a href="https://en.wikipedia.org">Wikipedia</a>
+```
+
 ## Message documentation
 
 The message keys and messages won't give a enough context about the message being translated to the translator. Whenever a developer adds a new message, it is a usual practice to document the message to a file named qqq.json

src/index.js

@@ -1,5 +1,6 @@
 import BananaParser from './parser'
 import BananaMessageStore from './messagestore'
+import BananaEmitter from './emitter'
 import fallbacks from './languages/fallbacks.json'
 
 export default class Banana {
@@ -73,4 +74,26 @@ export default class Banana {
     }
     return messageKey
   }
+
+  /**
+   * Register a plugin for the library's message parser
+   * Example:
+   * <pre>
+   *   banana.registerParserPlugin('foobar', nodes => {
+   *     return nodes[0] === 'foo' ? nodes[1] : nodes[2]
+   *   }
+   * </pre>
+   * Usage:
+   * <pre>
+   *   banana.i18n('{{foobar:foo|first message|second message}}') --> 'first message'
+   *   banana.i18n('{{foobar:bar|first message|second message}}') --> 'second message'
+   * </pre>
+   * See emitter.js for built-in parser operations.
+   * @param {string} name - the name of the plugin
+   * @param {Function} plugin - the plugin function. It receives nodes as argument -
+   * a mixed array corresponding to the pipe-separated objects in the operation.
+   */
+  registerParserPlugin (name, plugin) {
+    BananaEmitter.prototype[name] = plugin
+  }
 }

test/banana.test.js

@@ -513,6 +513,36 @@ describe('Banana', function () {
     )
   })
 
+  it('should allow custom parser plugins', () => {
+    let locale = 'en'
+    const banana = new Banana(locale)
+    banana.registerParserPlugin('foobar', (nodes) => {
+      return nodes[0] === 'foo' ? nodes[1] : nodes[2]
+    })
+    assert.strictEqual(
+      banana.i18n('{{foobar:foo|first|second}}'),
+      'first',
+      'Emits first argument on passing foo to foobar plugin hook'
+    )
+    assert.strictEqual(
+      banana.i18n('{{foobar:bar|first|second}}'),
+      'second',
+      'Emits second argument on passing bar to foobar plugin hook'
+    )
+
+    banana.registerParserPlugin('sitename', () => {
+      return 'Wikipedia'
+    })
+    banana.registerParserPlugin('link', (nodes) => {
+      return '<a href="' + nodes[1] + '">' + nodes[0] + '</a>'
+    })
+    assert.strictEqual(
+      banana.i18n('{{link:{{SITENAME}}|https://en.wikipedia.org}}'),
+      '<a href="https://en.wikipedia.org">Wikipedia</a>',
+      'complex use of custom parser plugins'
+    )
+  })
+
   it('should parse the Arabic message', () => {
     const locale = 'ar'
     const banana = new Banana(locale)

types/banana-i18n.d.ts

@@ -1,5 +1,5 @@
 export interface Messages {
-	[ messageKey: string ]: string|Record<string, any>; 
+	[ messageKey: string ]: string|Record<string, any>;
 }
 
 export interface BananaOptions {
@@ -22,6 +22,7 @@ export interface Banana {
 	setLocale( locale: string ): void;
 	getFallbackLocales(): string[];
 	getMessage( messageKey: string ): string;
+	registerParserPlugin( name: string, plugin: ((nodes: ParameterType[]) => string) ): void;
 }
 
 export const Banana: BananaConstructor;