This module is (when required) or exports as default (when imported) a Function implementing a string template tag interpreting a subset of JSONPath to construct a Lens. The only supported JSONPath operators are the single dot (.) and the square brackets ([...]); all other operators would result in a non-Lens optic. Within the square brackets, only string literals (in single- or double-quotes), unsigned or negative integers, and intercalated values are allowed. Use of unquoted @ (the JSONPath current object/element) in the expression is not allowed, and the $ (the JSONPath root object) is only allowed — and required — as the first character of the expression.

When an intercalated value is used within a subscript operator, the actual JavaScript value — not its string representation — is used as the step in the Lens; this allows for using lens.Step for custom stepping or arbitrary JavaScript values for keys into a Map or similar container.

This template tag processes the raw strings used in the template (to avoid doubling of backslashes for escape sequences); though this means a backslash-backtick combination (since backtick by itself ends the template) is processed as two characters, the only valid context for this to occur — due to the JSONPath syntax — is inside a string literal within square brackets, in which case the backslash-backtick sequence will be interpreted as a single backtick anyway. If this causes confusion, the \x60 escape sequence can be used instead.

Examples

const lens = require('natural-lenses'),  A = require('natural-lenses/sugar');

# Equivalent expressions

const lensExplicit1 = lens('foo', 'bar'), lensSugar1 = A`$.foo.bar`;

const lensExplicit2 = lens('street', 1), lensSugar2 = A`$.street[1]`;

const marker = Symbol('marker');
const lensExplicit3 = lens('item', marker), lensSugar3 = A`$.item[${marker}]`;