Installation
Quick Take
Examples
- Prefix validation errors with the calling library's name
- Reject an input made only from one opening marker
- Start looking for marker pairs at a selected index
- Return an empty result for unusable marker inputs
- Require each opening marker to use the tail at the same array index
- Return completed pairs without throwing on an unmatched marker
Purpose
There are many templating languages out there, each using different special “markers” — Nunjucks use {{ and }}, Salesforce use {! and }, Mailchimp use *| and |* — there are many templating languages.
We call those “markers” heads and tails (invented term) because we need to distinguish between the two.
This program finds out, where are the templating marker heads and tails located in a given string.
It will be used in JSON pre-processing and it will let you use any existing or invented templating language.
Context
It’s a non-parsing scanner for arbitrary templating language markers.
There are few rules:
- Each finding must be in sequence: heads — tails — heads — tails.
- When one heads is found, no new heads findings will be accepted into the results until there’s a new tails finding. Same goes the opposite way, for tails.
- Both heads and tails can be supplied either as a single string or array of strings. Findings are prioritised by their order in the array.
API — strFindHeadsTails()
The main function strFindHeadsTails() is imported like this:
It’s a function which takes four input arguments:
| Input argument | Type | Obligatory | Description |
|---|---|---|---|
strType: String Obligatory: yes | |||
str | String | yes | The string in which you want to perform a search |
headsType: String or Array of strings Obligatory: yes | |||
heads | String or Array of strings | yes | One or more string, the first half of the set. For example, ['%%-', '%%_']. |
tailsType: String or Array of strings Obligatory: yes | |||
tails | String or Array of strings | yes | One or more string, the second half of the set. For example, ['-%%', '_%%']. |
optsType: Plain object Obligatory: no | |||
opts | Plain object | no | An Optional Options Object. |
The Optional Options Object has the following shape:
| Key | Type | Default | Description |
|---|---|---|---|
fromIndexType: Natural number or zero as number or string Default: 0 | |||
fromIndex | Natural number or zero as number or string | 0 | If you want to start the search later, only from a certain index, set it here. Same as 2nd argument position in String.includes. |
throwWhenSomethingWrongIsDetectedType: Boolean Default: true | |||
throwWhenSomethingWrongIsDetected | Boolean | true | By default, if anything wrong is detected, error will be thrown. For example, tails precede heads. Or two consecutive heads or tails are detected. If you want to turn this functionality off, set to false. Turning this off automatically sets the allowWholeValueToBeOnlyHeadsOrTails (see below) to true, that is, error won’t be thrown when whole input is equal to one of heads or tails. This setting does not concern wrong input types. To allow input in wrong types, set relaxedAPI, see below. |
allowWholeValueToBeOnlyHeadsOrTailsType: Boolean Default: true | |||
allowWholeValueToBeOnlyHeadsOrTails | Boolean | true | If whole input str is equal to one of heads or tails AND opts.throwWhenSomethingWrongIsDetected is true, THEN error won’t be thrown and that input will not be processed. But if you set this to false AND error throwing is on (opts.throwWhenSomethingWrongIsDetected is true), error will be thrown. This feature is activated only when opts.throwWhenSomethingWrongIsDetected is true. |
sourceType: String Default: string-find-heads-tails | |||
source | String | string-find-heads-tails | Packages that consume this package as a dependency might rely on some of our error throwing functionality. Since thrown message mentions the name of the throwee, you can override it, setting to parent package’s name. |
matchHeadsAndTailsStrictlyInPairsByTheirOrderType: Boolean Default: false | |||
matchHeadsAndTailsStrictlyInPairsByTheirOrder | Boolean | false | If it’s set to true, the index numbers of heads and tails in their input arrays must match. Different pairs can have different indexes, as long as they match between the pair. For example, %%_test-%% or %%-test_%%. |
relaxedAPIType: Boolean Default: false | |||
relaxedAPI | Boolean | false | If it’s set to true, wrong inputs will instantly yield []. If it’s default setting, false, it would throw an error. This only concerns the checks before any real work is done on the input, where error-throwing is controlled by throwWhenSomethingWrongIsDetected (see above). |
Here are all defaults in one place for copying:
Function will return an array of zero or more plain objects, each having the following shape (ResObj type above):
Indexes are suitable for String.prototype.slice() — once you have the start and end positions, you can slice-out heads and tails.
API — defaults
You can import defaults:
It's a plain object:
The main function calculates the options to be used by merging the options you passed with these defaults.
API — version
You can import version: