Expand description
expry
is a fast schemaless binary format for data, with the ability for filtering and selecting parts of the information using expressions over the stored binary data. Expressions are compiled and optimized to bytecode, and during evaluation this bytecode is interpreted.
JSON can be read into these data structures (using expry_parse_json
). Because expry
supports binary strings, not all expry
values can be exported to JSON.
The following data types are supported:
null
;bool
;int64
;float
;double
;string
(can contain binary data);array
;object
.
§Expressions
Expressions over binary objects are compiled to byte code, and can be transmitted over the network. This bytecode can be quickly evaluated, as the bytecode is optimized on the way the binary objects are stored on a low level. Keys inside objects are stored in an ordered way. If keys are not needed any more for evaluation of the current expression, they are permanently skipped.
- Constants:
null
,false
,true
, numbers (including:0x...
,0b...
,...f
), strings with'string'
or"string"
(including raw strings usingr#"..."#
with variable number of#
, and hex strings withx'hex'
andx"hex"
and ). - Conditionals: if-then-else is support with the conditional (ternary) operator:
cond ? then-part : else-part
. - Object expression with
{
fields?}
, with optional fields, individual fields separated by,
(last entry can have a trailing,
):- fields can be
name: expr
with expr an expression or a primary data type (see above); - fields can be
"name": expr
with expr an expression or a primary data type (see above); - fields can be
field
(orfield???
), which copies the field from thethis
object; - fields can be
(expr): expr
to dynamically generate a field name (must be a string), e.g.{ (somefield): 42, }
(results in{x: 42}
ifsomefield
is"x"
).
- fields can be
- Array expressions:
[
expressions?]
, with the optionalexpressions
which are one or more expressions delimited by,
(last entry can have a trailing,
). Example:[ 42+42, 37+37, ]
. - Arithmetic operators:
+
,-
,*
,/
,**
(pow),%
(mod). - Bitwise operators:
|
,&
,^
(xor),<<
,>>
- Logical operators:
&&
,||
,a ? b : c
,==
,!=
,>
,>=
,<
,<=
. - Special
this
field, to signify current object. - Array subscription:
a[b]
(array subscription) is supported to access indiviual elements in arrays - Length operator:
field.len()
which result in the length of the field if it is a string (number of bytes), array (number of elements), or object (number of key-values).
- String operators:
a .. b
: concatenate stringsa
andb
;a *= b
: true if stringa
contains with stringb
a $= b
: true if stringa
ends with stringb
a ^= b
: true if stringa
starts with stringb
- Field operators:
a.b.c.d
is supported to access subfields;a.get(b).get(c).get(d)
is supported for dynamic subfields;
- Error operators:
- try operator:
a ??? b
: if there is an error during evaluation ofa
(like an undefined field, or division by zero). The shorthanda ???
is equivalent toa ??? null
. Alternative syntax istry(a, b)
andtry(a)
. - not-null-else operator:
a ?? b
: ifa
is null, returnb
.defined(x)
andundefined(x)
: checks if value is (un)defined (such as a field lookup).
- try operator:
- String methods:
.trim()
.lower()
.upper()
.hex()
.htmlescape()
.urlescape()
.sub(int[, int])
(third argument is length of resulting string, default the max integer value).basename()
.dirname()
.splitn(max, split_on)
(split_on is the splitting string, max is the max number of elements in the resulting array), results in an array of strings
- Type methods:
.tostring()
.toint()
.tofloat()
.todouble()
- Methods taking a lambda function as argument. Lambda functions are specified as
|x| expr
withx
the argument to the lambda function.array.filter(lambda)
filters array to only contain elementse
wherelambda(e)
returns true (note that lambda should always return a boolean, otherwise the filter will fail)array.map(lambda)
maps array of elementse
to an array of elementslambda(e)
array.sort_by_key(lambda)
sorts array of elementse
based on keylambda(e)
. Sorting of values is based on this type order: null, bool, int, float, double, string, array, object. If the type matches, the sorting is performed on the contents itself. Note that sorting of NaN floats will yield a dynamic error as this is not defined.array.to_object(lamba)
converts the array to an object, in which the key is the first value of the array returned by the lambda. The value is the second value of the array returned by the lambda.array.to_map(lamba)
creates a key - array of values object. The lambda returns [key, sort, value].
§User defined functions
During evaluation, there is also the possibility to add user defined functions. These user defined functions are only known at evaluation time, therefore there is no static type checking in place. Only runtime errors are generated if the number of arguments or type of arguments do not match.
§Easily convert custom data types to values
Using the From
trait, custom data types can be easily converted to values, even if they are
contained in data structures like Vec
.
use expry::*;
struct Foo {
foo: u32,
bar: bool,
}
impl<'a> From<&'a Foo> for DecodedValue<'a> {
fn from(v: &'a Foo) -> Self {
value!({
"foo": v.foo as i64,
"bar": v.bar,
})
}
}
let foos = vec![
Foo{foo:1,bar:true},
Foo{foo:2,bar:false},
];
let encoded_value = value!({
"foo": Foo{foo:1,bar:true},
"foos": foos,
}).encode_to_vec();
Re-exports§
pub use crate::raw_utils::EncodingError;
pub use crate::memorypool::*;
pub use crate::raw_utils::*;
pub use crate::termcolors::*;
pub use crate::parser::*;
pub use crate::stringparser::*;
Modules§
Macros§
- Construct a
expry::DecodedValue
from a JSON-like literal.
Structs§
- Reference to expry expression bytecode.
- Self-contained expry expression bytecode.
- Reference to a expry value.
- Self-contained expry value (in encoded form).
- An provided implementation of the custom function handler, that directly throws an error when invoked.
Enums§
- The central data type of expry. It is modelled similar to JSON, however, contains a couple of noteworthy differences.
- Described the different types of value
expry
supports.
Constants§
Traits§
- Trait that can be used to pass a custom user-provided function handler to
expry
eval functions. - Trait as input to
expry_slice_func
andexpry_eval_func
. This can provide lookup for not-yet encoded inputs to save on encoding/conversion time. For this to work, the input should be as much as possible be not encoded. To this end the bytecode generation should be different: instead of regular field lookups a new input should be added after field lookup, and on usage this input should be used. This leads to another optimization: common lookup/subexpression elimination. Implementations of this traits should case the get() method to save on conversion time.
Functions§
- Formats errors from compilation with a nice layout and underlines on the source lines, so that users can easily understand what to do. Returns the line number of the main error, and a string that can be displayed to the user.
- Formats errors for HTML from compilation with a nice layout including the source lines, so that users can easily understand what to do. Returns the line number of the main error, and a string that can be displayed to the user.
- Compiles an expression to bytecode that can quickly be evaluated using
expry_eval
andexpry_slice
. - Parses an encoded value to a decoded value.
- Parses an encoded value to a value that can be easily decoded on the go.
- Evaluate expression bytecode in the context of the given
value
, resulting in a decoded value. - Evaluate expression bytecode in the context of the given
value
, resulting in a decoded value. This version supports custom user defined functions. - Create an encoded object from individual sorted fields.
- Creates an object with a single key-value pair inside. Expects
value
to be binary encoded. - Parses an expry expression input to a decoded value. This involves compiling and evaluating the input. For more flexibility and re-use of compiled expression, see [
expry_compile
] andexpry_eval
. - Parses a JSON input to a decoded value.
- Evaluate expression bytecode in the context of the given
value
, resulting in an encoded value. - Evaluate expression bytecode in the context of the given
value
, resulting in an encoded value. This version supports custom user defined functions. - Returns empty key.
- Calculates the key as used in this crate from a str. There is also a
[u8]
version. - Calculates the key as used in this crate from an u8 slice. There is also a
str
version. - Merges two encoded objects. Left hand side take preference (so the left hand side value of keys occuring in both is taken).
Type Aliases§
- The keys in encoded expry objects.
- Keys in Binary uses a simple 8-bit hash to speed up look ups.