HAM RUNTIME SYNTAX FOR EHAM

Info: EHAM files are the standard format for the Ham Runtime environment and have their own syntax. This document will show you some of the functions it can perform. EHAM can be bundled with other resources into HCF files which are essentially binary applications.

Syntax is the structure that helps form programs. Like grammar, it dictates where text should be and how it should be formed.

The Ham Runtime environment is the program that allows EHAM programs to be made and run. The compact library editor extra is used to make and edit HCF programs.

SYNTAX AND FORM

All header functions must be on a new line, all functions in this document are header functions unless specified. The phraser will only search for functions (commands) on the first word of a line. All functions must be flush with the left hand side of the page with no spaces between the start of a line and the first word.

The functions in this document require the LBL mode of the runtime to be activated. If you do not know what this is then disregard it as it is enabled by default. DLG mode may be disabled for use with these commands but is recommended to be enabled so that admin commands can be accessed. Again, if you do not know what this is then disregard it as it too is enabled by default.

Notepad++ is recommended as the code editor for the runtime, we have built language xml files for use in notepad++ for syntax highlighting. You can find these files in %ham%/Extra/LANG/ .

BASIC FUNCTIONS

namespace+ [variable name for namespace] - adds a new namespace to perform functions, every program must have at least one namespace. Namespaces are comparable to objects in other languages. Example: namespace+ global.space

set [varname] [value] - sets a variable to a value. If being used to catch a value from a line below the syntax is: set [varname]= without a space after the ‘=‘ sign. Variable names may not have spaces. Example: set name “bob”

end - ends a program. with ([name of namespace]) { [function] } – tells a

namespace what to do. Example: with (global.space) { end } { and } are code block delimiters. ‘#’, ‘;’ and ‘!’ are comment delimiters, ‘~’ is a multil ine

comment delimiter. code – used when there is not a function for something,

input is raw ham code.

BASIC FUNCTIONS PT1

include <[fi le to include (EHAM)]> - Includes (+exec) a fi le in the main program. The fi le must be EHAM format.

exec <[fi le to execute]> - Executes a fi le. The fi le must be raw HAM format.

[id] script+ <[fi le to include],[EHAM?]]> - Adds a fi le as a script in the program for later calling. The fi le can be either raw HAM or EHAM (indicated with the ,1 tagged onto the end of the include section.) Returns a script ID.

script <[script to execute]> - Executes a previously included script.

[id] object+ <[object to include],[EHAM?]> - Adds an object to the program. The object can be raw HAM or EHAM.

ret <[return]> - returns a variable to the parent script. [ret] grab – grabs a returned variable and passes it to the

line above.

BASIC FUNCTIONS PT2

repeat [number of times] { [code] } – Repeats an instruction a set amount of times.

wait [time] – pauses all operation in the runtime for the set amount of milliseconds.

message <[string]> - Shows a message.question <[string]> - Shows a yes/no question,

returns 1 if yes is pressed.spawn <[x],[y],[object id]> - Spawns an object at the

coordinates [x,y]

BASIC FUNCTIONS PT3

VARIABLE TYPES

There are 2 main types of variables; Global variables which can be accessed by all namespaces and scripts within the same program and Local variables which can only be accessed within the namespace and script it is in.

Global variables are identified by the prefix global. on the variable name. Local variables are identified with either no prefix or with the local. prefix.

Inside of these classes of variable there are 2 other variable types; strings and reals. Strings are non-numerical characters (not numbers) and can be identified by the quotes surrounding the text. The delimiters for strings are “ ” and ‘ ’. Having 2 types of quotes is important because you can not nest the same quotes inside of each other. Reals are numerical characters (numbers) and have no delimiters.

VARIABLE TYPES PT1

Variables can be changed between the state of string and real with the non-header functions string([real var]) and real([string var]). Equally you can define a global variable as a local variable but it will be a copy of the global variable.

Strings can be joined together with the + symbol.Reals can be expressed with the mathematical

symbols ‘/’,‘*’,‘-’ and ‘+’. The syntax for this in the set command would be: set [var name][mathematical operation] [value], example: ‘set countvar+ 1’.

VARIABLE TYPES PT2

LOGIC

Logic is the main part of any program, it checks to see if a condition is met and performs an action based on the result. A basic check for this would be: if [condition] { [function if true] } else { [function if false] }

Conditions are formed like the following: [varname] = [value] OR [function name] = true.

Conditions can be lumped together with the following functions: and (&&) or (||) not (!)

Example: if global.name = “bob” && some_number = 1 {[action]}The keywords true and false have the alias yes and no.unless [condition] … – the same as if not (!) [condition] …

LOGIC PT1

COMMAND CONSOLE SYNTAX

con+ - starts a console window and hides the GUI. Will also unlock a locked EHAM fi le.

cout <[data]> - outputs to the console window, data must be a string. Adds a new line to the end of the string. Example: cout <“hello”>

/n - outputs a new line to the console window.cout_l <[data]> - same as cout but does not add a

new line to then end of the string.[data] cin – takes data from the console window and

precedes it to the line above, the data must be caught by the set function.

con- - stops the console window and shows the GUI again but will not lock an EHAM fi le.

CONSOLE SYNTAX PT1

conc – clears the console. cont <[string]> - sets the console title. con_col <[colour id]> - sets the console colour, the list of colours

are as follows; (you can type the name or the number of the colour as the id)

TX_NAVY=1 TX_GREEN=2 TX_DARKCYAN=3 TX_DARKRED=4 TX_DARKFUCSHIA=5 TX_DARKYELLOW=6 TX_SILVER=7 TX_GRAY=8 TX_BLUE=9 TX_LIME=10 TX_CYAN=11 TX_RED=12 TX_FUCHSIA=13

CONSOLE SYNTAX PT2

TX_YELLOW=14 TX_WHITE=15 BG_BLACK=0 BG_NAVY=16 BG_GREEN=32 BG_DARKCYAN=48 BG_DARKRED=64 BG_DARKFUCSHIA=80 BG_DARKYELLOW=96 BG_SILVER=112 BG_GRAY=128 BG_BLUE=144 BG_LIME=160 BG_CYAN=176 BG_RED=192 BG_FUCHSIA=208 BG_YELLOW=224 BG_WHITE=240

CONSOLE SYNTAX PT3

CONDITIONAL LOOPS

Conditional loops are loops in a program that only end if a certain condition is met. There are 2 functions for this use; while ([condition]) { [is true] } and do { [is true] } until [condition]. These functions are non-header.

A good use for these loops is when you want to initiate a program and have it run until you have either lost all lives in a game or run out of money, etc.

To make these loops run indefinitely you can use the condition until forever=1 which will always return -1 as an answer and therefore keep the loop running or while (1). The while loop works this way because the keyword true (yes) returns the number 1 which the function checks for in its conditional.

CONDITIONAL LOOPS PT1

RETURNING ERRORS

Sometimes a program will run into errors and need to stop, these errors may not be thought of as errors in the runtime. A program can force an error to be recognised with the following functions:

warn <[error message]> - Warns of a potentially fatal error but allows it to be ignored.

die <[error message]> - Alerts of a fatal error that can not be ignored, this will stop the program entirely.

The keyword stop will stop the compiler fully but may throw an error because of missing brackets or unfinished functions. This may be useful in debugging or when endpoints are required. The keyword skip [number of lines] can be used to make the compiler skip over the amount of lines specified.

RETURNING ERRORS PT1

FUNCTIONS

Functions are large groups of code that are reused many times throughout a program. The function [id] func+ <[code/fi lename],[EHAM?]> can be used to set a function and will return the function ID to the line above. The function can be in raw HAM format or EHAM format but if the code is in EHAM format if must be a fi lename and path, not just a single line of code. The function func <[function id]> can be used to execute a function.

FUNCTIONS PT1

FILE OPERATIONS

Files can be written to and read from with the following functions:

[id] f+ <[fi lename],[mode]> - Opens a fi le, mode 0 for read, mode 1 for write. In write mode, if the fi le does not exist it will be created.

ws <[id],[string]> - Writes a string to a fi le.wr <[id],[real]> - Writes a real to a fi le.[string] rs <[id]> - Reads a string from a fi le.[real] rr <[id]> - Reads a real from a fi le.wl <[id]> - Writes a line to a fi le.rl <[id]> - Reads a line from a fi le. f- <[id]> - Closes an open fi le.[size] f_size [fi lename] – Reads the size of a fi le in

bytes and passes it to the line above.

FILE OPERATIONS

fi le_exists <[fi le]> – returns true if the fi le exists, non-header.

FILE OPERATIONS

ENVIRONMENT

The Runtime has a special environment object separate to the main object which runs all of the program code, this environment object handles all of the data such as the type of program that is open (if any) and information on folder structures of the Runtime. This object can be referenced by the name _HAM_ENV or environment.

The variables that are stored there are as the following:

PROG – the root folder (program directory) of the runtime

ROOT – the system folder of the runtimeSTORE – the place where your program should store

any none temp fi les it hasTEMP – storage for temp fi les

ENVIRONMENT