Element reference syntax¶
References select bundle elements, such as properties or files. Selectors add conditions, and matches reduce those conditions to a boolean. Placeholders insert reference values into strings. Checklets and scheduler options use these syntaxes inside recipe and configuration option values.
Reference¶
A reference refers to one or more
Result,
Property,
File or
Option elements in bundles.
The syntax for a reference is:
typed_reference ::=type[ "["reference( ","reference)* "]" ] type ::= "file" | "prop" | "opt" | "result" |outcome|not_outcomeoutcome ::= "pass" | "fail" | "error" | "skip" not_outcome ::= "not-"outcomereference ::= [provider_id] [ ":"typeref] provider_id ::= [ "@"provider] [ "#"id( ","id)* ] provider ::= "recipe" | "config" | "product" | "step" | "result" typeref ::=propref|fileref|optrefpropref ::=namefileref ::=class| [class] "#"nameoptref ::=name[ "@"domain] id ::= result query, optionally containing task references name ::= element name, quoted when needed class ::= file class domain ::= option domain, optionally including a subdomain
The type defines the element type which is referenced. Choices are
element referenced |
|
|---|---|
One or more
|
|
One or more
|
|
One or more
|
|
One or more
|
|
All |
|
All |
The provider selects the bundle from which these elements are referenced. Choices are
element referenced |
|
|---|---|
The |
|
The |
|
The |
|
|
|
The current |
Not all type / provider combinations are valid.
For the prop, result, outcome
and not_outcome types, only the @result provider is valid.
Since there is only one provider valid for these types, specifying the provider is optional in this case.
For the opt and file types, all providers are valid,
but the provider must be explicit. For example, file[@product] selects all product files.
Since ResultsBundle bundles contain multiple results, one or more id tokens
can be specified to limit the list of results. If no id is given, all results in the bundle are referenced.
id is not used with other providers. The id can contain task id placeholders and these
will be expanded with the task numbers for the currently active task.
The file reference type accepts an optional
name or class filter. Without a filter, it selects all
files from the provider. Names can contain glob-like wildcards. Names with spaces
or special characters can be quoted.
The prop reference type requires an additional name to
select the property.
The opt reference type requires an additional
name with optional domain to select the option.
If domain is not provided it defaults to checklet.
Similar to id, task number references are expanded in names,
classes, and domains when a task id is available.
Result reference scope¶
Without a #id filter, result, pass, fail, skip, error, and
their not- forms inspect all results in Providers.results. They do not
read the current step’s <dependencies> declaration. This is also true when a
recipe bundle is available.
A results bundle can contain dependencies of dependencies. For example, a
summary step can depend on evaluate.*, while each evaluate task depends on
build. If the supplied bundle contains the build result and skipped evaluate
results, %all skip is false when build passed. %all skip[#evaluate.*] is
true because the query excludes build.
The same distinction appears through the Python API:
>>> from momotor.bundles import ResultsBundle
>>> from momotor.bundles.elements.result import Outcome, Result
>>> from momotor.options.parser.selector import match_by_selector
>>> from momotor.options.providers import Providers
>>> results = ResultsBundle()
>>> _ = results.create(results=[
... Result(results).create(step_id='build', outcome=Outcome.PASS),
... Result(results).create(step_id='evaluate.0', outcome=Outcome.SKIP),
... Result(results).create(step_id='evaluate.1', outcome=Outcome.SKIP),
... ])
>>> providers = Providers(results=results)
>>> match_by_selector('%all skip', providers)
(False, '')
>>> match_by_selector('%all skip[#evaluate.*]', providers)
(True, '')
>>> match_by_selector('%all skip[#missing.*]', providers)
(False, '')
A #id filter restricts the available results. It does not check whether every
expected task has produced a result. The Result query syntax describes
exact ids and wildcards.
Examples of references are:
reference |
result |
|
Selects properties with name |
|
Selects properties with name |
|
Same as above ( |
|
Selects the file with class |
|
Selects all files with class |
|
Selects all files with class |
|
Selects all files with class |
|
Selects the option with name |
|
Selects the option with name |
|
Select all results from the results bundle |
|
Select result with id |
|
Select all passed results from the results bundle |
|
Select results with result id |
|
Same as above ( |
|
Select results with result id |
Reference value¶
A reference value is a single value generated from a reference. Checklets can use reference values in options to resolve those options into values. Reference values are also used as part of the placeholder syntax.
A reference value is a reference, optionally prefixed with a modifier:
value_reference ::= [ "%"mod]typed_referencemod ::= "all" | "any" | "notall" | "notany" | "not" | "sum" | "sumf" | "sumr" | "max" | "min" | "cat" | "join" | "joinc" | "joins" | "joincs" | "json" | "first" | "last"
What value is produced by a reference value is determined by the reference type:
value |
|
|---|---|
The |
|
The |
|
|
The mod modifier indicates how the list of values produced by the reference
is converted into a reference value.
The default modifier is join, but this can be changed by the
caller of the resolve_reference_value() method.
result |
|
|---|---|
True if all values are considered True [2] |
|
True if at least one value is considered True [2] |
|
False if all values are considered True [2] |
|
False if at least one value is considered True [2] |
|
Alias for |
|
The sum of the values [3] |
|
The sum of the values, truncated toward zero [3] |
|
The sum of the values, rounded to the nearest int [3] |
|
The maximum of the values [3] |
|
The minimum of the values [3] |
|
All values concatenated without any separator |
|
All values concatenated with a single comma, without spaces |
|
Alias for |
|
All values concatenated with a space character |
|
All values concatenated with a comma followed by a space |
|
The values converted into a json list [4] |
|
The first value [5] |
|
The last value [5] |
For the all, any, not,
notall and notany the values are interpreted
as booleans in the same way Python does: a 0 (zero), None or empty string is considered to be False, and
anything else is considered to be True. Empty sequences result in None.
For the sum, sumf, sumr,
max and min
modifiers, string values will be cast into float or int if possible, or ignored otherwise. If all values
resolve to integers, the result of these modifiers will be an integer. If at least one of the values is a floating
point value, the result will be a float, except for sumf and
sumr which will resolve to an integer. Empty sequences result in None.
The json modifier returns JSON text. No values
produce null. One value produces a JSON scalar, object, or array matching
that value. Multiple values produce a JSON array. Missing values remain
null in the output.
The first and last modifiers return the first or last
value and keep the type intact. Empty sequences result in None.
All other modifiers convert the values to a string before joining.
Selector¶
A selector filters references on the value. The value is one of the attributes of the referenced elements, the same attribute as used for value references.
A selector has the following syntax:
selector ::=typed_reference[selection] selection ::=unary_oper|binary_opervalueunary_oper ::= "?" | "!" binary_oper ::= "==" | "!=" | ">" | ">=" | "<" | "<=" value ::= quoted string or number
operator |
action |
|---|---|
(no selector) |
Selects all elements (i.e. same as the reference) |
Unary operator which selects the elements whose value is considered True [6] |
|
Unary operator which selects the elements whose value is considered False [6] |
|
Binary operators. Selects the elements whose value matches the equation. String values to compare with need to be quoted. |
For the ? and ! operators the values are interpreted
as booleans in the same way Python does: a 0 (zero), None or empty string is considered to be False, and
anything else is considered to be True.
Example selectors:
selector |
|
|---|---|
|
Selects all passed results |
|
Also selects all passed results |
|
Selects all results containing a score property |
|
Selects all results with a score property greater than 1 |
Match¶
match ::= [ "%"mod]selectormod ::= "all" | "any" | "not" | "notall" | "notany"
A match takes a selector and collapses it into a boolean, depending on the mod
modifier.
match |
|
|---|---|
No modifier or |
Matches if the selector is “true” for all referenced elements |
Matches if there is at least one selected element “true” |
|
Matches if not all of the selected elements are “true” |
|
Matches if not any of the selected elements is “true” |
Selected values |
|
|
|
|
|---|---|---|---|---|
All comparisons true |
True |
True |
False |
False |
All comparisons false |
False |
False |
True |
True |
Mixed comparisons |
False |
True |
True |
False |
No selected values |
False |
False |
True |
True |
When no results match the result query, %all and %any are false.
%notall and %notany are true. A result that lacks the requested property
also makes %all false. These rules differ from reference-value modifiers,
which can return None for empty input.
For example, %all skip[#evaluate.*] needs at least one evaluate result, and
every selected evaluate result must have the skip outcome.
Example matches:
match |
|
|---|---|
|
Matches if all results passed |
|
Matches if at least one result passed |
|
Matches if not all results passed |
|
Matches if no result passed |
|
Matches if all results contain a score property |
|
Matches if at least one result contains a score property |
|
Matches if all results contain a score of more than 1 |
Reference placeholder¶
Reference placeholders can be used inside a longer string. The placeholder will be replaced by the value produced by the reference value.
placeholder ::= "${" value_reference "}"
Placeholders are reference values wrapped inside a ${...}.
To include a literal ${ in the string, use $${ to escape the placeholder syntax.
replace_placeholders() recursively
expands placeholders in resolved strings. When a valid placeholder resolves to
None, its reference text is removed and ${} remains. With the default
join modifier, missing properties produce an empty string, so their
placeholders are removed entirely.
For the results bundle above, no result has a property named missing:
>>> from momotor.options.parser.placeholders import replace_placeholders
>>> replace_placeholders('x ${%first prop[:missing]} y', providers)
'x ${} y'
>>> replace_placeholders('x ${%sum prop[:missing]} y', providers)
'x ${} y'
>>> replace_placeholders('x ${prop[:missing]} y', providers)
'x y'
Values that are not strings pass through unchanged. Option resolution does not expand placeholders automatically unless the caller explicitly invokes this function.
Task id placeholder¶
Task id placeholders can be used inside a longer string. The placeholder will be replaced by the sub-task number of the currently active task, either zero-based or one-based.
task_id_placeholder ::= "$" [ task_id_base ] "#"
task_id_base ::= "0" | "1"
Task id placeholders are $#, $0# and $1#. The 0 and 1 indicate whether the task id is zero-based or
one-based. If no base is given, the default is zero-based. If there is no task, the placeholder will be
replaced by a -.
Examples, for a task with id task.0.1:
placeholder |
replacement |
|---|---|
|
|
|
|
|
|