first commit

node_modules/@n8n_io/riot-tmpl/doc/API.md

@@ -0,0 +1,145 @@
+
+# The riot-tmpl API
+
+## tmpl
+
+
+### `tmpl` function
+
+_usage:_ `tmpl( str, data )`
+
+The exposed `tmpl` function returns the template value from the cache, render with data.
+
+_parameters_
+
+* `str`  : string - Expression or template with zero or more expressions
+* `data` : object - A Tag instance, for setting the context
+
+_returns:_ string - Raw value of the expression or template to render
+
+
+### `hasExpr` function
+
+_usage:_ `brackets.hasExpr( str )`
+
+Checks for an expression within a string, using the current brackets.
+
+_parameters_
+
+* `str` : string - String where to search
+
+_returns:_ boolean - `true` if the string contains an expression
+
+NOTE: This function only checks for a pair of unescaped riot brackets, does not validate
+the expression nor excludes brackets within quotes.
+
+
+### `errorHandler` property
+
+_type:_ function
+
+Defines a custom function to handle evaluation errors.
+
+The `tmpl.errorHandler` property allows to detect errors _in the evaluation_, by setting its value to a function that receives the generated Error object, augmented with an object `riotData` containing the properties `tagName` and `_riot_id` of the context at error time.
+
+Other (usually fatal) errors, such as "Parse Error" generated by the Function constructor, are not intercepted.
+
+If this property is not set, or set to falsy, as in previous versions the error is silently ignored.
+
+
+## brackets
+
+Since v2.3, setting the brackets to some characters throws an exception.
+This is the list of invalid characters:
+
+- Control characters from `\x00` to `\x1F` that can be changed by browsers or minification tools
+- Alphanumeric `a-z`, `A-Z`, and `0-9`, wich are confused with JS variable names
+- Single and double quotes, comma, semicolon and backslash `'`, `"`, `,`, `;`, `\`, for obvious reasons
+- The dangerous `<` and `>` characters, reserved for use in markup and strictly prohibited in unquoted text for any other purpose -- out of CDATA sections.
+
+See the [CHANGES](CHANGES.md) document for details.
+
+
+### `brackets` function
+
+_Syntax:_ `brackets( reOrIdx ) : RegExp | string`
+
+The brackets function accepts a RegExp or numeric parameter.
+
+_parameters_
+
+* `reOrIdx` : RegExp or number - regex to convert or index number of backets part
+
+_returns:_ RegExp or string - With a regex, this function returns the original regex if the current brackets are the defaults, or a new one with the default brackets replaced by the current custom brackets.
+With a numeric parameter, returns a value based on current brackets according to the following table (defaults are within parenthesis):
+
+* 0: left bracket (`{`)
+* 1: right bracket (`}`)
+* 2: left escaped bracket (`{`)*
+* 3: right escaped bracket (`}`)*
+* 4: RegExp which matches a brackets pair (`/{[^}]*}/`)\*\*
+
+\* only the characters in `[]()*+?.^$|` are escaped.
+
+\*\* not 100% accurate, because it does not recognize brackets within strings.
+
+
+### `set` function
+
+_Syntax:_ `brackets.set( brackets_pair )`
+
+Receives the new string for the brackets pair. If you pass a falsy value, brackets are reset to default.
+This function checks their parameter and reconfigures the internal state immediately.
+
+_parameters_
+
+* `brackets_pair` : string - (optional) new custom brackets pair. The start and end is separated with a space character.
+
+**NOTE:**
+From v2.3.15, any change in `riot.settings.brackets` is detected, resulting in a call to `brackets.set` and the reconfiguration is immediate.
+
+
+### `R_MLCOMMS` property
+
+_Type:_ RegExp
+
+Used by internal functions and shared with the riot compiler, matches valid, multiline JavaScript comments in almost all forms. Can handle embedded sequences `/*`, `*\/` and `//` in these. Skips non-valid comments like `/*/`.
+
+`R_MLCOMMS` does not make captures.
+
+
+### `R_STRINGS` property
+
+_Type:_ RegExp
+
+Used by internal functions and shared with the riot compiler, matches single or double quoted strings, handles embedded quotes and multi-line strings (not in accordance with the JavaScript spec). It is not for ES6 template strings, these are too complex for a regex.
+
+`R_STRINGS` does not make captures.
+
+
+### `S_QBLOCK` property
+
+_Type:_ string
+
+Combines the `brackets.R_STRINGS` source with regexes for matching division symbols and literal regexes.
+
+When dealing with clean JavaScript code, i.e. without comments, this is the only string you need to instantiate your RegExp object. For code containing comments, `S_QBLOCK` needs to be combined with other regexes for exclusion of multiline and single-line comments (`MLCOMMS` can be one of both).
+
+The `S_QBLOCK` part captures in `$1` and `$2` a single slash, depending if it matches a division symbol ($1) or a regex ($2). If there's no matches for any of these, they have empty strings.
+
+_Example:_
+
+```js
+// We can use riot.util.brackets if riot is in context
+var brackets = require('riot-tmpl').brackets
+
+// Creates the regex, $1 encloses the whole S_QBLOCK, for easier detection
+var JS_RMCOMMS = new RegExp(
+    '(' + brackets.S_QBLOCK + ')|' + brackets.R_MLCOMMS.source + '|//[^\r\n]*',
+    'g')
+
+// Replaces comments with a space (_1 is a string, division sign, or regex)
+function stripComments(str) {
+  return.replace(JS_RMCOMMS, function (m, _1) { return _1 ? m : ' ' })
+}
+```

node_modules/@n8n_io/riot-tmpl/doc/CHANGES.md

@@ -0,0 +1,83 @@
+
+# The Changes
+
+I'll try to explain the reason for the some changes in tmpl 2.3.x
+
+## Escaped brackets, backslashes, and EOLs
+
+Escaped brackets _within expressions_ are left unescaped, except in JavaScript strings and regexes, where are preserved. So far, I have not found a case where brackets within expressions must remain escaped.
+
+In the HTML part, escaped brackets are unescaped before the evaluation.
+
+EOLs are normalized to `\n` in the HTML and converted to compact spaces in expressions.
+In JavaScript strings and regexes, escaped characters `\r` and `\n` are preserved.
+
+## Handling evaluation errors
+
+The new `tmpl.errorHandler` property allows to detect errors _in the evaluation_, by setting its value to a function that receives the generated Error object, augmented with an object `riotData` containing the properties `tagName` and `_riot_id` of the context at error time.
+
+Other (usually fatal) errors, such as "Parse Error" generated for the Function constructor, are not intercepted.
+
+If this property is not set, or set to falsy, as in previous versions the error is silently ignored.
+
+Example:
+```html
+<mytag></mytag>
+<script type="riot/tag">
+  <mytag><p>{ foo.bar }</p></mytag>
+</script>
+<script>
+  riot.util.tmpl.errorHandler = function (err) {
+    console.error(err.message + ' in ' + err.riotData.tagName)
+  }
+  riot.mount('*')
+</script>
+```
+outputs "Cannot read property 'bar' of undefined in MYTAG" in the console.
+
+Ref: [riot#871](https://github.com/riot/riot/issues/871), [riot#1189](https://github.com/riot/riot/issues/1189)
+
+## The new brackets function
+
+brackets 2.3 combines the behavior of brackets 2.2 with a new one, based on a function to make immediate, more secure changes to custom brackets. ~~There is a performance penalty in supporting both schemes, but compatibility is maintained.~~
+
+If riot is available when `brackets` is instantiated, `brackets` uses the configuration in `riot.settings`. In this way, `brackets` works as in previous versions and the reconfiguration is delayed to the first use.
+If riot is not available, you can change the brackets through the new `brackets.set` function, which accepts the same parameter as `riot.settings.brackets` and makes the reconfiguration immediately.
+
+**NOTE:**
+From v2.3.15, brackets changes in browsers via `riot.settings.brackets` has immediate effect and always reflect the brackets in use, the `brackets.settings` property is not neccesary and will be removed in v2.4.0
+
+It is all, syntax and behavior are the same as older versions: `brackets(regex_or_number)`.
+
+## Characters not allowed in brackets
+
+There are characters not allowed to define brackets, some are common characters in JavaScript expressions that hinder finding the right riot brackets, and other are forbidden by the HTML specs for text elements.
+
+This is the list of invalid characters:
+
+- Control characters from `\x00` to `\x1F` that can be changed by browsers or minifier tools
+- Alphanumeric `a-z`, `A-Z`, and `0-9`, wich are confused with JS variable names
+- Single and double quotes, comma, semicolon and backslash `'`, `"`, `,`, `;`, `\`, for obvious reasons
+- The dangerous `<` and `>` characters, reserved for use in markup and strictly prohibited in unquoted text for any other purpose -- out of CDATA sections.
+
+Typically, by using `<>` the browser will send to riot something different to what the user wants. With preprocessors such as ASP, no problems. But riot is not one of them, even with precompiled tags, it's a postprocessor. See the difference:
+
+#### ASP
+
+Source &#x2013;>   | ASP parser &#x2013;> | Browser
+-------------------|----------------|-----------
+`<p><%= x %></p>`  |    `<p>X</p>`  |  (Renders "X")  
+
+ASP takes the value of `x`, does the substitution, and stops here. The browser (HTML parser) receives valid HTML.
+
+#### riot
+
+Source &#x2013;>  | Browser &#x2013;>    | riot parser &#x2013;>
+------------------|----------------------|----------------
+`<p><%= x %></p>` | Renders `<p><></p>`? | `<p><></p>`
+
+Here the browser (some version of IE) receives invalid markup and try to render the best it can without break the page (i.e. "fix" the error). riot has no chance to get the expression and re-render the value. Other browser _can_ keep the markup as-is depending on its location in the elements. Anyway, the result is unpredictable.
+
+## Final Note
+
+There's more new functions and properties added to `brackets`, you can use [hasExpr](https://github.com/riot/tmpl/blob/dev/doc/API.md#hasexpr-function) and the [regexes](https://github.com/riot/tmpl/blob/dev/doc/API.md#r_mlcomms-property) which will be maintained, but the additional functions are for internal use.