[brooklyn-docs] 02/04: add docs for interpolation_{mode,error}, and docs for retry limit exceeded

[he...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

heneveld pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git

commit b5099d012e30a007dd5dbff5fcd8ad9ce4014ed3
Author: Alex Heneveld <al...@cloudsoft.io>
AuthorDate: Tue Mar 21 16:11:00 2023 +0000

    add docs for interpolation_{mode,error}, and docs for retry limit exceeded
---
 guide/blueprints/workflow/steps/steps.yaml | 15 +++++++++++++--
 guide/blueprints/workflow/variables.md     |  8 ++++++--
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index 8360d37d..5bf117f3 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -34,6 +34,11 @@
           the special types `yaml` and `json` can be specified here to force conversion to a valid YAML or JSON string;
           the `name` here can be of the form `x.key` where `x` is an existing map variable, to set a specific `key` within it
         * `value`: the value to set, with some limited evaluation as described [here](../variables.html)
+        * `interpolation_mode`: whether to run interpolation, defaulting to `words` for shorthand or `full` if `value` is specified in a map;
+           options are to run on the `full` value (not touching quotes), on `words` (unquoting words, and interpolating only if unquoted),
+           or `disabled` (to prevent interpolation in the evaluation of this variable)
+        * `interpolation_errors`: whether unresolvable interpolated expressions `fail` and return an error (the default), or to `ignore`
+          them (leaving them in their interpolated form), or to replace them with a `blank` string
       output: the output from the previous step, or null if this is the first step
 
     - name: transform
@@ -109,6 +114,10 @@
              to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`)
         * `url`: the URL to load
         * `charset`: the charset to use to process the input
+        * `interpolation_mode`: whether to evaluated interpolated expressions in the content; default `disabled`; options are as for `let`
+        * `interpolation_errors`: how to handle errors in interpolated expressions, if `interpolation_mode` is set; 
+          the default `ignore` will leave unresolveable expressions in their expression form which is useful for scripts and other templating systems;
+          options are as for `let`
       output: |
         the output from the previous step or null if this is the first step
 
@@ -133,8 +142,10 @@
           if `replay` is specified without next, the default `next` is the `last` replay point
           (always excluding the retry step itself, even if it is a valid replay point)
         * `limit`: a list of limit definitions, e.g. `[ "10", "1h", "2 in 1 min" ]` to restrict to a max of 10 retries total,
-          an additional limit of 2 in any 1 minute period, and an additional limit of 1 hour; the retry will fail if any of these are exceeded;
-          as shorthand, per the syntax above, it takes one such limit definition
+          an additional limit of 2 in any 1 minute period, and an additional limit of 1 hour; 
+          as shorthand, per the syntax above, it takes one such limit definition;
+          the retry will fail with a `RetriesExceededException` if any of these are exceeded;
+          if it is intended to continue, it is necessary to attach an error handler to the retry step
         * `backoff`: a specification of how to delay, of the form `INITIAL [ "increasing" FACTOR ] [ "jitter" JITTER ] [ "up to" MAX ]`,
           where `INITIAL` is one or more durations applied to the respective iteration, and the last value applying to all
           unless an `increasing FACTOR` is supplied; 
diff --git a/guide/blueprints/workflow/variables.md b/guide/blueprints/workflow/variables.md
index 330b2475..5b865cc5 100644
--- a/guide/blueprints/workflow/variables.md
+++ b/guide/blueprints/workflow/variables.md
@@ -200,8 +200,8 @@ and the modulo operator `%` for integers giving the remainder.
 These are evaluated in usual mathematical order.
 Parentheses are not supported.
 
-The `let` step also supports a `trim` property (or keyword `trimmed` as the first word after the step type)
-to indicate that if the value is a string, it should be "trimmed" before setting into the variable.
+The `transform` step can be used for more complicated transformations, such as whether to `wait` on values that are not yet ready,
+conversion using `json` and `yaml`, and whether to `trim` strings or yaml documents.
 This supports two types of trimming: if a `type` is specified, the value is scanned for `---` on a line by itself
 and that token is used as a "document separator", and only the last document is considered;
 if no `type` is specified, the value has leading and trailing whitespace removed.
@@ -256,6 +256,7 @@ The `let` step has some special behavior. It can accept `yaml` and, when convert
 will strip everything before a `---` document separator.  Thus a script can have any output, so long as it
 ends with `---\n` followed the YAML to read in, then `let yaml fancy-bean = ${stdout}` will convert it to
 a registered type `fancy-bean`. It will be an error if `stdout` is not coercible to `fancy-bean`.
+For more conversion, see `transform`.
 
 Another special behavior of `let` is that its `value` is reprocessed, supporting arithmetic as described elsewhere,
 and also unwrapping quoted words in the value (removing quotes) _without_ evaluating expressions within them.
@@ -274,6 +275,9 @@ or a hybrid syntax `{ step: set-sensor x, value: value }`,
 which can be useful for complex types and bypassing the shorthand processor's unquoting strategy,
 but in this case note that YAML processing will unwrap quotes.
 
+The `interpolation_mode` and `interpolation_errors` options can be used to specify other
+behavior for interpolation, both on `let` and on `load` of data from a URL.
+
 
 ### Advanced Details