EasyCoder documentation

    

Core commands

These commands form the core of any programming language; variables, simple arithmetic and string handling, flow control and timing.

add

add is a numeric command that adds a value to a variable or adds 2 values and puts the result in a variable. See elsewhere in this documentation for an explanation of what is meant by a value. If you add to a variable it must already hold a numeric value, but if you assign a variable to hold the result of an addition it will lose whatever value it previously held.

Examples:
add 5 to ThisValue
add X to Y giving Z

alias

alias lets you use one variable in place of another. Suppose you have a number of identical objects, where an action on the part of the user requires an action to be taken with just one of them. EasyCoder has arrays but in some cases these are already in use - and the language does not support multidimensional arrays. In such cases you will often find that using an alias will provide you with an efficient way to perform a standard set of operations on any one of the objects.

The type of the alias variable can be anything but for clarity it's best to use a variable of the same type as the one being aliased. To see alias in use, take a look at our Factory simulation.

Examples:
variable Value1
variable Value2
variable Alias
. . .
alias Alias to Value2
put `Test` into Alias ! Value2 now contains "Test"

begin ... end

begin introduces a compound statement; a block of commands that start with begin and finish with end. The entire block is treated as a single statement. end marks the end of the compound statement block.

Example:
if true
begin
add 1 to Counter
set Repeat
end

clear

clear assigns the boolean value false to a variable, replacing whatever it previously held.

Example:
clear Flag

debug

debug is a tool for examining some aspect of your script after it has been compiled. This can be useful when trying to track down obscure spelling mistakes. Anyone wanting to build a plugin to extend the features of EasyCoder will need to use debug from time to time.

You can view the entire program using debug program.

You can debug the single program item at a given program counter address, using debug program item {pc} or debug program pc {pc}.

You can show the entire symbol table using debug symbols.

You can look at a single symbol using symbol {name}.

You can use debug step to cause the running program to display the name of the script (assuming the script command has been given) and the program counter, for every step of the running program.

Examples:
debug program
debug program pc 12
debug script
debug symbol Count
debug step

decode

decode performs a decoding operation on a text value, as defined by set encoding. The default encoding translates single and double quotes into special character sequences and is mainly for use when storing HTML or other data in your own database using EasyCoder's REST server.

Example:
decode Content

divide

divide is a numeric command that divides a variable by a value or divides one value by another and puts the result into a variable, overwriting its previous contents.

Examples:
divide Value by 5
divide Items by Count giving Length

encode

encode performs an encoding operation on a text value, as defined by set encoding. The default encoding translates single and double quotes into special character sequences and is mainly for use when storing HTML or other data in your own database using EasyCoder's REST server.

Example:
encode Content

fork

fork is a special kind of goto, that causes the program to execute from the given label, but also continues executing at the next command. The multitasking implied in this is handled by EasyCoder. JavaScript programmers will know that the language can only handle a single thread so a cooperative technique is used internally to create the illusion of true multitasking.

Example:
fork to Concurrent
...
Concurrent:
alert `Arrived at Concurrent`

go to, goto

go to and goto transfer control to the label named. The command(s) following the go/goto are not executed.

Examples:
go to Next
goto Next

gosub

gosub is also like go in that it transfers control to the named label. However, when the program encounters a return command, execution resumes at the command following the gosub.

Example:
gosub CountThisValue

if

if tests the condition that follows. If the result is true then control resumes at the named label; otherwise if there's an else section this is executed, then the program resumes at the next instruction after the if. (Unless a goto was encountered as in the example.)

Examples:
if Value1 is greater than Value2 put true into Result
if Remaining is 0 stop
else go to Repeat

import

import is part of a mechanism by which programs are broken up into separate modules that run independently. This lets you a) write smaller programs, b) separate parts of the program that don't interact much and c) include code downloaded as a plugin.

The import command sets up a list of variables that are required to be exported by the calling module. This list must match in both number and type, though you can use different names for the variables on each side.

By handing over variables to another module you are allowing it to work on them independently of your own code. However, variables are not truly shared; the system makes copies of them and tries to keep them in sync but you should avoid having a situation where 2 or more modules are likely to alter the value of a shared variable. Try wherever possible to view the imported variables as constant, fixed values provided solely for the information they contain.

Also bear in mind that after you import a variable its value may change if the calling script goes on working concurrently with your script. Again, this is a situation that should be avoided if possible.

Example:
import variable Count
and div Items
and button SortButton

index

index is a special command for array handling. In EasyCoder, all variables are arrays. Initially they only have one element but you can set an array to have as many elements as you like, using set the elements of {variable} to {value}. Inside each array is the current index for the array, which you can set to any value within the number of elements in the array. The array is still used as if it were a simple variable and only the element pointed to by the index is affected by whatever you do with the array. Where multitasking is used - with fork or by handling an event - you must be careful to set the index before using the array if there's any chance it may have been modified by another part of the program.

Example:
index List to 5
put Result into List

load

load currently has just one purpose; to load an EasyCoder plugin module prior to running a script that requires its functionality. Until the plugin is loaded, using any of its script commands will cause compilation errors. This feature of EasyCoder avoids the need for all modules to be loaded up-front, which improves the start-up time. It also permits pages to use functionality in a dynamic manner, which can be important in the planning of large single-page websites.

To use this feature you need to do a little setting up. See the documentation for plugins.

Example:
load plugin ckeditor

module

module defines a special kind of variable whose job is to hold information about a script module that has been run from the current script. See also run.

Example:
module EditorModule

multiply

multiply is a numeric command that multiplies a variable by a value or multiplies one value by another and puts the result into a variable, overwriting its previous contents.

Examples:
multiply Color by 256
multiply Result by 2 giving DoubleResult

negate

negate returns the value of the given variable subtracted from zero.

Example:
negate Count

on

on defines what happens when an event occurs. The only event currently handled here is trigger but there are more event handlers in the browser package. A trigger is sent by one script module to another as a signal that it should do something. What that something should be is up to the programmer to decide; the key factor is that the event has occurred.

Example:
on trigger go to StartMeUp

print

print evaluates what follows and writes it to the browser console. Use it for debugging.

Example:
print `The counter is now ` cat Counter

put

put evaluates what follows and puts it into the named variable, overwriting whatever was previously there.

Examples:
put 59 into Value
put Value1 into Value2
put `Some data` into MyData

replace

replace replaces all occurrences of one piece of text with another, in the given variable.

Examples:
replace `dog` with `cat` in MyPet
replace Search with Replace in Text

return

return marks the end of a subroutine - see gosub above.

run

run causes a second script module to be loaded, compiled and run. The syntax is

run {variable} [with {exports}] [as {module}]

where
{variable} is a variable containing the full URL of the script file
{exports} is an optional list of exported variables. These will need to match the list of imports in the loaded script.
{module} is an optional variable holding the module reference. You'll need this if you want to send a trigger.

Examples:
run Ticker
run Helper as HelperModule
run Editor with variable MainText and variable Index and div Panel as EditModule

script

script lets you name the module; useful when debugging multiple scripts.

Examples:
script Main
script EditorModule

set

set is probably the most heavily used command in EasyCoder. You'll find variations of it in most of the plugin modules. Here in the core module it doess all the following:

-- assigns the boolean true value to the named variable.
-- assigns an array of constant data to a variable.
-- converts a variable to an array, assigning the number of elements.
-- sets the encoding/decoding method. The default is 'ec', which encodes single and double quote characters; you can also have 'url', which performs standard URL-encoding and decoding. Once set the value is kept for the session.

Examples:
set Flag
set Squares to 1 4 9 16 25 36 49 64 81 100
set the elements of ThisVariable to 10
set the encoding to `url`

stop

stop causes the current program execution thread to halt. Other threads may continue and the program will still respond to events.

take

take is a numeric command that subtracts a value from a variable or subtracts one value from another and puts the result into another, overwriting what was previously there.

Examples:
take 2 from Count
take Small from Big giving Value

toggle

toggle converts the boolean value held in a variable from true to false or vice versa.

Example:
toggle Flag

trigger

trigger sends a prompt to a compiled script module to trigger whatever actions are programmed. You can trigger a module you started using run or you can trigger the parent module of the one you're in.

Examples:
trigger Editor
trigger parent

variable

variable defines a variable, that can hold a numeric, boolean or string value. Initially it contains none of these; a value must be assigned (e.g. using put) before the variable can be used. If a variable is defined to be an array with more than one element, each element can hold a different type (numeric, boolean or string).

Examples:
variable Flag
variable Count
variable Name

wait

wait causes program execution to stop for a given time, expressed in millis, ticks, seconds or minutes. A milli is a millisecond and a tick is 10 milliseconds. The default is seconds. Only the current program thread stops; others may continue and events will still be handled.

Examples:
wait 5
wait 10 mills
wait Count ticks
wait 1 minute

while

while tests a condition, and if the result of the test is true it executes the command (or begin...end block) that follows. It then repeats the test and continues to do so until the test fails.

Example:
put 0 into N
while N is less than 10
begin
gosub DoSomething
add 1 to N
end

When constructing loops like this it's common for programmers to forget to bump the loop counter, resulting in a tight loop that can bring the browser - and the computer - to its knees and risk overheating of the CPU in the process. It's surprisingly easy to get this wrong during development! EasyCoder detects when this happens and stops your script before any harm can be done.