iuliana commented on code in PR #358:
URL: https://github.com/apache/brooklyn-docs/pull/358#discussion_r907528444
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and
`config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the
`$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using
factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to
`test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion
if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural
ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the
other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other
argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
+* `in-range: <range>`, where `<range>` is a list of two numbers, e.g.
`[0,100]` (always inclusive)
+* `java-instance-of: <string>`, where the `<string>` is a registered type
name, to test
+ type assignment of the underlying java class of the value being tested with
the
+ underlying java class of the registered type referenced
+* `java-type-name: <test>`, where the `<test>` is a `DslPredicate` tested
against the
+ underlying java class name of the value
+
+Two composite tests are supported, both taking a list of other `<test>`
objects
+(as a list of YAML maps):
+
+* `any: <list of tests>`, testing that any of the tests in the list are true
(logical "or")
+* `all: <list of tests>`, testing that all of the tests in the list are true
(logical "and")
+
+
+
+### Presence
+
+The `when` test allows for testing of edge cases, to distinguish between
values which are unavailable
+(e.g. a sensor which has not been published, or a config which is unset),
those which are null,
+and those which are "truthy" (non-empty, non-false, per
`$brooklyn:attributeWhenReady`).
+Permitted values for this test are:
+
+* `absent`: value cannot be resolved (not even as null)
+* `absent_or_null`: value is null or cannot be resolved
+* `present`: value is available, but might be null
+* `present_non_null`: value is available and non-null (but might be 0 or empty)
+* `truthy`: value is available and ready/truthy (eg not false or empty)
+* `falsy`: value is unavailable or not ready/truthy (eg not false or empty)
+* `always`: always returns true
+* `never`: always returns false
+
+
+### Entity Tests
+
+To assist with tests on an `Entity` or `Location`, additional keys are
supported on
+the `DslPredicate` via `DslEntityPredicate`:
+
+* `target: <expression>`: to specify a value to test, resolved relative to the
"context entity"
+ (the one being tested, if appropriate, or otherwise the evaluating entity
where the predicate is defined);
+ this can be a DSL expression such as `$brooklyn:config("key")`
+ or a keyword, currently `location` or `children`, to evaluate
+ against the location(s) or children of that entity
+* `config: <string>`: indicates that the tests should be applied to the value
of config key
+ `<string> on the context entity, location, or policy
Review Comment:
missing closing oblique quote
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and
`config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the
`$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using
factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to
`test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion
if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural
ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the
other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other
argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
Review Comment:
missing closing oblique quote
##########
guide/blueprints/yaml-reference.md:
##########
@@ -323,3 +327,145 @@ These are:
including `config-widgets` (setting custom widgets to render fields) and
`config-quick-fixes` (proposals for fixing common errors);
see the code for the Blueprint Composer for more details
+## Predicate DSL
+
+In contexts where a `DslPredicate` or `DslEntityPredicate` is expected, the
`$brooklyn:object`
+DSL can be used to construct any suitable implementation, such as using
factory methods from `EntityPredicates`.
+In many cases, however, a simplified YAML DSL can be used,
+as defined by the Jackson deserialization rules on the `DslPredicate`.
+
+In its simplest form this can be a map containing the test or tests, e.g.:
+
+```
+equals: north
+```
+
+This will result in a `Predicate` which returns true if asked to
`test("north")`,
+and false otherwise. The full set of individual tests are:
+
+* `equals: <object>`, to test java object equality, attempting type coercion
if necessary
+* `regex: <string|number>`
+* `glob: <string|number>`
+* `when: <presence>`, where `<presence>` is one of the values described below
+* `less-than: <object>`, for strings and primitives, computed using "natural
ordering",
+ numeric order for numbers and digit sequences within numbers (`"9" < "10"`),
+ and ASCII-lexicographic comparison elsewhere (`"a" < "b"`);
+ otherwise if both arguments are the same type, or one a subtype of the
other, and both comparable,
+ it will use that type's compare method;
+ otherwise if one side side is JSON, it will attempt coercion to the other
argument's type;
+ and otherwise it will return false
+* `greater-than: <object>`, as above
+* `less-than-or-equal-to: <object>` as above
+* `greater-than-or-equal-to: <object>, as above
+* `in-range: <range>`, where `<range>` is a list of two numbers, e.g.
`[0,100]` (always inclusive)
+* `java-instance-of: <string>`, where the `<string>` is a registered type
name, to test
+ type assignment of the underlying java class of the value being tested with
the
+ underlying java class of the registered type referenced
+* `java-type-name: <test>`, where the `<test>` is a `DslPredicate` tested
against the
+ underlying java class name of the value
+
+Two composite tests are supported, both taking a list of other `<test>`
objects
+(as a list of YAML maps):
+
+* `any: <list of tests>`, testing that any of the tests in the list are true
(logical "or")
+* `all: <list of tests>`, testing that all of the tests in the list are true
(logical "and")
+
+
+
+### Presence
+
+The `when` test allows for testing of edge cases, to distinguish between
values which are unavailable
+(e.g. a sensor which has not been published, or a config which is unset),
those which are null,
+and those which are "truthy" (non-empty, non-false, per
`$brooklyn:attributeWhenReady`).
+Permitted values for this test are:
+
+* `absent`: value cannot be resolved (not even as null)
+* `absent_or_null`: value is null or cannot be resolved
+* `present`: value is available, but might be null
+* `present_non_null`: value is available and non-null (but might be 0 or empty)
+* `truthy`: value is available and ready/truthy (eg not false or empty)
+* `falsy`: value is unavailable or not ready/truthy (eg not false or empty)
+* `always`: always returns true
+* `never`: always returns false
+
+
+### Entity Tests
+
+To assist with tests on an `Entity` or `Location`, additional keys are
supported on
+the `DslPredicate` via `DslEntityPredicate`:
+
+* `target: <expression>`: to specify a value to test, resolved relative to the
"context entity"
+ (the one being tested, if appropriate, or otherwise the evaluating entity
where the predicate is defined);
+ this can be a DSL expression such as `$brooklyn:config("key")`
+ or a keyword, currently `location` or `children`, to evaluate
+ against the location(s) or children of that entity
+* `config: <string>`: indicates that the tests should be applied to the value
of config key
+ `<string> on the context entity, location, or policy
+* `sensor: <string>`: indicates that the tests should be applied to the value
of sensor
+ `<string> on the context entity
Review Comment:
missing closing oblique quote
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
