# BlitzMax/Modules/BASIC/BlitzMax runtime

The Blitz runtime module provides low level functionality required by BlitzMax applications when they are running. This includes things like memory management, exception handling and string and array operations.
Much of the functionality provided by this module is hidden from application programmers, but is instead used 'behind the scenes' by the compiler. However, there are some very useful commands for debugging, memory management and simple standard IO.

# Globals
## AppDir

Global AppDir$="bbAppDir"
Description: Application directory
Information: The AppDir global variable contains the fully qualified directory of the currently executing application. An application's initial current directory is also set to AppDir when an application starts.
Example:

## AppFile

Global AppFile$="bbAppFile"
Description: Application file name
Information: The AppFile global variable contains the fully qualified file name of the currently executing application.
Example:

## AppTitle

Global AppTitle$="bbAppTitle"
Description: Application title
Information: The AppTitle global variable is used by various commands when a default application title is required - for example, when opening simple windows or requesters. Initially, AppTitle is set the value "BlitzMax Application". However, you may change AppTitle at any time with a simple assignment.

## AppArgs

Global AppArgs$="bbAppArgs"
Description: Arguments passed to the application at startup
Information: The AppArgs global array contains the command line parameters sent to an application when it was started. The first element of AppArgs always contains the name of the application. However, the format of the name may change depending on how the application was launched. Use AppDir or AppFile for consistent information about the applications name or directory.
Example:

## LaunchDir

Global LaunchDir$="bbLaunchDir"
Description: Directory from which application was launched
Information: The LaunchDir global variable contains the current directory at the time the application was launched. This is mostly of use to command line tools which may need to access the 'shell' current directory as opposed to the application directory.
Example:

# Functions
## RuntimeError

Function RuntimeError( message$ )
Description: Generate a runtime error
Information: Throws a TRuntimeException.
Example:

## DebugStop

Function DebugStop
Description: Stop program execution and enter debugger
Information: If there is no debugger present, this command is ignored.

## DebugLog

Function DebugLog( message$ )
Description: Write a string to debug log
Information: If there is no debugger present, this command is ignored.
Comment: note that, unlike Assert, DebugLog will get compiled regardless of the compilation mode - just that nothing is printed in Release mode.

## OnEnd

Function OnEnd( fun )
Description: Add a function to be called when the program ends
Information: OnEnd allows you to specify a function to be called when the program ends. OnEnd functions are called in the reverse order to that in which they were added.
Example:

## ReadStdin

Function ReadStdin$
Description: Read a string from stdin
Returns: A string read from stdin. The newline terminator, if any, is included in the returned string.

## WriteStdout

Function WriteStdout( str$ )
Description: Write a string to stdout
Information: Writes str to stdout and flushes stdout.

## WriteStderr

Function WriteStderr( str$ )
Description: Write a string to stderr
Information: Writes str to stderr and flushes stderr.

## Delay

Function Delay( millis )
Description: Wait for a given number of milliseconds
Information: Delay suspends program execution for at least millis milliseconds. A millisecond is one thousandth of a second.

## MilliSecs

Function MilliSecs)
Description: Get millisecond counter
Returns: Milliseconds since computer turned on.
Information: MilliSecs returns the number of milliseconds elapsed since the computer was turned on. A millisecond is one thousandth of a second.

## MemAlloc

Function MemAlloc:Byte Ptr( size )
Description: Allocate memory
Returns: A new block of memory size bytes long

## MemFree

Function MemFree( mem:Byte Ptr )
Description: Free allocated memory
Information: The memory specified by mem must have been previously allocated by MemAlloc or MemExtend.

## MemExtend

Function MemExtend:Byte Ptr( mem:Byte Ptr,size,new_size )
Description: Extend a block of memory
Returns: A new block of memory new_size bytes long
Information: An existing block of memory specified by mem and size is copied into a new block of memory new_size bytes long. The existing block is released and the new block is returned.

## MemClear

Function MemClear( mem:Byte Ptr,size )
Description: Clear a block of memory to 0

## MemCopy

Function MemCopy( dst:Byte Ptr,src:Byte Ptr,size )
Description: Copy a non-overlapping block of memory

## MemMove

Function MemMove( dst:Byte Ptr,src:Byte Ptr,size )
Description: Copy a potentially overlapping block of memory

## GCSetMode

Function GCSetMode( mode )
Description: Set garbage collector mode
Information: mode can be one of the following: 1 : automatic GC - memory will be automatically garbage collected 2 : manual GC - no memory will be collected until a call to GCCollect is made The default GC mode is automatic GC.

## GCSuspend

Function GCSuspend
Description: Suspend garbage collector
Information: GCSuspend temporarily suspends the garbage collector. No garbage collection will be performed following a call to GCSuspend. Use GCResume to resume the garbage collector. Note that GCSuspend and GCResume 'nest', meaning that each call to GCSuspend must be matched by a call to GCResume.

## GCResume

Function GCResume
Description: Resume garbage collector
Information: GCResume resumes garbage collection following a call to GCSuspend. See GCSuspend for more details.

## GCCollect

Function GCCollect
Description: Run garbage collector
Returns: The amount of memory, in bytes, collected.
Information: This function will have no effect if the garbage collector has been suspended due to GCSuspend.

## GCMemAlloced

Function GCMemAlloced
Description: Memory allocated by application
Returns: The amount of memory, in bytes, currently allocated by the application
Information: This function only returns 'managed memory'. This includes all objects, strings and arrays in use by the application.

## GCEnter

Function GCEnter
Description: Private: do not use

## GCLeave

Function GCLeave
Description: Private: do not use

## HandleFromObject

Function HandleFromObject( obj:Object )
Description: Convert object to integer handle
Returns: An integer object handle
Information: After converting an object to an integer handle, you must later release it using the Release command.

## HandleToObject

Function HandleToObject:Object( handle )
Description: Convert integer handle to object
Returns: The object associated with the integer handle
Example:

# Keywords
## Strict

Description: Set strict mode
Information: See BASIC Compatibility for more information on Strict mode programming.
Comment: In Strict mode automatic data typing is permitted. The default data type is Int.
Example:

## SuperStrict

Description: Set SuperStrict mode
Comment: In SuperStrict mode data types must always be specified.

## End

Description: End program execution
Example:

## Rem

Description: Begin a remark block
Example:

## EndRem

Description: End a remark block
Example:

## True

Description: Constant integer of value 1
Example:

## False

Description: Constant integer of value 0
Example:

## Pi

Description: Constant Pi value: 3.1415926535897932384626433832795
Example:

## Null

Description: Get Default Null value
Example:

## Byte

Description: Unsigned 8 bit integer Type
Example:

## Short

Description: Unsigned 16 bit integer Type
Example:

## Int

Description: Signed 32 bit integer Type
Example:

## Long

Description: Signed 64 bit integer Type
Example:

## Float

Description: 32 bit Floating point Type
Example:

## Double

Description: 64 bit floating point Type
Example:

## String

Description: String Type
Example:

## Object

Description: Object Type
Example:

## Var

Description: Composite Type specifier for 'by reference' types
Example:

## Ptr

Description: Composite Type specifier for pointer types
Example:

## If

Description: Begin a conditional block.
Example:

## Then

Description: Optional separator between the condition and associated code in an If statement.
Example:

## Else

Description: Else provides the ability for an If Then construct to execute a second block of code when the If condition is False.
Example:

## ElseIf

Description: ElseIf provides the ability to test and execute a section of code if the initial condition failed.
Example:

## EndIf

Description: Marks the end of an If Then block.
Example:

## For

Description: Marks the start of a loop that uses an iterator to execute a section of code repeatedly.
Example:

## To

Description: Followed by a constant which is used to calculate when to exit a For..Next loop.
Example:

## Step

Description: Specifies an optional constant that is used to increment the For iterator.
Example:

## Next

Description: End a For block
Example:

## EachIn

Description: Iterate through an array or collection
Example:

## While

Description: Execute a block of code while a condition is True
Example:

## Wend

Description: End a While block
Example:

## EndWhile

Description: End a While block

## Repeat

Description: Execute a block of code until a termination condition is met, or forever
Example:

## Until

Description: Conditionally continue a Repeat block
Example:

## Forever

Description: Continue a Repeat block forever
Example:

## Select

Description: Begin a Select block
Example:

## EndSelect

Description: End a Select block
Example:

## Case

Description: Conditional code inside a Select block
Example:

## Default

Description: Default code inside a Select block
Example:

## Exit

Description: Exit enclosing loop
Example:

## Continue

Description: Continue execution of enclosing loop
Example:

## Const

Description: Declare a constant
Example:

## Local

Description: Declare a Local variable
Example:

## Global

Description: Declare a Global variable
Example:

## Field

Description: Declare a Field variable
Example:

## Function

Description: Begin a Function declaration
Example:

## EndFunction

Description: End a Function declaration
Example:

## Return

Description: Return from a Function
Example:

## Type

Description: Begin a user defined Type declaration
Example:

## EndType

Description: End a user defined Type declaration
Example:

## Extends

Description: Specify user defined Type supertype
Comment: The Type inherits a given base Type.
Example:

## Method

Description: Begin a Method declaration
Comment: Methods are instance-specific functions.
Example:

## EndMethod

Description: End a Method declaration
Example:

## Abstract

Description: Denote a Type or Method as Abstract
Comment: The Type or Method must be extended (compilation will fail if it was not extended).
Example:

## Final

Description: Denote a Type or Method as Final
Comment: The Type or Method is not extendable.
Example:

## New

Description: Create an instance of a user defined Type
Example:

## Self

Description: Reference to this Method's Object instance
Comment: Allows an object access to its own instance (not needed in most cases).
Example:

## Super

Description: Reference to the Super Type Object instance
Comment: Allows an object access to its parent type (the type that it extends).
Example:

## Delete

Description: Reserved for future expansion
Example:

## Release

Description: Release an integer Object handle
Example:

## Public

Description: Public makes a Constant, Global variable or Function accessible from outside the current source file (Default)
Example:

## Private

Description: Private makes a Constant, Global variable or Function only accessible from within the current source file
Example:

## Extern

Description: Extern marks the beginning of an external list of Function declarations
Example:

## EndExtern

Description: EndExtern marks the End of an Extern section
Example:

## Module

Description: Declare Module scope and identifier
Information: See Modules for more information.
Example:

## ModuleInfo

Description: Define Module properties
Example:

## Incbin

Description: Embed a data file
Example:

## IncbinPtr

Description: Get start address of embedded data file
Example:

## IncbinLen

Description: Get length of embedded data file
Example:

## Include

Description: Include effectively 'inserts' the specified file into the file being compiled.

## Framework

Description: Framework builds the BlitzMax application with only the Module specified rather than all modules installed.
Comment: If you specify some module with Framework, only that module and ones it imports are compiled with your code. You can then import additional modules using Import. Common framework modules are Brl.Basic and Brl.Max2D, for console and 2d applications respectively.

## Import

Description: Import declarations from a Module or source file
Example:

## Assert

Description: Throw a RuntimeError if a condition is False
Comment: Assert throws a runtime error in Debug mode.
Example:

## Goto

Description: Transfer program flow to specified label
Comment: Goto does not work in SuperStrict or Strict mode. Also, labels are limited to DefData.
Example:

## Try

Description: Begin declaration of a Try block
Comment: A Try block attempts to catch an exception that might have been thrown between Try and Catch and attempts to handle the exception (instead of ending the program).
Example:

## EndTry

Description: End declaration of a Try block
Example:

## Catch

Description: Catch an exception Object in a Try block
Example:

## Throw

Description: Throw an exception Object to the enclosing Try block
Example:

## DefData

Description: Define class BASIC style data
Example:

## ReadData

Description: Read classic BASIC style data

## RestoreData

Description: Restore classic BASIC style data
Example:

## And

Description: Conditional 'And' binary operator
Example:

## Or

Description: Conditional 'Or' binary operator
Example:

## Not

Description: Conditional 'Not' binary operator
Example:

## Shl

Description: Bitwise 'Shift left' binary operator
Example:

## Shr

Description: Bitwise 'Shift right' binary operator
Example:

## Sar

Description: Bitwise 'Shift arithmetic right' binary operator
Example:

## Len

Description: Number of characters in a string or elements in an array
Comment: You can also use the length field of an array or string as they are objects.
Example:

## Abs

Description: Numeric 'absolute value' unary operator
Example:

## Mod

Description: Numeric 'modulus' or 'remainder' binary operator
Example:

## Sgn

Description: Numeric 'sign' unary operator
Example:

## Min

Description: Numeric 'minimum' builtin function
Returns: The lesser of the two numeric arguments

## Max

Description: Numeric 'maximum' builtin function
Returns: The larger of the two numeric arguments

## Varptr

Description: Find the address of a variable
Example:

## SizeOf

Description: Size, in bytes, occupied by a variable, string, array or object
Example:

## Asc

Description: Get character value of the first character of a string
Example:

## Chr

Description: Create a string of length 1 with a character code
Example: