property height as Int
property board as Board
property head as Square
property body as [Square]

property names List
...
if names is empty List

repeat (loop)

The repeat..end repeat when condition loop is used when you want at least one execution of the enclosed statements followed by a test that chooses either to execute them again or to exit from the loop.

condition is either a Boolean variable or an expression that evaluates to a Boolean value.

If condition is true then the loop ends, if false it resumes. For example:

+repeat call file.writeLine(names[i]) set i to i + 1 end repeat when i is names.length()

set

The set statement is used to assign a new value to an existing variable. The new value must be of the same Type as (or a Type compatible with) that of the variable. A set statement may not assign a new value to a parameter within a procedure unless it the parameter is preceded by out in the parameter list.

throw (exception)

You can deliberately generate, or 'throw', an exception when a specific circumstance is identified, using a throw statement which defines an explanatory string. An example:

+if value > maximum then throw exception "proportion exceeds 100%" else set r to value/maximum*r end if

At runtime, if the condition is met, execution will stop and the Display will show:

A Runtime error occurred in the Elan code
Error: proportion exceeds 100%

This example that puts current values into the exception message string:

+if yp is 0 then throw exception "yp is zero: {xp},{yp} + {xq},{yq}" end if

For the program to retain control when an exception is raised, put the code that may cause the exception into a try statement, where you can catch (i.e. receive) the exception message string, and continue as appropriate.

try (test)

You can test whether another piece of code might throw an exception by wrapping it in a try statement. This might arise when calling a System method that is dependent upon external conditions, for example:

+try call fooprocedureName() print "not caught"expression +catch exception in evariableName print eexpression end try The variable holding the exception (by default named e, but this may be changed by you) is of Type String. You can compare the exception message to one or more expected messages and, if the message does not match an expected exception, you may choose to throw the exception 'up', as in this example: +try call fooprocedureName() print "not caught"expression +catch exception in evariableName +if e isnt "an expected message"condition then throw exception emessage end if end try

variable

The variable statement defines the name to be used to store mutable (i.e. changeable) data. The name defined must be a valid identifier, and the initial value is given by a following expression. For example:

variable notename set to 440expression

while (loop)

The while condition..end while loop is used when you want execution of the enclosed statements to begin only if condition is true.

condition is either a Boolean variable or an expression that evaluates to a Boolean value.

When condition is true the enclosed code is executed; when false the loop is bypassed. For example:

+while not file.endOfFile() print file.readLine() end while

Expressions

One of the most important constructs in programming is the expression. An expression evaluates and returns a value using the following elements:

• Literal value
• Named value
• Operator (including brackets)
• function reference
• lambda

Literal value

A literal value is where a value is written 'literally' in the code, such as 3.142 – in contrast to a value that is referred to by a name.

Here is a table showing some example literal values. Follow the links for more information about each Type.

Type	Example of literal
Int	3
Float	2.0
Boolean	true
String	"Hello"
Tuple	tuple(3, "banana")
List	["lemon", "lime", "orange"]
Dictionary	["a":3, "b":5]
ListImmutable	{"lemon", "lime", "orange"}
DictionaryImmutable	{"a":3, "b":5}

For more about List and Dictionary literals see the Standard (mutable) data structures table.
For more about ListImmutable and DictionaryImmutable literals see the Immutable data structures table.

Indexed values

If a variable is of an indexable Type, then an index or index range may be applied to the variable within an expression. For example:

    variable a set to "Hello World!"
    print a[4]        ⟶ o
    print a[4..]    ⟶ o World!
    print a[..7]    ⟶ Hello W   (since the upper bound of a range is exclusive)
    print a[0..4]  ⟶ Hell         (for the same reason)

In the examples above, the result is of Type String in all cases.

When using indexing on other Types:

• with a single index, the result is of the same Type as the elements of the data structure being indexed
• with an index range, the result is of the same Type as the data structure itself

Indexable Types are String, Array, Array2D, List, Dictionary, ListImmutable and DictionaryImmutable.

Index ranges cannot be applied to Dictionary or DictionaryImmutable.

If the index values in a range are equal, or the second is smaller than the first, then an empty data structure of the correct Type is generated.

Unlike in many languages, indexes in Elan (whether, single, multiple, or a range) are only ever used for reading values. Writing a value to a specific index location is done through a method such as in these examples:

    put           on a   List
    withPut   on a    ListImmutable
    put           on a    Dictionary
    withPut   on a    DictionaryImmutable

Operators

Arithmetic operators

Arithmetic operators can be applied to Float or Int arguments. The result may be a Float or an Int depending on the arguments.

For the ^ + − * operators, the result is a Float if either of the arguments is a Float, and an Int if both arguments are Int.

For the / operator, the result is always a Float. It can be converted to an Int using standalone function floor.

The operator mod is applied only to Int arguments, and the result is Int.

The operator div is deprecated (as of v1.8.0). The recommended coding pattern for integer division is to use regular division and the standalone function floor.

    2^3             ⟶  8
    2/3             ⟶  0.666..
    2*3             ⟶  6
    2 + 3         ⟶  5
    2 − 3         ⟶  −6
    11 mod 3   ⟶  2 (integer remainder)
    11 div 3   ⟶  3 (integer division) is deprecated, use instead:
    (11/3).floor()    ⟶  3, and note that rounding is always down:
    (-11/3).floor()   ⟶ −4

Arithmetic operators follow the conventional rules for precedence i.e. 'BIDMAS' (or 'BODMAS').

When combining mod with other operators in an expression, insert brackets to avoid ambiguity e.g.:

    (5 + 6) mod 3

Note that mod is more of a remainder operator than a modulus operator. The result takes the sign of the first argument. If both arguments are positive, there is no difference.

The minus sign may also be used as a unary operator, and this takes precedence over binary operators so:

    2*−3           ⟶  −6

The editor automatically puts spaces around the operators + and −, but not around ^, / or *. This is just to visually reinforce the precedence.

The + operator is also used for concatenating String values.

The editor automatically inserts spaces around the + and – binary operators, but not around ^, / or *. This is just to visually reinforce the precedence.

The + operator is also used for concatenating Strings. See String.

Logical operators

Logical operators are applied to Boolean arguments and return a Boolean result.

and and or are binary operators
not is a unary operator.

The operator precedence is not → and → or, so this example, which implements an 'exclusive or', need not use brackets and can rely on the operator precedence:

+function xorname(a as Boolean, b as Booleanparameter definitions) returns BooleanType return a and not b or b and not aexpression end function

Equality testing

Equality testing uses the is and isnt keywords with two arguments. The arguments may be of any Type.

• a is b returns true, if a and b are both of the same Type and their values are equal. The only exception is that if one argument is of Type Float and the other is of Type Int, then is will return true if their values are the same, i.e. are the same whole number.
• isnt returns the opposite of is.
• Where a binary operator is expected, as soon as you type is the editor will automatically insert a space after it. To enter isnt you need to delete the space (using the Backspace key) and then type nt.

Note that in Elan equality testing is always 'equality by value'; there is no such thing as 'equality by reference'.

If the items being compared are composite Types, the elements within them are compared sequentially to see if the objects are equal. For example two distinct instances of the same class compare equal if the values of all their properties compare equal. And two Lists compare equal if they contain the same elements in the same order.

The compiler rejects any attempt to compare instances of different classes unless abstract classes and inheritance are involved. Two instances which are subclasses of the same abstract class compare equal only if they are of the same class (and have the same property values).

Numeric comparison

The numeric comparison operators are:

    >         for     greater than
    <         for     less than
    >=        for     greater than or equal to
    <=        for     less than or equal to

Each is applied to two arguments of Type Float, but any named value or expression that evaluates to an Int may always be used where a Float is expected.

Notes

• These operators cannot be applied to strings. Use the dot methods isBefore and isAfter to compare strings alphabetically. See Dot methods on a String.
• Where a binary operator is expected, as soon as you type < or > the editor will automatically insert a space after it. To enter <= or >= you need to delete the space (using the Backspace key) and then type =.

Combining operators

You can combine operators of different kinds, e.g. combining numeric comparison with logical operators in a single expression. However the rules of precedence between operators of different kinds are complex. It is strongly recommend that you always use brackets to disambiguate such expressions, for example:

(a > b) and (b < c)expression
(a + b) > (c - d)expression

Function reference

An expression may simply be a reference to a function, or it may include several function references within it. Examples: print sinDeg(30)expression variable xname set to sinDeg(30)^2 + cosDeg(30)^2expression variable namename set to inputString("Your name")expression print name.upperCase()expression

Notes

• The third example above is not strictly a function call, but is a 'system method' call. System methods may be used only within the main routine or a procedure, because they have external dependencies or side effects.
• In the fourth example, upperCase is a dot method that may be applied to any instance (variable or literal) of Type String. See Dot methods on a String.

lambda

A lambda is a lightweight means to define a function 'in line'. You typically define a lambda:

• If the functionality it defines is needed in only one location: typically for a particular call to a Higher-order Function (HoF).
• If you need to capture a local variable in the implementation. This is called 'closing around a variable'.

The syntax for a lambda is as follows:

• Start with the keyword lambda.
• Parameter definitions, comma-separated, follow the same form as parameter definitions in a function or procedure, but without surrounding brackets.
• The => symbol, which is usually articulated as 'returns', 'yields' or even 'fat arrow'.
• An expression that makes use of the parameters, and may also make use of other variables that are in scope.

Example: +function liveNeighboursname(cells as List<of Boolean>, c as Intparameter definitions) returns IntType let neighboursname be neighbourCells(c)expression let livename be neighbours.filter(lambda i as Int => cells[i])expression return live.length()expression end function Notes:

• Although a lambda is commonly defined 'inline' (as shown above) it is possible to assign a lambda to a variable and hence to reuse it within the scope of that variable.

if expression

The if expression has a similar structure to the if statement, but is an expression that returns a value.

• The conditions are Boolean values or expressions.
• It specifies which of several expressions is to be evaluated to give the returned value.
• else if and else clauses are optional.
• You can add as many else if clauses as you wish, but only one unconditional else which, if present, must be last.
• Though structured like the if statement, it is edited in one field rather than in separate frames. On moving away from editing an if expression, it is automatically reformatted to be similar to an if statement, though without indentation. This means that an if expression should usually be kept simple.
• An if expression may be used within an if expression but will be hard to read even if it is enclosed in brackets.

new

A 'new instance' expression is used to create a new instance of a library data structure, or a user-defined class or record – either to assign to a named value, or as part of a more complex expression. Example of use from demo program snake_PP.elan:

let blocksname be new Array2D<of Int>(40, 30, white)expression

Where the new instance is of a user-defined class or record the expression may optionally be followed by a with clause in order to specify any property values. Example of this use:

+function dealCard(random as Float) returns Card let number be (random*52).floor() let rank be rankValue.keys()[(number/4).floor()] let suit be number mod 4 return new Card() with
rank set to rank,
suit set to suitexpression end function

copy..with

A copy..with expression is used to make a copy of an existing instance, but with a different value for one or more of the properties – either to assign to a named value, or as part of a more complex expression.

It is used extensively within functional programming where you are dealing with records or other immutable Types. Example of use in this manner, taken from demo program snake_FP.elan:

+function newApplename(g as Gameparameter definitions) returns GameType let x, rnd2name be g.rnd.nextInt(0, 39)expression let y, rnd3name be rnd2.nextInt(0, 29)expression let apple2name be newSquare(x, y)expression let g2name be copy g with
apple set to apple2,
rnd set to rnd3expression return if bodyOverlaps(g2, apple2) then newApple(g2)
else g2expression end function

copy..with may also be used in object-oriented programming with instances of regular (mutable) classes. Also, note that a with clause (following the same syntax as in a copy..with expression), may be used within a new instance expression to set up properties for the object not specified in the constructor.

empty

An 'empty of Type' expression is used to make the default (empty) instance of any Type – usually only created for comparing to another instance to test whether that other instance is also empty or default. This may arise, for example, if a class or record is defined with a property that has never had a value assigned to it. The following example is taken from demo program pathfinder.elan:

+procedure visitNextPointname(parameter definitionsparameter definitions) call updateNeighboursprocedureName() set property.currentvariableName to nextNodeToVisit()expression +if (property.current is empty Node) or (property.current.point is property.destination)condition then set property.runningvariableName to falseexpression else if call property.current.setVisitedprocedureName(truearguments) end if end procedure

It is also possible explicitly to set a property or a named value to an empty instance of the appropriate Type.

Comments

# comment

A comment is not an instruction: it is ignored by the compiler and does not change how the program works. Rather, a comment contains information about the program, intended to be read by a person seeking to understand or modify the code.

Every comment starts with the hash symbol # followed by some text or a blank line. The text field in a comment may contain any text, except that it must not start with the open square bracket symbol [.

Comments may be inserted at any level: in the Global, Member, or Statement instruction levels, as well as from the new code prompt – every prompt provides a # for entering a comment.

Every Elan program has a single comment at the top of the file, which is generated by the system and cannot be edited or deleted by the user. This comment is known as the 'file header' and shows the version of Elan being run.

Compile errors and warnings

Q: What is the difference between a compile error and a warning.

A: A warning usually indicates that the fix may involve adding some more code, for example adding a definition for an unknown identifier. An error usually indicates that you will need to alter code to fix the error. But they are similar in that you will not be able to run your program until the issues are fixed. In all programming languages it is a good practice 'treat all compile warnings as errors' i.e. fix them as soon as you see them appear.

Messages

Expression must be ...

An expression, when evaluated, results in a value of a Type that is not compatible with its 'target', for example: if the result of the expression is being assigned to an existing variable, or if an expression is defined 'inline' as an argument into a method call.

Cannot use 'this' outside class context

The keyword this may only be used within an instance method on a class to refer to the current instance.

Abstract Class ... must be declared before it is used

If a class inherits from one or more abstract classes, then the latter must all have already been declared (defined) earlier in the code file.

Member ... must be of type ...

This error occurs when a class is defined as inheriting from an abstract class, and has implemented an inherited member (method or property) with the correct name, but with different Types.

Incompatible types. Expected: ... Provided: ...

Cannot determine common type between ... and ...

... is not defined for type ...

Arises when 'dot calling' a member (method or property) that does not exist on the Type of the named value or expression before the dot.

Cannot call a function as a procedure

A function (or function method) is to be used within an expression, not via a call instruction.

Cannot use a system method in a function

A 'system method' (defined in the Standard Library) returns a value like a function does. However, because a system method either makes changes to the system and/or depends on external inputs, it may be used only within a procedure or the main routine.

Code change required ...

Indicates that a library method or class has been changed since the version in which your Elan code was written. The link in the message should take you directly to information in the Library Reference documentation on how to update your code to cope with the change.

Cannot call procedure ... within an expression

A procedure may be used only within a call instruction.

Cannot invoke ... as a method

The code is attempting to use a free-standing method (function or procedure) as a 'dot method' on a named value or the result of an expression.

Cannot ...index ...

An index (in square brackets) may be applied only to certain data structure Types: String, Array, Array2D, List, ListImmutable, Dictionary, and DictionaryImmutable.

Cannot range ...

A range may be applied only to certain data structure Types: String, Array, List, and ListImmutable.

Cannot new ...

The Type specified after the call keyword cannot be instantiated. Either the Type is inapplicable, or it is an abstract class or interface.

Source for 'each' must be an Array, List, or String.

Superclass ... must be inheritable class

A concrete class may inherit from an abstract class, and/or an interface, but not from another concrete class. In Elan, all classes must be either abstract or 'final' – a final class being concrete and not-inheritable.

Superclass ... must be an interface

An interface may inherit from other interfaces, but not from any class.

Class/interface ... cannot inherit from itself

The message is self explanatory.

There must be only one abstract superclass ...

A class may inherit from only one abstract class. However, it may additionally inherit from one or more interfaces.

Cannot reference private member ...

A private member (method or property) may be accessed only by code within the class, or within subclasses of it. It may not be accessed by any code outside the class hierarchy.

... must implement ...

If a concrete class inherits from any abstract class or interface(s) it must implement all abstract methods defined in those Types.

... must be concrete to new

You cannot create an instance of any abstract class or interface: only of a concrete class.

Cannot pass ... as an out parameter

If a parameter of a procedure is marked with out then this means that the parameter may be reassigned within the procedure. Therefore you must pass in a variable that can be re-assigned. You cannot pass in: a constant, a literal value, or a named value that is defined by a let instruction.

Cannot call extension method directly

A method that is defined within the Library as an extension method, such as asString, may be called on a named value or an expression only using dot syntax.

Cannot prefix function with 'property'

The prefix property. may only be used before a property name: not a function name.

Missing argument(s) ...

The method being called expects more arguments than have been provided.

Too many argument(s) ...

A method has been passed more arguments than it expects.

Argument types ...

One or more arguments provided to the method are of the wrong Type.

...<of Type>...

Certain data structure Types, including Array, Array2D, List must specify the Type of their members, for example List<of Int>. Failure to specify the '<of Type>' on these Types will give an error, as will specifying 'of Type' where it is not required. Dictionaries require Types to be specified for both the keys and the values, for example: Dictionary<of String, Float>.

May not re-assign the ...

Attempting to re-assign, or mutate, a named value that may not be re-assigned in the current context.

Name ... not unique in scope ...

Attempting to create an identifier with the same name as one already defined within the same scope.

May not set ... in a function

A property can be re-assigned only within a procedure method, not within a function, because re-assigning a property is a 'side effect'.

The identifier ... is already used for a ... and cannot be re-defined here.

An existing named value may not be defined again within the same scope.

Duplicate Dictionary key(s)

Attempting to define a literal Dictionary or DictionaryImmutable with one or more duplicated keys in the definition.

Library or class function ... cannot be used without brackets

a comment may not start with [ unless it is a recognised compiler directive

Compiler directives are a planned future capability. They will look like comments, but begin with an open square bracket. To avoid the possibility of ambiguity, you may not start your own comments with an open square bracket.

Condition of 'if' expression does not evaluate to a Boolean.

Cannot have any clause after unconditional 'else'.

... is a keyword, and may not be used as an identifier.

An Elan keyword cannot be used to as the name for a value, property, or method. Try shortening the name, lengthening it, or using a different name

For reference, the complete list of keywords is:
#, abstract, and, as, assert, be, call, catch, class, constant, constructor, copy, div, each, else, empty, end, enum, exception, for, from, function, global, if, image, in, inherits, interface, is, isnt, lambda, let, library, main, mod, new, not, of, or, out, print, private, procedure, property, record, ref, repeat, return, returns, set, step, test, then, this, throw, to, try, variable, while, with

... is a reserved word, and may not be used as an identifier.

In addition to Elan keywords there are certain other 'reserved words' that cannot be used to define the name for a value, property, or method.If you encounter this error you may eliminate the error simply by adding more valid characters to the name – for example just by changing case to case_.

Why are there any reserved words that are not Elan keywords? There are three kinds of reserved word:

• Potential keywords that might be added to Elan in future releases.
• Lowercase versions of Elan Type names, such as int, float, string, boolean, array, list, dictionary. It is not considered good practice to use Type names for identifiers: instead you should give each identifier a name that indicates what it does (for a method), or represents (for a named value).
• Words that are keywords in JavaScript (but not in Elan). Elan compiles to JavaScript and use of these words as identifiers could cause errors. (If you are asking, 'Why doesn't the Elan compiler just obfuscate these?' the answer is that we evaluated that option but concluded that it added a lot of complexity – especially in regard to debugging and interaction with the Elan editor – just to eliminate the minor inconvenience of having to extend the word so as to make your identifier distinct.)

For reference, the complete list of reserved words is:
action, arguments, array, async, await, boolean, break, by, byte, case, char, const, continue, curry, debugger, default, delete, dictionary, do, double, eval, export, extends, final, finally, float, goto, ignore, implements, import, instanceof, int, into, list, long, match, namespace, native, null, on, optional, otherwise, package, partial, pattern, protected, public, short, static, string, super, switch, system, synchronized, throws, todo, transient, typeof, void, volatile, var, when, yield

Index cannot be negative.

An index into an array or list cannot have a negative value. If a negative is given in literal form e.g. a[−3] then this will generate a compile error. If you use a named value for an index and it is negative, then this will cause a runtime error.

Cannot do equality operations on Procedures or Functions.

It is not possible to apply comparison operations to functions or procedures as themselves. It is, however, possible to compare the results of two function evaluations. You may see this message because you intended to evaluate a function but forgot to add the brackets after the name.

Property ... is not of an immutable type.

Properties on a record may only be of immutable Types.

... cannot be of mutable type ...

Element Type for a ListImmutable must itself be an immutable Type. Similarly, for an DictionaryImmutable the Types for both the key and the value must be immutable ones.

... cannot have key of type ...

The Type of the key for any dictionary Dictionary must be an immutable Type, and not itself an indexable Type.

No such property ... on record ...

The property name given in the record deconstruction does not match a property on the given Type of record.

Cannot discard in record deconstruction ...

Wrong number of deconstructed variables.

referencing a property requires a prefix.

If you are referring to a property of a class from code defined within the class then the property name must be preceded by property.

'out' parameters are only supported on procedures.

You cannot defined an out parameter in a function (because that would imply the possibility of creating a side effect).

There can only be one 'main' in a program.

Unsupported operation.

You cannot chain two 'unary' operators (those that apply to a single value), such as - or not successively within an expression.

Parameter ... may not have the same name as the method in which it is defined.

A function or procedure named e.g. 'foo' may not define a parameter with that same name.

Field help

'arguments' field in a call instruction

An argument list passed into a function or procedure call, must consist of one or more arguments separated by commas. Each argument may in general be any of:

• A literal value
• A named value
• An expression

In certain very specific contexts, however, some options are disallowed by the compiler.

'computed value' field in an assert instruction

The 'actual' field should be kept as simple as possible, preferably just a named value or a function evaluation. Generally, if you want to use a more complex expression, it is better to evaluate it in a preceding let instruction and then use the named value in the 'actual' field of the assert instruction. Some more complex expressions are permissible, but these two restrictions apply:

• Any expression involving a binary operator such as +, isnt, etc., must have brackets around it.
• You may not use the is operator within the 'actual' field, because the parser will confuse this with the is keyword that is part of the assert instruction.

'variable name' field in a set instruction

The first field in a set instruction most commonly takes the name of an existing variable. It may, however, may also take the following forms:

• Within a class it may take the form property.name to set the property name
• A tuple deconstruction. See Tuple
• A list deconstruction. See List

'comment' field

literal value or data structure in a constant

The value of a constant must be a literal value of a Type that is not mutable. This can be a simple value (e.g. a number or string), or an immutable List or Dictionary.

'values' field in an enum definition

enum values must each be a valid identifier, separated by commas.

'message' field in a throw instruction

An exception message must be either a literal string or a named value holding a string.

expression field - used within multiple instructions

This field expects an expression. For the various forms of expression see Expressions.

identifier field - used within multiple instructions

'if' field in an else clause

'inherits ClassName' field in a class

An inheritance clause, if used, must consist of the keyword inherits followed by a space and then one or more Type names separated by commas.

'name' field in a function or procedure definition

A method name must follow the rules for an identifier.

'parameter definitions' in a function or procedure definition

Each parameter definition takes the form:

name as Type

The name must follow the rules for an identifier.

The Type must follow the rules for a Type.

If more than one parameter is defined, the definitions must be separated by commas.

'procedureName' in a call statement

Valid forms for a procedure call are

• call procedureName()
• call instanceName.procedureMethodName()
• call property.propertyName.procedureMethodName()
• call library.procedureName()

The last one is used only if there is a need to disambiguate between a library procedure and a user-defined (global) procedure with the same name.

'Type' field in a function or property definition

For certain Types the name may be followed by an of clause, for example:

List<of Int>
Dictionary<of String, Int>

'Name' field in a class or enum definition

Type names always begin with a capital letter, optionally followed by letters of either case, numeric digits, or underscore symbols. Nothing else.

'name' field in a let or variable instruction

The definition for a variable or for a let statement is most commonly a simple name. Less commonly, it may take the form of a dconstruction of a List, ListImmutable, Tuple or Record.

Advisory

Code change suggested. Method was deprecated in v7.1.

'div' is deprecated. Recommended code for integer division is e.g. (10/3).floor()

Runtime errors

Messages

Tests timed out and were aborted

An error or infinite loop found in a test. Refer to ghosting tests.

Overly complex expressions

Overly complex expressions – for example involving a sequence of open brackets – can result in very slow parsing. We strongly recommend that you you simplify the contents of this field, for example by breaking out parts of it into separate let statements; otherwise it might become impossible to add more text.

ReferenceError: Cannot access '[name]' before initialization

---

Elan Language Reference go to the top