Elan IDE Reference

IDE means Integrated Development Environment which, for Elan, is one browser page in which code is written and tested, and in which text and graphic outputs are displayed.

It looks like this:

# 1. Menu

At the top left of the screen is the 'menu' of commands:

Some of the options shown act like a button to perform that command directly; others, when clicked will show a drop-down submenu of further commands. Individual commands may be greyed-out if unavailable. If you use the mouse to hover over any option you will usually be shown a 'tooltip' that provides a description or information about why the option is currently unavailable.

To the right of the buttons is the name of the Elan file currently loaded. When starting afresh, it is given the default name 'code.elan'.

## Demo

If the Demo button is shown, clicking on it shows the list of available demo programs, which you may load by selecting the program name. You can then run the program with the Run button.

## File

The File button has a drop-down menu with the following actions:

### New

New clears the current code, allowing you to start writing a new program. The code editor will then show this:

# c3a9b1928be74fe1bd94ec5d2cd07c9763a1031fbefe8de4d44d76669c1ad8f6 Elan 1.1.4 guest default_profile new code main procedure function test constant enum record class abstract interface # ?

The first line shows a standard Elan 'header' comment, which is required on every code file, and which you are not able to move, edit, or delete. The second line shows the Global prompt.

### Load

Load presents you with a file selector dialog from which you can navigate to and then load an .elan file: it will be loaded in place of your current code. As with New (above) if your existing code is not saved, you will see a confirmation dialog.

The name of the file that has been loaded is displayed to the right of the buttons above the code editor.

Note: you may only load a valid Elan file, i.e. one that has been created and saved by the Elan IDE. No other type of file can be loaded: trying to do so will result in a message in the Debug display:

Cannot load file: it has been created or modified outside Elan IDE

### Append

Append, like Load, offers a file selection dialog. If you select a valid .elan file it will be appended onto the end of your current code. From there the appended code may be moved within the existing code See Editing code.

### Auto Save

Auto Save offers a file selection dialog to allow you to specify the name and location where your code will be saved. If you use this option, every time you modify the code and its parse status is 'valid' the code will be saved automatically, overriding the previous version in the file. Once this option has been selected, the File menu will offer a Cancel Auto Save option, after which you may use Manual Save, or re-select Auto Save.

Note that you may auto-save a New code file, even though you haven't added any instructions yet, because the file contains a valid header.

### Manual Save

Manual Save offers a file selection dialog to allow you to specify the name and location where your code will be saved.

Unlike Auto Save, the Manual Save option is a one-off event. You must remember to save any subsequent changes if you need them saved. As a reminder, if your existing code is not saved, you will see a confirmation dialog:

Note that for both Auto Save and Manual Save, code may be saved only when its parse status is 'valid'. It may, however, then be saved even if it does not compile or pass any tests.

### Save as Standalone

Save as Standalone permits a compiling program to be saved as a standalone Html file, which allows your application to be run without the Elan IDE. This file can be opened from your desktop, emailed to others, or installed on a web-server. When the file is opened in a browser:

- The page shows just the Display pane from the IDE, magnified to the full visible browser height but preserving the 4:3 ratio needed in case the program uses Block Graphics.
- The Elan program is run as soon as the page is opened - or refreshed. It is up to you to provide options for exiting the program or running it again, if desired.

The standalone web page includes the the program, compiled to JavaScript, and the .css for styling. The latter may be easily customised by editing the .html file directory. For example, if you wish to:

- Alter the size of the Display area, and (if Block Graphics are not used) the aspect-ratio.
- Add any text around the Display area
- Edit the title attribute for the web page

### Preferences

Selecting Preferences brings up a dialog, currently showing only one option (there will be more in future releases):

- CVD colour scheme changes the colour scheme to use colours and tones likely to be more distinct to users with CVD.

## Trim

The Trim command is used to neaten up your code: it removes any new code prompts from your code that can be removed which is typically most of them. Where a new code prompt is not removed by Trim this indicates that code is still expected in that location.

The keyboard shortcut for Trim is Alt+t. (This is because browsers use Ctrl+t to open a new tab).

## Outlining

The outlining menu command is labelled +/-. Pressing it toggles the presentation of the code between its expanded (normal) format, and an outline format, where instructions are collapsed to a single line, for example:

+main new code end main
+function binarySearch name(list as List<of String>, item as String parameter definitions) returns Boolean Type return true expression end function +test optional description new code end test +constant example name set to "example"literal value or data structure

Any collapsed instruction may be expanded individually by double-clicking on the + sign next to it. The background colour for the + shows the status of the code that is currently hidden so that you may easily find the parts of code that contain issues.

## Undo & Redo

The Undo command allows you to undo recent change(s) and go back to the last point at which the code parsed as 'valid' – you cannot go back to any state when the code was still parsing as 'incomplete' or 'invalid'. You may apply Undo repeatedly, to go back through all parse-valid states of the code since you loaded the code, or started from New. Use the Redo command to revert the last Undo if you went back too far.

The keyboard shortcut for Undo is ctrl+z, and for Redo is ctrl+y.

# 2. Code editor

The main pane within the IDE is the 'code editor'.

When entering, editing, or just navigating (browsing) through, different sections of code will be highlighted at two different levels: whole instruction(s) or an individual field within an instruction.

### Instructions

The following show examples of instructions being highlighted.

Here a single instruction is highlighted: variable grid name set to new Array2D<of Int>(40, 30, white)expression call fillRandom procedureName(grid arguments) +while true condition call displayBlocks procedureName(grid arguments) call nextGeneration procedureName(grid arguments) call pause procedureName(50 arguments) end while

Here a container instruction is highlighted. The highlight shows the full extent of the instruction, indicating the sequence of other instructions that it contains, which are all indented by two spaces:

variable grid name set to new Array2D<of Int>(40, 30, white)expression call fillRandom procedureName(grid arguments) +while true condition call displayBlocks procedureName(grid arguments) call nextGeneration procedureName(grid arguments) call pause procedureName(50 arguments) end while It is also possible to select multiple instructions (to move, or delete them, together), for example: +while true condition set g variableName to g.withText(x, y, "*", red, black)expression call g.display procedureName(arguments) call pause procedureName(100 arguments) set g variableName to g.withBlock(x, y, black)expression let dir name be randomInt(0, 3)expression set x, y variableName to updateCoordinates(x, y, dir)expression end while The following example shows a single instruction that has been formatted over multiple lines – either because it is too long to fit on one line, or because the editor formats that instruction over multiple lines for readability. Note that the second and subsequent lines are indented by just one space: let b name be new CircleVG() with
cx set to i*5 + 2,
cy set to 75,
r set to 1,
fill set to -1,
stroke set to white expression

### Fields

Instructions consist of fixed (or 'templated') code – keywords and sometimes symbols – plus a number of 'fields' which is where you enter code that define specific details for that instruction. When the field is highlighted it will be highlighted with a background colour and a thin black border. This indicates that you may now enter or edit code in that field, for example:

variable name set to x expression

A green background (as above) indicates that the text in field is valid for that field. An amber background indicates that the text is not complete but that additional text could be added to make it valid. Commonly, the field will contain a prompt that suggests what else might be needed, and/or a drop-down list of 'symbols' that might be valid for the field – though it is not guaranteed that all those options will then compile:

variable x name set to expression expression

A red background indicates that the contents of the field are not valid for that field. In the following example a variable name cannot contain a bracket:

variable y(name set to 15 expression

If a field background turns red as you type, it is best to hit Backspace until it goes green or amber again, so that you can identify the first character that caused the issue.

If the background to a field is grey, it means that that field is optional – you may enter valid text or move on to the next field, or the next instruction.

## Adding Instructions into a program

At various places in the code you may see a new code prompt, for example:

+main new code end main
new code

which indicates that new instruction(s) may be created there. When the line containing a new code prompt is given focus it changes form to show the list of instructions that you may insert, for example, within main:

new code call each for if let print repeat set variable while # or, outside main: new code procedure function test constant enum #

### Using a prompt to insert a new instruction

When a new code prompt has focus (for example as shown above) in most cases you can type just the first character of the instruction to be inserted. And you will then see the template for that instruction including any mandatory and/or optional fields. For example, given the initial list shown above, typing f will result in this being inserted:

+function name name(parameter definitions) returns Type new code return expression end function new code

Note that when an instruction is inserted is is followed by a new code prompt, and if, as in the example above, the inserted instruction template is for a container instruction then the template will contain its own new code prompt for inserting further instructions within it.

Where two or more instruction start with the same letter(s) typing the initial letter will filter the options. For example, if the initial list were:

new code call each for if let print repeat set throw try while variable #

then after typing t you will see:

t new code throw try

and the desired instruction can be selected by then typing the second character (h or r). In the following example, starting from this Member prompt:

Note that some of the keywords in this particular prompt are presented only when the Advanced level coding option has been selected from menu File → Preferences.

### Why do the options I can see differ from those shown here?

The specific list offered may depends upon various factors including:

- The specific context where the new code prompt is located
- What other instructions already exist in that context

which means that you won't necessarily see all the instructions shown in this explanation. However, in general there are three distinct forms of new code prompt: the global prompt, the statement prompt, and the member prompt.

### Global prompt

The global prompt appears only at 'global' level – in other words when the new code prompt is located directly within the file, rather than within container instruction. When given focus, it will list the global instructions that you may insert. This is the full list:

new code main procedure function test constant enum record class abstract interface # ? Note that main will not be shown if the program already contains a main routine.

### Statement prompt

### Member prompt

### What if there is no new code prompt shown where you want to insert an instruction?

If you want to insert new instructions in a place where there is no new code prompt, then either:

- select the instruction immediately before where you want the new instruction and press Enter or
- select the instruction immediately after where you want the new instruction and press Shift+Enter

### How to remove unneeded new code prompts

### # Comments

All prompts, include new code, include a # to insert a comment.

## Navigation – using the keyboard

Note for Apple Mac users: commands that use the Ctrl key in this reference should use the macOS ⌘ Command key instead.

Keystroke | On a selected Frame | On a selected Field
--- | --- | ---
Home | First peer-level frame. | Move text cursor to start of field.
End | Last peer-level frame. | Move text cursor to end of field.
Tab | First field in frame. | Select next field within frame or, if from last field in a frame, select the frame itself. (If the field has a selected option in the auto-complete popup list then Tab will use that option – the same as Enter)
↑ | Select previous frame (within peer-level only). | Select previous frame (in tab order).
↓ | Select next frame (within peer-level only). | Select next frame (in tab order).
← | Select parent frame (if any). | Move text cursor left within field.
→ | Select first child frame (if any). | Move text cursor right within field.
Shift+↑ | Add previous frame (peer-level) to current selection. | If auto-complete options are offered (drop-down list), move the selection down one in the list. (See also Enter)
Shift+↓ | Add next frame (peer-level) to current selection. | If auto-complete options are offered (drop-down list), move the selection up one in the list. (See also Enter)
Esc | Escape from the code editor, and put focus on the first Button in the IDE |
ctrl+o | Toggle (expand/collapse) outlining on selected frame. | Toggle (expand/collapse) outlining on the frame enclosing this field.
ctrl+O ctrl+Shift+o | Toggle (expand/collapse) outlining on all frames. | Toggle (expand/collapse) outlining on all frames.

## Editing code

Keystroke | On a selected Frame | On a selected Field
--- | --- | ---
Alt+t | Remove all new code prompts that can be removed. This is equivalent to clicking on the Trim button. (This cannot be ctrl+t as that is defined and executed by the browser).
Backspace | On any new code prompt: delete the prompt. (Note that all new code prompts can be removed with the +/- button above the code pane). On a new, unmodified, frame, or from any unedited field within that new frame: delete the whole frame and go back to the prompt. This capability is to facilitate deleting a frame created unintentionally. As soon as any field has been edited, or any child frame added – the frame can only be deleted using ctrl+Delete (see below). | Delete character to the left of the cursor.
Delete |  | Delete the character to the right of the cursor.
ctrl+Delete or ctrl+d | Delete the selected frame, including any frames within it. |
Enter | Insert a new code prompt frame below the selected one, at peer level – if permissible. | If auto-complete options are offered (as a drop-down list), enter the selected option into the field. Otherwise, move to the next field (in the same frame) – like Tab. For last field in frame only: insert 'new code' after this field.
Shift+Enter | Insert a new code prompt frame above the selected one, at peer level – if permissible | -
ctrl+↑ | Move selected frame(s) up, within peer level. | -
ctrl+↓ | Move selected frame(s) down, within peer level. | -
ctrl+← |  | Move the cursor to the end of the next 'word' or other transition
ctrl+→ |  | Move the cursor to the end of the next 'word' or other transition
ctrl+x | Cut selected frame(s) into the scratchpad | Cut any selected text from the field
ctrl+v | Paste text from the clipboard into the field, at the cursor. | On a selected new code prompt: Paste the frame(s) added to the scratchpad in place of the 'new code' field. If any of the frames to be added is not compatible with the content of the 'new code' field then no action will take place.
ctrl+b | Insert or remove a breakpoint on the frame |
ctrl+i | Toggle the ignore setting of a test |
ctrl+m | Open menu of help options |
ctrl+p | Toggle the private status of members property, function or procedure of a class |
ctrl+y | Redo last undo provided that the code you undid from was parsing successfully |
ctrl+z | Undo last edit Takes you back to the next most recent version that parsed successfully. Any changes made that did not result in a successful parse will be lost. |

#### Notes

- A literal string may contain any characters except " (which would terminate the string) and { or } which are used to define 'interpolated' fields. If you want to include those specific characters literally see Special characters. Similarly you can copy from elsewhere and paste into a literal string provided only those valid ASCII characters are included.
- If a literal string includes \n this will result in a newline being inserted when the string is printed. However a \ ('backslash') followed by any other character than \ will be printed literally as the two characters.

## Mouse operation – quick reference

- To select a frame, click on the keyword at the start the frame. (You can successfully click in several other places within the frame, but the simplest rule to remember is click on the starting keyword).
- To select an additional frame ('multi-select'), hold down the Shift key on the keyboard and click on the frame to add to the current selection. Note that all the multi-selected frames must be at peer-level (the same level of indentation) and, unless global frames, must be within the same 'parent' frame.
- To select a field, click on the text (or, if empty, the prompt) shown for that field. Having selected the field, you may then click again at a particular place within the text to position the text cursor. (By default, when a field is selected the text cursor will be at the right-hand end of any existing text).
- To collapse a multi-line frame, double-click on the keyword at the start of the frame
- To expand a collapsed frame, double-click on the keyword at the start of the frame (or the '+' symbol in front of it).

## Context menu

When an instruction is highlighted, you may right-mouse-click on it, or type ctrl+m to bring up the context menu, for example:

Note that several of the options show a keyboard shortcut – which you may use just by selecting the instruction and pressing the specified keys without having to bring up the context menu.

# 3. Controls

## Run controls

The top two buttons shown here are the initial 'run controls':

- Run This is the normal way to run the program. It will run at full speed, ignoring any breakpoints, and is the most efficient in terms of memory usage.
- Stop When a program is running, or is paused, this button will stop and exit the program.

When the Debug button is clicked, the lower three buttons provide further run controls:

- Debug Run in 'debug' mode. See Debugging
- Pause Pause the program (if running in debug mode). See Debugging
- Step From a paused state, execute the next instruction only and pause again. See Debugging

## Help

The Help button offers links to online documentation:

- Reference Manual: drop-down menu to access the reference manuals.
- Other Help: drop-down menu to access other resources.

Each link will open in a new tab in the browser so that you don't lose your current work.

Note that the Context Menu opened on a selected instruction offers a direct link to help concerning that specific instruction.

As with the main Help menus, the documentation will open in a separate browser tab.

## Display

The Display button switches to the program's output display.

Below the pane is provided button Clear display.

## Debug

The Debug button switches to debugging mode, showing the Debug, Pause and Step buttons to control debugging.

## Worksheet

The Worksheet button opens buttons Standard worksheets and Load external worksheet to provide training materials.

# 4. Status

## Status panel

The status panel shows the current status of four conditions:

- Parse: this indicator aggregates the parse status of each field and shows the worst status of any field. It is important to get the Parse Status to green ok at the earliest opportunity because, unless the parse status is green ok, Elan cannot attempt to compile the code. Nor can it save the code to a file, when the parse status is amber incomplete or red error.
- Compile: if the parse status is green ok, Elan will attempt to compile the code.
- Test: 'pass' or 'fail' of the tests in the code
- Run: 'running' to indicate the code is executing

Here are examples of the status display:

Each of the four status bars may appear with a green, amber, or red background – with a superimposed word to clarify the meaning. Alternatively the bar may be replaced by the blue background, with no text, indicating that that particular status is not relevant at present.

If the Parse, Compile, or Test status shows amber or red, you can click on that status bar to highlight the first location in your code where the status shown was identified.

# 5. Display

## Help display

The chosen documentation file is shown here.

## Program output display

The Display button switches to the program's output pane which is blank initially, but when the program is run it shows its text and graphics output.

For example, here is the block graphics output from the demo program maze-generator.elan:

This Display pane is always rendered with an aspect ratio of 4:3 so, if the size of the browser window is changed, the pane will change its dimensions also.

The pane is used for the following purposes, on their own or in combination:

- to display plain text or formatted Html, using the print instructions and print procedures.
- to input text from the keyboard using various system methods.
- for Block graphics (as shown in the 'maze' example above)
- for Vector graphics
- for Turtle graphics

Any of the three forms of graphics may be overlaid with printed text or Html, or each other, with the one exception that Turtle graphics and Vector graphics may not be used together – as the former makes exclusive use of the latter.

The Clear display button clears all of contents of the Display pane, irrespective of the mechanism by which it was generated. However, the individual forms of display listed above may be cleared individually using specific methods (see the links above).

## Debug display

The Debug display pane shows only messages generated by the Elan system. They are of three forms:

- Feedback on a user action, for example: Paste Failed: Nothing to paste
- Runtime error messages, as shown in the screenshot above. Following the error message (the first two lines), you may also see a 'stack trace', the topmost line of which indicates the routine (function, procedure, or main) in which the error occurred. If it is not obvious which instruction within the routine caused the error, you can use the Debugging facilities.
- Status of all variables, whenever program execution is paused. See Debugging

If the information presented exceeds the space available for the pane, a vertical scroll bar will be shown.

## Worksheet display

The chosen worksheet is shown in the Display pane.

# Debugging

## Debug tools

Elan contains some simple debugging tools. To use these tools, you need to run the program via the Debug button). Note that because of the additional overhead involved in debugging, the program may run slower than when run normally.

When debugging, a program may be paused at any point with the Pause button. The Run status will then show as paused. Note, however, that:

- the Pause button is not active if the program is currently waiting for a user input.)
- it is not possible to pause within a loop that is executing very fast. For that you should use a breakpoint (below)

## Variables dump

Whenever the run status is shown as paused , the instruction that would have been executed next will be highlighted with an amber background, and the System info will display the current value of each named value that is defined in the current scope, for example:

From the paused state, you may continue execution of the program by clicking the Debug button, or you may execute just the next instruction by clicking the Single step button.

## Breakpoints

You can place a breakpoint on an instruction, by selecting the instruction and then hitting ctrl+b, or by bringing up the Context menu and selecting set breakpoint. The breakpoint will be shown as a red flash adjacent to the instruction:

+if len > 1 condition then let mid name be (len/2).floor()expression 🗲let frontHalf name be mergeSort(li[..mid])expression let backHalf name be mergeSort(li[mid..])expression set result variableName to merge(frontHalf, backHalf)expression end if

Pressing ctrl+b on a selected instruction that already has a breakpoint will clear that breakpoint. The context menu also offers options to clear a breakpoint that has been set, or to clear all breakpoints from the program in one go.

Breakpoints are active only when running the program via the Debug button. Then,whenever a breakpoint is reached, execution will be paused, and the instruction containing the breakpoint will be highlighted with an amber background:

+if len > 1 condition then let mid name be (len/2).floor()expression 🗲let frontHalf name be mergeSort(li[..mid])expression let backHalf name be mergeSort(li[mid..])expression set result variableName to merge(frontHalf, backHalf)expression end if

and the Debug pane will display the current value of each named value that is defined in the current scope.

Elan IDE Guide go to the top