LEO Literals and Expressions ​
Literals and expressions are used to in code to denote values. In both cases the result is a specific value:
- Literals directly represent specific values in the code, like 6, 4.6, "Hello World".
- Expressions represent code that has to be evaluated to determine a value. They can use literals, variables and functions. Expressions are always written between parentheses (
()
). Examples for expressions are(2 + 4)
,(max(2.6, 4.6))
,("Hello " + "World")
,("Hello World")
,(3 * iMyValue)
.
Hint
The individual examples can be tested using a CC "AdoScript" INFOBOX (...)
or a CC "AdoScript" VIEWBOX text:(STR ...)
command.
Data types ​
In the end both literals and expressions represent a value. This value is of a specific type. The following list describes the types that are used in AdoScript and also how they are referred to in this documentation:
intValue
- A positive or negative integer number, i.e. a number without a fractional part. Integer values are written directly as their number. Examples are:0
,1
,2
,5
,5438
,79957234
,-1
,-3
,-5422
etc.realValue
- A positive or negative real number, i.e. a number that has both a decimal part and a fractional part. Real values are written directly as their number. Examples are:0.0
,1.4
,5.42
,-2.6
etc.strValue
- A sequence of characters (bytes) typically called a string. It is mostly used to store text. Strings are written between double quotes"
and use the backslash\
to escape various characters, like\n
to represent a new-line character or\"
to represent a double quote without ending the string. Examples are:"Hello I am a string"
,"Size: 42"
,"Line 1\nLine 2"
etc.timeValue
- A time value most often denotes a duration. To a limited degree it can also be used to denote a specific point in time. It uses the format YY:DDD:HH:MM:SS, with years, days, hours, minutes and seconds. Examples are:00:000:00:05:00
,00:000:01:00:00
,00:001:00:00:00
,23:094:11:15:42
etc.measureValue
- A measure indicates a spacial distance as a single real number. It is generally from a point of reference, is one-dimensional and can be positive or negative indicating direction. The spatial details are handled by the context it is used in, e.g. when used for a parameter x it typically means a distance on the x-Axis. It differs fromrealValue
by also specifying a unit. The allowed units are mm, cm, m and pt, with cm being the most commonly used one. Examples are:1cm
,1.5cm
,15mm
,18pt
etc.arrayValue
- An array is a sequence of other values. The values can be of different types, even in the same array. An array can be multi-dimensional and contain other arrays. The order of the values in an array is relevant. The values in an array are accessed by their index, starting at 0 as the first index. The size of an array is not fixed and can be increased or decreased as needed. Arrays start with opening curly-brackets{
, end with closing curly-brackets}
and the values inside an array are separated by commas,
. Examples are:{1, 2, 3}
,{2, 1, 3}
,{"a", 1, "b", 2}
,{1, 1cm, {"a", "b"}, "c"}
etc.mapValue
- A map is a collection of key-value pairs. The keys and values can be of different types, even in the same map. The key specifies the "identifier" under which a value is located (can be accessed through). It is recommended to use simple values (intValue
,realValue
,strValue
,timeValue
,measureValue
or similar) for keys. For consistency with other systems that use for example JSON it is best to stick to keys being astrValue
. Values can be any type, including arrays or other maps. This allows to build tree structures through nesting maps. The key-value pairs are sorted internally by the map and it should be avoided to rely on a specific sorting. The size of a map is not fixed and can be increased or decreased as needed. Maps start with opening curly-brackets{
, end with closing curly-brackets}
and the key-value pairs inside are separated by commas,
while the key and the value are separated by a colon:
. Examples are{"a": 1, "b": 2}
,{1cm: "a", "b": 00:000:01:00:00}
,{"an array": {1, 2, 3}, "a number": 42, "a map": {"a": "A", "b": "B"}}
etc.
A note on strValue
These are MOSTLY used to store and process text. The end of the text is denoted by a null character (0x00). Almost all functions operating on a string treat the content as text. There are however a few cases where strings are used to store a sequence of binary data, which can include the null character (see the command "AdoScript" FREAD
and "AdoScript" FWRITE
, both used with the binary
parameter). The documentation does however indicate where this is the case. Still, be mindful not to mix a string that stores binary data with functions that work on text.
Additional data types used ​
Furthermore this documentation uses some special types to also indicate the purpose of used or returned values. These are realized using the previously described types and for the program are indistinguishable from them. However, for the purpose of the documentation they provide a useful meaning for the user.
anyValue
- This indicates that "any" type of value can be used. Which types of values are actually valid depends on the command. Typically these areintValue
,realValue
,strValue
,timeValue
ormeasureValue
.boolValue
- This indicates that the provided value denotes "truthfulness". What values are considered "true" or "false" depends on their type, however it is best to stick to anintValue
. For most numeric types (intValue
,realValue
) a value of 0 is considered "false" and string values (strValue
) are considered "false" when their length is 0. All other values of those types are considered "true". Measure (measureValue
) and time (timeValue
) values are always considered "false". Anundefined
value is also considered to be "false". For arrays (arrayValue
) and maps (mapValue
) it is recommended to break them down to one of the other types, for example using theLEN
function to get their length as a number. The most common usedboolValue
are0
and1
.idValue
- This indicates that an identifier (ID) is used. An identifier is always a positive integer number (intValue
). IDs are also larger than zero, with the exception of some very specific cases deep inside the core of the platform that is seldomly used directly.tokenStr
- This indicates that a list of tokens is used. These are always strings (strValue
) and are sometimes called a "string list" or "token string". The tokens of a string list are separated using a specific character, typically a single white space. String lists are intended to be used with various functions and commands for processing them, like the token version of the
FOR
loop or functions liketoken(...)
,tokcnt(...)
,tokcat(...)
,tokunion(...)
etc. They are astrValue
based alternative to arrays.enumValue
- This indicates that only specific pre-defined values are allowed. Which values are allowed depends on the command.