LEO Literals and Expressions

This page provides some information on literals, expressions and the types of values that are used in AdoScript and LEO-based languages.

Hint

The individual examples can be tested using a CC "AdoScript" INFOBOX (...) or a CC "AdoScript" VIEWBOX text:(STR ...) command.

Values

Literals and expressions are used 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).

Generally when a value is required for a specific part of code, like a value for a parameter, it can be either provided through a literal to denote a constant or through an expression to be evaluated.

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 position on the x-Axis. It differs from realValue 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. The most precise value for measures is 0.01cm (or 0.1mm) and any further decimal places are truncated (0.009cm + 0.009cm evaluates to 0cm). Furthermore 1cm is around 28.3464567pt or 10pt are around 3.5277777mm.
• 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 a strValue. 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 are intValue, realValue, strValue, timeValue or measureValue.
• 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 an intValue. For the numeric types intValue and realValue a value of 0 is considered "false" and all other values of those types are considered "true". All other types of values (strValue, measureValue, timeValue, arrayValue and mapValue) are always considered "false". An undefined value is also considered to be "false". For strings (strValue), arrays (arrayValue) and maps (mapValue) it is recommended to break them down to a number, for example using the LEN operator to get their length as a number. For measures (measureValue) and time (timeValue) use comparison operators to evaluate to a boolValue. The most common used boolValue are 0 and 1.
• 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", "token string" or "token list". 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 like token(...), tokcnt(...), tokcat(...), tokunion(...) etc. They are a strValue based alternative to arrays.
• enumValue - This indicates that only specific predefined values are allowed. Which values are allowed depends on the command.

LEO Colors

Colors in LEO are typically specified as a strValue, either through their name ("blue", "chartreuse" or "green") or as a hexadecimal representation following the format of "$rrggbb" for red, green and blue. It is also possible to specify a color through an RGB intValue in which case it is recommended to use the special color functions available. The color specifications are used in various places, for example to specify a color as part of a GraphRep.

Color as intValue

When a color is specified as or transformed to an integer value, then the last three bytes are used for the values of red (rr0000), green (00gg00) and blue (0000bb). This can be useful to process or transform color values with special color functions, for example to sort colors bei their hue:

SETL aAllColors:({"aliceblue", "antiquewhite", "aqua", "aquamarine", "azure", "beige", "bisque", "black", "blanchedalmond", "blue", "blueviolet", "brown", "burlywood", "cadetblue", "chartreuse", "chocolate", "coral", "cornflowerblue", "cornsilk", "crimson", "cyan", "darkblue", "darkcyan", "darkgoldenrod", "darkgray", "darkgreen", "darkkhaki", "darkmagenta", "darkolivegreen", "darkorange", "darkorchid", "darkred", "darksalmon", "darkseagreen", "darkslateblue", "darkslategray", "darkturquoise", "darkviolet", "deeppink", "deepskyblue", "dimgray", "dodgerblue", "firebrick", "floralwhite", "forestgreen", "fuchsia", "gainsboro", "ghostwhite", "gold", "goldenrod", "gray", "green", "greenyellow", "honeydew", "hotpink", "indianred", "indigo", "ivory", "khaki", "lavender", "lavenderblush", "lawngreen", "lemonchiffon", "lightblue", "lightcoral", "lightcyan", "lightgoldenrodyellow", "lightgreen", "lightgray", "lightmagenta", "lightpink", "lightsalmon", "lightseagreen", "lightskyblue", "lightslategray", "lightsteelblue", "lightyellow", "lime", "limegreen", "linen", "magenta", "maroon", "mediumaquamarine", "mediumblue", "mediumorchid", "mediumpurple", "mediumseagreen", "mediumslateblue", "mediumspringgreen", "mediumturquoise", "mediumvioletred", "midnightblue", "mintcream", "mistyrose", "moccasin", "navajowhite", "navy", "oldlace", "olive", "olivedrab", "orange", "orangered", "orchid", "palegoldenrod", "palegreen", "paleturquoise", "palevioletred", "papayawhip", "peachpuff", "peru", "pink", "plum", "powderblue", "purple", "red", "rosybrown", "royalblue", "saddlebrown", "salmon", "sandybrown", "seagreen", "seashell", "sienna", "silver", "skyblue", "slateblue", "slategray", "snow", "springgreen", "steelblue", "tan", "teal", "thistle", "tomato", "turquoise", "violet", "wheat", "white", "whitesmoke", "yellow", "yellowgreen"})
# Sorting lambda function to sort the order of colors primarily on hue, secondarily on saturation and tertiary on brightness.
SETL lam_SortByHue:(lambda(x, y, cond((byte(hsvval(x), 2)) = (byte(hsvval(y), 2)), cond((byte(hsvval(x), 1)) = (byte(hsvval(y), 1)), (byte(hsvval(x), 0)) < (byte(hsvval(y), 0)), (byte(hsvval(x), 1)) < (byte(hsvval(y), 1))), (byte(hsvval(x), 2)) < (byte(hsvval(y), 2)))))
SETL dummy:(aAllColors.sort(lam_SortByHue))

The following color names are available in LEO:

Color name	Color name	Color name	Color name	Color name
black	dimgray	darkgray	gray	silver
lightgray	gainsboro	whitesmoke	white	snow
rosybrown	lightcoral	indianred	brown	firebrick
maroon	darkred	red	mistyrose	salmon
tomato	darksalmon	coral	orangered	lightsalmon
sienna	seashell	chocolate	saddlebrown	sandybrown
peachpuff	peru	linen	bisque	burlywood
darkorange	antiquewhite	tan	blanchedalmond	navajowhite
papayawhip	moccasin	oldlace	wheat	orange
floralwhite	goldenrod	darkgoldenrod	khaki	cornsilk
gold	lemonchiffon	palegoldenrod	darkkhaki	ivory
beige	lightyellow	lightgoldenrodyellow	olive	yellow
olivedrab	yellowgreen	darkolivegreen	greenyellow	chartreuse
lawngreen	honeydew	darkseagreen	lightgreen	palegreen
forestgreen	limegreen	darkgreen	green	lime
mediumseagreen	seagreen	mintcream	springgreen	mediumspringgreen
aquamarine	mediumaquamarine	turquoise	mediumturquoise	lightseagreen
azure	lightcyan	paleturquoise	darkslategray	teal
darkcyan	aqua	cyan	cadetblue	darkturquoise
powderblue	lightblue	deepskyblue	skyblue	lightskyblue
steelblue	aliceblue	slategray	lightslategray	dodgerblue
lightsteelblue	cornflowerblue	royalblue	ghostwhite	lavender
midnightblue	navy	darkblue	mediumblue	blue
darkslateblue	slateblue	mediumslateblue	mediumpurple	blueviolet
indigo	darkorchid	darkviolet	mediumorchid	thistle
plum	violet	purple	darkmagenta	fuchsia
lightmagenta	magenta	orchid	mediumvioletred	deeppink
hotpink	lavenderblush	palevioletred	crimson	pink
lightpink

Expressions

In ADOxx, three different types of expressions can be found:

• LeoExpressions: LeoExpressions are a set of basic functions and operators, from which an expression can be aggregated. They are used to calculate values, manipulate strings and perform other similar basic tasks. LeoExpressions can be used with every LEO language. Wherever LEO strings are possible, LEO expressions can be used.
• CoreExpressions:: A CoreExpression is an ADOxx-specific extension of a LeoExpression. When creating a CoreExpression, both functions and operators of LeoExpressions and core-specific functions designed specifically for ADOxx can be utilized. CoreExpressions can only be used in attributes of type EXPRESSION or as part of the EVAL_EXPRESSION MessagePort command.
• AdoScriptExpressions:: An AdoScriptExpression is an extension of a LeoExpression. Consequently, all functions and operators of the LeoExpressions can be used here as well. Furthermore, specifically designed AdoScript functions can be utilized. AdoScriptExpressions can only be used within AdoScripts.

CoreExpressions

Syntax for EXPRESSION Attributes

Expressions as part of an EXPRESSION type attribute provide a basic set of functions and operators for investigating or calculating within a model context and across multiple models. This can be both a fixed calculation and the processing of attribute values. The syntax of the language for EXPRESSION attributes is based on the following grammar:

Non-terminal	Definition
ExprDefinition	EXPR type: ResultType [ format: FormatString ] expr:[ fixed: ] CoreExpression .
ResultType	double | integer | string | time .
FormatString	(WIP)

Hint

The above syntax is necessary when specifying the "default value" on an expression type attribute in the Development Toolkit. When specifying an expression in the Modelling toolkit through the expression dialog only the CoreExpression is specified.

Each definition of the EXPRESSION attribute starts with the keyword EXPR. The result type will be fixed by means of the attribute type: and a standard formula expr. Each time an instance is created (object, model or connector), the formula will be used to calculate the result value of the expression.

The type of the calculated value is defined as part of the expression and must be either a text, number or time (duration). The expression or value entered can be up to 3600 characters.

By setting the modifier as fixed: the expression will be unchangeable in the Modelling Toolkit. It means that the EXPRESSION attribute evaluates the same formula everywhere.

In the expressions where you can change the instances, each evaluation instance will be assigned to an appropriate expression. Then the specification of an expression in the "Expression-Definition" is optional and is of use for initial assignment of an expression to evaluation instances. For each evaluation instance, you can open an input window from the ADOxx Notebook, which enables the editing of the expression. The changeable expression will be saved to the evaluation instance under expr.

For every evaluation instance the result of its expression is calculated and saved to the attribute values of the EXPRESSION attribute under val. A new calculation is triggered every time the result could possibly have changed. This is the case when the expression was changed or when an attribute value necessary for the expression has been changed in the core component.

HINT

The command EVAL_EXPRESSION allows to evaluate an expression (see above) without the need for an EXPRESSION attribute.

Preset Variables

The following variables are preset for every EXPRESSSION attribute:

• objid: the ID of the own object/connector.
• classid: the ID of the own class/relation class.
• modelid: the ID of the model containing the own object.
• attrid: the ID of this attribute.

Available Functions

All the operators and functions from LEO Operators and Functions are available. It is not possible to use custom functions specified through the FUNCTION AdoScript command. Additionally, the following functions can be used in an attribute of type EXPRESSION:

aval ( instID , attrName ) Returns the value of the instance attribute specified by the two parameters.

aval ( attrName ) Returns the value of the same-instance instance attribute specified by attrName.

aval ( instName , attrName ) Returns the value of the same-model same-class instance attribute specified by the two parameters.

aval ( className , instName , attrName ) Returns the value of the same-model instance attribute specified by the three parameters.

avalf ( format , instID , attrName ) Returns a formatted string of the value of the instance attribute specified by the two parameters.

avalf ( format , attrName ) Returns a formatted string of the value of the same-instance instance attribute specified by attrName. For INTERREF attributes, format is returned with the following replacements: %o by object name, %c by class name, %m by model name, %t by model type name of the target model.

avalf ( format , instName , attrName ) Returns a formatted string of the value of the same-model same-class instance attribute specified by the two parameters.

avalf ( format , className , instName , attrName ) Returns a formatted string of the value of the same-model instance attribute specified by the three parameters.

maval ( attrName ) Returns the value of the same-model model attribute specified by attrName.

irtmodels ( attrName ) Returns the models referenced from the specified same-instance INTERREF attribute attrName.

irtmodels ( instID , attrName ) Returns the models referenced from the speified INTERREF attribute.

irtmodels ( instName , attrName ) Returns the models referenced from the specified same-model same-class INTERREF attribute.

irtobjs ( attrName ) Returns the objects referenced from the specified same-instance INTERREF attribute.

irtobjs ( instID , attrName ) Returns the objects referenced from the specified INTERREF attribute.

irtobjs ( instName , attrName ) Returns the objects referenced from the specified same-model same-class INTERREF attribute.

objirsobjs () Returns the objects referencing the current instance. The usage of this function is not recommended due to high performance costs.

objirsobjs ( targetName ) Returns the objects referencing the same-class object targetName. The usage of this function is not recommended due to high performance costs.

objirsobjs ( targetID ) Returns the objects referencing the object with the specified ID targetID. The usage of this function is not recommended due to high performance costs.

modelirsobjs () Returns the objects referencing this model. The usage of this function is not recommended due to high performance costs.

profile ( attrName ) Returns the ID of the referenced attribute profile from the specified same-instance PROFILEREF attribute.

paval ( profilerefAttrName , attrNameInProfile ) Returns the value of the instance attribute of a referenced attribute profile.

pavalf ( format , profilerefAttrName , attrNameInProfile ) Returns a formatted string of the value of the instance attribute of a of a referenced attribute profile.

ctobj() Returns the to-object of this connector.

cfobj() Returns the from-object of this connector.

ctobjs ( relnName ) Returns the to-objects connected from this object with the specified relation type relnName.

ctobjs ( instid , relnName ) Returns the to-objects connected from the specified object with the specified relation type relnName.

cfobjs ( relnName ) Returns the from-objects connected to this object with the specified relation type relnName.

cfobjs ( instid , relnName ) Returns the from-objects connected to the specified object with the specified relation type relnName.

conn ( relnName , fromObjs , toObjs ) Returns the connectors of the specified type relnName between the specifed objects. An objs parameter can be a single ID or a string containing a sequence of IDs.

objofrow ( rowID ) Returns the modelling object owning the RECORD attribute containing the row rowID.

rcount ( recordAttrName ) Returns the number of rows of a record.

row ( recordAttrName , rowIndex ) Returns the ID of the internal object representing the record row with the given rowIndex (between 1 and rcount()).

rasum ( recordAttrName , columnName ) Returns the sum of all values of the record column columnName. You can sum INTEGER, DOUBLE, TIME, and EXPRESSION attributes.

rasum ( idStr , recordAttrName , columnName ) Returns the sum for all objects specified by idStr of the sum of all values of a record column. You can sum INTEGER, DOUBLE, TIME, and EXPRESSION attributes.

prasum ( profileAttrName , recordAttrName , columnName ) Returns the sum of all values of a column of a record in an attribute profile. You can sum INTEGER, DOUBLE, TIME, and EXPRESSION attributes.

Attention

Please note that values added using rasum() or prasum() must be of the same type. INTEGER, DOUBLE and TIME values return the same value type. When adding values from EXPRESSION attributes, the type the expression itself returns is chosen. Expressions returning other types than the ones mentioned cannot be tackled using rasum() or prasum(). Invalid values appearing during processing are ignored.

isloaded ( modelid ) Returns '1' if the model modelID is loaded, otherwise '0'.

allobjs ( modelID , className ) Returns all objects of the class className in the specified model modelID.

aql ( aqlExpr ) Returns a string with the IDs of the AQL expression's result.

prevsl() Returns the ID of the previous swimlane.

nextsl() Returns the ID of the next swimlane.

asum ( idStr , attrName ) Returns the sum for all objects specified by idStr of all attribute values of the attribute specified by attrName.

amax ( idStr , attrName ) Returns the maximum for all objects specified by idStr of all attribute values of the attribute specified by attrName.

awsum ( instIDStr , objAttrName , connIDStr , connAttrName ) Returns the weighted sum for all objects specified by instIDStr of all attribute values of the attribute specified by objAttrName weighted with attribute values of connectors specified by connIDStr and connAttrName.

pmf ( className , profileAttrName , recAttrName , orgunitColName , quantityColName , factorAttrName ) Human resource management function.

pmf ( className , recAttrName , orgunitColName , quantityColName , factorAttrName ) Human resource management function (old version).

class ( instID ) Returns the class ID of an instance instID.

class ( className ) Returns the ID of the class with the name className.

mtype () Returns the model type name of same-model.

mtype ( modelID ) Returns the model type name of the specified model modelID.

mtclasses ( modelTypeName ) Returns the classes allowed in the model type modelTypeName.

mtrelns ( modelTypeName ) Returns the visible relation classes in the model type modelTypeName.

allcattrs ( classID ) Returns all class attributes of the class classID.

alliattrs ( classID ) Returns all instance attributes of the class classID.

allrattrs ( relationID ) Returns all attributes of the relation relationID.

attrname ( attrID ) Returns the name of the attribute attrID.

atttype ( attrID ) Returns the type name ("INTEGER", "DOUBLE", "STRING", "DISTRIBUTION", "TIME", "ENUMERATION", "ENUMERATIONLIST", "LONGSTRING", "PROGRAMCALL", "INTERREF", "EXPRESSION", "RECORD","ATTRPROFREF", "DATE", "DATETIME") of the attribute attrID.