Instruction Set

This section defines the set of instructions that make up the Elan language, and which form the building blocks for any program.

There are three categories of instruction, which are distinguished where the instructions of that categeory are located within a program:

All instructions are added into a program using the new code 'selectors'.

Comments

Every Elan program has a single comment at the top of the file, which is generated by the system and may not be edited or deleted by the user. This comment is known as the 'header' and gives the version of Elan being run, together with other optional information depending upon your user profile.

Global Instructions

When you navigate to a new code that is at global level (not indented from the left-hand edge of the code pane) you will be shown the set of globals that may be inserted there, for example:

The specific globals offered will depend upon your user profile. The full set of globals is shown here with links to explanations below:

Main method

A file must have a main method if it is intended to be run as program. (You may however develop and test code that does not have a main method, either as a coding exercise or for subsequent use within another program).

The main method defines the start point when a program is run.

The main method does not have to be at the top of the file, but this is a good convention to follow.

There may not be more than one main method in a file – and the global selector (above) will not show the main option when one already exists in the file.

Example:

The main method may delegate work to one or more procedure or function.

Procedure

A procedure is a named piece of behaviour that can define parameters which are given inputs via arguments in a call() statement. Unlike a function, a procedure does not return a value. Also unlike a function, a procedure can have ‘side-effects’: indeed it should have side-effects, otherwise there would be no point in calling it! For this reason the statements within a procedure can:

Procedures are executed within a call statement, for example:

Function

A function is a named piece of behaviour that can define parameters which are given inputs via arguments when reference to the function occurs in an expression. Unlike a procedure, a function returns a value. Also unlike a procedure, a function can have no ‘side-effects’ and may not depend on any System methods. Example of a function:

Parameters

Recursion

Test

Example of a Test:

Testing Float values

When testing Float values it is recommend that you always use the round function to round the computed result to a fixed number of decimal places. This avoids rounding errors and is easier to read:

+test round()optional description1 assert sqrt(2).round(3)computed value is 1.414expected value pass2 end test

Testing for runtime errors

If the expression you are testing causes a runtime error then the error will be displayed in the red fail message:

+test optional description1 let aname be [5, 1, 7]expression2 assert a[0]computed value is 5expected value pass3 assert a[2]computed value is 7expected value pass4 assert a[3]computed value is 0expected value actual: Out of range index: 3 size: 35 end test

If this occurs, mark the tests that you added since the last successful test run with ignore (see below), and then remove the ignores one by one until the cause is identified and can be fixed.

Marking a test with ‘ignore’

It is possible to mark a test with the ignore keyword, by selecting the test frame and then hitting Ctrl-i for example:

+ignore test clockTickoptional description1 let g1name be newGame(new Random())expression2 let g2name be newApple(g1)expression3 let g3name be clockTick(g2, "s")expression4 assert g3.head()computed value is newSquare(22, 16)expected value5 end test

When a test is marked with ignore, that test will not be executed when the tests are run, and its result will be shown as ‘not run’. The overall test status will also show in the ‘warning’ status (amber colour), even if all the tests that did run passed. This is to discourage you from leaving a test marked ignore for long.

The principal reason for marking a test ignore is when either the test code or code in any function being called, would not terminate. This typically means that there is a loop (or a recursive call) with no exit condition, or where the exit condition is never met.

If you do create such code without realising it, then when the tests are executed the test runner will ‘time out’ after a few seconds (most tests will pass in milliseconds), and an error message will be shown on the Console. The test that caused the time-out will automatically then be marked ignore. Your priority should then be to identify the cause of the time-out and attempt to fix it before then restoring the test by selecting the test frame and hitting Ctrl-i, which is a toggle for setting and unsetting an ignore status)

Constant

A constant defines a named value that cannot change.

A constant is always defined at ‘global’ level (directly within a file) and is global in scope. A constant may not be defined within any method. (However, see [missing hyperlink]).

The name of a constant follows the rules for an Identifier.

The value to which a constant is set must be a Literal value, of one of the following Types: Int, Float, Boolean, String, Dictionary, or DictionaryImmutable.

Examples:

(In the last example above, Suit is an Enum).

Enum

An enum – short for ‘ 'enumeration' ’ – is the simplest form of ‘user-defined Type’. It specifies a set of values, each of which is defined as a name, such that a named value of that enum Type must always hold one of those values.

Examples:

Type name

The name given to an enum (see below), which must begin with an upper-case letter, is used as the Type name when passing a value to or from a procedure or function.

Using an enum

The value is specified by the Type name for the specified enum, followed by a dot and the value name, for example:

Notes

Record

A record is a user-defined data structure that is given a Type name – (which must begin with an upper-case letter). The record defines one or more properties, each of which has a name (starting with a lower-case letter) and a Type. The Type of a property may be any simple value Type (as in the example above), or a data structure such , another Type of record (or even the same Type of record).

Note that a record Type has some similarity to a class:

However a record is different from a class in that:

Examples:

Having defined a record Type, such as Game above, you can create as many instances as you wish using the following syntax to specify the values:

Note that you are not required to provide a value for each property because, where a property is not specified in the ‘with clause’ (as above), that property will be given the empty (default) value of the correct Type.

You can then read the values from the properties using ‘dot syntax’ for example:

record Types are immutable: the properties on an instance may not be changed, directly. However, you can easily create another instance that is a copy of the original, with all the same property values except for any specific changes made in another with clause. The newly-minted copy (with changes) must be assigned to a new named value. For example:

This last example shows how you enter the comma-separated with clauses. The earlier examples show how the Editor displays a set of with clauses.

If you want to use one or more existing property values in order to determine a new value, the property name(s) must be prefixed with the name of the instance being copied, for example:

Record deconstruction

A record may be ‘deconstructed’, meaning that its properties are read into separate variables using the same syntax as for deconstructing a Tuple. For example, assuming that Square is a record defined as in the example above then this code:

will read the properties into the four names defined.

Note

Class

See also: Inheritance

A class is a user-defined Type offering far richer capability than an enum.

(A record is in some ways similar to a class but simpler: it defines properties, but has no constructor and no methods. See Working with records).

Definition

Here is an example of class definition, taken from the Snake OOP demo program:

Notes

A class must have:

A class may define:

Using a class

A class is instantiated using the keyword new followed by the class name and brackets, which should enclose the comma-separated arguments required to match the parameters (if any) defined on the constructor for that class. For example (also from the Snake OOP demo):

The created instance may then be used within expressions, like any other variable.

Inheritance

An ordinary class (also known as a 'concrete class') may optionally inherit from just one abstract class but may additionally inherit from any number of interfaces. The concrete class must define for itself a concrete implementation of every abstract member defined in the abstract class or any interfaces that it inherits from, directly or indirectly.

Notes

Abstract Class

See also: Inheritance

An abstract class may not be instantiated (and hence may not define a constructor). It may define concrete members i.e.:

As with a concrete class, any of these members may be made private after the corresponding frame has been added, by selecting that member frame and pressing Ctrl_p.

These concrete members are automatically inherited by any subclass, but they may not be overridden (re-defined) by the subclass. Therefore you should define concrete members only if they are intended to work identically on every subclass.

You may also define abstract methods on an abstract classes i.e. abstract property, abstract function, abstract procedure. Such methods define only the signature of the method, not the implementation (body). Therefore they have no end statement. For example:

If you wish to have several subclasses of an abstract class that share a common implementation for a method, but require that some of the subclasses can define a different implementation, then you should:

Interface

See also: Inheritance

An interface is similar to an abstract class, with the difference that it may define only abstract members. The advantage of using an interface instead of an abstract class is that a concrete class can inherit from multiple interfaces. See Inheritance.

An interface may inherit only from other interfaces.

Important: An interface must not re-declare abstract interfaces that are defined in any interface it inherits from, directly or indirectly.

Member Instructions

When you navigate to a new code that is at member level (located directly within a record, class, abstract class, or interface) you will be shown the set of statements that may be inserted there, for example:

The specific members offered will depend upon the context, and/or upon your user profile. The full set of entries is shown here, with links to explanations below:

Constructor

A concrete class may define a single constructor, which may:

If a class does define a constructor, and the constructor defines any parameters, then when the class is instantiated (using new) then values of the correct types must be provided, for example, if the class Snake defines this constructor:

then it may be instantiated like this:

Property

Examples:

If the property is not initialised within the constructor then it will automatically be given the empty value for that Type. You may test whether a property contains this default value by writing e.g.:
if head is empty Square

Procedure Method

A ‘procedure method’ follows the same syntax and rules as a global procedure. The differences are:

Function Method

A function method follows the same syntax and rules as a global function>. The differences are:

Abstract Property

An abstract property may be defined only on an abstract class. Any concrete sub-class must then implement a concrete (regular) property to match.

Abstract Procedure Method

An abstract procedure method may be defined only on an abstract class. Any concrete sub-class must then implement a concrete (regular) property to match.

Abstract Function Method

An abstract function method may be defined only on an abstract class. Any concrete sub-class must then implement a concrete (regular) property to match.

Statement Instructions

When you navigate to a new code that is at statement level (located within a global or a member instruction) you will be shown the set of statements that may be inserted there, for example:

The specific statements offered will depend upon the context, and/or upon your user profile. The full set of entries is shown here, with links to explanations below:

Assert statement

Procedure Call

Each loop

Else clause

For loop

The loop counter variable does not have to bave been defined in a variable statement.

The three defining values (from, to, and step) must all be integer, positive or negative.

They may be defined by literal integers, variables of Type Int, or expressions that evaluate to an integer.

However, if you require a negative step then the literal value, variable, or expression must start with a negative sign as this is needed at compile time to determine the nature of the exit condition. So if you have a variable s that holds a negative value to be used as the step, then you will need to write something like the following:

If statement

See also if expression

Example1:

Example 2:

Notes

Let statement

Print statement

The simplest way to print is with the print statement. For example

Note

Repeat loop

Set statement

Throw statement

You can deliberately generate, or ‘throw’, an exception when a specific circumstance is identified with a throw statement, for example:

Try statement

Where another piece of code might throw an exception, for example when calling a System method that is dependent upon external conditions, it may be executed within a try statement, for example:

The variable holding the exception (by default named e, but this may be changed by you) is of Type String. You may 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:

Variable statement

While loop

Types defined as part of the language

Int

An integer or whole number, i.e. one that has no fractional component.

Type name

Int

Defining a literal integer

variable meaningOfLife set to 42

Default value

0

Constraints

If either limit is exceeded the number will automatically be represented as a Float, with possible loss of precision.

Notes

Float

A ‘floating-point number’, i.e. a number that may have both integer and fractional parts.

Type name

Defining literal floating-point value

Constraints

Since Elan compiles to JavaScript, the constraints on floating point numbers are those of JavaScript:

For greater detail, refer to the official JavaScript documentation

Notes

A variable that has been defined as being of Type Float may not be passed as an argument into a method that requires an Int, nor as an index into an Array, even if the variable contains no fractional part. However, it may be converted into an Int before passing, using the functions floor() or ceiling():
floor() returns the integer value left by removing any fractional part, and
ceiling() returns the lowest integer greater than the Float value if does have a fractional part.

If you wish to define a variable to be of Type Float but initialise it with an integer value then add .0 on the end of the whole number, for example:
variable a set to 3.0.

Boolean

A Boolean value is either true or false.

Type name

Defining a literal Boolean

variable a set to true

true and false must be written lower-case

Default value

String

A String represents ‘text’ i.e. a sequence of zero or more characters.

Type name

Defining a literal string value

variable a set to "Hello"

Strings are always delineated by double-quotes.

Default value

"", known as ‘the empty string’.

Notes

Strings may be appended to using the plus operator, for example
print "Hello" + " " + "World"

A newline may be inserted within a string as \n, for example:
print "Hello\nWorld"

Interpolated string

Elan strings are automatically interpolated. This means that you may insert the values of variables or simple expressions within a string by enclosing them in curly braces. For example (assuming that the variables a and b are already defined as integers) :
print "{a} times {b} equals {a*b}"

You cannot include the characters ", {, or } directly within a literal string because of their special meanings. Instead, you use the constants quotes, leftBrace and rightBrace respectively:
print "This is double quote mark: " + quotes
Alternatively, you can insert their Unicode codepoints by means of the unicode() standalone function:
print "This is a double quote mark: " + unicode(34)

or

Dot methods on a String

Note: There are no ‘substring’ methods in Elan because you can always use an index range get a substring e.g. s[3..7] gives a string containing the fourth through the eighth characters of string s. See Indexed Value.

returns a new string based on the input with all alpha-characters in upper-case.

returns a new string based on the input with all alpha-characters in lower-case.

takes a single parameter of Type String, and returns a Boolean value indicating whether or not that argument string is contained within the string on which contains was called. Usage:

prints true

returns a new string where all occurrences of the match string are replaced with the replacement string.

returns a new string based on the string on which the method is called, but with all leading and trailing spaces removed.

indexOf(partString as String) returns Int

The following methods are used for comparing strings alphabetically, for example in a sort routine:

returns the Unicode (integer) value for a character. If the string is more than one character long, the Unicode value returned is that for the first character in the string only. Note that the opposite method to create a single-character string from its numeric Unicode value is e.g. unicode(123) which returns "{".

Arrays and Lists

Quick reference

Array

An ‘Array’ is a simple data structure that holds multiple elements of the same Type.

Unlike a List, an Array is mutable, meaning that the elements within the data structure can be altered without creating a new Array from the old.

The Type is specified in the following form:

where, in these examples, String and Int represent the Type of each element in the Arrays. The element Type can be any Type value – Int, Boolean, Float, String – or the name of a specific class such as Player, or an enum such as Direction. It may also be another data structure, including another Array (sometimes referred to as a ‘nested Array’).

Creating an Array

An Array may be defined in ‘literal’ form, ‘delimited’ by square brackets, and with all the required elements separated by commas. The elements may be literal values but must all be of the same Type:

variable fruit set to ["apple", "orange", "pear"]

including ‘nested ’:

variable coordinates set to [[3.4, 0.1, 7.8], [1, 0, 1.5], [10, -1.5, 25]]

or variables (provided they are all of the same Type):

variable values set to [x, y, z]

or a mixture of literal values and variables (all of the same Type):

variable values set to [3.1, y, z]

where y and z are existing variables of Type Float.

You may also define an Array of a specified size, with each element initialised to the same value, for example:

creates an Array of Type String with exactly 20 elements, each initialised to the empty String and:

creates an Array of Type Float with exactly 12 elements, each initialised to 100.0.

Although the resulting Array may still be expanded subsequently (by using the add procedure), the typical use for these two methods is for cases that would originally have used a traditional (fixed-size) array.

Dot methods on an Array

Functions:

myArray.contains(item) returnss true or false

myArray.asList() returnss a List containing the same elements as the Array on which the method was called. This is often used to permit an Array to be passed into a function that has been designed to accept a List.

Procedures:

call fruit.append("banana")
call fruit.appendArray(anotherArray)
call fruit.insertAt(4, "cherry")
call fruit.prepend("melon")
call fruit.putAt(2, "grape")
call fruit.removeAll("apple")
call fruit.removeAt(3)
call fruit.removeFirst("apple")

Using an Array

Elements are read using an index in square brackets, the first element being element [0]. The last element of an Array of size 10 will therefore be accessed by the index [9].

Attempting to read an element by index, where that element does not exist, will result in an ‘Index out of range’ run-time error.

Unlike in many programming languages you may not modify data by index: elements are modified by calling the putAt procedure on the Array.

Try these examples (the last one will produce an error – make sure you understand why):

Unlike in some languages, Elan Arrays may be dynamically extended, using append and prepend methods.

2-dimensional Array

In Elan, as in many languages, a ‘2-dimensional Array’ is just an Array of Arrays. However, Elan provides a couple of convenient short-cut methods for working with such data structures:

However, this is not recommended as subsequently adding elements takes a lot of care and effort. It is recommended that you always use the method createArray2D to create a 2-dimensional Array initialised to the desired size. That way you can modify individual elements in the initialised Array with e.g.:

and you can read individual elements with a double index, for example:

If you want to define a function or procedure with a parameter that should be a 2-dimensional Array, the Type is specified as Array2D, for example:

Creating Arrays of specific sizes

The following methods return an Array of a specified size, and with all elements initialised to a specified value. Although the resulting Array may still be expanded subsequently (by using the add procedure), the typical use for these two methods is for cases that would originally have used a traditional (fixed-size) array:

where Type is one of the following Types: Int, Float, Boolean, String or any Type of enum.

There is also a variant of the method that creates a ‘2-dimensional’ rectangular Array (actually an Array of Arrays):

List

A List is a simple data structure that holds multiple elements of the same Type.

A list, like a String but unlike an Array, is immutable. You can still insert, delete, or change elements in a List, but the methods for these operations do not modify the input List: they return a new List based on the input List but with the specified differences.

Type name

The Type is specified in the following way:

Creating a List

A List may be defined in ‘literal’ form, ‘delimited’ by curly braces, and with all the required elements separated by commas. The elements may be literal values but must all be of the same Type):

Dot methods on a List

The dot methods on a list are all functions.

The following functions all return a new List, copied from the List on which the function was called, but with the differences specified by the function parameters:

Try these examples:

Dictionaries

There are two forms of dictionary in Elan: an ordinary Dictionary (which is mutable) and a DictionaryImmutable (which is not).

Quick reference

Dictionary

Type name

In the following example, the keys are of Type Int, and the values associated with the keys are of Type String:

For both Dictionary and DictionaryImmutable the values can be of any Type, including a specific Type of class, a List, another Dictionary or some other data structure. However, the key’s Type must be one of: Int, Float, String, Boolean, or a specific Type of enum.

Defining a literal

A literal Dictionary is defined as a comma-separated list of ‘key:value pairs’ (key,colon.value) surrounded by square brackets:

Using a Dictionary

Try these examples:

Constraints

Key values must be unique within a Dictionary.

There is no difference in syntax between adding an entry with a new key, and setting a new value for an existing key: if the key does not exist in the dictionary, it will be added.

Dot methods on a Dictionary

See also Quick reference.

DictionaryImmutable

An immutable dictionary may be defined in a constant.

Type name

In the following example, the keys are of Type Int, and the values associated with the keys are of Type String:

Defining a literal

A literal DictionaryImmutable is defined as a comma-separated list of ‘key:value pairs’ (key,colon.value) surrounded by curly braces:

Using an Immutable Dictionary

Try these examples:

Dot methods on an Immutable Dictionary

See also Quick reference.

Tuple

A tuple is a way of holding a small number of values of different Types together as a single reference. They are referred to as 2-tuples, 3-tuples, etc. according to the number of values they hold. Common uses include:

Holding a pair of x and y coordinates (each of Type Float) as a single unit, and

Allowing a function to pass back a result comprised of both a message in a String and a Boolean indicating whether the operation was successful.

A tuple is considered a ‘lightweight’ alternative to defining a specific class for some purposes.

Type name

Written as a comma-separated list of the Type of each member, surrounded by round brackets:

Defining a literal tuple

A tuple is defined, where it is needed, by the keyword tuple and a number of elements, each being a variable or a literal value, separated by commas and surrounded by round brackets, for example:

Using a tuple

You may pass a tuple into a function, or return one from a function, for example:

An existing tuple (for example point1 below) may be ‘deconstructed’ into new variables or named values (where the number of variables/names must match the number of elements in the tuple):

or into existing variables of the correct Type:

The ‘discard’ symbol _ (underscore) may also be used when deconstructing a tuple when there is no need to capture specific elements:

Notes

As in most languages, Elan tuples are immutable. Once defined they are effectively ‘read only’. You cannot alter any of the elements in a tuple nor (unpke a pst for example) can you create a new tuple from an existing one with specified differences.

You cannot deconstruct a tuple into a mixture of new and existing variables.

tuples may be nested: you can define a tuple within a tuple.

Func

A function may be passed as an argument into another function (or a procedure), or returned as the result of calling another function. This pattern is known as ‘Higher order Function’ (HoF), and is a key idea in the functional programming paradigm. To define a function that takes in another function as a parameter, or returns a function, you need to specify the Type of the function, just as you would specify the Type of every parameter and the return Type for the function.

Type name

The Type of any function starts with the word Func followed by angle brackets defining the Type of each parameter, and the return Type for that function, following this syntax:

This example defines the Type for a function that defines three parameters of Type String, String, and Int respectively, and returns a Boolean value. T this Type would match that of a function definition that started:

Expressions

One of the most important constructs in programming is the ‘expression’. An expression is evaluated to return a value. An expression is made up of the following possible elements:

which this chapter describes.

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.

The following data Types may be written as literal values (follow the links to view the form of each literal value):

Named value

A named value is a value that is associated with a name rather than being defined literally in code. There are various kinds of named value:

Constant, let statement, variable statement, Parameter passing, enum statement

Identifier

For all kinds of named values, the name must follow the rules for an ‘identifier’. It must start with a lower-case letter, followed by any combination of lower-case and upper-case letters, numeric digits, and the _ (underscore) symbol. It may not contain spaces or other symbols. Once a named value has been defined, it can be referred to by the name.

Scoping and name qualification

With the exception of a constant (below), which is global in scope, named values are always ‘local’: their scope is confined to the method in which they are defined.

Elan allows local named values to be defined with the same name as a constant, function, or procedure defined at global level or defined in the standard library. In such cases, when the name is used within the same method, then it will refer to the local definition. If you have done this, but then need to access the constant, function, or procedure with the same name, then you can simply prefix the use of the name with a ‘qualifier’ of either global. or library. as appropriate.

Indexed Value

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:

See also: Using an Array, Using a Dictionary

Important: 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:

putAt on an Array
withPutAt on a List
putAtKey on a Dictionary
withPutAtKey on a DictionaryImmutable

Operators

Arithmetic operators

Arithmetic operators can be applied to Float or Int arguments, but the result is always a Float:

2^3 → 8
2/3 → 0.666..
2*3 → 6
2 + 3 → 5
2 - 3 → -1
11 mod 3 → 2 (integer remainder)
11 div 3 → 3 (integer division)

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

Note: When combining div or mod with any other operators within an expression, insert brackets to avoid ambiguity e.g.:

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

2*-3 → -6

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

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.

Example that implements an ‘exclusive or’.

function xor(a as Boolean, b as Boolean) returns Boolean
  return a and not b or b and not a
end Function

Equality testing

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

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

Note

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 variable or expression that evaluates to an Int may always be used where a Float is expected.

Notes

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:

Function call

An expression may simply be a function call, or it may include one or more function calls within it. Examples:

Notes

Lambda

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

The syntax for a lambda is as follows:

Example:

Notes

The following example uses both these techniques within a function:

If expression

The ‘if expression’ is in certain respects similar to an If statement, but with the following differences:

Here are three examples: