Keywords

Variables

Declaration / Creation

Variables are created with static types, and must be declared before attempting to use them.

Syntax

bool <name>
Creates a variable with a value of false, and type boolean.

number <name>
Creates a variable with a value of 0, and type number.

string <name>
Creates a variable with a value of "", and type string.

group <name>
Creates a variable with a value of [], and type group.

var <name>
Creates a variable with no value, and type undefined. This will create a warning on declaration. var-declared variables will take on the type of the first assigned value.

(deprecated) declare var <name>

Examples

//Creates a string variable called `name`
string name

//Creates a number variable called `age`
number age

Deletion

delete Deletes a variable, allowing redeclaration.

Syntax

delete <variable>
Deletes the specified variable.

Example

string name

\name\
//=> ''

//Deletes the variable 'name'
delete name

\name\
//=> Error 'Variable 'name' does not exist!'

Value Setting

set Sets a variable's value.

Syntax

set <variable> <value>
Sets the specified variable's value to the specified value.

set <variable>
Sets the specified variable's value to null. Acts as a redeclaration.

Example

string name

\name\
//=> ''

//Sets name to "Robert"
set name "Robert"

\name\
//=> 'Robert'

Addition

add Adds to or concatenates a variable's value with another value.

Syntax

add <variable> <value>
Adds the specified value to the specified variable's value.
If one or more of the values are strings, the values will be concatenated instead.

Example

number a
number b
number result

set a 10
set b 20

//Add the numbers to the result (which is default zero)
add result \a\
add result \b\

\result\
//=> 30

Subtraction

subtract Subtracts a number from a variable's value.

Syntax

subtract <variable> <number>
Subtracts the specified value from the variable's value.

Example

number a
number b
number result

set a 10
set b 5

//subtract b from a
set result \a\
subtract result \b\

\result\
//=> 5

Multiplication

multiply Multiplies a variable's value by a number.

Syntax

multiply <variable> <number>
Multiplies the specified variable's value by the specified number.

Example

number a
number b
number result

set a 4
set b 5

//multiply a and b
set result \a\
multiply result \b\

\result\
//=> 20

Division

divide Divides a variable's value by a number.

Syntax

divide <variable> <number>
Divides the specified variable's value by the specified number.

Example

number a
number b
number result

set a 30
set b 5

//divide a by b
set result \a\
divide result \b\

\result\
//=> 6

Rounding

round Rounds a variable to the nearest integer.

Syntax

round <variable>
Rounds the specified variable to the nearest integer.

Example

number a
set a 4.25

\a\
//=> 4.25

round a

\a\
//==> 4

Negation

negate Sets a variable to its negative value. e.g. 1 becomes -1, -3.2 becomes 3.2.

Syntax

negate <variable>
Negates the specified variable.

Example

number a
set a 7

\a\
//=> 7

negate a

\a\
//==> -7

Exponentiation

exponent Raises a variable's value to the power of a number.

Syntax

exponent <variable> <power>
Raises the specified variable's value to the specified power. e.g. exponent x 2 would square x.

Example

number a
number b
number result

set a 2
set b 10

//raise a to the power of b
set result \a\
exponent result \b\

\result\
//=> 1024

Inverse Exponentiation / Roots

root Sets a variable's value to the specified root of its current value.

Syntax

root <variable> <root>
Sets the specified variable's value to the specified root of its current value. e.g. root x 2 would square root x.

Example

number a
number b
number result

set a 64
set b 3

//get the bth root of a
set result \a\
root result \b\

\result\
//=> 4

Functions

Function Creation

function can be used to create a function, a block of code that can be called multiple times in one program, and optionally take parameters. end Ends a function declaration.
Technically, these functions are procedures, as no values are, or can be, returned.

Syntax

(deprecated) declare cmd <name>
function <name> [parameters]
Starts a function with the specified name and parameters.
end <name>
Ends the specified function declaration.

Parameters

Each parameter is declared as name:type, for example divisor:number, where the parameter divisor is created as a number. The parameter can then be accessed just like a local variable, but read-only. Parameters take precedence over variables.

Example

//Create the function 'log_sum'
function log_sum a:number b:number
number result
set result \a\
add result \b\
log \result\
//End the declaration (important!)
end log_sum

//See next section
execute log_sum 4 6
//logs '10'

Function Execution

execute Runs a function, then returns to the line number it was called from, and continues as normal.

Syntax

execute <name> [arguments]
Runs a function with the specified name, passing in the arguments to be used within the function as parameters..

Accepted Labels

default Uses the default for each type as the parameter, i.e. 0 for number, blank string for a string, etc.

Example

function log_sum a:number b:number
number result
set result \a\
add result \b\
log \result\
end log_sum

//Execute the function 'log_sum', passing in 4 and 6 as a and b, respectively.
execute log_sum 4 6
//logs '10'

Flow Control

Jumping to a Line

jump Jumps to a line number.

Syntax

jump <line>
Jumps to line line.

Relative Line Numbers

~<number> can be used to indicate relative line nmbers, e.g. ~2 indicates 2 lines ahead.

Example

log "I'm running!"
jump ~2
log "I'm skipped!"
log "I'm running!"
//logs "I'm running" twice

Stopping Execution

stop Halts execution of the program. It's good practice to put a stop statement at the end of a program, and use jump or restart to make loops, rather than let the interpreter roll over.

Syntax

stop
Stops the program.

Example

log "I'm running!"

//Stop the program.
stop

log "I'm never reached."
//logs "I'm running!"

Restarting Execution

Stops execution, then starts it again at the same speed.
Restarts from line 1, with all variables cleared.

Syntax

restart
Jumps to line 1, and deletes all local variables.

Accepted Labels

non-destructive Does not delete local variables. Instead, marks them as re-declareable.

Example

log "I'm running!"
flush

//Restart the program.
restart

log "I'm never reached."
//logs "I'm running!" infinitely.

Pausing Execution

pause Pauses execution of the program.
Does not alter line number or local variables, just simply stops execution.

Syntax

pause <timeout>
Pauses execution for the specified number of instructions.

Example

log "I'm running!"

//Hold the program for 100 instructions.
pause 100

log "I'm running!"
//logs "I'm running!", and then "I'm running!" much later.

Changing Run Delay

rundelay Changes the interpreter's execution speed. Has no effect until restart is used.

Syntax

rundelay <delay>
Sets the delay to the specified number of milliseconds.

Example

log "I'm running!"
flush

//Hold the program for 100 instructions.
pause 100

log "I'm running!"

rundelay 10
//logs "I'm running!", and then "I'm running!" much later. The next time, the two messages will be (approximately) one second apart.

Conditional Statements / Selection

if Runs an ISL statement if the condition is met.

Syntax

if <value1> <comparator> <value2> <code>
Runs the code code if the condition is met. code can be any valid ISL code string.
Condition is made with value1, value2 and the comparator.

Valid Comparators:

• = Checks equality. Checks if value1 is the same as value2.
• < Checks if value1 is less than value2.
• > Checks if value1 is greater than value2.
• != Checks inequality. Checks if value1 is different to value2.
• in Checks if value1 appears in value2, either as a substring, or a group element.
• !in Checks if the value1 does not appear in value2.

Chaining

if can be chained indefinitely by placing the next statement as the code of the last, and all conditions are checked at once.

Groups and the in operator

The in operator can take a list or group of items to check exactly against. These groups are denoted by square brackets, and each item is separated by a vertical pipe |, i.e. [item1|item2|"item 3"].

Examples

string validFruits
set validFruits ["apple"|"banana"|"orange"|"lemon"|"lime"]
string userInput
//(Get user input)

//Check if userInput is in validFruits, and if so, skip the next line.
if \userInput\ in \validFruits\ jump ~2
log "Invalid fruit!"
log "Valid fruit."
stop

number minAge
set minAge 16
number userAge
//(Get user input)

//Check if userAge is over 16, and if so, skip the next line.
if \userAge\ > 16 jump ~2
log "You must be 16 or older to continue."
log "You may pass."
stop

IO

[!] Some IO ISL might not be entirely constant on different implementations and environments, make sure to use metatags to tell the user the right environment for your program.

Message Logging

log Logs a message to the interpreter's console.

Syntax

log <message>
Logs a message to the interpreter's console.

Examples

Most programs in this document

log "I am ""a console ""message"

//logs "I am a console message"

log "I am "
log "a console "
log "message"

//logs "I am 
//      a console 
//      message"

Awaiting Key Presses / Keyboard Input

awaitkey Sets a variable to the next key pressed. Pauses until a key is pressed.

Syntax

awaitkey as <variable> [type] Listens for a key press, then manipulates the specified variable with it.
type can be set or add, default is set

Example

string input
log "Press R to continue, press anything else to stop now."
awaitkey as input
if \input\ != "r" stop
//other code
stop

Getting Key Presses / Keyboard Input

getkeys Sets a variable to all currently pressed keys, joined as one string. Does not pause execution.

Syntax

getkeys as <variable> [type] Gets all pressed keys as a string, then manipulates the specified variable with it.
type can be set or add, default is set
Pressed keys are given as a comma-separated string, e.g. holding 'a', 'b', and 'c' gives a,b,c.

Accepted Labels

grouped Gives keys as a group: [...|...]

Example

number x
number y
string input
log "Use WASD to move."
flush
//Get held keys
grouped getkeys as input
if "w" in \input\ add y 1
if "s" in \input\ subtract y 1
if "a" in \input\ subtract x 1
if "d" in \input\ add x 1
log "You are at: "\x\", "\y\
non-destructive restart

Prompting / Text Input

popup-input Opens the browser's default prompt popup, and assigns a variable to the input.

Syntax

popup-input as <variable> <prompt>
Opens a popup with the given text to give input. Once the input has been processed, sets the variable to the given value in the prompt.

Program Interface

In- and Exporting

import Sets a local variable's value to an external one.
export Sets an external variable's value to an internal one.
For security, the ISLInterpreter.allowExport and ISLInterpreter.allowImport options can be set to false to disable exporting and importing, respectively.
Both import and export can only access properties of ISLInterpreter.communication.

Syntax

export <as|to> <local-variable> <external-variable>
With to: Changes the specified external variable to the value of the specified local variable.
With as: Creates an external variable with the specified name, and a default value taken from the specified local variable.
import <as|to> <external-variable> <local-variable>
Changes (to)/Creates (as) the specified local variable with/to the value of the specified external variable.

Example

In host JS file:

//interpreter creation with ISLInterpreter.allowExport and ISLInterpreter.allowImport true and ISL loading
var name = "Robert"
interpreter.startExecution()

In the ISL program:

string ext_name
//Import the 'name' variable to 'ext_name'
import name to ext_name
set ext_name "Jeff"
//Export to the 'name' variable
export ext_name name
stop

Then, in a separate ISL program:

//Import name as a new variable called ext_name
import name as ext_name
log \ext_name\
//logs "Jeff"

stop

Meta Tags

Meta tags are a way of adding extra info to an ISL program, to change what the interpreter does with it.
They are always surrounded by [square brackets] and are placed alone on a line, without any keywords. They cannot have dynamic values (i.e. using \variable references\). They do not apply retroactively, so they only apply to ISL after the tag is parsed.

Requiring Extensions

If an ISL program is made with a certain extension in mind, using a require tag can make sure that all users import that extension. If the file is run with a require tag, and the interpreter doesn't have the extension, an EnvironmentError will be thrown.

Syntax

[require <extension>]
Flags that the file requires the specified extension.

Multiple Tags

Multiple require tags will check for all the extensions specified.

Example

//Require the extension 'multisl'
[require multisl]
string nameToPass
set nameToPass "Jeff"
//Use multisl to pass a name to a different interpreter and log it
create thread "worker"
in thread "worker" string name
in thread "worker" set name \name\
in thread "worker" log "\name\"
stop thread "worker"
delete thread "worker"

//logs "Jeff"

Setting Environment

Some features of basic ISL and extensions require certain environments to work, and throw errors if they're in the wrong one. However, this is only after the rest of the program has run, so can be wasteful. environment or env tags are used to declare the environment to the interpreter, so it can throw errors early.

Syntax

[environment <environment>]
[env <environment>]
Throws an error if the interpreter's environment doesn't match the specified one.

Multiple Tags

Adding this tag multiple times will require all environments at once, which is impossible, so an error will be thrown regardless.

Ignoring Keywords

ignore tags can be used to effectively 'comment out' entire keywords, and stop them being parsed.

Syntax

[ignore <...keywords>]
Adds the keyword(s) to the ignore list. Ignored keywords are passed over during interpretation. Can take a list of keywords, for example [ignore add subtract multiply divide] will ignore the keywords add, subtract, multiply and divide.

Multiple Tags

Multiple ignore tags will add all the tags to the ignore list.

Example

string name
set name "Jerry"
//Ignores any further instances of the 'set' keyword.
[ignore set]
set name "Bob"
log \name\
flush
//logs "Jerry"
stop

Changing Display Name

display tags can be used to change how the ISL file's name will be displayed, for example in errors.

Syntax

[display <...name>]
Changes the file's display name. The name can include spaces.

Preferred IPT

Instructions Per Tick (IPT) is another property of an interpreter that determines how fast a program runs, but one that ISL cannot change. The ipt tag can tell the interpreter that it should run at the specified IPT, but will only create a warning, rather than throwing an error.

Syntax

[ipt <number>]
Creates a warning if the interpreter's IPT doesn't match <number>. The warning will look something like: ''' Interpreter is running too fast: 100 IPT. Recommended speed for this file is 60 IPT. ''' This warning comes from [ipt 60] in a 100 IPT interpreter.

Strict Mode

Strict mode is a toggle that, if enabled, throws all warnings as errors, with type EscalatedError. Using the tag [strict] will enable/disable this for the following code.

Syntax

[strict]
Enables strict mode for all following code. [strict off] Disables strict mode for all following code.

Custom Tags

Every single metatag is stored as an object with the following properties:
tag: The first part. e.g. require ([require graphics]).
value: The second part, usually the value of the tag. e.g. graphics ([require graphics]).
isl: The full ISL of the tag. e.g. [require graphics] ([require graphics]).
An array of all of them can be accessed through ISLInterpreter.metatags.