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") Print("Hello, cruel world!")
 * 1) somewhere

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)