Crate datafu[−][src]
Datafu is a regex-inspired query language. It was primarily designed for processing object trees parsed from configuration files, but can also be used with JSON APIs, and even XML.
Languge Reference
Datafu expressions have the ability to iterate, index, validate and filter data structures, through the use of the syntax elements below.
Syntax Elements of Datafu Expressions
An arrow is ->
and indicates indexing/iteration. Whether indexing or
iteration is used is defined by the elements that follow, with iteration
being used by default.
A variable is a sequence of alphanumeric characters, not starting with
a digit. A (key, value)
tuple containing the respective matched
element will be identified by this name in the results map.
A literal is a sequence of characters delimited by '
, optionally
followed by ?
, with %
as the escape character, and defines a
string-keyed indexing operation. A literal can contain any character,
except unescaped %
or '
symbols, which must be escaped as
%%
and %'
, respectively. The sequence of characters defined by
a literal is used as the string object in the indexing operation.
A parameter is $
, optionally followed by ?
, followed by a
sequence of alphanumeric characters, not starting with a digit, and
defines an object-keyed indexing operation. The sequence of characters
defined by a parameter is used to retrieve, from the pattern’s
definitions, the object to be used in the indexing operation.
A regex is a sequence of characters delimited by /
, optionally
followed by ?
, with %
as the escape character. A regex can
contain any character, except unescaped %
or /
symbols, which
must be escaped as %%
and %/
, respectively. The sequence of
characters defined by a regex is passed to the regex
crate, which
may apply further restrictions on the characters used, and is used to
accept the respective keys processed by the iterator.
A predicate is :
, optionally followed by ?
, followed by an
$
and a sequence of alphanumeric characters, not starting with a
digit, and is used to accept values to be processed based on an
external Predicate
.
A key match is a datafu expression (including, but not limited to, the
empty datafu expression) enclosed within [
and ]
, optionally
prefixed with one or more predicates, and applies the enclosed
predicates and datafu expression to the key (or index) being processed.
A key match enables additional validation of keys and/or extraction of
values from keys, and accepts a key if and only if the enclosed
predicates accept the key and the enclosed expression matches the key.
A subvalue is a datafu expression (including, but not limited to, the
empty datafu expression) enclosed within (
and )
, and applies
the enclosed datafu expression to the value (or index) being processed.
A subvalue enables the ability to match multiple values on the same
object, and accepts a value if and only the enclosed expression
matches the value. A subvalue can be made optional by the presence of
a ?
after the subvalue - in case of no match, it will just omit
the relevant keys in the result. Optional subvalues are unrelated to
non-validating syntax elements (see below), they just use the same
syntax.
Some syntax elements can be validating or non-validating. Validating
syntax elements will return a errors::MatchError::ValidationError
whenever a non-accepted element is encountered, whereas non-validating
ones will skip them. Whether an element is validating is determined by
the absence of an optional ?
in the documented position. Note that
it is possible for a validating syntax element to still yield results
before returning a errors::MatchError::ValidationError
, so one
needs to be careful when writing code where such behaviour could
result in a security vulnerability.
The empty pattern matches anything, but only does so once.
Syntax of Datafu Expressions
Datafu Expressions follow the given syntax, in (pseudo-)extended BNF:
expression ::= {arrow tag} {subvalue}
tag ::= identifier [arg] {predicate} | arg {predicate}
arg ::= parameter | literal | regex | keymatch
arrow ::= '->'
keymatch ::= '[' {predicate} expression ']'
subvalue ::= '(' {predicate} expression ')' ['?']
For a description of the terminals “parameter”, “literal”, “regex” and “predicate”, see “Syntax Elements of Datafu Expressions” above.
Examples
Modules
errors |
Structs
Matcher | |
Pattern |
Enums
RefOwn | A borrowed or owned value of various types. |
Traits
PatternTypes | Defines the types and operations used for matching. |
Type Definitions
KVPair | A tuple representing a key-value pair. |
Predicate | A predicate for keys and values. |