Syntax of CubePL

# Syntax step by step

This chapter introduced the CubePL syntax of the most common programming structures.

## Expressions

### Constants

Any constant expression is an `expression`. eg. 123.0, "someString"

### Arithmetical Expressions

Common mathematical notation of an arithmetical expression is valid in CubePL. Any arithmetical expression is an `expression`. eg. 123.0 + 23.6, sin(23)

### Boolean Expressions

Common literal notation of a boolean expression is valid in CubePL. Any boolean expression is an `expression`.

[expression] or|and|xor [expression]

or

not [expression]

Any `expression` can be a term of a boolean expression. Non zero value is observed as `TRUE`, zero value is `FALSE`.

### Function call expressions

Function calls have the following syntax:

name ( [expression ] )

## Lambda function (In-place function definition)

To define a function in-place, one uses the following syntax:

{
[statement];
[statement];
...
return [expression];
}

In-place definition of a function is an `expression`. It means, it can appear everywhere, where one can use an `expression`.

## Control structures

Control structures like if-else or while are `statements`.

### Condition IF-ELSE

One can execute series of statements under a condition using the short form of the `if` statement:

if ( condition )
{
[statement];
[statement];
...
}

or full form with `else` :

if ( condition )
{
[statement];
[statement];
...
}
else
{
[statement];
[statement];
...
}

`condition` is a boolean `expression`

### Loop WHILE

One can execute a series of statements as long as a condition is true using the `while` statement:

while ( condition )
{
[statement];
[statement];
...
}

Sequence of statements will be executed till condition is not fulfilled, max 1000000000 times.

## Variables

CubePL allows to work with memory, by using variables. All variables are multi-typed:

• In string context value of a numeric variable is presented in string format.
• In numerical context a string variable is converted to its numerical representation, if possible. Otherwise it is 0.

All variables are arrays. Indexless access to the variable assummes mutually index value 0.

### User defined Variables

The user can define a variable using the syntax:

\${ name } = [expression];

or

\${ name }[index] = [expression];

Currently its name is a fixed string of characters. In later versions of CubePL it will allow any `expression`.

Example of a string context :

\${name} seq "STRING"

Example of a numeric context :

\${name} >= 0.34

\${name}[ \${i} ] >= 0.34

Access to the variable is an `expression`.

Index for the access to the value is also an `expression`.

### Predefined Variables

Cube provides a set of predefined variables for every calculation, which values are independend. Following predefined variables do contain the general information about the cube:

 Predefined variable Explanation cube::#mirrors Number of mirrors in cube file cube::#metrics Number of metrics in cube file cube::#root::metrics Number of root metrics in cube file cube::#regions Number of regions in cube file cube::#callpaths Number of call paths in cube file cube::#root::callpaths Number of root call paths cube::#locations Number of locations in cube file cube::#locations::void Number of void locations in cube file cube::#locations::nonvoid Number of nonvoid locations in cube file cube::#locationgroups Number of location groups in cube file cube::#locationgroups::void Number of void location groups in cube file cube::#locationgroups::nonvoid Number of nonvoid location groups in cube file cube::#stns Number of system tree nodes in cube file cube::#rootstns Number of root system tree nodes in cube file cube::filename Name of the cube file

CubePL engine defines a set of variables, which do depend on an index, their "id". Using call `sizeof(...)` one can run over them and inspect within CubePL expression.

 cube::metric::unit::name Unique name of the metric cube::metric::disp::name Display name of the metric cube::metric::url URL of the documentation of the metric cube::metric::description Description of the metric cube::metric::dtype Data type of the metric cube::metric::uom Unit of measurement of the metric cube::metric::expression CubePL expression of the metric cube::metric::initexpression CubePL initialisation expression of the metric cube::metric::parentd::id ID of the parent of the metric cube::metric::#children Number of children in the metric
 cube::callpath::mod Module of the call path cube::callpath::line File line of the call path cube::calleeid ID of the callee region cube::callpath::#children Number of children in the call path cube::callpath::parent::id ID of the parent callpath
 cube::region::name Name of the region cube::region::mangled::name Mangled name of the region cube::region::paradigm Name of the paradigm of the region cube::region::role Name of the role the region is playing within the paradigm cube::region::url URL with the description of the region of the call path cube::region::description Description of the region of the call path cube::region::mod Module of the region of the call path cube::region::begin::line Begin line of the region of the call path cube::region::end::line End line of the region of the call path
 cube::stn::name Name of the system tree node cube::stn::class Class of the system tree node cube::stn::description Description of the system tree node cube::stn::#children Number of children (other system tree nodes) of the system tree node cube::stn::#locationgroups Number of location groups of the system tree node cube::stn::parent::id ID (among all system tree nodes) of the parent of the system tree node cube::stn::parent::sysid ID (global) of the parent of the system tree node
 cube::locationgroup::name Name of the location group cube::locationgroup::rank Rank of the location group cube::locationgroup::type Type of the location group cube::locationgroup::void Is the this location group void? cube::locationgroup::#locations Number of locations of the location group cube::locationgroup::parent::id ID (amoung all system tree nodes) of the parent system tree node cube::locationgroup::parent::sysid ID (global) of the parent system tree node
 cube::location::name Name of the location cube::location::rank Rank of the location cube::location::type Type of the location cube::location::void Is the this location void? cube::location::parent::id ID (among all location groups) of the parent location group cube::location::parent::sysid ID (global) of the parent location group

CubePL engine sets a series of context sensetive variables, which value depends on the paramaters, for which the derived metric is being calculated. Their value can be used to refer to the values of context insensitive variables described above:

 calculation::metric::id ID of the metric, being calculated calculation::callpath::id ID of the callpath, for what is the metric being calculated calculation::region::id ID of the region, for what is the metric being calculated calculation::sysres::id ID (global) if the sysem resource, for what is the metric being calculated calculation::sysres::kind Type of the system element: `0 = unknown` `5 = system tree node` `6 = location group` `7 = location`

## Different ways to refer an another metric

### Context sensitive reference to another metric

To use values of another metric in the same calculation context, one uses syntax:

metric::[uniq_name]( modificator, modificator )

or

metric::[uniq_name]( modificator)

or

metric::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an `expression`.

### Context insensitive reference to another metric

To use values of another metric in the some fixed calculation context (e.g. aggregated over threads), one uses syntax:

metric::fixed::[uniq_name]( modificator, modificator )

or

metric::fixed::[uniq_name]( modificator)

or

metric::fixed::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an `expression`.

### Direct reference to another metric

To use values of another metric with an specific call path id and system resource id (!), one uses syntax:

metric::call::[uniq_name]( callpath id, modificator, sysres id, modificator )

or

metric::call::[uniq_name]( callpath id, modificator )

There are two version of this call:

1. with four arguments (call path and system); - Only callculation of an inclusive or exclusive value is performed
2. with one argument (call path); - Aggragation over system tree is performed additionally to the calculation of the inclisive or exclusive value for the calltree id

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive.

Metric reference is an `expression`.

Note that "sysres id" is a global identificator and can be refered using \${calculation::sysres::id}.

### Definition of an encapsulated calculation within CubePL expression using metrics of Cube.

One special mechanis of CubePL processing engine allows some level of calculation separation. A derived metric can be created within another CubePL expression. Such "ghost" metric gets its name and properties and exists inside of the cube object as a casual metric. Only difference to the casual metric is in the fact that ghost metric is not visible in GUI and tools and is not stored inside of the metric tree of the cube file.

One can refer such metric as a casual metric using metric references (see 'Context sensitive reference to another metric' , 'Context insensitive reference to another metric' and 'Direct reference to another metric' ).

Example for definition of such metric :

cube::metric::nvisitors(e)
<<
{
\${return}=0;
if ( \${cube::locationgroup::void}[\${calculation::sysres::id}] != 1)
{
if (metric::visits()>0 )
{
\${return} = 1;
};
};
return \${return};
}
>>;
\${visitors} = metric::fixed::nvisitors(e);

where

cube::metric::prederived::nvisitors(e)

gives a type (prederives, exclusive) and unique name (nvisitors) of this metric. Unique name is used then later to refer to this metric via

\${visitors} = metric::fixed::nvisitors(e);

There are kinds of metrics, which can be defined on such manner:

1. ` cube::metric::prederived::name(e)` - An exclusive prederived metric with the name `name`;
2. ` cube::metric::prederived::name(i)` - An inclusive prederived metric with the name `name`;
3. ` cube::metric::postderived::name` - A postderived metric with the name `name`.

Notice that once the metric with some unique name created it exists whole lifetime of the cube object. Therefore one can refer to some somewhere previously defined ghost metric from any following it CubePL expressions.

Ghost Metric definition is a `statement`.

### Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an initialisation phase for previously created ghost metric. For that purpose one uses expression `cube::init::metric::[name]`. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::init::nvisitors
<<
{
global(nvisitors);
}
>>;

where

cube::init::metric::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a `statement`.

### Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an aggregation operator "+" or "-" for previously created ghost metric. For that purpose one uses expression `cube::metric::plus::[name]` or `cube::metric::minus::[name]`. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::plus::nvisitors
<<
max( arg1, arg2)
>>;

or

cube::init::metric::minus::nvisitors
<<
min( arg1, arg2)
>>;

where

cube::init::metric:plus::nvisitors

or

cube::init::metric:minus::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a `statement`.

# Grammar of CubePL

Here will be a full grammar of CubePL expressions (later).