You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by he...@apache.org on 2022/11/04 17:14:46 UTC
[brooklyn-docs] branch master updated (1296ad3a -> 31aeb898)
This is an automated email from the ASF dual-hosted git repository.
heneveld pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
from 1296ad3a use underscores, add some new options on steps
new 6ad2450e expand docs for `let` step
new 06fa4f35 add docs for yaml/json output mode in let
new 31aeb898 tidy let yaml/json semantics, add load step
The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
guide/blueprints/workflow/steps/steps.yaml | 61 +++++++++++++++++++++++-------
1 file changed, 47 insertions(+), 14 deletions(-)
[brooklyn-docs] 01/03: expand docs for `let` step
Posted by 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 6ad2450e53ddafc37a8834136b001108725bdcf5
Author: Alex Heneveld <al...@cloudsoft.io>
AuthorDate: Thu Nov 3 09:07:37 2022 +0000
expand docs for `let` step
---
guide/blueprints/workflow/steps/steps.yaml | 24 +++++++++++++++++-------
1 file changed, 17 insertions(+), 7 deletions(-)
diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index 652ad33a..8fcaa22d 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -27,13 +27,23 @@
- name: set-workflow-variable
summary: Sets the value of a workflow internal variable. The step `let` is an alias for this.
- shorthand: '`set-workflow-variable ["trimmed"] [TYPE] VARIABLE_NAME = VALUE`'
+ shorthand: '`set-workflow-variable ["trim"] ["merge" ["deep"] ["clean"]] ["wait"] [TYPE] VARIABLE_NAME = VALUE`'
input: |
* `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type`
- to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`)
+ to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`);
+ the `name` can be of the form `x.key` if `x` is a map to set a `key` within it
* `value`: the value to set, with some limited evaluation as described [here](../variables.md)
- * `trim`: whether the value, if a string, should be trimmed after evaluation and prior to setting, as described [here](../variables.md);
- this can be set from shorthand if the first word after the step type is `trimmed`
+ * `trim`: whether the value should be trimmed after evaluation and prior to setting, removing whitespace
+ and for complex types coerced from YAML or JSON processing only the last YAML document after a `---` line separator as described [here](../variables.md)
+ * `merge`: indicates the value will be a space-separated list of values, with quotes significant, usually including `$(vars)`, which will be merged and
+ set as the indicated variable; `type` must be specified; for maps, all values must be maps;
+ for lists and sets, any value is permitted and collection values are flattened (to insert a list as an entry in a list, it must be wrapped in another list using longhand syntax);
+ if `trim` is specified, null or unresolvable values are ignored; if `clean` is specified, null entries (including key or value for maps) are removed;
+ if `wait` is specified, unavailable values are waited on
+ * `merge_deep`: whether to merge maps deeply, i.e. where the keys are identical the values should be maps and those maps are themselves merged deeply;
+ the value should be as per `merge` but containing maps only;
+ the values to merge are not otherwise coerced so must be pre-transformed to the appropriate type
+ * `wait`: whether to block on expressions such as `entity.sensor.x` which are well-formed but not yet available
output: the output from the previous step, or null if this is the first step
- name: clear-workflow-variable
@@ -57,15 +67,15 @@
summary: |
Waits for a value which might not yet be resolved, or a task which might not have finished,
optionally setting the value or the task's result to a workflow variable.
- shorthand: '`wait [ [TYPE] VARIABLE_NAME = ] [MODE] VALUE`'
+ shorthand: '`wait [ [TYPE] VARIABLE_NAME = ] [ "task" ] VALUE`'
input: |
* `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type`
to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`)
- * `mode`: either `expression` (the default) or `task` to treat value as a task or task ID
+ * `task`: boolean to indicate that value should be treated as a task or task ID to wait on and take its result
* `value`: the expression to wait on and optionally set
output: |
the value once available if a `variable` is not being set,
- or if a variable is being set either the output from the previous step or null if this is the first step
+ or if a variable is being set the output from the previous step or null if this is the first step
- name: fail
summary: Fails the workflow, throwing an exception which can be handled by an `on-error` block or returned to the user
[brooklyn-docs] 02/03: add docs for yaml/json output mode in let
Posted by 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 06fa4f3580ac47ef5dd4eab85c5e8f9064ffa205
Author: Alex Heneveld <al...@cloudsoft.io>
AuthorDate: Thu Nov 3 11:17:22 2022 +0000
add docs for yaml/json output mode in let
---
guide/blueprints/workflow/steps/steps.yaml | 21 ++++++++++++---------
1 file changed, 12 insertions(+), 9 deletions(-)
diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index 8fcaa22d..c087dd4d 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -29,9 +29,10 @@
summary: Sets the value of a workflow internal variable. The step `let` is an alias for this.
shorthand: '`set-workflow-variable ["trim"] ["merge" ["deep"] ["clean"]] ["wait"] [TYPE] VARIABLE_NAME = VALUE`'
input: |
- * `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type`
- to coerce (needed e.g. if you want to set a bean registered type, or in shorthand to set an `integer`);
- the `name` can be of the form `x.key` if `x` is a map to set a `key` within it
+ * `variable`: either a string, being the workflow variable name, or a map, containing the `name` and optionally the `type`;
+ the value will be coerced to the given type, e.g. to force conversion to an integer or to a bean registered type;
+ 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.md)
* `trim`: whether the value should be trimmed after evaluation and prior to setting, removing whitespace
and for complex types coerced from YAML or JSON processing only the last YAML document after a `---` line separator as described [here](../variables.md)
@@ -259,9 +260,10 @@
summary: Sets the value of a config key on an entity.
shorthand: '`set-config [TYPE] CONFIG_KEY_NAME = VALUE`'
input: |
- * `config`: a string being the config key name or a map containing the `name` and
- optionally the `type` (defaulting to the declared type of the config key, if present, or to `Object`)
- and/or the `entity` where the config should be set (defaulting to the entity where the workflow is running)
+ * `config`: either a string, being the config key name, or a map, containing the `name` and
+ optionally the `type` (defaulting to the declared type of the config key, if present, or to `Object`)
+ and/or the `entity` where the config should be set (defaulting to the entity where the workflow is running);
+ the value will be coerced to the given type, e.g. to force conversion to an integer or to a bean registered type
* `value`: the value to set
output: the output from the previous step, or null if this is the first step
@@ -269,9 +271,10 @@
summary: Sets the value of a sensor on an entity.
shorthand: '`set-sensor [TYPE] SENSOR_NAME = VALUE`'
input: |
- * `sensor`: a string being the sensor name or a map containing the `name` and
- optionally the `type` (defaulting to the declared type of the sensor, if present, or to `Object`)
- and/or the `entity` where the sensor should be set (defaulting to the entity where the workflow is running)
+ * `sensor`: either a string, being the sensor name, or a map, containing the `name` and
+ optionally the `type` (defaulting to the declared type of the sensor, if present, or to `Object`)
+ and/or the `entity` where the sensor should be set (defaulting to the entity where the workflow is running);
+ the value will be coerced to the given type, e.g. to force conversion to an integer or to a bean registered type
* `value`: the value to set
output: the output from the previous step, or null if this is the first step
[brooklyn-docs] 03/03: tidy let yaml/json semantics, add load step
Posted by 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 31aeb8985ed461f3bc475b38df96a36c659896ee
Author: Alex Heneveld <al...@cloudsoft.io>
AuthorDate: Fri Nov 4 17:14:18 2022 +0000
tidy let yaml/json semantics, add load step
---
guide/blueprints/workflow/steps/steps.yaml | 32 ++++++++++++++++++++++++------
1 file changed, 26 insertions(+), 6 deletions(-)
diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml
index c087dd4d..0bcbeae5 100644
--- a/guide/blueprints/workflow/steps/steps.yaml
+++ b/guide/blueprints/workflow/steps/steps.yaml
@@ -27,23 +27,30 @@
- name: set-workflow-variable
summary: Sets the value of a workflow internal variable. The step `let` is an alias for this.
- shorthand: '`set-workflow-variable ["trim"] ["merge" ["deep"] ["clean"]] ["wait"] [TYPE] VARIABLE_NAME = VALUE`'
+ shorthand: '`set-workflow-variable ["merge" ["deep"]] ["trim"] ["yaml"|"json"] ["wait"] [TYPE] VARIABLE_NAME = VALUE`'
input: |
* `variable`: either a string, being the workflow variable name, or a map, containing the `name` and optionally the `type`;
the value will be coerced to the given type, e.g. to force conversion to an integer or to a bean registered type;
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.md)
- * `trim`: whether the value should be trimmed after evaluation and prior to setting, removing whitespace
- and for complex types coerced from YAML or JSON processing only the last YAML document after a `---` line separator as described [here](../variables.md)
- * `merge`: indicates the value will be a space-separated list of values, with quotes significant, usually including `$(vars)`, which will be merged and
- set as the indicated variable; `type` must be specified; for maps, all values must be maps;
+ * `merge`: indicates the value will be a space-separated list of values, with quotes significant, usually including `$(vars)`,
+ which will be merged and set as the indicated variable; `type` must be specified;
+ for maps, all values must be maps;
for lists and sets, any value is permitted and collection values are flattened (to insert a list as an entry in a list, it must be wrapped in another list using longhand syntax);
- if `trim` is specified, null or unresolvable values are ignored; if `clean` is specified, null entries (including key or value for maps) are removed;
+ if `trim` is specified, null or unresolvable values and entries (including either key or value for maps) are ignored;
if `wait` is specified, unavailable values are waited on
* `merge_deep`: whether to merge maps deeply, i.e. where the keys are identical the values should be maps and those maps are themselves merged deeply;
the value should be as per `merge` but containing maps only;
the values to merge are not otherwise coerced so must be pre-transformed to the appropriate type
+ * `trim`: whether the value should be trimmed after evaluation and prior to setting;
+ this applies to string input and to an explicit string type result
+ * `yaml`: indicates the input should be converted to YAML if not already a string,
+ and if a type other than string is specified, the YAML will be parsed as YAML to make that type;
+ if no type is specified then the YAML will be parsed and the resulting primitive/map/list/string returned;
+ if the type `string` is specified, the encoded YAML will be returned;
+ in all cases apart from the last (`yaml string`), any content in a string input before a YAML document separator `---` is dropped
+ * `json`: as for `yaml`, but using JSON for any conversion and parse; in particular `json string` can be used to get a JSON-encoded string for passing to scripts
* `wait`: whether to block on expressions such as `entity.sensor.x` which are well-formed but not yet available
output: the output from the previous step, or null if this is the first step
@@ -78,6 +85,19 @@
the value once available if a `variable` is not being set,
or if a variable is being set the output from the previous step or null if this is the first step
+ - name: load
+ summary: |
+ Loads the contents of a URL into a string or coerced to a type.
+ Particularly useful when reading classpath resources.
+ shorthand: '`load ["charset" CHARSET] [TYPE] VARIABLE_NAME = URL`'
+ input: |
+ * `variable`: a string being the workflow variable name or a map containing the `name` and optionally the `type`
+ 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
+ output: |
+ the output from the previous step or null if this is the first step
+
- name: fail
summary: Fails the workflow, throwing an exception which can be handled by an `on-error` block or returned to the user
shorthand: '`fail [ "rethrow" ] [ "message" MESSAGE ]`'