roboto.domain.triggers.query_templates#

Module Contents#

roboto.domain.triggers.query_templates.QUERY_FIELD = 'query'#

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.

class roboto.domain.triggers.query_templates.QueryPlaceholder#

Bases: NamedTuple

One {{placeholder}} found in a RoboQL query, and the literal enclosing it.

end: int = 0#

Index one past the placeholder’s last character.

name: str#

The placeholder’s dotted name, without the braces.

quote: str | None = None#

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).

start: int = 0#

Index of the placeholder’s first character in the query.

roboto.domain.triggers.query_templates.escape_string_literal(value, quote)#

Return value escaped for splicing inside a quote-delimited RoboQL string literal.

Parameters:

  • value (str) – The value to splice.

  • quote (str) – The literal’s delimiter, " or '.

Raises:

ValueError – value holds a character the literal cannot carry under any escape, namely a carriage return or a newline.

Return type:

str

roboto.domain.triggers.query_templates.iter_query_templates(invocation_input)#

Yield every RoboQL query in invocation_input, in document order.

Parameters:

invocation_input (collections.abc.Mapping[str, Any])

Return type:

collections.abc.Iterator[str]

roboto.domain.triggers.query_templates.map_query_templates(invocation_input, transform)#

Return invocation_input with transform applied to every RoboQL query it holds.

Parameters:

  • invocation_input (collections.abc.Mapping[str, Any]) – An InvocationInput in its JSON form, whose top-level values are selectors or lists of them.

  • transform (collections.abc.Callable[[str], str]) – Called with each selector’s query; its result replaces that query.

Returns:

A copy, shallow below the selectors it rewrites.

Return type:

dict[str, Any]

roboto.domain.triggers.query_templates.placeholders_outside_string_literals(query)#

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 (str) – A RoboQL query, possibly carrying {{placeholder}} templates.

Returns:

The names of those placeholders, in the order they appear.

Return type:

list[str]

roboto.domain.triggers.query_templates.scan_placeholders(query)#

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 (str) – A RoboQL query, possibly carrying {{placeholder}} templates.

Return type:

list[QueryPlaceholder]

roboto.domain.triggers.query_templates.substitute_query_template(query, resolve)#

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 (str) – A RoboQL query carrying {{placeholder}} templates.

  • resolve (collections.abc.Callable[[str], str]) – Returns the value for a placeholder name.

Raises:

ValueError – A placeholder sits outside a string literal, or a value cannot be escaped into the literal it lands in.

Return type:

str

On this page