Modules/BRL/Blitz

BRL.Blitz is the main module for BlitzMax, and is included into every application.

NOTE: EndFunction, EndWhile, EndMethod, EndIf, ElseIf, EndRem, EndSelect, EndExtern and EndTry can also be written with the two words separated.

Example:

Rem
	Comment block!
End Rem
Function MyFunction()
End Function

' etc..

Globals

AppDir

Global AppDir:String
Description: Application directory.
Information: The AppDir global variable contains the full directory of the currently executing application. An application's initial current directory is also set to AppDir when an application starts.

Example:

Print(AppDir)

AppFile

Global AppFile:String
Description: Application file.
Information: The AppFile global variable contains the full file path of the currently executing application.

Example:

Print(AppFile)

AppTitle

Global AppTitle:String
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.

'NOTE: AppTitle is used as the title of a graphics window.

Example:

Print(AppTitle) ' Default is "BlitzMax Application"
AppTitle = "My Application Title!"

AppArgs

Global AppArgs:String[]
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 application's name or directory.

Example:

Local index:Int
' We want to ignore the first element
If AppArgs.Length > 1
	For index = 1 To AppArgs.Length - 1
		Print("Application argument: " + AppArgs[index])
	Next
End If

LaunchDir

Global LaunchDir:String
Description: The directory from which the 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's current directory as opposed to the application directory (AppDir).

Example:

Print(LaunchDir)

Constants

True

Const True:Int
Description: Constant integer value equaling 1.

Example:

Print("True = " + True)
If True
	Print("This line will always execute")
End If
If Not True
	Print("This line will never execute")
End If

False

Const False:Int
Description: Constant integer value equaling 0.

Example:

Print("False = " + False)
If False
	Print("This line will never execute")
End If

Pi

Const Pi:Double
Description: Constant double value equaling 3.1415926535897932384626433832795.

Example:

Print("Pi = " + Pi)

Null

Internal constant Null
Description: Empty object reference.

Example:

Type TMyType
	Field	integer:Int = 100
End Type

Local obj:TMyType
If obj = Null Print("obj has not been initialized")

obj = New TMyType
If obj <> Null Print("obj is initialized")

Keywords

Strict

Description: Set Strict coding mode.
Information: With the Strict mode enabled, variables cannot be defined without a preceding Local, Const or Global keyword. Labels are not allowed in Strict (except for DefData labels).

NOTE: In Strict mode return types/variables/parameters have automatic data typing when set. The default data type for variables is Int.

Example:

Local a = 10
b = 20 ' Fails to compile because identifiers must be defined before use

SuperStrict

Description: Set SuperStrict coding mode.
Information: With the SuperStrict mode enabled, all variables (constants, globals, locals, fields, parameters, etc.), all Functions and Methods (parameters and return types) must define a data type. Labels are not allowed in SuperStrict (except for DefData labels).

Example:

SuperStrict
Local myint:Int, myfloat:Float
Local myint ' Fails to compile because datatype is missing (there is no default data type like in Strict)

End

Description: End the application.

Example:

Print("Hello!")
End
Print("Goodbye?") ' Program ends before this can be executed

Rem ... EndRem

Description: Mutli-line comment block.

Example:

Rem
Multi-line comment blocks!
How useful!
EndRem

Return

Description: Return from a function or a method.

Example:

Print(MyFunction())
Function MyFunction:Int()
	Return 10
End Function

MyFunction2(100)
Function MyFunction2(value:Int)
	If value = 100
		Return ' Return to the main program without returning any value
	End If
	Print("value = " + value)
End Function

Release

KEYWORD
Description:
Information:

Example:

Goto

Goto
Description: Go to the specified label.
Information: Evil. Avoid at all costs.
Note: Goto does not work in SuperStrict or Strict mode. Also, labels are limited to DefData in either Strict or SuperStrict mode.

Example:

Print("One")
Goto somewhere
Print("Not executed")
#somewhere
Print("Hello, cruel world!")

Try, Catch, EndTry

A Try ... Catch ... EndTry 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:

For Local index:Int = 0 To 4
	Try
		MyFunction(index)
	Catch e:Object
		' Strings are actually objects, so we can account for all types of possible exceptions by
		' making the caught variable an Object and calling ToString on it.
		Print("Caught exception: " + e.ToString())
	EndTry
Next

Function MyFunction(index:Int)
	If index = 2
		Throw "I don't like the number 2!"
	End If
	Print("index = " + index)
End Function

Throw

Description: Throw an exception (can be any object).

Example:

Throw "Error!"

Assert

Description: Assert is the same as Throw, except that it only gets compiled in Debug mode (useful for debugging-only purposes), and that it is a conditional wrapper.
Information: If the given condition/expression evaluates to a non-value (False or Null), the exception will be thrown.

Example:

' In debug mode, an assert will be thrown, but in Release mode, the program will continue on without a stop
Local MyInteger:Int = 8

' There are two ways to write an Assert, either:
Assert MyInteger = 10, "MyInteger must equal 10!"
' Or this (using Else instead of a comma):
'Assert MyInteger = 10 Else "MyInteger must equal 10!"

Len

KEYWORD
Description:
Information:

Example:

Abs

KEYWORD
Description:
Information:

Example:

Mod

KEYWORD
Description:
Information:

Example:

Sgn

KEYWORD
Description:
Information:

Example:

Min, Max

KEYWORD
Description:
Information:

Example:

Functions

RuntimeError

Function RuntimeError(error:String)
Description: Throw a runtime error.
Information: This will Throw a TRuntimeException with the given error string.

Example:

Local MyInteger:Int = 9
If MyInteger <> 10
	RuntimeError("MyInteger <> 10!!")
End If

OnEnd

Description: Add a function to be called when the program ends.
Information: Functions added are called in the reverse order to that in which they were added.

Example:

OnEnd(MyFunction)
End

Function MyFunction()
	Print("Bye!")
End Function

HandleFromObject, HandleToObject

Function HandleFromObject:Int(obj:Object)
Description: Convert the given object to an integer handle (not a pointer).
Returns: The integer handle for the given object.
Information: After converting an object to an integer handle, you must later release it using the Release command.

Function HandleToObject:Object(handle:Int)
Description: Convert the given integer handle to an object.
Returns: The object for the given handle.

Example (of both functions):

Type TMyType
	Field myfield:Int = 100
End Type

Local obj:TMyType = New TMyType, objhandle:Int
objhandle = HandleFromObject(obj)
Print(objhandle)

Local obj2:TMyType
obj2 = TMyType(HandleToObject(objhandle)) ' Cast the object back to a TMyType
If obj = obj2
	Print("Matches!")
End If
Print(obj2.myfield)