Pardon Template Patterns

In Pardon templates, interpolated patterns are substrings beginning with {{ and ending with }}. Patterns which are entirely one "{{...}}" can represent any javascript scalar value: strings, booleans, numbers, null. (If they’re not simple then they can only represent strings, of course).

Note

Patterns are only recognized in some contexts, for instance, we don’t look for patterns when parsing an http response.

A pattern is composed of the following parts, and all of them are optional (spaces are also allowed around/in many of the syntax elements).

param

{{?scope.subscope.param=expression%/regex/}}

The param part identifies the value for use in other templates or expressions.

This names the value for use in other expressions, or gives it a name that can be parameterized by external values (input).

hint

{{?scope.subscope.param=expression%/regex/}}

The hint has multiple uses: configuing the regular expression matched by the pattern and for configuring the rendering / matching engine:

For instance, the inclusion of ?, ! and @ characters:

• ? marks a pattern optional for rendering.
• ! marks a pattern required for response matching.
• @ marks a pattern as redacted in persistence layers and logging.

And * changes the default regex from /.+/ to /.*/ (but this is context-depdenent).

Currently the hint is defined as zero or more of these characters .?!@#:~*/+-.

expressions

{{?scope.subscope.param=expression%/regex/}}

The expression provides a default value when rendering a pattern. The expression can reference other values in the same scope or in parent scopes. (Scopes are discussed more in schemas).

As it can evaluate to an asynchronous value (a javascript promise), as the result of making another call, the expression evaluation system was initially designed for automatically handling the generation of auth tokens.

export scope

{{?scope.subscope.param=expression%/regex/}}

If a pattern is inside a scope (for instance, an array of items), the export scope path provides a way to name the value in the top level scope. (Scopes are discussed more in schemas).

The input values can also be read through these scope paths.

regex

{{?scope.subscope.param=expression%/regex/}}

A regex can be specified to override the default regular expression of the pattern.

The default regex for most patterns is /.+/, but the * hint changes that to /.*/.

Caution

The pattern regex is used only when matching/resolving a schema, in particular, an evaluated expression is not checked (this includes {{a%/hello/}} when a is resolved through {{a = 'world'}} in another expression).

literals

{{"{{hello}}"}}

or

{{'{{hello}}'}}

If you do need a value with {{ or }} in it, you can use double or single-quoted strings to escape the pattern syntax inside a pattern.

Note

Double and single-quoted strings in expressions are also recognized to not end a pattern. Javascript back-tick string templates are not since the pattern parsing engine is currently regex-based and string templates can contain string templates!

On top of this value-structure we also allow patterns themselves to be transformed by the current configuration.

Pattern hints

The hint part annotates the value. In addition to configuring the rendering and matching engine, it can be used to configure the regular expression that the pattern expand to. This can be contextual, for instance, in URLs, https://example.com/items/{{item}} would match https://example.com/items/abc but not https://example.com/items/abc/color.

If you need to match a path with multiple parts, use the hint ...: E.g., https://example.com/blog/{{...post}} would match https://example.com/blog/path/to/my/post.

Note

Not currently supported: customized pattern definitions provided by scripts.