Atelerix

Atelerix is a custom programming language that we created to make transforming data easier. You can use Atelerix anywhere you can specify an Expression. Here you will find an overview of how the language works.

A note about case

Atelerix is not case sensitive. You can call the function text or TEXT or Text they are all the same. Even variable names: data.field.value is the same as DaTa.FiElD.VaLuE (but probably don’t do that). However, if you compare two strings, that is case sensitive, 'hello' == 'HELLO' will return false. If you need to compare two strings and are worried about case use the Text.ToLower() function (or Text.ToUpper() if that suits your fancy!)

Atelerix in Infomaptic

Atelerix is used within infomaptic as a scripting language, or expression language. You can use expressions in infomaptic to have more control over what is displayed to the user by formatting dates, numbers, text, etc. You can even choose to display different values by using ternary expressions (if statements).

If you are already familuare with the concepts used in programming languages or expression languages, you might want to jump straight to the examples.

Within infomaptic a special data object is used to hold all of the data present for use within your template. This object has the form data.<field name>.{name | alias | value} where <field name> is the name of the field that you wish to access. Each field has three properties, name, alias and value.

  • name - The name of the field (yes, it is the same as <field name> but is useful for displaying that value so that you don’t have to hardcode it)
  • alias - The alias for the field as reported by ArcGIS. If no alias exists, the name is returned.
  • value - The value for the field.

Logic Operations

Logic operations are used to combine other values in order to see if they are the same or different.

Atelerix implements a standard set of logic operations, each side of a logic operation is passed through the Boolean function before evaluation.

Operations

  • and - &&
  • or - ||

Examples

  • 'true' && true => true
  • true && true => true
  • 5 > 7 && true => false

Math Operations

  • add - +
  • subtract - -
  • multiply - *
  • divide - /

String/Text Operations

  • concatenate - +

Note: When combining different data types, the first value is used as the “primary” type and the second will be converted to that type. For example, this will work (the string is first, and the number can be converted to a string)

  • 'hello number ' + 5 = > 'hello number 5'

But this will not work, the string is second and cannot be converted to a number:

  • 5 + ' goodbye'

however if the second value can be converted to a number:

  • 5 + '5' => 10

Things will work out just fine!

The Technical details

When combining different data types, the first value is used as the result type, the second value is passed through the appropriate data type function to convert it to that type. So the expression:

5 + '5'

is equivalent to:

5 + number('5')

which will yield the value 10.

However if the first value is a string:

'5' + 5

is equivalent to:

'5' + text(5)

which will yield the string 55.

This is true for all data types, not just numbers and strings, although numbers and strings are probably the most common types to combine. If in doubt, you can convert anything to text using the text() function.

Examples

  • 'hello' + ' ' + 'world' => 'hello world'

Math Comparison Operations

  • Less than - <
  • Greater than - >
  • Less than or Equal to - <=
  • Greater than or Equal to - >=

Equality Operation

  • Equal to - ==
  • Not equal to = !=

Statements and Semicolons

Atelerix requires that each statement end in a semicolon. The only exception to this is the if statement.

Note: there are other exceptions as well, if the application is only using single expressions, the semicolon may be optional, like in Infomaptic.

Comments

Atelrix supports both single line and multi-line comments using the standard double slash notation:

//this is a single line comments

/*
This is a multi 
line comment
*/

Variable

Atelerix supports storing data in memory using variables. This data may be injected at runtime by a parent application or may be created within Atelerix.

Note: new variables can only be created when executing a code block, variables may not be created where only a single line is being executed.

Atelerix uses the keyword var to instantiate a new variable.

Declaring a new variable 

var myVariableName = 'hello world';

Setting an existing variable

In this case a variable is created with one type, but the type is changed by setting a new value. Atelerix automatically understands this.

var myVariable = 5;
myVariable = 'new value';

Functions

In Atelerix functions are just variables, you define them using a pretty common “fat arrow” syntax, like this:

var myfunction = (param) => {
    // do something
    return param + 1;
}

This function takes in a single parameter (you may have as many as you want, they should just be comma separated). Functions do not have to return values, but the can.

Literals

Atelerix supports numeric, boolean and string literals. A boolean may be either true or false. A number can be any combination of numerals and a single decimal, like:

  • 8
  • 0.8
  • .8
  • 8.0 All numerics as treated as decimals and math will be executed using a c# decimal type, basically math will be done the way you expect it to be done if you were doing it by hand.

Strings may be enclosed in double quotes: ", quotes or other special characters may be escaped using a single backslash \. A single backslash may also be used to create a multi line string, for example:

var test = "this string \
contains an enter";

Will create a string that has a new line character after the space and before the word contains.

You can escape quotes using a slash as well:

var test = "this string contains \" more quotes";

This string will contain a double quote in the middle of the string.

Setting attributes on more complex variables

In some cases, more complex objects may be present and you wish to alter an existing variable on that object.

NOTE: you can not create a new attribute on an existing object, attributes must be defined by the object’s specification, or created at initialization.

data.fieldName.Value = 5;

One-Line If statements (ternary) 

<boolean expression> ? <result if true> : <result if false>

Ternary expressions act as a single line if statement. If expressed in their full form:

function () {
    if (<boolean expression>)
    {
        return <result if true>;
    }
    else 
    {
        return <result if false>;
    }
}

where the function() would take the place of the ternary in-line above.

Ternary expressions make it simple to add logic to a single line evaluation of atelerix but also make it easy to use more complex logic within multi-line applications.

Ternary expressions may be a single line operation, or may be used to set a variable or in a more complex operation.

Ternary expressions may also be nested, but nested ternary expressions must be expressed within parenthesis, for example:

typeof(5) == 'number' ? (5 < 4 ? 'wrong' : 'right') : 'also wrong'

will return the value right since 5 is a number and 5 is actually less than 4. Note the inner ternary is expressed within parenthesis.

Ternary expressions may also be used within functions:

typeof(5 > 4 ? 'a string' : 122)

will return text.

The results, either <result if true> or <result if false>, are not evaluated until after the <boolean expression> and so can be have type-unsafe code within them.

The results of the <boolean expression> are always passed through the Boolean function

An example that tests the type of a variable and returns a formatted version if the variable is a number, otherwise returns the text directly.

TypeOf(variable.name) == 'number' ? Text(variable.name, '0.00' : variable.name)

Standard If Statements

Atelerix also supports standard if statements using the following structure:

if (<expression>) {
    // do this
}
else if (<expression>) {
    // do this instead
}
else {
    //do this if nothing else works
}
  • you can add as many else if clauses as you like
  • the else is optional
  • If statements do not require semicolons.

Import Statements

Atelerix files and packages can be imported using import statements.

Package Import

Additional packages such as json or geometry can be imported into an Atelerix script using import statements.

import json;

Functions within the json packakge will be accessed with dotted expressions such as json.FromString('["one", ["two", "two"]]';.

Package imports can be aliased using the following type of statement

import json as j;

Now the json package can be accessed using the alias. For example: j.FromString('["one", ["two", "two"]]';

File Imports

Atelerix files can be imported and variables within the file accessed. To import an atelerix file, the file name and location must be in quotes and the file must be aliased.

import 'C:\myFile.at' as myFile;

Functions within the variable can be accessed using a dotted expression with the alias such as myFile.myFunction(5);

Variables from the imported file can also be accessed but cannot be reassigned. To access a variable it must be written as a function. For example, if the file contains a variable var temp = 5;, it would be accessed as myFile.temp();.