roboto.domain.triggers.query_templates
Module Contents
QUERY_FIELD
Selector field holding a RoboQL query, the one field of an invocation input whose value is an expression rather than a value the expression compares against.
QueryPlaceholder
Bases: NamedTuple
One {{placeholder}} found in a RoboQL query, and the literal enclosing it.
Attributes
QueryPlaceholder.quote
The quote character of the string literal the placeholder sits in, or None when it sits in expression text (a comment counts as expression text: a value could close it).
escape_string_literal()
Return value escaped for splicing inside a quote-delimited RoboQL string literal.
Parameters
value strThe value to splice.
quote strThe literal’s delimiter, " or '.
Raises
ValueErrorvalue holds a character the literal cannot carry under any escape, namely a carriage return or a newline.
Return type
iter_query_templates()
Yield every RoboQL query in invocation_input, in document order.
Parameters
invocation_input collections.Return type
map_query_templates()
Return invocation_input with transform applied to every RoboQL query it holds.
Parameters
invocation_input collections.An InvocationInput in its JSON form, whose top-level values are selectors or lists of them.
transform collections.Called with each selector’s query; its result replaces that query.
Returns
A copy, shallow below the selectors it rewrites.
placeholders_outside_string_literals()
Return the placeholders in query that do not sit inside a string literal.
A value spliced inside a literal can be escaped into it (see escape_string_literal()), so it can only ever be data. A value spliced anywhere else becomes query syntax: a tag or path carrying an operator would rewrite the query it was meant to be compared against.
Parameters
query strA RoboQL query, possibly carrying {{placeholder}} templates.
Returns
The names of those placeholders, in the order they appear.
scan_placeholders()
Return every {{placeholder}} in query, each with the literal enclosing it.
Follows the lexical rules of the RoboQL grammar: both quote characters open a string literal, a backslash inside one escapes the next character, and // and slash-star comments run to their terminator.
Parameters
query strA RoboQL query, possibly carrying {{placeholder}} templates.
Return type
substitute_query_template()
Return query with each placeholder replaced by resolve’s value for it, escaped in place.
Each placeholder is substituted exactly once, and a value is escaped for the literal that encloses it, so a value that itself looks like a template or carries a quote stays data.
Parameters
query strA RoboQL query carrying {{placeholder}} templates.
resolve collections.Returns the value for a placeholder name.
Raises
ValueErrorA placeholder sits outside a string literal, or a value cannot be escaped into the literal it lands in.
Return type