Ham runtime syntax for eham

1. 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.

2. 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/ .

3. Basic functions

4. Basic functions pt1 • 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 multiline comment delimiter. • code – used when there is not a function for something, input is raw ham code.

5. Basic Functions pt2 • include<[file to include (EHAM)]> - Includes (+exec) a file in the main program. The file must be EHAM format. • exec<[file to execute]>- Executes a file. The file must be raw HAM format. • [id] script+<[file to include],[EHAM?]]>- Adds a file as a script in the program for later calling. The file 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.

6. Basic functions pt3 • 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]

7. Variable types

8. Variable Types pt1 • 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.

9. Variable types pt2 • 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: ‘setcountvar+ 1’.

10. Logic

11. Logic pt1 • 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]…

12. Command console syntax

13. Console syntax pt1 • con+ - starts a console window and hides the GUI. Will also unlock a locked EHAM file. • 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 file.

14. Console syntax pt2 • 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

15. Console syntax pt3 • 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

16. Conditional loops

17. Conditional loops pt1 • 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 untilforever=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.

18. Returning errors

19. Returning errors pt1 • 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.

20. Functions

21. Functions pt1 • Functions are large groups of code that are reused many times throughout a program. The function [id] func+<[code/filename],[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 filename and path, not just a single line of code.The function func<[function id]>can be used to execute a function.

22. File operations

23. File operations • Files can be written to and read from with the following functions: • [id] f+<[filename],[mode]>- Opens a file, mode 0 for read, mode 1 for write. In write mode, if the file does not exist it will be created. • ws<[id],[string]>- Writes a string to a file. • wr<[id],[real]> - Writes a real to a file. • [string] rs<[id]> - Reads a string from a file. • [real] rr<[id]> - Reads a real from a file. • wl<[id]> - Writes a line to a file. • rl<[id]> - Reads a line from a file. • f-<[id]> - Closes an open file. • [size] f_size[filename] – Reads the size of a file in bytes and passes it to the line above.

24. File Operations • file_exists<[file]>– returns true if the file exists, non-header.

25. Environment

26. 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 runtime • STORE – the place where your program should store any none temp files it has • TEMP – storage for temp files