<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-GB">
<head>
<meta charset="utf-8" name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="../ide/styles/colourScheme.css">
<link rel="stylesheet" href="../ide/styles/documentation.css">
<link rel="stylesheet" href="../ide/styles/elanStyle.css">
<!-- Font Awesome has link symbols in Unicode Private Use Area) external U+F08E, internal U+F14C -->
<!-- See https://www.w3schools.com/icons/tryit.asp?filename=tryicons_fa-external-link -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<link rel="icon" href="favicon.ico">
<title>Elan Language Reference</title>
<script type="text/javascript" src="generated_toc.js"></script>
<script type="text/javascript" src="doc-scripts.js"></script>
<script type="text/javascript" src="accordion.js"></script>
</head>
<body id="top">
<div class="docTitle">Elan Language Reference</div>
<div id="docTOC">
 <div id="generated-toc" class="generate_from_h1 generate_for_page"></div>
</div>

<h1 id="namedValue">Named values</h1>

<p>In most programming, the term <i><b>variable</b></i> describes a data entity in a program that contains a value and has a name by which you can read and write its value,
 i.e. its value can be varied. In Elan, these data entities are called <b><i>named values</i></b> so that a distinction can be made between:</p>
<ul>
 <li><b><i>mutable named values</i></b> whose content can be assigned and reassigned, e.g. defined with a <b>variable definition</b> instruction and reassigned with a <b>change variable</b> instruction or,
 for standard data structures, there are methods for their update.</li>
 <li><b><i>immutable named values</i></b> whose content is assigned, e.g. with a <b>constant</b> instruction, or a <b>let</b> instruction in a function, and then cannot be reassigned.
 There are, however, methods for copying an immutable named value into another (or even the same) named value with specified changes.</li>
</ul>
<p>This distinction applies both to single values and to data structures (which contain multiple values) and, while it is most pertinent in Functional Programming,
it provides a useful discipline in any code. Preferring immutable named values can help avoid duplication, assist in the modularisation of code and reduce errors.</p>
<p>Both kinds of named value must be initialised with literals, expressions or initialisation methods. The counter variable in a <b>for</b> loop, however, may be used without having been initialised.</p>

<h2 id="Type">Data Types</h2>

<p>There are two fundamentally different kinds of data Type, differing by how their values
are passed around in a running program:</p>
<ul>
 <li><i><b id="ValueType">Value Types</b></i> that contain a single value, and are passed around directly:<br>
 <code>Int</code>, <code>Float</code>, <code>Boolean</code></li>
 <li><i><b id="ReferenceType">Reference Types</b></i> that contain a more complex structure of values, and are passed around by references to them:<br>
 <code>String</code>, <code>List</code>, etc. as well as
 any <b>concrete class</b> pr <b>abstract class</b>.</li>
</ul>

<p>This table lists the value Types and the standard data structure (reference) Types, each linking to its definition and further details:</p>
<table>
 <tr><th>Type group</th><th colspan="3">Value Types</th><th colspan="4">Reference Types</th>
 </tr><tr>
  <td>Value data</td>
  <td><br><a href="LibRef.html#Int"><el-topic>Integer</el-topic><br><code>Int</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#Float"><el-topic>Floating point<br>(Real) number</el-topic><br><code>Float</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#Boolean"><el-topic>Truth<br>value</el-topic><br><code>Boolean</code> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td></td>
  <td></td>
  <td></td>
 </tr><tr>
  <td rowspan="2">Standard<br>data structures</td>
  <td rowspan="2"></td>
  <td rowspan="2"></td>
  <td rowspan="2"></td>
  <td><a href="LibRef.html#String"><el-topic>Character string</el-topic><br><code>String</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#RegExp"><el-topic>Regular expression</el-topic><br><code>RegExp</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#List"><el-topic>List</el-topic><br><code>List</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#Dictionary"><el-topic>Look-up dictionary</el-topic><br><code>Dictionary</code> <i class="fa">&#xf14c;</i></a></td>
 </tr><tr>
  <td><a href="LibRef.html#HashSet"><el-topic>Set</el-topic><br><code>HashSet</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#Stack"><el-topic>LIFO stack</el-topic><br><code>Stack</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#Queue"><el-topic>FIFO queue</el-topic><br><code>Queue</code> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
 </tr><tr>
  <td>Graphics</td>
  <td></td>
  <td></td>
  <td></td>
  <td><a href="LibRef.html#TurtleGraphics"><el-topic>Turtle graphics</el-topic><br><code>Turtle</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#VectorGraphics"><el-topic>SVG vector graphics</el-topic><br><code>LineVG</code><br><code>RectangleVG</code>
  <br><code>CircleVG</code><br><code>ImageVG</code><br><code>RawVG</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="LibRef.html#BlockGraphics"><el-topic>Block graphics<br>(2D array)</el-topic><br><code>List&lt;of List&lt;of Int&gt;&gt;</code> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
 </tr><tr>
  <td>Data I/O</td>
  <td></td>
  <td></td>
  <td></td>
  <td><a href="LibRef.html#TextFileWriter"><el-topic>Text file output</el-topic><br><code>TextFileWriter</code> <i class="fa">&#xf08e;</i></a></td>
  <td><a href="LibRef.html#TextFileReader"><el-topic>Text file input</el-topic><br><code>TextFileReader</code> <i class="fa">&#xf08e;</i></a></td>
  <td></td>
  <td></td>
 </tr><tr>
  <td>User-defined</td>
  <td></td>
  <td></td>
  <td></td>
  <td><a href="#enum"><el-topic>Enumeration</el-topic><br><code>enum</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="#class"><el-topic>Concrete class</el-topic><br><code>class</code> <i class="fa">&#xf14c;</i></a></td>
  <td><a href="#abstract_class"><el-topic>Abstract class</el-topic><br>abstract <code>class</code> <i class="fa">&#xf14c;</i></a></td>
 </tr><tr>
  <td>Other</td>
  <td></td>
  <td></td>
  <td></td>
  <td><a href="LibRef.html#Random"><el-topic>Random number</el-topic><br><code>Random</code> <i class="fa">&#xf08e;</i></a></td>
  <td><a href="#CallByRef"><el-topic>Argument reference</el-topic><br><code>AsRef</code> <i class="fa">&#xf14c;</i></a></td>
<!--  <td><a href="LibRef.html#Func"><el-topic>Function reference</el-topic><br>Func <i class="fa">&#xf08e;</i></a></td> -->
  <td><a href="#Maybe"><el-topic>Optional property</el-topic><br><code>Maybe</code> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  </tr>
</table>

<p>Named values are statically typed: their Type, once defined, cannot be changed. A named value's type is:
<ul>
 <li><i>either</i> automatically inferred from the value of the literal or expression defining a value Type,</li>
 <li><i>or</i> specified in the definition of:
 <ul>
  <li>data structures whose items have a particular Type, e.g. <code>List&lt;of Int&gt;</code></li>
  <li>parameters of functions and procedures</li>
  <li><b>return</b> value of a function</li>
  <li><b>property</b> of an <b>abstract class</b> or <b>concrete class</b></li>
 </ul></li>
</ul>

<h2 id="Mutability">Mutability of named values</h2>

<p>The properties or contents of a named value that is of an immutable type may not be changed directly.
You can, however, create another instance that is a copy of the original
with all the same property values except for specific changes that you want to make.
 The newly-minted copy (with changes) may be assigned either to a new named value, or as a re-definition of the original named value.</p>

<p>This table shows which named values can be reassigned and/or mutated depending on how they were defined:</p>
<table>
 <tr><th colspan="3">define named value</th><th colspan="3">named value</th><th rowspan="2">notes</th></tr>
 <tr><th>with</th><th>as<br>mutable Type</th><th>as<br> immutable Type</th><th>reassign<br>with <b>reassign</b></th><th>mutate</th><th>scope</th></tr>
 <tr><td><a href="#constant"><b>constant</b> <i class="fa">&#xf14c;</i></a></td><td>&#x2718;</td><td>&#x2714;</td><td>&#x2718;</td><td>&#x2718;</td><td>global</td>
  <td>values are assigned only at compile time</td></tr>
 <tr><td><a href="#variable"><b>variable definition</b> <i class="fa">&#xf14c;</i></a></td><td>&#x2714;</td><td>&#x2714;</td><td>&#x2714;</td><td>&#x2714;</td><td>local</td>
  <td>values are assigned during execution</td></tr>
 <tr><td><a href="#Parameter_value">parameter (by value) <i class="fa">&#xf14c;</i></a></td><td>&#x2714;</td><td>&#x2718;</td><td>&#x2718;</td><td>&#x2714;</td><td>local</td>
  <td>formal input argument<br> of <b>function</b>, <b>procedure</b> or <b>lambda</b></td></tr>
 <tr><td><a href="#Parameter_reference">parameter (by reference) <i class="fa">&#xf14c;</i></a></td><td>&#x2714;</td><td>&#x2718;</td><td>&#x2718;</td><td>&#x2718;</td><td>local</td>
  <td>formal input and output argument<br> of <b>function</b>, <b>procedure</b> or <b>lambda</b></td></tr>
</table>

<h2 id="Identifier">Identifiers and type names</h2>

<h3 class="no-TOC">Named value identifier</h3>
<p>The name given to every named value must follow the rules for an <b>identifier</b>:</p>
<ul>
 <li>It must start with either a lowercase letter or an underscore, followed by any combination ot letters (upper- or lowercase), digits and underscore symbols.</li>
 <li>It must not contain spaces or symbols other than underscore.</li>
 <li>It cannot be the same as any language keyword, method or other reserved word. If you happen to choose such a name, an error message will tell you that it cannot be used for an identifier.</li>
 <li>Like all the language's keywords, it is case-sensitive.</li>
 <li>You cannot use two identifiers within the same scope that differ only in case, e.g. <code>varx</code> and <code>varX</code>.</li>
</ul>

<h3 class="no-TOC" id="TypeName">Type name</h3>
<p>Every Type, whether system (e.g. <code>List</code>) or user-defined (e.g. <code>class</code> <el-type>MyClass</el-type>), is named like an identifier but
 with one important difference: its first character must be an uppercase letter. Type names are also case-sensitive.</p>

<div id="global"></div>
<div id="library"></div>
<h2 id="Scope">Scope and name qualification</h2>
<p>'Scope' in the table above refers to where in your code a named value is accessible.
 <a href="#constant">Global <b>constant</b>s <i class="fa">&#xf14c;</i></a> and <a href="#enum"><b>enum</b>s <i class="fa">&#xf14c;</i></a>, being the only values having <i>global</i> scope, can be referenced from anywhere in your program.
 Every other kind of named value is <i>local</i> and restricted to the <b>procedure</b> or <b>function</b> within which it is defined.</p>
<p>Local named values can have the same name as a global <b>constant</b>, <b>function</b>, or <b>procedure</b> (which are all defined at global level or are in the standard library).
 In such cases, when the name is used within the same method, then it will refer to the local definition.</p>

<h2 id="dotSyntax">Dot syntax</h2>
<p>Reference to a named value is in many cases made with <b>dot syntax</b>, also referred to as applying a <b>dot method</b>. Here are its uses:</p>
<ul>
 <li>To apply a function method to a named value, e.g. to obtain the length of <el-type>String</el-type> <el-id>s</el-id> using a library method:<br>
 <code>variable n set to s.length()</code></li>
 <li>To apply a procedure to a named value, e.g. to initialise <code>List</code> <el-id>li</el-id> using a library procedure:<br>
 <code>call li.initialise(10,0)</code></li>
 <li>To refer to the property (<el-id>body</el-id>) of an instance (<el-id>g</el-id>) of class <el-type>Game</el-type> and, in this example, to get the length of the property's current string value, using
 library methods:<br>
 <code>variable bodyGL set to g.body.toString().length()</code></li>
 <li>To extract an item from a Tuple using its special properties <el-id>item_</el-id>N, e.g. to get the first value from a 2-Tuple:<br>
 <code>variable point set to (3, 7)</code><br>
 <code>variable x set to point.item_0</code>
 </li>
 <li>To refer to a 'value' in an <b>enum</b>, e.g.to pick one of the identifiers in the <b>enum</b> <code>Suit</code>:<br>
  <code>enum Suit spades, hearts, diamonds, clubs</code><br>
  <code>variable suit set to Suit.spades</code></li>
</ul>
<p>You cannot use dot syntax with functions and procedures that you define at the global level,
 nor with some system functions (e.g. <el-method>abs</el-method>) and procedures (e.g. <el-method>clearPrintedText</el-method>).</p>

<h1 id="GlobalInstructions">Global instructions</h1>
<p>Global instructions (also referred to as <b>globals</b>) are located <em>directly</em> in your code at the highest level.
They are never indented from the left-hand edge, nor may they be located <em>within</em> other instructions. They are:
 <a href="#main"><b>main</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#procedure"><b>procedure</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#function"><b>function</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#test"><b>test</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#class"><b>concrete class</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#abstract_class"><b>abstract class</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#constant"><b>constant</b> <i class="fa">&#xf14c;</i></a> and
 <a href="#enum"><b>enum</b> <i class="fa">&#xf14c;</i></a>.
</p>
<div id="Method"></div>
<ul>
 <li><b>main</b>, <b>procedure</b> and <b>function</b> are described as <b>methods</b> and these are defined by one or more <a href="#statement">statement instructions <i class="fa">&#xf14c;</i></a> within them.</li>
 <li><b>test</b> also contains instructions, in particular the <a href="#assert"><b>assert</b> equal <i class="fa">&#xf14c;</i></a> instruction for testing functions during development of your program.</li>
 <li><b>concrete class</b> and <b>abstract class</b> define data structures and these always contain <a href="#Member">members <i class="fa">&#xf14c;</i></a>.</li>
 <li><b>constant</b> and <b>enum</b> do not contain any further instructions: only names and values.</li>
 <li>The sequence of global instructions in your code is immaterial, with two exceptions:
  <ul>
   <li>If one <b>constant</b> is used in the definition of another constant, the first must be declared above the second.</li>
   <li>An <b>abstract class</b> must be declared above any <b>concrete class</b> that inherits from it.</li>
  </ul>
</ul>

<h2 id="main"><b>main</b></h2>
<p>A program must have a <b>main</b> method, sometimes called its <b>main</b> routine, if it is intended to be run as a program. You may, however, develop and test code that does not have a <b>main</b> method, either as a coding exercise or for subsequent use within another program.</p>
<p>The <b>main</b> method defines the start point of a program when it is run (executed).</p>
<p>It does not have to be at the top of the file, but this is a good convention to follow.</p>
<p>It may delegate work to one or more <a href="#procedure">procedures <i class="fa">&#xf14c;</i></a> or <a href="#function">functions <i class="fa">&#xf14c;</i></a>.</p>
<p>There may not be more than one <b>main</b> in a program file, and the Global prompt will not show <b>main</b> as an option when one already exists in the file.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example of a <b>main</b> method</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; A <b>main</b> method</p>
<codeblock>
main
  variable li set to [3, 6, 1, 0, 99, 4, 67]
  call inPlaceRippleSort(li)
  print(li)
end main
</codeblock>
<hr>
</div></div>

<h2 id="procedure"><b>procedure</b></h2>
<div id="Parameter_value"></div>
<p id="Argument">A <b>procedure</b> is a named piece of code that may have <b>parameters</b> that are given inputs via <b>arguments</b> in a <a href="#call"><b>call procedure</b> <i class="fa">&#xf14c;</i></a> instruction.</p>
<p>Its name must follow the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>
<p> Unlike a function:</p>
<ul>
 <li>a <b>procedure</b> can have side effects: indeed it <i>should</i> have side effects, otherwise there would be no point in calling it.</li>
 <li>a <b>procedure</b> does not return a value.</li>
 <li>a <b>procedure</b>'s parameter named values (that are mutable) may be changed <i>inside</i> the <b>procedure</b>, but they do not affect the value of arguments in the <b>call procedure</b> instruction outside the <b>procedure</b>.</li>
 <li>to pass a changed parameter back to its calling argument, it must have been called <a href="#CallByRef"><i>by reference</i> <i class="fa">&#xf14c;</i></a>.</li>
</ul>
<p>The instructions within a <b>procedure</b> can therefore:</p>
<ul>
 <li>include calls to other procedures, or to itself if <a href="#recursion">recursion <i class="fa">&#xf14c;</i></a> is required.</li>
 <li>include data input methods and other system functions such as for random number generation.</li>
</ul>
<p>Procedure calls are of two kinds:</p>
<ul>
 <li>to execute an action:<br>
 <code>print(aList)</code></li>
 <li>to apply a <b>procedure</b> to a value using <a href="#dotSyntax">dot syntax <i class="fa">&#xf14c;</i></a>:<br>
 <code>call aList.removeAt(4)</code></li>
</ul>
<p>These calls are to library procedures, but the same options are applicable to the procedures you write.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example of a <b>procedure</b></h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Procedure to order a list of integers:</p>
<codeblock>
procedure inPlaceRippleSort(li as List&lt;of Int&gt;)
  variable hasChanged set to true
  variable lastComp set to li.length() - 2
  while hasChanged is true
    assign hasChanged to false
    for i in range(0, lastComp + 1)
      if li[i] > li[i + 1] then
        variable temp set to li[i]
        assign li[i] to li[i + 1]
        assign li[i + 1] to temp
        assign hasChanged to true
      end if
    end for
    assign lastComp to lastComp - 1
  end while
end procedure
</codeblock>
<hr>
</div></div>

<div id="AsRef"></div>
<div id="set_Ref"></div>
<div id="value_Ref"></div>
<div id="Parameter_reference"></div>
<h3 class="no-TOC" id="CallByRef">Call by reference</h3>
<p>To change the value in named value <el-id>arg</el-id> supplied as an argument in a procedure call, both the call argument and the procedure parameter
must use a reference (or pointer) to it, defined as type <code>AsRef</code>.
This then allows use of the dot methods <el-method>value</el-method> and <el-method>set</el-method> on it to read and change its value, as in this example:
<div class="accordion">
<h4 class="no-TOC acc-title">Example of a call by reference</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; <el-id>argRef</el-id> is a pointer to variable <el-id>arg</el-id> in <b>main</b>,
 so that <el-id>arg</el-id> can be accessed elsewhere <i>by reference</i>:</p>
<codeblock>
main
  variable arg set to "abc"
  variable argRef set to new AsRef&lt;of String&gt;(arg)
  call changeArg(argRef)
  print(argRef.value())
end main
procedure changeArg(pointer as AsRef&lt;of String&gt;)
  variable r set to pointer.value()
  call pointer.set(r.upperCase())
end procedure
</codeblock>
<hr>
</div></div>

<h2 id="function"><b>function</b></h2>
<p>A <b>function</b> is a named piece of code that can define <b>parameters</b> which are given inputs via <b>arguments</b> when reference to the function occurs in an instruction or expression. Its name must follow the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>
<p>Unlike a <a href="#procedure">procedure <i class="fa">&#xf14c;</i></a>:</p>
<ul>
 <li>a function always returns a value.</li>
 <li>a function can have no side effects (i.e. no references outside its code) and cannot depend on any <a href="LibRef.html#SystemMethods">System methods <i class="fa">&#xf08e;</i></a>.</li>
 <li>a function's execution cannot be interrupted by any external event, though a a non-terminating loop in a function may be detected with tests that <a href="#ignore">time out <i class="fa">&#xf14c;</i></a>.</li>
</ul>
<p id="returns">A function definition is comprised of its unique name and, in brackets, its input parameters with their Types, followed by <code>returns</code>,
and the type of the value that will be returned.</p>
<p id="return">
A <b>return</b> instruction is automatically added as the last instruction of a function (since a function <i>must</i> return a value),
and there can be only one <b>return</b> instruction in a function.
You follow the <b>return</b> instruction with the value to be returned by the function.
This may be an expression that will be evaluated before returning.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples of <b>function</b>s</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Function to search a list of strings:</p>
<codeblock>
function binarySearch(li as List&lt;of String&gt;, item as String) returns Boolean
  variable result set to false
  if li.length() > 0 then
    variable mid set to divAsInt(li.length(), 2)
    variable value set to li[mid]
    if item.equals(value) then
      assign result to true
    elif item.isBefore(value) then
      assign result to binarySearch(li.subList(0, mid), item)
    else
      assign result to binarySearch(li.subList(mid + 1, li.length()), item)
    end if
  end if
  return result
end function
</codeblock>
<hr>
<p>&nbsp;&nbsp;&nbsp;&#x25cf; A function definition and reference to it:</p>
<codeblock>
function score(g as Game) returns Int
  return g.body.length() - 2
end function
main
  variable g set to new Game()
  print(score(g))
end main
</codeblock>
<hr>
</div></div>

<h3 class="no-TOC" id="recursion">Recursion</h3>
<p>Procedures and functions may be called or referenced recursively, as in this simple factorial calculation:</p>
<codeblock>
function factorial(n as Int) returns Int
  return (if_(n > 1, n*factorial(n - 1), 1))
end function
</codeblock>

<h2 id="test"><b>test</b></h2>
<p>A <b>test</b> instruction is at the global level, and consists of a set of assertions about the outputs of functions.</p>
<p>Without having to run your program, the <b>assert</b> equal instructions show whether your assertions pass or fail.

<div class="accordion">
<h4 class="no-TOC acc-title">Example of a set of <b>assert</b> equal instructions that test a <b>function</b></h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Test function <el-method>binarySearch</el-method> on four test lists</p>
<codeblock>
test test_binarySearch
  variable li1 set to ["lemon", "lime", "orange"]
  assert binarySearch(li1, "lemon") is true
  assert binarySearch(li1, "lime") is true
  assert binarySearch(li1, "orange") is true
  assert binarySearch(li1, "pear") is false
  variable li2 set to ["lemon", "orange"]
  assert binarySearch(li2, "lemon") is true
  assert binarySearch(li2, "orange") is true
  assert binarySearch(li2, "pear") is false
  variable li3 set to ["lemon"]
  assert binarySearch(li3, "lemon") is true
  assert binarySearch(li3, "lime") is false
  variable li4 set to new List&lt;of String&gt;()
  assert binarySearch(li4, "pear") is false
end test
</codeblock>
<hr>
</div></div>

<h4 class="no-TOC">Notes</h4>
<ul>
 <li>Elan tests are designed to test functions only. It is not possible to call a <b>procedure</b> or <b>main</b> routine within a test.
  Nor is it possible to use any <a href="LibRef.html#SystemMethods">System method <i class="fa">&#xf08e;</i></a> (the same rule as for a function).</li>
 <li>A test may optionally be given a name or description in free-form text, just like a comment, which plays no role in the execution of the test.
 You might give the test the same name as a function that it is testing, or you might describe a particular scenario that is being tested.</li>
 <li><b>test</b> instructions may be written anywhere in the code, provided they are at the global level. </li>
 <li>A <b>test</b> instruction may contain any number of <b>assert</b> equal instructions. The test runner is part of the IDE and it automatically attempts to run all <b>assert</b> equal instructions showing each one's pass or fail outcome alongside. However, if the test hits a runtime error (as distinct from an <b>assert</b> equal failure) then execution of the test will stop and remaining <b>assert</b> equals will be shown as 'not run'.</li>
 <li>In addition to <b>assert</b> equal instructions, a <b>test</b> may contain any other instructions that may be added into a <b>function</b>.</li>
 <li>All <b>assert</b> equal statements should be at the top level within the <b>test</b> instruction; none may be put into a loop structure.</li>
</ul>

<h3 class="no-TOC">Testing <code>Float</code> values</h3>
<p>When testing <code>Float</code> values it is recommend that you use the <el-method>round</el-method> method to round the computed result to a fixed number of decimal places. This avoids rounding errors and is easier to read. For example:</p>

<codeblock>
test test_round
  assert sqrt(2).round(3) is 1.414
end test
</codeblock>

<h3 class="no-TOC">Testing for runtime errors</h3>
<p>If the expression you are testing would cause a runtime error then the error will be displayed in the red fail message:</p>
<p>If there are failures, mark the tests that you added since the last successful test as <a href="IDENavigation.html#EditInstructions"><code>ghosted</code> <i class="fa">&#xf08e;</i></a> and then remove their ghosted status one by one until the cause is identified and fixed.</p>
<codeblock>
test test_list
  variable a set to [5, 1, 7]
  assert a[0] is 5
  assert a[2] is 7
end test
</codeblock>

<p>This <b>assert</b> shows how testing can also be done against an expected error message:</p>
<codeblock>
test test_message
  variable a set to [5, 1, 7]
  assert a[4] is 0
  assert a[4] is "Out of range index: 4 size: 3"
end test
</codeblock>

<h3 class="no-TOC" >Testing long strings</h3>
<p>If you have a test that compares strings longer than 20 characters, any test failure message will be reduced to reporting the
 <i>first</i> character at which the actual (computed) and expected strings differ.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example of testing long strings</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Reporting the first character at which the actual (computed) and expected strings differ:</p>

<codeblock>
constant sGW set to "grid { display: flex; flex-direction: column; margin-top: 40px; width: 500px; } word { display: flex; flex-direction: row; margin: auto; }"
function setInStyle(s as String) returns String
  return "&lt;style&gt;" + s + "&lt;style&gt;"
end function
test test_setInStyle
  assert setInStyle(sGW) is "&lt;style&gt;" + sGW + "&lt;style&gt;"
  # assert fail message will be "s found at [146] {expected: /)"
end test
</codeblock>
<hr>
</div></div>

<h3 class="no-TOC" id="ignore">Ignoring tests</h3>
<p>To ignore tests, use <a href="IDENavigation.html#EditInstructions"><code>ghosting</code> <i class="fa">&#xf08e;</i></a>.</p>
<p>Even when <b>test</b>s or <b>assert</b> equals are <code>ghosted</code>, all the tests will be run and their status shown, but
the overall test status will show the status of only the unghosted tests (green <b>pass</b>, amber <b>warning</b> or red <b>fail</b>).</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples of ghosting tests</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Ghosting an entire test:</p>

<codeblock>
[ghosted] test test_overApple
  variable g1 set to new Game(new Random())
  variable g2 set to g1.withApple(new Square(23, 15))
  assert headOverApple(g2) is false
  variable g3 set to g2.withHead(new Square(23, 15))
  assert headOverApple(g3) is true
end test
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; Ghosting an assert:</p>

<codeblock>
test test_overApple
  variable g1 set to new Game(new Random())
  variable g2 set to g1.withApple(new Square(23, 15))
  [ghosted] assert headOverApple(g2) is true
  variable g3 set to g2.withHead(new Square(23, 15))
  assert headOverApple(g3) is true
end test
</codeblock>
<hr>
</div></div>

<h3 class="no-TOC">Non-terminating loops and recursion</h3>
<p>The principal reason for ghosting a test is when either the test code, or code in any function being called, does 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.</p>
<p>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 appear. Your priority should then be to identify the cause of the timeout and attempt to fix it before then unghosting the <code>test</code>.</p>

<h2 id="class"><b>concrete class</b></h2>
<p>A <b>concrete class</b> is a user-defined type offering richer capability than an <a href="#enum"><b>enum</b> <i class="fa">&#xf14c;</i></a>.</p>
<p>Like any other type its name must begin with an uppercase letter.</p>

<h3 class="no-TOC">Defining a concrete class</h3>
<p>A <b>concrete class</b> is instantiated using the <b>concrete class</b> instruction followed by the class name, and optional <b>inherits</b> to refer to a <b>menu option class</b> or <b>abstract class</b> defined above in the program.</p>
<p>A class definition must include properties, a <b>constructor</b> and at least one method called <el-method>toString</el-method>.</p>
<p>Its properties must all be initialised in the <b>constructor</b>.</p>
<p>It may contain functions and procedure methods.</p>
<p>The <b>constructor</b> may optionally define parameters to force the calling code to provide initial values.</p>
<p> Code in the constructor may make use of any functions, and follows the same constraints as a <b>function</b> (i.e. it may not call any <b>procedure</b>, whether defined in the <b>class</b> or outside).</p>
<p>A simple demonstration of a concrete class is:</p>
<codeblock>
main
  variable x set to new Thing()
  print(x)
  print(x.names.toString())
end main
class Thing
  property names as List&lt;of String&gt;
  constructor()
    assign this.names to createPopulatedList(6, "X")
  end constructor
  function toString() returns String
    return "instance of class Thing"
  end function
end class
</codeblock>

<p>Here is an example of <b>concrete class</b> definition taken from demo program <b>snake - object-oriented</b>:</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example definition of a <b>concrete class</b></h4>
<div class="acc-body">

<p>&nbsp;&nbsp;&nbsp;&#x25cf; Apple:</p>
<codeblock>
class Apple
  constructor()
    assign this.location to new Square(0, 0)
  end constructor
  function toString() returns String
    return ""
  end function
  property location as Square
  procedure newRandomPosition(snake as Snake)
    variable changePosition set to true
    while changePosition
      variable ranX set to randint(0, 39)
      variable ranY set to randint(0, 29)
      assign this.location to new Square(ranX, ranY)
      if not snake.bodyCovers(this.location) then
        assign changePosition to false
      end if
    end while
  end procedure
  procedure updateBlocks(blocks as List&lt;of List&lt;of Int&gt;&gt;)
    assign blocks[this.location.x][this.location.y] to red
  end procedure
end class
</codeblock>
<hr>
</div></div>

<h3 class="no-TOC" id="this"><b>this</b></h3>
<p>If in the code of <code>class</code> <el-type>A</el-type> you want to invoke a method in <code>class</code> <el-type>S</el-type> <i>and</i> pass to it the current instance of <el-type>A</el-type>,
you can refer to this instance with <code>this</code>, as shown by this line in demo program <b>Snake - object-oriented</b>:</p>
<code> call apple.newRandomPosition(this)</code>

<p>Here, method <el-method>newRandomPosition</el-method> is defined on class <code>Apple</code> which needs to be passed an instance of class <code>Snake</code>,
<el-id>apple</el-id> being an instance of class <code>Apple</code>.</p>

<h3 class="no-TOC" id="inherits"><b>inherits</b></h3>
<p>A <a href="#class">concrete class <i class="fa">&#xf14c;</i></a> (often referred to simply as a class) 
  may optionally inherit from just one <a href="#abstract_class"><b>abstract class</b><i class="fa">&#xf14c;</i></a>.
 The concrete class must define for itself a concrete implementation of every <em>abstract</em> member defined in the <b>abstract class</b> that it inherits from, directly or indirectly.</p>

<h4 class="no-TOC">Notes</h4>
<ul>
  <li>An <b>abstract class</b> must be declared in the code above any class that inherits from it.</li>
  <li>You cannot override any concrete member defined in an abstract class.</li>
  <li>Inheritance hierarchies must form a tree, that is you must avoid creating a circular dependency where, for example, type <el-type>A</el-type> inherits from type <el-type>B</el-type>, which inherits from type <code> C</code>, which inherits from type <code>A</code>.</li>
</ul>

<h2 id="abstract_class"><b>abstract class</b></h2>
<p>An <b>abstract class</b> may not be instantiated (and hence may not define a constructor). It may define these concrete members:</p>
<ul>
<li>a <b>property</b> </li>
<li>a <b>function</b></li>
<li>a <b>procedure</b></li>
</ul>
<p>As with a <b>concrete class</b>, any of these members may be made <code>private</code>, after the corresponding instruction has been added, by selecting that member instruction and keying <b>Ctrl+p</b>.</p>
<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.</p>

<p>You may also define abstract methods on an <b>abstract class</b>, i.e. <b>abstract property</b>, <b>abstract function</b>, <b>abstract procedure</b>. Such methods define only the signature of the method, not the implementation (body), therefore they have no <code>end</code> instruction. For example:</p>
<codeblock>
function calculateDiscount(a as Float, d as Float) returns Float
  let discount be a*d
return discount
</codeblock>

<p>If you wish to have several subclasses of an <b>abstract class</b> that share a common implementation for a method, but require that some of the subclasses can define a different implementation, then you should:</p>
<ul>
<li>Define the method as <b>abstract</b> on the superclass.</li>
<li>Define a concrete implementation on the superclass with a similar, but slightly different, name e.g. by adding a prefix such as: <code>default</code>.</li>
<li>Each subclass must then define its implementation of the abstract method, but the ones needing a common implementation can be just one line, delegating responsibility up to the 'default' method on the superclass. </li>
</ul>

<h2 id="constant"><b>constant</b> </h2>
<p>A <b>constant</b> instruction defines a named value that is defined at the global level in a program, is global in scope and cannot be changed.
 Its name follows the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>
<p>A <b>constant</b> is defined by a literal of a value Type, namely <code>Int</code>, <code>Float</code>, <code>Boolean</code> or
 <code>String</code>.</p>
<p>Constants are created at compile time, so cannot be defined with reference to any function, nor can they use any operators in an expression.</p>
<p>A constant can be defined by reference to a previously defined constant or to a system constant,
 but take care not to re-define a <a href="LibRef.html#Constants">system constant <i class="fa">&#xf08e;</i></a> such as <el-id>pi</el-id> or <el-id>blue</el-id> without good reason.</p>
<p>A 'constant' data structure can be defined by using a <b>function</b> which is then referenced from wherever needed.
 See <a href="#constantStructure">Constant data structures <i class="fa">&#xf14c;</i></a>.</p>

<p>Examples of literal definitions of the valid Types of constant:</p>

<codeblock>
constant maxHits set to 10
constant turquoise set to 0x00ced1
constant liveCell set to black
constant speedOfLight set to 299792.458
constant gameOver set to true
constant euro set to 0x20ac
constant warningMsg set to "Limit reached"
</codeblock>

<h3 class="no-TOC" id="constantStructure">Constant data structures</h3>
<p>To use a data structure that is to be a constant in your program, you define it as the value of a <b>function</b>
which cam then be referenced from anywhere in the program, often from within an expression.</p>
<p>These examples define a constant <code>List</code> and a constant <code>Dictionary</code> of colours which
are indexable:</p>

<codeblock>
main
  call print ($"{rainbow()[0]} is violet")
  call print ($"{suitColours()["hearts"]} is red")
end main
function rainbow() returns List&lt;of Int&gt;
  return [0x9400D3, 0x4B0082, 0x0000CD, 0x008000, 0xFFFF00, 0xFFA500, 0xFF0000]
end function
function suitColours() returns Dictionary&lt;of String, Int&gt;
  return ["spades":black, "hearts":red, "diamonds":red, "clubs":black]
end function
</codeblock>

<h3 class="no-TOC">System constants</h3>
Some useful constants are provided: see <a href="LibRef.html#systemConstants">System constants <i class="fa">&#xf08e;</i></a> 

<div id="enumValue"></div>
<h2 id="enum"><b>enum</b></h2>
<p>An <b>enum</b> &ndash; short for 'enumeration' &ndash; provides for the simplest form of user-defined Type.
It is used to provide a fixed set of options that are self-explanatory, and the references to its
those options (its 'values') are checked at compile time.</p>
<p>You define an <b>enum</b> with a type name (so starting with an uppercase letter) followed by a
number of 'values' (separated by commas) which must all be valid <a href="#Identifier">identifiers <i class="fa">&#xf14c;</i></a>.</p>
<p>A reference to an <b>enum</b> by its type name necessarily holds one of the 'values'.</p>
<p>Reference to the value in an <b>enum</b> is made by using <a href="#dotSyntax">dot syntax <i class="fa">&#xf14c;</i></a> with method <el-method>enumValue</el-method>.</p>
<p>An <b>enum</b> is read-only: once it has been defined it is not possible to add, remove, or update its values.</p>
<p>Examples of <b>enum</b> definitions:</p>
<codeblock>
enum Suit spades, hearts, diamonds, clubs
enum Outcome undecided, win, lose, draw, winDouble
</codeblock>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples using <b>enum</b></h4>
<div class="acc-body">

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To retrieve a valid 'value':</p>
<codeblock>
enum Status pending, playing, standing, blackjack, bust
main
  variable state set to Status.pending
end main
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To get a valid option from an abbreviation (in demo program pathfinder.elan):</p>
<codeblock>
enum Algorithm dijkstra, aStar, heuristic
function getAlgFromLetter(letter as String) returns Algorithm
  variable algs set to ["a":Algorithm.aStar, "d":Algorithm.dijkstra, "h":Algorithm.heuristic]
  return algs[letter]
end function
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; A function to turn directions held in an <b>enum</b> through 90&deg; clockwise:</p>
<codeblock>
enum Compass north, east, south, west
main
  variable dir set to Compass.south
  print(enumValue(clockwise(dir)))
end main
function clockwise(d as Compass) returns Compass
  variable newDir set to Compass.north
  if d.equals(Compass.north) then
    assign newDir to Compass.east
  elif d.equals(Compass.east) then
    assign newDir to Compass.south
  elif d.equals(Compass.south) then
    assign newDir to Compass.west
  end if
  return newDir
end function
</codeblock>
<hr>
</div></div>

<div id="Member"></div>
<h1 id="MemberInstructions">Member instructions</h1>

<p>Member instructions (also referred to simply as 'members') are located within an <b>abstract class</b> or <b>concrete class</b>.
The <b>new code</b> prompt offers a context appropriate subset of the following member instructions:</p>
<p>
 <a href="#abstract_property"><b>abstract property</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#abstract_function"><b>abstract function</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#abstract_procedure"><b>abstract procedure</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#property"><b>property</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#function"><b>function</b> method <i class="fa">&#xf14c;</i></a>,
 <a href="#procedure_method"><b>procedure</b> method <i class="fa">&#xf14c;</i></a> and
 <a href="#constructor"><b>constructor</b> <i class="fa">&#xf14c;</i></a>,
</p>together with these 'private' versions:<p>
 <a href="#private"><b>private property</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#private"><b>private function</b> <i class="fa">&#xf14c;</i></a> and
 <a href="#private"><b>private procedure</b> <i class="fa">&#xf14c;</i></a>.
</p>

<p>This table shows which kinds of <b>property</b>, <b>function</b>, <b>procedure</b> and <b>constructor</b> are applicable to the various kinds of class.</p>
<table class="tableType">
 <tr>
  <th></th>
  <th colspan="2">Abstract</th>
  <th>Concrete</th>
  <th>notes</th>
 </tr><tr>
  <td width="150"></td>
  <td width="40"><a href="#abstract_class"><b>abstract class</b> <i class="fa">&#xf14c;</i></a></td>
  <td width="40"><a href="#class"><b>concrete class</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
 </tr><tr>
  <td><a href="#abstract_property"><b>abstract property</b> <i class="fa">&#xf14c;</i></a></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td></td>
  <td></td>
 </tr><tr>
  <td><a href="#abstract_function"><b>abstract function</b> <i class="fa">&#xf14c;</i></a></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td></td>
  <td>prototype for function reference only</td>
 </tr><tr>
  <td><a href="#abstract_procedure"><b>abstract procedure</b> <i class="fa">&#xf14c;</i></a></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td></td>
  <td>prototype for procedure call only</td>
 </tr><tr>
  <td><a href="#property"><b>property</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td></td>
 </tr><tr>
  <td><a href="#function"><b>function</b> method <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td>method <el-method>toString</el-method> must be defined</td>
 </tr><tr>
  <td><a href="#procedure_method"><b>procedure</b> method <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td>&#x2714;</td>
  <td>&#x2714;</td>
  <td></td>
 </tr><tr>
  <td><a href="#private"><b>private property</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td></td>
  <td>&#x2714;</td>
  <td></td>
 </tr><tr>
  <td><a href="#private"><b>private function</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td></td>
  <td>&#x2714;</td>
  <td></td>
 </tr><tr>
  <td><a href="#private"><b>private procedure</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td></td>
  <td>&#x2714;</td>
  <td></td>
 </tr><tr>
  <td><a href="#constructor"><b>constructor</b> <i class="fa">&#xf14c;</i></a></td>
  <td></td>
  <td></td>
  <td>&#x2714;</td>
  <td></td>
 </tr>
</table>

<h2 id="constructor"><b>constructor</b></h2>
<p>A <b>concrete class</b> may have an optional <b>constructor</b> so as to:</p>
<ul>
 <li>initialise properties with fixed values</li>
 <li>define parameters which are used to initialise properties</li>
</ul>
<p>If a <b>concrete class</b>'s <b>constructor</b> defines parameters then, when the class is instantiated (using <b>new</b>), the values of
the correct type must be provided. For example, if the class <code>Square</code> has this <b>constructor</b>:</p>

<codeblock>
class Square
  constructor(x as Int, y as Int)
    assign this.x to x
    assign this.y to y
  end constructor
end class
</codeblock>

<p>then it may be instantiated like this:<br>
<code>variable tail set to new Square(20, 15)</code></p>

<h2 id="property"><b>property</b></h2>
<p>A <b>property</b> is a named value defined on a <b>concrete class</b> with a name conforming to the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>,
 and a type (which may be another class name).</p>
<p>It may be read, but not written to: properties may be modified only from outside the class by means of a <a href="#procedure_method">procedure method <i class="fa">&#xf14c;</i></a>.</p>
<p>It may be given an initial value within a <b>constructor</b>, for example:</p>
<codeblock>
class Game
  property height as Int
  property board as Board
  property head as Square
  property body as List&lt;of Square&gt;
  constructor()
  end constructor
  function toString() returns String
    return "undefined"
  end function
end class
</codeblock>

<h3 class="no-TOC" id="Maybe"><code>Maybe</code></h3>
<p>When a class property is optional, it is defined with the type <code>Maybe</code>.</p>
<p>Before reading the property's value, you must test if it has a value with function <el-method>hasValue</el-method> which returns a <code>Boolean</code>.
If <code>true</code> is returned, then you retrieve the value with function <el-method>getValue</el-method>; if <code>false</code> is returned, then it has no current value,
and using <el-method>getValue</el-method> will give a runtime error.</p>
<p>To update the property's value, use function <el-method>setValue</el-method>. To restore it to having no value, use function <el-method>clearValue</el-method>.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example using <code>Maybe</code></h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Here a pupil (of class <el-type>Pupil</el-type>) need not have a tutor (of class <el-type>Teacher</el-type>):</p>
<codeblock>
main
  variable tTom set to new Teacher()
  variable pPete set to new Pupil()
  if pPete.tutor.hasValue() then
    print(pPete.tutor)
  end if
  print(p)
end main
class Teacher
  constructor()
  end constructor
  function toString() returns String
    return $"{this}"
  end function
end class
class Pupil
  constructor()
    assign this.tutor to new Maybe&lt;of Teacher&gt;()
  end constructor
  property tutor as Maybe&lt;of Teacher&gt;
  function toString() returns String
    return "undefined"
  end function
end class
</codeblock>
<hr>
</div></div>

<h2 id="FunctionMethod"><b>function</b> method</h2>
<p>A function method follows the same syntax and rules as a global <a href="#function">function <i class="fa">&#xf14c;</i></a>. The differences are:</p>
<ul>
<li>A <code>function</code> method is always referenced (used) by code outside the class using <a href="#dotSyntax">dot syntax <i class="fa">&#xf14c;</i></a> on an instance.</li>
<li>A <code>function</code> method may directly reference (read only) any <b>property</b> defined on the class as though it were a variable or parameter.</li>
<li>A <code>function</code> method may be marked <code>private</code>, in which case it is visible only to code within the class and, if defined on<b> abstract class</b> <code>A</code>, within its subclasses.
 This is done by selecting the <b>property</b> instruction and then keying <b>Ctrl+p</b>. (Pressing these keys again will remove the <code>private</code> modifier).</li>
<li><el-method>toString</el-method> method is just a regular function method with the specific name, takes no parameters and and returns a value of type <code>String</code>.
 If defined for a class then, if an instance of the class is printed, function method <el-method>toString</el-method> will automatically be used.
  Typically <el-method>toString</el-method> will return a string made up of one or more of the property values, perhaps with additional text, or the results of function calls.</li>
</ul>

<h2 id="procedure_method"><b>procedure</b> method</h2>
<p>A 'procedure method' follows the same syntax and rules as a global <a href="#procedure">procedure <i class="fa">&#xf14c;</i></a>. The differences are:</p>
<ul>
<li>A procedure method, like a function method, is always referenced (used) by code outside the class using <a href="#dotSyntax">dot syntax <i class="fa">&#xf14c;</i></a> on an instance.</li>
<li>A procedure method may read, or write to, any <b>property</b> defined on the class.</li>
<li>A procedure method may be marked <code>private</code>, in which case it is visible only to code within the class and, if defined on an abstract <code>class</code>, within its subclasses.
 This is done by selecting the <b>property</b> instruction and then keying <b>Ctrl+p</b>. (Pressing these keys again will remove the <code>private</code> modifier).</li>
</ul>

<h2 id="abstract_property"><b>abstract property</b></h2>
<p>An abstract <code>property</code> may be defined only on an <a href="#abstract_class"><b>abstract class</b> <i class="fa">&#xf14c;</i></a>. Any concrete subclass must then implement a concrete (regular) property to match.</p>

<h2 id="abstract_function"><b>abstract function</b></h2>
<p>An abstract function method may be defined only on an <a href="#abstract_class"><b>abstract class</b> <i class="fa">&#xf14c;</i></a>. Any concrete subclass must then implement a concrete (regular) function to match.</p>

<h2 id="abstract_procedure"><b>abstract procedure</b></h2>
<p>An abstract procedure method may be defined only on an <a href="#abstract_class"><b>abstract class</b> <i class="fa">&#xf14c;</i></a>. Any concrete subclass must then implement a concrete (regular) procedure to match.</p>

<h2 id="private"><b>private</b> (property, function, procedure)</h2>
<p>A <b>property</b> may be marked <b>private</b>, in which case it is visible only to code within the class and,
if defined on an <b>abstract class</b>, within its subclasses.
 This is done by using the context menu on the property instruction or selecting it and keying <b>Ctrl+p</b>.
This action is a toggle used both to assign and to remove the modifier <b>private</b>.</p>
<ul>
 <li></li>
 <li>A property that is not private may be read, but not written to.</li>
 <li>A property that is private may </li>
</ul>

<ul>
<li>Whenever you wish to access a property from within a method (or from within the constructor) on the same class, then the name of the property must be prefixed with the 'qualifier': <code>property</code>.('property-dot'). This applies whether you are reading or setting the property. By this means you can have a method parameter with the same name as a property, but they are unambiguous, because the property must be prefixed. A common pattern is to use the same name in a 'setter' method, for example:</li>
</ul>
<codeblock>
class Game
  constructor(board as Board)
    assign this.board to board
  end constructor
  procedure setHeight(height as Int)
    assign this.height to height
  end procedure
end class
</codeblock>

<div id="statement"></div>
<h1 id="StatementInstructions">Statement instructions</h1>
<p>Statement instructions (sometimes referred to as 'statements') are the imperative instructions used in the methods (procedural logic) of a program.They are:</p>
<p>
 <a href="#variable"><b>variable definition</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#reassign"><b>reassign variable</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#if"><b>if</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#while"><b>while loop</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#for"><b>for loop</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#call"><b>call procedure</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#try"><b>try</b> <i class="fa">&#xf14c;</i></a>,
 <a href="#throw"><b>throw</b> <i class="fa">&#xf14c;</i></a>
 and, within a test, <a href="#assert"><b>assert</b> equal <i class="fa">&#xf14c;</i></a>.
</p>

<h2 id="variable"><b>variable definition</b></h2>
<p>The <b>variable definition</b> .. set to .. instruction declares and initialises
 a mutable named valued. The name defined must be a valid <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.>/p>
<p>The initial value is given by a following expression. For example:
  <code>variable note set to 440</code>
</p>

<h2 id="reassign"><b>reassign variable</b></h2>
<p>The <code>assign a to b</code> instruction assigns a new value to an existing named value:
the value in <code>b</code> is copied into the named value <code>a</code></p>
<p>The two named values must be of the same Type.</p>
<p>A <b>assign variable</b> instruction may not assign a new value to a parameter within a procedure.</p>
<p>To change the value of an argument supplied in a procedure call, the corresponding parameter must have been defined as of type <code>AsRef</code>,
which then allows use of the dot method <el-method>set</el-method> on it. See <a href="#CallByRef">Call by reference <i class="fa">&#xf14c;</i></a></p>

<div id="if"></div>
<div id="then"></div>
<div id="else"></div>
<div id="elif"></div>
<h2 id="if_statement"><b>if</b> (instruction)</h2>
<p>The <b>if</b> instruction specifies which of several code sequences is to be executed next.</p>
<ul>
 <li>It is structured like this:
<codeblock>
if (x < 1) then
  assign x to 1
elif x < 2 then
  assign x to 2
elif x < 3 then
  assign x to 3
else
  assign x to 0
end if
</codeblock>
</li>
 <li>The conditions, one of which is shown above enclosed in brackets, are Boolean values or expressions.</li>
 <li><b>else if</b> and <b>else</b> clauses are optional.</li>
 <li>You can add as many <b>else if</b> clauses as you wish, but only one unconditional <b>else</b> which, if present, must be last.</li>
</ul>
<p>See also <a href="#if_expression"><b>if</b> (expression) <i class="fa">&#xf14c;</i></a> for using the related <b>if</b> to return a value.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples using <b>if</b> instruction</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Simple choice between equality and inequality:</p>
<codeblock>
  if head is apple then
    call setAppleToRandomPosition(apple, body)
  else
    call body.removeAt(0)
  end if
</codeblock>
<hr>
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Choice between an equality, a Boolean and the alternative:</p>
<codeblock>
main
  variable result set to false
  if item.equals(value) then
    assign result to true
  elif item.isBefore(value) then
    assign result to binarySearch(li.subList(0, mid), item)
  else
    assign result to binarySearch(li.subList(mid + 1, li.length()), item)
  end if
end main
</codeblock>
<hr>
</div></div>

<h2 id="while"><b>while loop</b></h2>
<p>The <b>while loop</b> construct provides a <i>conditional</i> loop, used when you want execution of the enclosed instructions to begin
 only if some condition is <el-id>true</el-id>.</p>
<p>The condition is either a <code>Boolean</code> variable or an expression that evaluates to a <code>Boolean</code> value.</p>
<p>The value of the condition must a some point become <el-id>false</el-id> otherwise the loop will not terminate and exit.</p>
<p>While the condition is <el-id>true</el-id> the enclosed code is executed;
 when <el-id>false</el-id> the loop is bypassed. For example:</p>
<codeblock>
main
  variable file set to openFileForReading()
  while not file.endOfFile()
    print(file.readLine())
  end while
  call file.close()
end main
</codeblock>

<h2 id="for"><b>for loop</b></h2>
<p>The construct
<codeblock>
  for p in q
  end for
</codeblock>
specifies looping through a sequence either of characters in a <code>String</code>, or of items in a <code>List</code>.</p>
<p>The loop variable <el-id>p</el-id> does not have to have been previously declared or initialised.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples using the <b>for loop</b></h4>
<div class="acc-body">

<p>&nbsp;&nbsp;&nbsp;&#x25cf; The loop variable <el-id>n</el-id> is of the type of a List's items (here <code>Int</code>),
and each integer in the List <el-id>primes</el-id> is in turn put into <el-id>n</el-id>:</p>
<codeblock>
procedure printPrimes()
  variable primes set to [2, 3, 5, 7, 11]
  for n in primes
    print(n)
  end for
end procedure
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; The loop variable <el-id>fruit</el-id> is of the type of a List's items (here <code>String</code>).
and each String in the List <el-id>basket</el-id> is in turn put into <el-id>fruit</el-id>:</p>
<codeblock>
main
  variable basket set to ["apple", "banana", "cherry", "date"]
  for fruit in basket
    print(fruit)
  end for
end main
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To print first the keys and then the values from a <code>Dictionary</code>:</p>
<codeblock>
main
  variable di set to ["A":1, "B":2, "C":3]
  for s in di.keys()
    print(s)
  end for
  for n in di.values()
    print(n)
  end for
end main
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; Function to reverse a <code>String</code>:</p>
<codeblock>
main
  print(reverse("stressed"))
end main
function reverse(s as String) returns String
  variable sReturn set to ""
  for ch in s
    assign sReturn to ch + sReturn
  end for
  return sReturn
end function
</codeblock>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; Alternatively the loop variable may be defined as an integer range using methods <a href="LibRef.html#range"><el-method>range</el-method> <i class="fa">&#xf08e;</i></a> and
<a href="LibRef.html#rangeInSteps"><el-method>rangeInSteps</el-method> <i class="fa">&#xf08e;</i></a> in order to index into a subject List:</p>
<codeblock>
main
  variable numbers set to ["zero", "one", "two", "three", "four", "five", "six"]
  for n in range(2, 6)
    print(numbers[n])
  end for
end main
</codeblock>
<hr>
</div></div>

<div class="accordion">
<h4 class="no-TOC acc-title">Technical note about the <b>for loop</b> variable</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; The <b>for</b> instruction creates its own working copy of the values through which to loop sequentially.
So even if the loop variable is changed in any way within the <b>for loop</b>, this will not affect which subject items are referred to.</p>
<p>It is therefore recommended never to reassign the loop variable within the loop.</p>
<hr>
</div></div>

<h2 id="call"><b>call procedure</b></h2>
<p>The <b>call procedure</b> instruction is used when you want to run a <a href="#procedure">procedure <i class="fa">&#xf14c;</i></a>.</p>
<p>The procedure may be:</p>
<ul>
<li>a procedure that you have defined at the global level<br>
  <code>call fillRandom(grid)</code></li>
<li>a procedure method on an object of a class that you have defined<br>
  <code>call apple.newRandomPosition(snake)</code>
</li>
<li>a procedure method that belongs to the same class as the procedure that you are calling from<br>
  <code>call updateNeighbours()</code></li>
<li>a procedure provided by the standard library<br>
  <code>call sleep_ms(2000)</code></li>
<li>a procedure method on an object of a type provided by the standard library<br>
  <code>call vg.append(rect)</code>
</li>
</ul>
<p>The arguments provided must match the number and type of the parameters specified in the definition of the procedure. If there are no parameters, leave the brackets empty.</p>
<p>An argument whose value is changed by the procedure must be:</p>
<ul>
 <li>either a mutable data structure (List or Dictionary)</li>
 <li>or a <b>Ref</b> reference to a named value Type</li>
 <li>or a <b>Ref</b> reference to an immutable data structure (Set, Stack or Queue)</li>
</ul>
<p>For procedures that you define yourself, any argument whose value is changed must be of a mutable Type.</p>
<p>An expression of the correct type can be used as an argument, but its value cannot be changed in the procedure.</p>
<p>Procedures may have side effects, for example input/output or changing a data value in an object.
 They can change the contents of any mutable object passed in as an argument.
  For this reason, procedures cannot be called from functions, which are not allowed to have side effects.
  To enforce this, <b>call procedure</b> instructions are not allowed in functions.</p>
<p>There is a limit to the complexity of a <b>call procedure</b> instruction.
 Only one dot is allowed in the procedure name field, or two dots if the first word is <b>property</b>.
 If you need anything more complicated, use a <b>change variable</b> instruction on the line above.
  See the error message explanation for <a href="#ProcRefField">'procedureName' in a call instruction <i class="fa">&#xf14c;</i></a>.</p>

<div id="catch"></div>
<h2 id="try"><b>try</b></h2>
<p>You can enclose code in a <b>try</b> construction when you want it to be able, at execution, to throw an exception that you handle.</p>
<p>This might arise when calling a <a href="LibRef.html#SystemMethods">System method <i class="fa">&#xf08e;</i></a> that is dependent upon external conditions,
 such as when cancelling the writing of a text file, as in the example in <a href="LibRef.html#tryCatchOnFile">Writing text files <i class="fa">&#xf08e;</i></a>.</p>
<p>The <b>try</b> construction automatically provides a <b>catch</b> clause in which you provide a String for an message.</p>
<p>You can also use a <b>test</b> to check whether another piece of code might throw an exception by wrapping it in a <b>try</b> instruction.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples using <b>try</b></h4>
<div class="acc-body">

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To check a function input, and throw an exception up:</p>
<codeblock>
main
  try
    variable t set to foo(true)
    print("no error")
  catch err as CustomError
    print(err)
  end try
end main
function foo(torf as Boolean) returns Boolean
  if torf then
    throw CustomError "error in foo()"
  end if
  return torf
end function
</codeblock>
<p>When foo is given argument <el-id>true</el-id>, output is "error in foo()"; when given <el-id>false</el-id>, output is "no error". </p>
<hr>

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To stop the program if one of two points (each a Tuple) has negative <i>x</i> or <i>y</i>:</p>
<codeblock>
main
  variable a set to (1.0, 2.0)
  variable b set to (3.0, -6.0)
  variable fQ set to firstQuadrant(a, b)
end main
function firstQuadrant(a as (Float, Float), b as (Float, Float)) returns Float
  if (a.item_0 < 0) or (a.item_1 < 0) or (b.item_0 < 0) or (b.item_1 < 0) then
    throw CustomError $"point {a} or (b} is not in the first quadrant"
  end if
  return 0
end function
</codeblock>
<hr>
</div></div>

<h2 id="throw"><b>throw</b></h2>
<p>You can deliberately generate, or 'throw', an error exception when a specific circumstance is identified, using a <b>throw</b> instruction
 which defines an explanatory string.</p>
<p>For the program to retain control when an exception is raised, use the <a href="#try"><b>try</b> <i class="fa">&#xf14c;</i></a> instruction.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Example using <b>throw</b> exception</h4>
<div class="acc-body">

<p>&nbsp;&nbsp;&nbsp;&#x25cf; To stop the program if a value calculated in a function is out of range:</p>
<codeblock>
main
  print($"{percent(23, 20)}" + "%")
end main
function percent(value as Float, maximum as Float) returns Float
  if value > maximum then
    throw ElanRuntimeError "proportion exceeds 100%"
  end if
  return value/maximum*100
end function
</codeblock>
<p>At runtime, if the condition is met, execution will stop and the display will show:</p>
<pre>
    proportion exceeds 100%
    Error
</pre>
<hr>
</div></div>

<h2 id="assert"><b>assert</b></h2>
<p>The <b>assert</b> equal instruction is used only within a <a href="#test"><b>test</b> <i class="fa">&#xf14c;</i></a>,
which is the mechanism for running unit tests during program development, not during program execution.</p>
<p>Some programming languages have a feature for making assertions while your program is running.
 In Elan, you can get equivalent functionality by throwing an exception, as described in the <a href="#throw"><b>throw exception</b> <i class="fa">&#xf14c;</i></a> instruction.</p>

<h2 id="constant_let"><b>let statement</b></h2>
<p>Of use only in <code>test</code> instructions and in Functional Programming functions <code>let</code> is used to define constant values defined by expressions (or literals).</p>
<p>The <b>let statement</b> instruction declares and initialises an immutable named value whose scope is confined to the function.</p>
<p>The name defined must be a valid <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>
<p>You can declare a such a constant within a loop, so that the named value gets a new value each time it is executed, but its value cannot be changed in any other way.</p>
<p>Unlike a <a href="#constant">global constant <i class="fa">&#xf14c;</i></a>, the value assigned in a <b>let statement</b> may be any value, literal or expression:</p>
<codeblock>
function numbers() returns (Float, Float)
  let tau be 2*pi
  let phi be (1 + sqrt(5))/2
  return (tau, phi)
end function
</codeblock>

<h1 id="Expression">Expressions</h1>
<p>One of the most important constructs in programming is the <b>expression</b>. An expression evaluates and returns a value using the following elements:</p>
<ul>
<li><a href="#literalValue">Literal value <i class="fa">&#xf14c;</i></a></li>
<li><a href="#namedValue">Named value <i class="fa">&#xf14c;</i></a></li>
<li><a href="#operator">Operator <i class="fa">&#xf14c;</i></a> (including round brackets)</li>
<li><a href="#functionCall"><b>function</b> reference <i class="fa">&#xf14c;</i></a></li>
<li><a href="#lambda"><b>lambda</b> <i class="fa">&#xf14c;</i></a></li>
</ul>

<h2 id="literalValue">Literal value</h2>
<p>A literal value is where a value is written 'literally' in the code, such as <code>3.142</code>, in contrast to a value that is referred to by a name.</p>
<p>Here is a table showing some example literal values.  Follow the links for more information about each Type.</p>
<table>
<tr><th>Type</th><th>Example of literal</th></tr>
<tr><td><a href="LibRef.html#Int">Int <i class="fa">&#xf08e;</i></a></td><td><code>3</code></td></tr>
<tr><td><a href="LibRef.html#Float">Float <i class="fa">&#xf08e;</i></a></td><td><code>2.0</code></td></tr>
<tr><td><a href="LibRef.html#Boolean">Boolean <i class="fa">&#xf08e;</i></a></td><td><el-id>true</el-id></td></tr>
<tr><td><a href="LibRef.html#String">String <i class="fa">&#xf08e;</i></a></td><td><code>"Hello"</code></td></tr>
<tr><td><a href="LibRef.html#Tuple">Tuple <i class="fa">&#xf08e;</i></a></td><td><code>(3, "banana")</code></td></tr>
<tr><td><a href="LibRef.html#List">List <i class="fa">&#xf08e;</i></a></td><td><code>["lemon", "lime", "orange"]</code></td></tr>
<tr><td><a href="LibRef.html#Dictionary">Dictionary <i class="fa">&#xf08e;</i></a></td><td><code>["a":3, "b":5]</code></td></tr>
</table>
<p>For more about List and Dictionary literals see the <a href="LibRef.html#StandardDataStructures">Standard data structures <i class="fa">&#xf08e;</i></a> table.</p>

<div id="range"></div>
<h2 id="IndexedValue">Indexed values</h2>
<p>If a named value is of an indexable type (<code>String</code> or <code>List</code>), then you can refer to a contiguous subset (or range) of its values
 using methods <el-method>subString</el-method> and <el-method>subList</el-method> respectively.</p>
<p>The upper index of a range is <i>exclusive</i>, so to define a range that picks items indexed from <i>i</i> to <i>j</i>, you would specify the range as <code>(i, j + 1)</code>.</p>
<p>If the two index values of a range are equal, or the second is smaller than the first,
then an empty string or list is returned.</p>
<p>Indexes are used only for <i>reading</i> values. Writing a value to a specific index location in a list is done using method
<a href="LibRef.html#put_List"><el-method>put</el-method> <i class="fa">&#xf08e;</i></a>.</p>

<p>Example using indexing on a string:</p>
<table class="tablePlain">
<tr>
 <td>
<codeblock>
main
  variable a set to "Hello world!"
  print(a[4])
  print(a.subString(4, a.length()))
  print(a.subString(0, 7))
end main
</codeblock>
 </td><td><br><br>&#x27f6;<br>&#x27f6;<br>&#x27f6;</td>
  <td><el-code><br><br>o</el-type><br>o world!<br>Hello w</el-code> &nbsp;&nbsp;&nbsp; (since the upper bound of a range is <i>exclusive</i>)</td>
</tr>
</table>

<p>And on a list:</p>
<table class="tablePlain">
<tr>
 <td>
<codeblock>
main
  variable li set to new List&lt;of Int&gt;()
  assign li to [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
  print(li[4])
  print(li.subList(4, li.length()))
  print(li.subList(0, 7))
end main
</codeblock>
 </td><td><br><br><br>&#x27f6;<br>&#x27f6;<br>&#x27f6;</td>
  <td><el-code><br><br><br>4</el-code> &nbsp;&nbsp;&nbsp; (the value of the list item)<br><el-code>[4, 5, 6, 7, 8, 9, 10, 11]</el-code> &nbsp;&nbsp;&nbsp; (a new list)<br><el-code>[0, 1, 2, 3, 4, 5, 6]</el-code> &nbsp;&nbsp;&nbsp; (since the upper bound of a range is <i>exclusive</i>)</td>
</tr>
</table>

<div id="operator"></div>
<h2 id="Operators">Operators</h2>

<h3 class="no-TOC" id="ArithmeticOperators">Arithmetic operators</h3>

<p>Arithmetic operators can be applied to <code>Float</code> or <code>Int</code> arguments. The result may be a <code>Float</code> or an <code>Int</code> depending on the arguments.</p>
<p>For the  + &minus; *  operators, the result is a <code>Float</code> if either of the arguments is a <code>Float</code>, and an <code>Int</code> if both arguments are <code>Int</code>.</p>
<p>For the  /  operator, at least one of the values must be a <code>Float</code>, and the result is always a <code>Float</code>. It can be converted to an <code>Int</code> using standalone function <a href="LibRef.html#floor"><el-method>floor</el-method> <i class="fa">&#xf08e;</i></a>.</p>
<div id="power"></div>
<p>For raising one value to the power of another, use the syntax in these examples:<br></p>
<code>print(pow(4, 4))</code><br>
<code>variable c set to sqrt(pow(a, 2) + pow(b, 2))</code>
<p>If, when including a power in an expression, it does not parse, try enclosing parts of the expression in brackets to remove potential ambiguity.</p>
<div id="mod"></div>
<p> The operator <b>mod</b> (integer remainder) is applied only to <code>Int</code> arguments, and the result is <code>Int</code>.</p>
<table class="tablePlain">
<tr>
 <td><code>2/3.0</code></td><td>&#x27f6;</td><td>0.666..</td>
</tr><tr>
 <td><code>2*3</code></td><td>&#x27f6;</td><td>6</td>
</tr><tr>
 <td><code>2 + 3</code></td><td>&#x27f6;</td><td>5</td>
</tr><tr>
 <td><code>2 - 3</code></td><td>&#x27f6;</td><td>&minus;1</td>
</tr><tr>
 <td><code>11 mod 3</code></td><td>&#x27f6;</td><td>2</td>
</tr>
</table>
<p>For integer division, either use method <el-method>floor</el-method> on a <code>Float</code> result, or use method <el-method>divAsInt</el-method> on <code>Float</code> arguments (which returns an <code>Int</code>):</p>
<table class="tablePlain">
<tr>
 <td><code>(11.0/3.0).floor()</code></td><td>&#x27f6;</td><td>3</td>
</tr><tr>
 <td><code>(-11.0/3.0).floor()</code></td><td>&#x27f6;</td><td>&minus;4</td>
</tr><tr>
 <td><code>divAsInt(11.0, 3.0)</code></td><td>&#x27f6;</td><td>3</td>
</tr>
</table>
<p>Note that rounding is always down.</p>

<p>Arithmetic operators follow the conventional rules for precedence i.e. 'BIDMAS' (or 'BODMAS').</p>
<p>When combining <b>mod</b> with other operators in an expression, insert round brackets to avoid ambiguity e.g.:</p>
<table class="tablePlain">
<tr>
 <td><code>(5 + 6) mod 3</code></td><td>&#x27f6;</td><td>2</td>
</tr>
</table>
<p>Note that <b>mod</b> 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.</p>
<p>The minus sign may also be used as a unary operator, and this takes precedence over binary operators so:</p>
<table class="tablePlain">
<tr>
 <td><code>2*-3</code></td><td>&#x27f6;</td><td>&minus;6</td>
</tr>
</table>

<p>The editor automatically puts spaces around the operators + and &minus;, but not around / or *.
This is just to visually reinforce the precedence.</p>

<div id="and"></div>
<div id="not"></div>
<div id="or"></div>
<h3 class="no-TOC" id="LogicalOperators">Logical operators</h3>
<p>Logical operators are applied to <code>Boolean</code> arguments and return a <code>Boolean</code> result.</p>
<p><code>and</code> and <code>or</code> are binary operators<br>
<code>not</code> is a unary operator. </p>
<p>The operator precedence is <code>not</code> &rarr; <code>and</code> &rarr; <code>or</code>, so this
example, which implements an 'exclusive or', need not use brackets and can rely on the operator precedence:</p>

<codeblock>
function exOr(a as Boolean, b as Boolean) returns Boolean
  return a and not b or b and not a
end function
</codeblock>

<h3 class="no-TOC" id="StringOperators">String operator</h3>
<p>The + operator is also used for concatenating <code>String</code> values.</p>

<h3 class="no-TOC" id="EqualityTesting">Equality testing</h3>
<h4 class="no-TOC">Testing equality of <code>Int</code>, <code>Float</code> or <code>Boolean</code> values</h4>
<p>Equality testing of these Value Types uses the <b>is</b> and <b>isnt</b> operators between two values and returns a <code>Boolean</code> result:</p>
<ul>
 <li><b>isnt</b> returns the opposite of <b>is</b>.</li>
 <li><code>(a is b)</code> returns <b><el-id>true</el-id></b>, if <el-id>a</el-id> and <el-lit>b</el-lit> are both of the same type and their values are equal.
 The only exception is that if one argument is of type <code>Float</code> and the other is of type <code>Int</code>,
  then <b>is</b> will return <el-id>true</el-id> (and <b>isnt</b> will return <el-id>false</el-id>) if their values are the same,
  i.e. they are the same whole number.</li>
 <li>It is also possible to use methods <el-method>equals</el-method> and <el-method>notEqualTo</el-method> described below.</li>
</ul>

<h4 class="no-TOC">Testing equality of <code>String</code> values and of all Reference Types</h4>
<p>Equality testing of these Reference Types uses <a href="LibRef.html#CommonDotMethods">common dot methods <i class="fa">&#xf08e;</i></a> <el-method>equals</el-method> and <el-method>notEqualTo</el-method>:</p>
<ul>
<li>
<codeblock>
if listA.equals(listB) then

end if
</codeblock>
</li>
<li><code>assign differs to set1.notEqualTo(set2)</code></li>
</ul>
<p>The comparison is made sequentially through the characters or items in the structures to see if the objects are equal.
Two Lists compare equal if they contain the same items in the same order.
And two instances of the same class compare equal if the values of all their properties compare equal.</p>
<p>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).</p>

<h3 class="no-TOC">Numeric comparison</h3>
<p>The numeric comparison operators are:</p>
<table class="tablePlain">
<tr>
 <td>&gt;</td><td>for</td><td>greater than</td>
</tr><tr>
 <td>&lt;</td><td>for</td><td>less than</td>
</tr><tr>
 <td>&gt;=</td><td>for</td><td>greater than or equal to</td>
</tr><tr>
 <td>&lt;=</td><td>for</td><td>less than or equal to</td>
</tr>
</table>

<p>Each may be applied between two values of type <code>Float</code>, but any named value or expression that evaluates to an <code>Int</code> may always be used where a <code>Float</code> is expected.</p>
<p>These operators cannot be applied to strings. Use the dot methods <el-method>isBefore</el-method> and <el-method>isAfter</el-method> to compare strings alphabetically. See <a href="LibRef.html#isAfter">Dot methods on a String <i class="fa">&#xf08e;</i></a>.</p>

<h3 class="no-TOC">Combining operators </h3>
<p>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:</p>
<code>assign x to (a > b) and (b < c)</code><br>
<code>assign x to (a + b) > (c - d)</code>

<h2 id="functionRef">Function reference</h2>
An expression may simply be a reference to a function, or it may include several function references within it. Examples:
<codeblock>
main
  print(sin(radians(30)))
  variable x set to pow(sin(radians(30)), 2) + pow(cos(radians(30)), 2)
  variable name set to input("Your name")
  print(name.upperCase())
end main
</codeblock>

<h4 class="no-TOC">Notes</h4>
<ul>
<li>The third example above is not strictly a function call, but is a 'system method' call.
System methods may be used only within the <b>main</b> routine or a <b>procedure</b>, because they have external dependencies or side effects.</li>
<li>In the fourth example, <code>upperCase</code> is a dot method that may be applied to any instance (variable or literal) of type <code>String</code>.
See <a href="LibRef.html#upperCase">Dot methods on a String <i class="fa">&#xf08e;</i></a>.</li>
</ul>

<h2 id="lambda"><b>lambda</b></h2>
<p>A <b>lambda</b> is a lightweight means of defining a function 'inline' and without a name (i.e. an anonymous function).</p>
<p>You can use a lambda only as an argument to a <a href="LibRef.html#HoFs">Higher-order Function <i class="fa">&#xf08e;</i></a>.</p>
<p>You would typically define a <b>lambda</b> when the functionality it defines is needed in only one location,
e.g. in a particular call to a Higher-order Function.</p>
<!-- when you need to capture a local variable in the implementation: this is called 'closing around a variable'. -->
<p>The syntax for a <b>lambda</b> is as follows:</p>
<ul>
<li>Start with the word <b>lambda</b>.</li>
<li>Parameter definitions, comma-separated, follow the same form as parameter definitions in a function or procedure, but without surrounding brackets.</li>
<li>The =&gt; symbol, which is usually articulated as 'returns', 'yields' or 'fat arrow'.</li>
<li>An expression that makes use of the parameters, and may also make use of other variables that are in scope. </li>
</ul>
<p>For examples of using lambda in Higher-order Functions, see <a href="LibRef.html#libraryHoFs">Library functions that process Lists <i class="fa">&#xf08e;</i></a></p>
<!-- <p>Although a <b>lambda</b> is commonly defined 'inline' it is also possible
 to assign a <b>lambda</b> to a named value, so as to reuse it within the scope of that named value.</p>

Example using a <b>lambda</b> to look for <el-id>true</el-id> in a list of Boolean values:
<codeblock>
function liveNeighbours(cells as List&lt;of Boolean&gt;, c as Int) returns Int
  variable neighbours set to neighbourCells(c)
  variable live set to neighbours.filter(lambda i as Int => cells[i])
  return live.length()
end function
</codeblock> -->

<h2 id="if_expression"><b>if</b> (expression)</h2>

<p>The <b>if</b> expression returns one of two values or expressions dependent upon the evaulation of a Boolean value:</p>
<p>Its syntax is shown in this <b>reassign variable</b> instruction:</p>
<code>variable isBigger set to if_(a >= b, true, false)</code>
<p>Similarly, but returning an evaluated expression:</p>
  <code>variable d set to if_(c < 580, c - 40, c + 60)</code>
<p>in which variable <el-id>d</el-id> takes the value of <code> c - 40</code> if <code>c < 580</code>, or <code>c + 60</code> otherwise.</p>
<p>An <b>if</b> expression may be used within an <b>if</b> expression but may be hard to read and understand.</p>

<div class="accordion">
<h4 class="no-TOC acc-title">Examples using <b>if</b> expression:</h4>
<div class="acc-body">
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Choice in a <b>return</b> instruction:</p>
<codeblock>
function foo() returns Int
  return if_(isGreen(attempt, target, n), setChar(attempt, n, "*"), attempt)
end function
</codeblock>
<hr>
<p>&nbsp;&nbsp;&nbsp;&#x25cf; Using an <b>if</b> expression in a <b>call procedure</b> <el-method>print</el-method>:</p>
<table class="tablePlain">
<tr>
 <td>
<codeblock>
main
  variable p set to unicode(0x03c0)
  call testPi(p, 3)
  call testPi(p, 4)
end main
procedure testPi(p as String, v as Float)
  print(if_(pi > v, $"{p} > {v}", $"{p} < {v}"))
end procedure
</codeblock>
 </td><td><br><br>&#x27f6;<br>&#x27f6;</td><td><br><br>&#x03c0 &gt; 3<br>&#x03c0 &lt; 4</td>
</tr>
</table>
<hr>
</div></div>

<h2 id="new"><b>new</b></h2>
<p>A 'new instance' expression is used to create a new instance of a <a href="LibRef.html#StandardDataStructures">library data structure <i class="fa">&#xf08e;</i></a>,
   or a <a href="#class"> user-defined class <i class="fa">&#xf14c;</i></a>, either to assign to a named value, or as part
  of a more complex expression. Example of use from demo program snake_PP.elan:</p>
<code>variable headRef set to new AsRef&lt;of List&lt;of Int&gt;&gt;(head)</code>

<h1 id="Comment">Comments</h1>
<h2># comment</h2>
<p>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 <em>about</em> the program, intended to be read by a person seeking to understand or modify the code.</p>
<p>A comment is entered at any editor prompt by typing the hash symbol # which then provides a field in which you may enter text, or leave blank.
 Your text may contain any characters, except that it must not start with an open square bracket [.</p>
<p>Comments may be inserted at any level: in the <a href="#GlobalInstructions">Global <i class="fa">&#xf14c;</i></a>,
<a href="#MemberInstructions">Member <i class="fa">&#xf14c;</i></a>, or <a href="#StatementInstructions">Statement <i class="fa">&#xf14c;</i></a> instruction levels,
as well as from the <b>new code</b> prompt. Every prompt provides a <code>comment</code> option, namely a # symbol.</p>
<p> 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.</p>

<h1 id="compile_error">Compile errors and warnings</h1>

 <p>Q: What is the difference between a compile <i>error</i> and a <i>warning</i>.</p>
 <p>A: A warning usually indicates that the fix may involve <i>adding</i> some more code,
 for example adding a definition for an unknown identifier. An error usually indicates
 that you will need to <i>alter</i> 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.</p>

<h2>Messages</h2>

<h3 id="TypeCompileError" class="no-TOC">Expression must be ...</h3>
 <p>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.</p>

<h3 id="ThisCompileError" class="no-TOC">Cannot use 'this' outside class context</h3>
 <p><code>this</code> may only be used within an instance method on a class to refer to the current instance.</p>

<h3 id="DeclaredAboveCompileError" class="no-TOC">Abstract class ... must be declared before it is used</h3>
 <p>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.</p>

<h3 id="MemberTypeCompileError" class="no-TOC">Member ... must be of type ...</h3>
 <p>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.</p>

<h3 id="TypesCompileError" class="no-TOC">Incompatible types. Expected: ... Provided: ...</h3>

<h3 id="TernaryCompileError" class="no-TOC">Cannot determine common type between ... and ...</h3>

<h3 id="UndefinedSymbolCompileError" class="no-TOC"> ... is not defined for type ...</h3>
 <p>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.</p>

<h3 id="CannotCallAFunction" class="no-TOC">Cannot call a function as a procedure</h3>
 <p>A function (or function method) is to be used within an expression, not via a <b>call procedure</b> instruction.</p>

<h3 id="CannotUseSystemMethodInAFunction" class="no-TOC">Cannot use a system method in a function</h3>
 <p>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 <b>main</b> routine.</p>

<h3 id="IsDeprecated" class="no-TOC">Code change required ...</h3>
 <p>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.</p>

<h3 id="CannotUseLikeAFunction" class="no-TOC">Cannot call procedure ... within an expression</h3>
 <p>A procedure may be used only within a <b>call procedure</b> instruction.</p>

<h3 id="CannotCallAsAMethod" class="no-TOC">Cannot invoke ... as a method</h3>
 <p>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.</p>

<h3 id="NotIndexableCompileError" class="no-TOC">Cannot ...index ...</h3>
 <p>An index (in square brackets) may be applied only to certain data structure Types: <code>String</code>, <code>List</code>
 and <code>Dictionary</code>.</p>

<h3 id="NotRangeableCompileError" class="no-TOC">Cannot range ...</h3>
 <p>A range may be applied only to certain data structure Types: <code>String</code> and <code>List</code>.</p>

<h3 id="NotNewableCompileError" class="no-TOC">Cannot new ...</h3>
 <p>The type specified after the <b>call procedure</b> instruction cannot be instantiated. Either the type is inapplicable,
 or it is an <b>abstract class</b>.</p>
<!--
<h3 id="InvalidSourceForEachCompileError" class="no-TOC">Source for 'each' must be a List or String.</h3>
-->
<h3 id="MustBeAbstractCompileError" class="no-TOC">May inherit from one abstract superclass only</h3>
 <p>The message is self explanatory.</p>

<h3 id="MustNotBeCircularDependencyCompileError" class="no-TOC">class ... cannot inherit from itself</h3>
 <p>The message is self explanatory.</p>

<h3 id="MustBeSingleAbstractCompileError" class="no-TOC">May inherit from one abstract superclass only.</h3>
<p>The message is self explanatory.</p>

<h3 id="PrivateMemberCompileError" class="no-TOC">Cannot reference private member ...</h3>
 <p>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.</p>

<h3 id="MustImplementCompileError" class="no-TOC">... must implement ...</h3>
 <p>If a concrete class inherits from any abstract class it must implement all abstract methods defined in the abstract type (or in any super-type of the abstract class).</p>

<h3 id="MustBeConcreteCompileError" class="no-TOC">... must be concrete to new</h3>
 <p>You cannot create an instance of any abstract class: only of a concrete class.</p>

<!--
<h3 id="OutParameterCompileError" class="no-TOC">Cannot pass ... as an out parameter</h3>
 <p>If a parameter of a procedure is marked with <b>out</b> then this means that the parameter may be
 reassigned within the procedure. Therefore you must pass in a variable that can be reassigned. You cannot pass in: a
 constant, a literal value, or a named value that is defined by a <b>let</b> instruction.</p>
-->

<h3 id="ExtensionCompileError" class="no-TOC">Cannot call extension method directly</h3>
 <p>A method that is defined within the Library as an <b>extension method</b>, such as <el-method>toString</el-method>, may be called on a named
 value or an expression only using <a href="#dotSyntax">dot syntax <i class="fa">&#xf14c;</i></a>.</p>

<h3 id="PropertyCompileError" class="no-TOC">Cannot prefix function with 'property'</h3>
 <p>The prefix <b>property.</b> may only be used before a property name: not a function name.</p>

<h3 id="MissingParameterCompileError" class="no-TOC">Missing argument(s) ...</h3>
 <p>The method being called expects more arguments than have been provided.</p>

<h3 id="ExtraParameterCompileError" class="no-TOC">Too many argument(s) ...</h3>
 <p>A method has been passed more arguments than it expects.</p>

<h3 id="ParameterTypesCompileError" class="no-TOC">Argument types ...</h3>
 <p>One or more arguments provided to the method are of the wrong Type.</p>

<h3 id="GenericParametersCompileError" class="no-TOC">...&lt;of Type&gt;...</h3>
 <p>Certain data structure Types, including <code>List</code>, must specify the type of their members, for example <code>List</code>&lt;<b>of</b> <code>Int</code>&gt;.
 Failure to specify the '&lt;of Type&gt;' on these Types will give an error, as will specifying 'of Type' where it is <i>not</i> required.
 Dictionaries require Types to be specified for both the keys and the values,
 for example: <code>Dictionary</code>&lt;of <code>String</code>, <code>Float</code>&gt;.</p>

<h3 id="MutateCompileError" class="no-TOC">May not reassign the ...</h3>
 <p>Attempting to reassign, or mutate, a named value that may not be reassigned in the current context.</p>

<h3 id="NotUniqueNameCompileError" class="no-TOC">Name ... not unique in scope ...</h3>
 <p>Attempting to create an identifier with the same name as one already defined <i>within the same scope</i>.</p>

<h3 id="ReassignInFunctionCompileError" class="no-TOC">May not set ... in a function</h3>
 <p>A property can be reassigned only within a procedure method, not within a function, because reassigning a property is a side effect.</p>

<h3 id="RedefinedCompileError" class="no-TOC">The identifier ... is already used for a ... and cannot be re-defined here.</h3>
 <p>An existing named value may not be defined again within the same scope.</p>

<h3 id="DuplicateKeyCompileError" class="no-TOC">Duplicate Dictionary key(s)</h3>
 <p>Attempting to define a literal <code>Dictionary</code> <!--or <code>DictionaryImmutable</code>-->
 with one or more duplicated keys in the definition.</p>

<!-- This message deleted>
<h3 id="FunctionRefCompileError" class="no-TOC">To evaluate function ... add brackets ...</h3>
 <p>If you intend to <i>evaluate</i> a function, the function name must be followed by brackets even if the function
 defines no parameters. If your intent was to define a <i>reference</i> to the function (a pattern used commonly in
 Functional Programming) then only the name of the function is needed.</p>
<-->

<h3 id="NotGlobalFunctionRefCompileError" class="no-TOC">Library or class function ... cannot be used without brackets</h3>
<!-- this text removed when keyword ref removed>
 The keyword <b>ref</b> may be applied only to functions that you have defined in your own code as a standalone (global) function.
 It may not be applied to a function method defined on a class, nor to a library function.
 You may, however, define your own function that simply <i>delegates</i> its implementation to a library function.
<-->

<h3 id="UnknownCompilerDirectiveCompileError" class="no-TOC">a comment may not start with [ unless it is a recognised compiler directive</h3>
 <p>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.</p>

<h3 id="mustBeBooleanCondition" class="no-TOC">Condition of 'if' expression does not evaluate to a Boolean.</h3>

<h3 id="mustNotHaveConditionalAfterUnconditionalElse" class="no-TOC">Cannot have any clause after unconditional 'else'.</h3>

<h3 id="mustNotBeReservedWord" class="no-TOC">...  is a reserved word, and may not be used as an identifier.</h3>
 <p>Most programming languages define keywords, or other 'reserved words' that may not be used as identifiers - for technical reasons.
  Because Elan supports multiple programming languages and guarantees that any program written in one language
  will convert correctly to the other languages, it must disallow the use of keywords from <i>any</i>
  of the supported languages - not just the ones defined by the language you are writing. Fortunately many
  of the keywords are common to more than one of the languages.</p>

  <p>If you see this message, just alter the identifier you have defined - by extending the word, perhaps even just by adding an underscore -
    or choose a different word altogether.</p>

<h3 id="mustNotBeNegativeIndex" class="no-TOC">Index cannot be negative.</h3>
 <p>An index into a list cannot have a negative value. If a negative is given in literal form e.g.
 a[&minus;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.</p>

<h3 id="CannotCompareProcFunc" class="no-TOC">Cannot do equality operations on Procedures or Functions.</h3>
 <p>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.</p>

<!--
<h3 id="mustBeImmutableGenericType" class="no-TOC">... cannot be of mutable type ...</h3>
 <p>Element type for a <a href="LibRef.html#ListImmutable">ListImmutable <i class="fa">&#xf14c;</i></a> must itself be an immutable Type.
 Similarly, for an <a href="LibRef.html#DictionaryImmutable">DictionaryImmutable <i class="fa">&#xf14c;</i></a> the Types for both the key and the value must be immutable ones.</p>
-->

<h3 id="mustBeValidKeyType" class="no-TOC">... cannot have key of type ...</h3>
 <p>The type of the key for any dictionary <a href="LibRef.html#Dictionary">Dictionary <i class="fa">&#xf08e;</i></a> must be an immutable Type, and not itself an indexable Type.</p>

<h3 id="mustBeCompatibleDefinitionNode" class="no-TOC">Wrong number of deconstructed variables.</h3>

<h3 id="mustBePropertyPrefixedOnMember" class="no-TOC">referencing a property requires a prefix.</h3>
 <p>If you are referring to a property of a class <i>from code defined within the class</i> then the
 property name must be preceded by <b>property</b>.</p>

<h3 id="mustNotBeOutParameter" class="no-TOC">'out' parameters are only supported on procedures.</h3>
 <p>You cannot defined an <b>out</b> parameter in a function (because that would
 imply the possibility of creating a side effect).</p>

<h3 id="mustNotHaveDuplicateMain" class="no-TOC">There can only be one <b>main</b> in a program.</h3>

<h3 id="mustNotBeTwoUnaryExpressions" class="no-TOC">Unsupported operation.</h3>
 <p>You cannot chain two 'unary' operators (those that apply to a single value), such as &minus;
 or <b>not</b> successively within an expression.</p>

<h3 id="paramNameNotSameAsItsMethod" class="no-TOC"> Parameter ... may not have the same name as the method in which it is defined.</h3>
 <p>A function or procedure named e.g. 'foo' may not define a parameter with that same name.</p>

<h2>Field help</h2>

<h3 id="ArgListField" class="no-TOC">'arguments' field in a call instruction</h3>
 <p>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:</p>
<ul>
 <li>A literal value</li>
 <li>A named value</li>
 <li>An expression</li>
</ul>
 <p>In certain very specific contexts, however, some options are disallowed by the compiler.</p>

<h3 id="AssertActualField" class="no-TOC">'computed value' field in an assert instruction</h3>
 <p>The 'actual' field should be kept as simple as possible, <i>preferably</i>
 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 <b>variable definition</b>
 instruction and then use the named value in the 'actual' field of the <b>assert</b> equal
 instruction. Some more complex expressions are permissible, but these two restrictions apply:</p>
 <ul>
  <li>Any expression involving a binary operator such as +, <b>isnt</b>, etc.,
  must have brackets around it.</li>
  <li>You may <i>not</i> use the <b>is</b> operator within the 'actual' field, because
  the parser will confuse this with the <b>is</b> keyword that is part of the <b>assert</b> equal instruction.</li>
 </ul>

<h3 id="AssignableField" class="no-TOC">'variable name' field in a set instruction</h3>
 <p>The first field in a <b>change variable</b> instruction most commonly takes the name of an existing variable.

<h3 id="CommentField" class="no-TOC">'comment' field</h3>

<h3 id="ConstantValueField" class="no-TOC">literal value or data structure in a constant</h3>
 <p>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 <i>immutable</i> List or Dictionary.</p>

<h3 id="EnumValuesField" class="no-TOC">'values' field in an enum definition</h3>
 <p><b>enum</b> values must each be a valid identifier, separated by commas.</p>

<h3 id="ExceptionMessageField" class="no-TOC">'message' field in a throw instruction</h3>
 <p>An exception message must be either a literal string or a named value holding a string.</p>

<h3 id="ExpressionField" class="no-TOC">expression field - used within multiple instructions</h3>
 <p>This field expects an expression. For the various forms of expression see <a href="#Expression">Expressions <i class="fa">&#xf14c;</i></a>.</p>

<h3 id="IdentifierField" class="no-TOC">identifier field - used within multiple instructions</h3>

<h3 id="IfSelectorField" class="no-TOC">'if' field in an else clause</h3>

<h3 id="InheritsFromField" class="no-TOC">'inherits className' field in a class</h3>
 <p>An inheritance clause, if used, must consist of the keyword <b>inherits</b>
 followed by a space and then one or more type names separated by commas.</p>

<h3 id="MethodNameField" class="no-TOC">'name' field in a function or procedure definition</h3>
 <p>A method name must follow the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>

<h3 id="ParamListField" class="no-TOC">'parameter definitions' in a function or procedure definition</h3>
 <p>Each parameter definition takes the form:</p>
 name as Type
 <p>The name must follow the rules for an <a href="#Identifier">identifier <i class="fa">&#xf14c;</i></a>.</p>
 <p>The type must follow the rules for a <a href="#TypeName">Type <i class="fa">&#xf14c;</i></a>.</p>
 <p>If more than one parameter is defined, the definitions must be separated by commas.</p>

<h3 id="ProcRefField" class="no-TOC">'procedureName' in a call statement</h3>
 <p>Valid forms for a procedure call are
 <ul>
  <li><b>call procedure</b> <el-method>procedureName</el-method>()</li>
  <li><b>call procedure</b> <el-id>instanceName</el-id>.<el-method>procedureMethodName</el-method>()</li>
  <li><b>call procedure</b> <b>property</b>.<el-id>propertyName</el-id>.<el-method>procedureMethodName</el-method>()</li>
  <li><b>call procedure</b> <b>library</b>.<el-method>procedureName</el-method>()</li>
 </ul>
<p>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.</p>

<h3 id="TypeField" class="no-TOC">'Type' field in a function or property definition</h3>
 <p>For certain Types the name may be followed by an <b>of</b> clause, for example:</p>
<code>List</code>&lt;<b>of</b> <code>Int</code>&gt;<br>
<code>Dictionary</code>&lt;<b>of</b> <code>String</code>, <code>Int</code>&gt;

<h3 id="TypeNameField" class="no-TOC">'Name' field in a class or enum definition</h3>
 <p>Type names always begin with a capital letter, optionally followed by letters of either case, numeric digits,
 or underscore symbols. Nothing else.</p>

<h3 id="ValueDefField" class="no-TOC">'name' field in a let or variable instruction</h3>
 <p>The definition for a variable instruction is most commonly
 a simple name. Less commonly, it may take the form of a deconstruction of a
 <a href="LibRef.html#deconstructList"><code>List</code> <i class="fa">&#xf08e;</i></a> or
<!-- <a href="LibRef.html#deconstructListImmutable"><code>ListImmutabl</code>e <i class="fa">&#xf08e;</i></a> or-->
 <a href="LibRef.html#deconstructTuple">Tuple <i class="fa">&#xf08e;</i></a>.</p>

<h2>Advisory</h2>

<h3 id="methodDeprecated" class="no-TOC">Code change suggested. Method was deprecated in v7.1.</h3>

<h1 id="runtime_error">Runtime errors</h1>

<h2>Messages</h2>

<h3 id="TestTimeout" class="no-TOC">Tests timed out and were aborted</h3>
<p>An error or infinite loop found in a test. Refer to <a href="#ignore">ghosting tests <i class="fa">&#xf14c;</i></a>.</p>

<h3 id="complexityWarning" class="no-TOC">Overly complex expressions</h3>
<p>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 <b>variable definition</b> instructions; otherwise it might become impossible to add more text.</p>

<h3 id="ReferenceError" class="no-TOC">ReferenceError: Cannot access '[name]' before initialisation</h3>
<hr>
<p><b>Elan Language Reference</b> go to the <a href="#top">top <i class="fa">&#xf14c;</i></a></p>
</body>
</html>
