string-template-parser/README.md

Parsing & evaluating utilities for string templates

# string-template-parser

String template parsing utilities.

- `parseStringTemplate` uses the default configuration (i.e. variable
start is marked by `${` and variable end by `}`, the escape character
is ` \ `, a pipe is started with `|` and a pipe parameter starts after
a `:`, e.g. `'string ${var | pipe : parameter}'`).

- `parseStringTemplateGenerator` returns a string parsing function
that uses the supplied expressions from the configuration parameter
to parse the string.

- `evaluateStringTemplate` takes a string and a list of variables and
one of pipe functions and returns a string where the variables are
replaced with their values (transformed by the pipe functions if
necessary).

- `evaluateParsedString` takes a parsed string object generated by the
`parseStringTemplate` function and returns a concatenated string with
the variables replaced by the given values in the variable dictionary,
passed through the pipe functions if necessary. This function is useful
when not using the default `parseStringTemplate` function, but one
generated by passing a parameter to `parseStringTemplateGenerator`.
`evaluateParsedString(parseStringTemplateGenerator()(input), ...args)`
is equivalent to `evaluateStringTemplate(input, ...args)`

## Usage

#### `parseStringTemplate`

```typescript
import { parseStringTemplate } from 'string-template-parser';

parseStringTemplate('a ${v1|p:param} b ${v2} c');
/* returns:
        {
          literals: ['a ', ' b ', ' c'],
          variables: [
            { name: 'v1', pipes: [{ name: 'p', parameters: ['param'] }],
            { name: 'v2', pipes: []}
          ]
        }
 */
```

#### `parseStringTemplateGenerator`

```typescript
import { parseStringTemplateGenerator } from 'string-template-parser';

const parseAngularStringTemplate = parseStringTemplateGenerator({
	VARIABLE_START: /^\{\{\s*/,
	VARIABLE_END: /^\s*\}\}/
});

parseAngularStringTemplate('a {{v1|p:param}} b {{v2}} c');
/* returns:
        {
          literals: ['a ', ' b ', ' c'],
          variables: [
            { name: 'v1', pipes: [{ name: 'p', parameters: ['param'] }],
            { name: 'v2', pipes: []}
          ]
        }
 */
```

#### `evaluateStringTemplate`

```typescript
import { evaluateStringTemplate } from 'string-template-parser';

evaluateStringTemplate(
	'x ${a|upper} y',
	{a: 'string'},
	{upper: value => value.toUpperCase()}
);
// returns 'x STRING y'
```

#### `evaluateParsedString`

```typescript
import { 
	parseStringTemplateGenerator,
	evaluateParsedString
} from 'string-template-parser';

const parseAngularStringTemplate = parseStringTemplateGenerator({
	VARIABLE_START: /^\{\{\s*/,
	VARIABLE_END: /^\s*\}\}/
});

evaluateParsedString(
	parseAngularStringTemplate('x {{a|upper}} y'),
	{a: 'string'},
	{upper: value => value.toUpperCase()}
);
// returns 'x STRING y'
```