flextag-mapper

Parsing/unparsing flextags using a declarative mapping

See flextag-mapper-cli for command line interface.

Example

const { Mapper } = require('flextag-mapper')
const mapper = new Mapper()

mapper.onMatch('Good (morning|evening), ?name', match => {
  console.log('Name =', match.name)
})

mapper.onMatch('Hello, ?location!', match => {
  console.log('Location =', match.location)
})

mapper.parse('Hello, World! Good evening, Human.')
// => Location = World
// => Name = Human

console.log(mapper.unparse({ location: 'Paris' }))
// => Hello, Paris!

console.log(mapper.unparse({ name: 'Professor' }))
// => Good morning, Professor

console.log(mapper.unparse({ somethingElse: 'abc' }))
// => undefined

Template Spec Syntax

The mapper is configured with a custom template language, using terms like ?x for wildcards.

Branches

The mapper has zero or more "branches", which are template phrases it's trying to match against the input during parse(), or use for formatting on unparse().

• In a template spec, blank lines separate branches
• Parens and vertical bars can also be used to make branches. They are syntactic sugar, expanding out to branches. The spec a(b|c)(1|2|3|) expands to 8 branches: ab1, ac1, ab2, ac2, ab3, ac3, ab, ac.

Slots (wildcards, variables)

Slots are indicated by a question mark followed immediately by a word:

• At ?location the time is ?time
• At ?location the time is ?time.
• loc=?location time=?time

If you want a slot in the middle of a word, use parens to separate the variable name from the text that follows it. To match tags like "I can work 2x faster", with the number being a slot value:

• I can work ?(rate)x faster

Fixed variables

Fixed values can also be associated with slots, instead of text in the data stream:

Good evening, ?name ?(mode=late)
Good night, ?name ?(mode=late)

Good morning, ?name ?(mode=early)

On parse(), these will emit matches whic include the appropriate values, like {mode: "late"}. On unparse(), the value is required to be present for that branch to be used.

Whitespace

Outside of quotes, all whitespace is effectively normalized to a single space. Inside of quotes, whitespace is maintained.

Special Characters

At the moment there is no way to match parens or quotation characters occuring in flextags. Still considering the best way to do this.

Slot matching

The input text which matches a slot is:

• a quoted string, using exactly the rules of JSON for quoting and escaping
• a "square quoted" string: a sequence of characters starting with open bracket ("[") and ending with a matching close bracket ("]"). Within square quotes, no escaping is possible: strings containing unbalanced square brackets cannot be expressed this way and must us JSON-style quoting instead.
• a sequence without whitespace or trailing punctuation, called a "bare string". Typically this is a number, a word, or a URL. The allowed punctuation are the characters that MAY occur unescaped in URLs: -$.+!*',?&=%;:/@~#. Internationalization of this set is being considered but raises implementation difficulties.

The .unparse function uses bare strings when possible, then falls back to square quotes, then finally JSON quotes, if necessary to make sure .parse() would get the same value. The reasoning here is that flextags are supposed to be easy and natural for humans to read and write. Quotation marks in many contexts, while understood, have strong implications of distrust ("scare quotes"). The backslash escaping rules are also unknown by the general public and very hard to manage when there are several layers of nesting. In contrast, square brackets nest naturally, which is expected to be common for metadata.