BinPath Expression Language

All BinPath expressions are executed in a context of some node. This node is called context node. It is the reference point for all calculations and reference paths executions.
Result of each expression execution will be interpreted depend on execution context - see table below.
Expression type Execution context Result type
AcceptRule Enclosing type (structure) boolean
Array dimensions Enclosing type (structure) number (long)
Restrictions, single item Current item boolean
Restrictions, array Current array element boolean
Expression inside predicate Enclosing type (structure) If the result is boolean value, this expression will be executed against each set of nodes. Otherwise, this is a number and expression will return n-th element from the node set.
User made query Current (selected) node Node. This node may contain a real node from document or pseudo-node contained a number, boolean or string, or pseudo-node contained a set of nodes.

Besides the context node, execution context includes following elements:
  1. Current node. In root level expression - the same as context node. In subexpressions (predicates), points to the currently processed node.
  2. Position. For the main expression it equals to 0; for subexpressions - position of the currently processed node.
  3. Size of the context. In main expression it equals to 1; in subexpressions - size of node set in the current reference step.
  4. Index. When binary parser or validator works with arrays, it initializes index value with an index of currently processed element. Works only in binary parser or validator.
BinPath expression elements are calculated only when it is necessary. The following calculations will be skipped:
  • Further calculation of && operands if previous operand is equal to false.
  • Further calculation of || operands if previous operand is equal to true.
  • One of choice function operands, depending from condition result.
BinPath expressions is similar to Xpath and other mathematical expressions. It consists of the following elements:

Immediate, or literal values
They include:
  • decimal numeric values, including floating point values, e.g., 3576, 14.4556, etc.
  • hexadicimal values, with 0x prefix - 0x5786afdd. Values must fit into ulong.
  • octal values, with 0 prefix - 0578626. Values must fit into ulong.
  • symbol values, will be converted into bytes - 'a', 'b', and escaped special symbols - '\\' - backslash itself, '\s' - space character, '\t' - tab character, '\r' - carriage return, '\n' - line feed, '\f' - form feed, '\'' - single quote symbol, '\"' - double quote symbol, \xNNNN - hexadecimal Unicode symbol.
  • string constants, enclosed with double qutation marks - "abcde". Inside these constants you may use the same escaped symbols as in symbol values.
  • bool constants "true" and "false".
Numeric immediate values will have auto assigned best-fit types.

Reference path
A reference path is an BinPath expression used for selecting a set of nodes relative to the context node. The evaluation of a reference path expression results in a node-set built from the nodes specified by the reference path. Reference path can contain nested expressions for filtering node sets.
Reference path consists of one or more reference steps (axes), each separated with a dot (.).
Each reference step selects a set of nodes relative to the context node - i.e., to the node selected by the preceding reference step.
In a reference path, reference steps are evaluated from left to right. The leftmost reference step selects set of nodes relative to the context node. These nodes then become the context used to process the next reference step. Processing of a step and updating the context node repeats over and over again until all the reference steps are processed.
Reference steps (axes) in a reference expressions can be mixed with predicates enclosed in square brackets: 

step.step[predicate].step
Predicate is a filter expression. It refines selection of nodes in the reference step. Predicates are build of BinPath expression. Predicates are optional. Predicate execution does not change context node, but set current node to currently processed node in the set and change position and size of the context. It is possible to use several predicates one after another. Each of them will refine results of previous predicates.

Here is a list of references (axes):
Reference Meaning
root root node (document)
parent parent node of the current node. For structures which are target types in views, parent of source data structure will be also a parent of view target structure in schema compilation stage check and in runtime.
preceding all nodes that are before the context node in the tree, excluding any ancestors
following all nodes that are after the context node in the tree, excluding any descendants
ancestor the ancestors of the context node
descendant the descendants of the context node
ancestor_or_self the context node and its ancestors
descendant_or_self the context node and its descendants
following_sibling all the following siblings of the context node
preceding_sibling all the preceding siblings of the context node
first_following_sibling first following sibling of the context node
last_preceding_sibling last preceding sibling of the context node
child the children of the context node
current currently processing node
context context node

Functions
Function could have 0 or more parameters. Parameters are be separated by ',' (comma). You can use the following predefined BinPath functions to enhance BinPath queries:
Function Arguments Returns Description
boolean empty or BinNode BinValueCalculated containing boolean value Converts any value to boolean, without parameters uses context node.
number empty or BinNode or BinNode node, BinNode radix BinValueCalculated containing number (not string and not boolean) value Converts any value to number. For collections and BinValueArrays, returns length of collection (array). Without parameters uses context node. When used to convert string to number, second parameter may be used to provide radix value for conversion. Valid values are 2, 8, 10, 16. Deafult radix value is 10. Zero radix value is equal to 10.
string empty or BinNode or BinNode node, BinNode radix BinValueCalculated containing string value Converts any value to string. Builds string from BinValueArrays and BinNodeCollections (if collection contains BinValue or BinValueCalculated nodes) converting each element into char value. For numeric types, returns string representation of number(). Without parameters uses context node. When used to convert integer value to string, second parameter may be used to provide radix value for conversion. Valid values are 2, 8, 10, 16. Deafult radix value is 10. Zero radix value is equal to 10.
uint8 BinNode BinValueCalculated containing uint8 value Converts any value to uint8 (byte)
int8 BinNode BinValueCalculated containing int8 value Converts any value to int8 (sbyte)
uint16 BinNode BinValueCalculated containing uint16 value Converts any value to uint16 (ushort)
int16 BinNode BinValueCalculated containing int16 value Converts any value to int16 (short)
uint32 BinNode BinValueCalculated containing uint32 value Converts any value to uint32 (uint)
int32 BinNode BinValueCalculated containing int32 value Converts any value to int32 (int)
uint64 BinNode BinValueCalculated containing uint64 value Converts any value to uint64 (ulong)
int64 BinNode BinValueCalculated containing int64 value Converts any value to int64 (long)
float BinNode BinValueCalculated containing float value Converts any value to float (single)
double BinNode BinValueCalculated containing double value Converts any value to double
power BinNode x, BinNode y BinValueCalculated containing double value Converts parameters to double and calculates xy
count empty or BinNode BinValueCalculated containing long value Returns Count value of BinNode, without parameters uses context node
sizeof empty or BinNode BinValueCalculated containing long value Returns Size value of the specified BinNode. When called without parameters, returns size of the context node
sum empty or BinNode BinValueCalculated containing long value Calculates the sum of nodes recursively, converting all nodes to number, without parameters uses context node
name empty or BinNode BinValueCalculated containing string value Returns name of binary schema item representing this value, without parameters uses context node
type empty or BinNode BinValueCalculated containing string value Returns type of binary schema item represenging this value, without parameters uses context node. For BinValueArrays, appends "*" to the type. For collections, returns empty string.
array BinNode BinNodeCollection If argument is a BinValue or BinValueArray, wraps a collection around the value. This function should be used to create collection context
arrayof empty or BinNode BinValueCalculated containing string value Appends "*" array indicator to type(parameter) result.
isarray BinNode BinValueCalculated containing boolean value Returns true if the argument is a collection or BinValueArray.
isstruct BinNode BinValueCalculated containing boolean value Returns true if argument is a type (structure) or document.
isscalar BinNode BinValueCalculated containing boolean value Returns true if argument is a BinValue or BinValueCalculated.
false none BinValueCalculated containing boolean value Returns false.
true none BinValueCalculated containing boolean value Returns true.
last none BinValueCalculated containing long value Returns last position (size of set) in node-set when executed in predicate.
position empty or BinNode BinValueCalculated containing long value If used without parameters, returns position of the currently processing elements in node-set when executed in predicate. If used with node parameter, returns its Position in the document.
lookup BinNode dictionary, BinNode key BinValueCalculated containing dictionary value corresponding key Converts first argument to string and performs a search of the value by in Dictionary keys. Dictionary shall be defined it data definition file. If some of these entities were not found, returns default value (0 of type long). Please, note that BinaryDom runtime does not check the name of Dictionary passed to lookup().
index empty or BinNode BinValueCalculated containing long value Returns index value in expressions used in binary parser and validator. If parameter is present, it defines recursive level of index, if used in nested arrays.
slice BinNode index, BinNode count, BinNode array BinNodeCollection Returns a slice of array or collection. If index is negative value, index is an offset from the end of collection.
alterview empty or BinNode source or BinNode source, BinNode viewname BinNode Returns an alternate view for the specified source node. Name of the view is calculated from viewname parameter - it might contain an expression which will be converted into string.
Both parameters are optional; default source parameter is context node, default viewname is an empty string which means default view.
iswhitespace empty or BinNode BinValueCalculated containing boolean value Converts parameter to char value and returns Char.IsWhiteSpace(); without parameters uses context node.
isdigit empty or BinNode BinValueCalculated containing boolean value Converts parameter to char value and returns Char.IsDigit(); without parameters uses context node.
isletter empty or BinNode BinValueCalculated containing boolean value Converts parameter to char value and returns Char.IsLetter(); without parameters uses context node.
isletterordigit empty or BinNode BinValueCalculated containing boolean value Converts parameter to char value and returns Char.IsLetterOrDigit(); without parameters uses context node.
ispunctuation empty or BinNode BinValueCalculated containing boolean value Converts parameter to char value and returns Char.IsPunctuation(); without parameters uses context node.
toupper BinNode BinValueCalculated containing string value Converts parameter to string and returns it in uppercase.
tolower BinNode BinValueCalculated containing string value Converts parameter to string and returns it in lowercase.
Some functions represent operations and could be used instead of them.
In most cases, it is more convenient to use operations.
Function Arguments Returns Description
not BinNode boolean BinValueCalculated Logical not. Returns inverted value of node converted to boolean.
bitnot BinNode unsigned integer BinValueCalculated Bitwise not. Returns binary inverted value of node converted to nearest unsigned integer.
uminus BinNode integer BinValueCalculated Unary minus. Returns negative value of node converted to nearest integer.
choice BinNode condition, BinNode true_expr, BinNode false_expr BinNode Ternary operation. Calculates condition, converts it to boolean and executes (returns) true_expr if result is true, false_expr if result is false. Only one expression will be actually calculated.
op_less BinNode, BinNode boolean BinValueCalculated Less.
op_more BinNode, BinNode boolean BinValueCalculated More.
op_less_equ BinNode, BinNode boolean BinValueCalculated Less or equal.
op_more_equ BinNode, BinNode boolean BinValueCalculated More or equal.
op_equ BinNode, BinNode boolean BinValueCalculated Equal.
op_ne BinNode, BinNode boolean BinValueCalculated Not equal.
op_add BinNode, BinNode BinValueCalculated Add.
op_sub BinNode, BinNode BinValueCalculated Substract.
op_mul BinNode, BinNode BinValueCalculated Multiply.
op_div BinNode, BinNode BinValueCalculated Divide.
op_rem BinNode, BinNode BinValueCalculated Reminder.
op_and BinNode, BinNode BinValueCalculated Bitwise and.
op_or BinNode, BinNode BinValueCalculated Bitwise or.
op_xor BinNode, BinNode BinValueCalculated Bitwise xor.
op_lshift BinNode, BinNode BinValueCalculated Shift left.
op_rshift BinNode, BinNode BinValueCalculated Shift right.
op_land BinNode, BinNode BinValueCalculated Logical and.
op_lor BinNode, BinNode BinValueCalculated Logical or.
Every parameter in every function could be a BinPath expression of any complexity, not just a single BinNode.

Besides the predefined functions, you can write and use your own functions and use them in expressions.
To write a custom user a function, you need to build a DotNet assembly with a class which implements IExternalFunction interface, build it, and make the dll available to the main application.
Syntax of a user function is 

namespace::name(parameters)

or 

namespace(parameters)
where namespace is a Namespace name defined in a document schema. Name is a name of the function. Actually, this is a name of the class in the assembly.
In a case when function name is omitted, system searches for a first suitable class (which implements IExternalFunction interface).

Operations
This is a set of common mathematic operations.
Operations can be executed in three possible contexts which will affect some operations result:
  • Collection context. True if both operands are collections. If you need to enforce use of this context, array() function will help. Applicable operations: & (And), | (Or).
  • String context. True if both operands are strings. BDDL does not include string type, but it has string functions and string context. String context applies in the following cases:
    • when using type(), name(), arrayof(), string() functions
    • when using string literals in expressions
    • when BinValueArrays of types char and wchar is implicitly converted into strings in string context.
    Applicable operations are: +, <, >, <=, >=, ==, !=.
  • Common context. Usual context for numbers and nodes.
Here is a list of operations with their priorities:
Operation Priority Note
! 12 Logical not. Operand will be converted to boolean and inverted.
~ 12 Bitwise not. Operand will be converted to unsigned integer.
- 12 Unary minus. Operand will be converted into signed value.
* 11 Multiply.
/ 11 Divide.
% 11 Reminder. Operands will be converted into integers.
+ 10 Add. In string context - concatenates strings.
- 10 Substract.
<< 9 Shift left. First operand converted to unsigned integer, second - to int.
>> 9 Shift right. First operand converted to unsigned integer, second - to int.
< 8 Less. Works in common and string contexts.
> 8 More. Works in common and string contexts.
<= 8 Less or equal. Works in common and string contexts.
>= 8 More or equal. Works in common and string contexts.
== 7 Equal. Works in common and string contexts. Alternative symbol for this operation is '='.
!= 7 Not equal. Works in common and string contexts.
& 6 And. Operands will be converted to unsigned integers. In collection context performs intersection of collections.
^ 5 Xor. Operands will be converted to unsigned integers.
| 4 Or. Operands will be converted to unsigned integers. In collection context performs union of collections.
&& 3 Logical And. Operands will be converted to boolean.
|| 2 Logical Or. Operands will be converted to boolean.
?: 1 Ternary operation. Calculates first expression (before question mark) and, if it is true, calculates and returns second expression (before colon); otherwise uses third expression (after colon).
Parentheses can be used in expressions to change operation priorities.

See also: