Data References
In general,
Enki language expressions are stored either at a
dispel
or at a data item. From an expression, all the data published to the dispel or accessible from the data
item can be used.
Data external to the expression are accessed by writing the
name
of object in which the desired data item is located, followed by a dot separated
reference
to the data item. For example, if there is a table named
customers
in the document section
Data,
it is accessed from an
Enki expression as follows:
document.data.customers
Some object names are optional. Thus, for instance, instead of writing
this.x,
it is sufficient to write just
x.
Whether the object name is optional can be, for instance, decided in a
data
provider definition for the local variables object name.
A variable name defined with the keyword
var
can serve as an object name, too.
Sequence Element Identification
As has been described, a data reference consists of the names of structure components separated by dots.
If an array or sequence element is to be identified, an index instead of a name is used (the index of
the first element is 0). Equivalently, the index can be enclosed in square brackets, as is common in
many other programming languages.
For instance:
document.data.customers.0.name
refers to the same data item (the name component of the first row of the customers
table stored in the document section Data) as:
document.data.customers[0].name
The Concept of L-Value
A reference identifies a data item, the value of which can not only be used in a computation, but it
can be changed, as well. In this respect, references differ from constants and function results, which
are mere values. A reference, on contrary, identifies an object (a variable or a data item), to which
a value can be stored. A value that identifies an object (whose value can be changed) is called an l-value
(“l” for “left”, as such a value can be
placed at the left side of an assignment operator). A mere direct value is then called an r-value.
Every l-value can be used at the place of an r-value, as it can
be converted to an r-value by reading the current value stored in the referred object.
Dynamic Determination of Sequence Element
In the example above, a reference to a sequence element was created. However, it is often needed to refer
to a sequence element, the index of which is a result of a computation. Let us suppose, that i
is an integer variable. If the i-th sequence element is to be referred, the variable
(or even a whole expression) is written enclosed in the square brackets:
document.data.customers[i].name
However, an equivalent expression written using the dot-notation document.data.customers.i.name
would not work, because it would be interpreted as referencing a component with the name i,
which is, however, not present in the table customers.
In order to distinguish a direct name from a variable name or an expression, it is necessary to enclose
the computed index in parentheses:
document.data.customers.(i).name
Dynamic Determination of Arbitrary Part of Reference
The concept of dynamic index determination described above can be generalized to dynamic computation
of any part of reference. To help this task, two data type are defined:
Atom
A single name, from which a reference is built up. A value of this data type can be created by the
typecast
operator from a string. For instance:
[Atom]"name".
Dref
A value representing a part of or a whole reference; i.e. one or more atoms and/or indexes. A value of
this data type can be created by the
typecast
operator from a string. For instance:
[Dref]"customers.0.name".
Conversely, the values of the both types can be converted to String.
With the dot operator, any value of the types Atom
or Dref can be chained with another
reference. For instance:
var
Atom column = [Atom]"name";
document.data.customers.0.(column)
Again, it is necessary to enclose the computed part in parentheses to distinguish it from a direct component
name.
Similarly for Dref:
var
Dref item = [Dref]"customers.0";
document.data.(item).name
L-Value and Reference Alteration
If a Dref value contains a whole reference,
the corresponding l-value can be obtained with the asterisk (*)
operator:
var
Dref item = [Dref]"document.data.customers.0.name";
*item = "Joseph Smith";
Conversely, the Dref value corresponding
to an l-value can be obtained with the ampersand (&)
operator:
var
Dref item_ref = &document.data.customers.0.name
This can be useful with a parameter passed by reference (see the
function
editor), where the acquired valued of the type
Dref
can be converted to a
String and further
analyzed.
Data Declaration
In the most cases, it can be inferred from the function location, which external data are accessible
from the functions. However, in some cases (e.g. in a
tool
definition), this does not necessarily hold. Then, it may be needed to declare what data are expected
to be present during the run-time and what their type is. The
declare
statement serves this purpose:
declare Type name
If the exact type is not known, it suffices to declare it as a Union,
which is a union of all types (i.e. any type).