Cerberus X Documentation

Module reflection

Reflection allows your program to inspect and access all or some of your program's declarations dynamically at runtime. More...

Declarations

Classes
ArrayBoxer<T> The ArrayBoxer class is a utility class that allows you to box and unbox arrays for use with reflection.
ClassInfo ClassInfo objects describe classes declared by your program and in modules.
ConstInfo ConstInfo objects describe constant values declared by your program.
FieldInfo FieldInfo objects describe fields declared within a class.
FunctionInfo FunctionInfo objects describe functions declared by your program.
GlobalInfo GlobalInfo objects describe globals declared by your program.
MethodInfo MethodInfo objects describe methods declared by your program.
Constants
ATTRIBUTE_ABSTRACT : Int
ATTRIBUTE_EXTERN : Int
ATTRIBUTE_FINAL : Int
ATTRIBUTE_INTERFACE : Int
ATTRIBUTE_PRIVATE : Int
Functions
ArrayClass : ClassInfo ( elementType:String ) Returns the class of an array.
BoolClass : ClassInfo () Returns the class of a 'bool'.
BoxBool : Object ( value:Bool ) Creates a box object with the given value.
BoxFloat : Object ( value:Float ) Creates a box object with the given value.
BoxInt : Object ( value:Int ) Creates a box object with the given value.
BoxString : Object ( value:String ) Creates a box object with the given value.
FloatClass : ClassInfo () Returns the class of a 'float'.
GetClass : ClassInfo ( obj:Object ) Returns the ClassInfo object with the given name, or Null if no object is found.
GetClass : ClassInfo ( name:String ) Returns the ClassInfo object with the given name, or Null if no object is found.
GetClasses : ClassInfo[] () Returns an array of all reflected classes.
GetConst : ConstInfo ( name:String ) Returns the ConstInfo object with the given name, or Null if no object is found.
GetConsts : ConstInfo[] () Returns an array of all consts declared at module scope.
GetFunction : FunctionInfo ( name:String, argTypes:ClassInfo[] ) Returns the FunctionInfo object with the given name and parameter types, or Null if no object is found.
GetFunctions : FunctionInfo[] () Returns an array of all reflected functions.
GetGlobal : GlobalInfo ( name:String ) Returns the GlobalInfo object with the given name, or Null if no object is found.
GetGlobals : GlobalInfo[] () Returns an array of all reflected globals.
IntClass : ClassInfo () Returns the class of an 'int'.
StringClass : ClassInfo () Returns the class of a 'string'.
UnboxBool : Bool ( box:Object ) Unboxes a bool.
UnboxFloat : Float ( box:Object ) Unboxes a float.
UnboxInt : Int ( box:Object ) Unboxes an int.
UnboxString : String ( box:Object ) Unboxes a string.

Detailed Discussion

Reflection allows your program to inspect and access all or some of your program's declarations dynamically at runtime.

Enabling reflection

To enable reflection, you must at least import the reflection module.

In addition, you must provide a 'reflection filter' to specify which modules are to be reflected. This is done using the REFLECTION_FILTER app config setting, which should contain the set of modules you want to be reflected. In addition, the reflection filter may use the '*' wildcard character to match 'any text' in a module path.

The simplest way to set the reflection filter is to use the wildcard character '*' on its own, eg:

#REFLECTION_FILTER="*" 'reflect everything!

Import reflection

However, this will cause all modules to be reflected, which in the case of even moderately sized programs will incur major overhead both in terms of compilation time and runtime app size. Instead, it's best to set the filter to only specify the modules you need reflected.

Multiple reflection filters may be specified using the ';' separator character, eg:

#REFLECTION_FILTER="myapp.gadgets;myapp.listeneres" 'reflect both the myapp.gadgets and myapp.listeners modules

The reflection filter may also be appended to using the preprocessor += operator, eg:

REFLECTION_FILTER="myapp.gadgets" 'reflect the myapp.gadgets module...
REFLECTION_FILTER+="myapp.listeners" '...and the myapp.listeners module.

Using the '*' wildcard, sets of 'submodules can be specified, eg:

REFLECTION_FILTER="myapp.gadgets;myapp.gadgets.*" 'reflect the myapp.gadgets module AND any myapp.gadgets submodules.

Declaration names

Declarations that appear at 'module scope' - that is, declarations that do not appear within a class - are fully qualified by the module they appear in.

For example, the DrawImage function that appears in the mojo.graphics module is named "mojo.graphics.DrawImage".

This is the name returned by the various Name() methods, and is the name you should use with the GetConst, GetGlobal, GetFunction and GetClass functions.

As a convenience, you can also use unqualified names with the Get functions as long as there is only one unique declaration with the given name.

For example, GetFunction( "mojo.graphics.DrawImage" ) and GetFunction( "DrawImage" ) will return the same FunctionInfo object, as long as DrawImage is only declared in one module.

Declarations that appear at class scope are not qualified.

Box objects

Non-object values of type int, float, string and array must be 'boxed' before they are passed to reflection methods such as SetValue and Invoke.

To do this, use the BoxInt, BoxFloat, BoxString functions. These functions all return a 'box' Object which is suitable for use with SetValue and Invoke.

Similarly, reflection methods such as GetValue and Invoke that return non-object values will return boxed values.

To unbox these values, use the UnboxInt, UnboxFloat and UnboxString functions.

Here's an example of boxing and unboxing in action:

#REFLECTION_FILTER="*"

Import reflection

Global MyGlobal:=123

Function Main()

'Get GlobalInfo for MyGlobal
Local g:=GetGlobal( "MyGlobal" )

'Read and unbox value of MyGlobal
Local n1:=UnboxInt( g.GetValue() )

'Print it...
Print "n1="+n1

'Box and write value of MyGlobal
g.SetValue( BoxInt( n1*2 ) )

'Read, unbox and dump...
Local n2:=UnboxInt( g.GetValue() )
Print "n2="+n2
End

Boxing and Unboxing arrays is slightly trickier - you must use the Box and Unbox functions declared in the ArrayBoxer class to do this. Here's an example:

#REFLECTION_FILTER="*"

Import reflection

Global MyGlobal:Int[]

Function Main()

'create an int array
Local intArray:Int[]=[1,2,3,4,5]

'box it...
Local boxedArray:=ArrayBoxer<Int>.Box( intArray )

'set value of MyGlobal
GetGlobal( "MyGlobal" ).SetValue( boxedArray )

'dump array
For Local i:=Eachin MyGlobal
Print i
Next

'reassign MyGlobal
MyGlobal=[6,7,8,9,10]

'read value of MyGlobal
boxedArray=GetGlobal( "MyGlobal" ).GetValue()

'Unbox it...
intArray=ArrayBoxer<Int>.Unbox( boxedArray )

'dump unboxed array
For Local i:=Eachin intArray
Print i
Next

End

Constants Documentation

Const ATTRIBUTE_ABSTRACT : Int
Const ATTRIBUTE_EXTERN : Int
Const ATTRIBUTE_FINAL : Int
Const ATTRIBUTE_INTERFACE : Int
Const ATTRIBUTE_PRIVATE : Int

Functions Documentation

Function ArrayClass : ClassInfo ( elementType:String )

Returns the class of an array.

The elementType parameter is case sensitive, and must be the fully qualified name of the element type.

The elementType parameter may itself be an array, in which case the returned class represents a multidimensional array.

This is actually the class of the objects used to box arrays, since arrays aren't objects and therefore don't have a class.

Parameters

elementType - Array element type.

Function BoolClass : ClassInfo ()

Returns the class of a 'bool'.

This is actually the class of the objects used to box bools, since bools aren't objects and therefore don't have a class.

Function BoxBool : Object ( value:Bool )

Creates a box object with the given value.

Box objects can be passed to the SetValue methods of FieldInfo and GlobalInfo objects, and used as parameters for the Invoke methods of MethodInfo and FunctionInfo objects.

Box objects are also returned by the GetValue methods of ConstInfo, FieldInfo and GlobalInfo objects, and by the Invoke methods of MethodInfo and FunctionInfo objects.

See also

UnboxBool

Function BoxFloat : Object ( value:Float )

Creates a box object with the given value.

Box objects can be passed to the SetValue methods of FieldInfo and GlobalInfo objects, and used as parameters for the Invoke methods of MethodInfo and FunctionInfo objects.

Box objects are also returned by the GetValue methods of ConstInfo, FieldInfo and GlobalInfo objects, and by the Invoke methods of MethodInfo and FunctionInfo objects.

See also

UnboxFloat

Function BoxInt : Object ( value:Int )

Creates a box object with the given value.

Box objects can be passed to the SetValue methods of FieldInfo and GlobalInfo objects, and used as parameters for the Invoke methods of MethodInfo and FunctionInfo objects.

Box objects are also returned by the GetValue methods of ConstInfo, FieldInfo and GlobalInfo objects, and by the Invoke methods of MethodInfo and FunctionInfo objects.

See also

UnboxInt

Function BoxString : Object ( value:String )

Creates a box object with the given value.

Box objects can be passed to the SetValue methods of FieldInfo and GlobalInfo objects, and used as parameters for the Invoke methods of MethodInfo and FunctionInfo objects.

Box objects are also returned by the GetValue methods of ConstInfo, FieldInfo and GlobalInfo objects, and by the Invoke methods of MethodInfo and FunctionInfo objects.

See also

UnboxString

Function FloatClass : ClassInfo ()

Returns the class of a 'float'.

This is actually the class of the objects used to box floats, since floats aren't objects and therefore don't have a class.

Function IntClass : ClassInfo ()

Returns the class of an 'int'.

This is actually the class of the objects used to box ints, since ints aren't objects and therefore don't have a class.

Function StringClass : ClassInfo ()

Returns the class of a 'string'.

This is actually the class of the objects used to box strings, since strings aren't objects and therefore don't have a class.

Function UnboxBool : Bool ( box:Object )

Unboxes a bool. The box must have been previously created with BoxBool.

See also

BoxBool

Function UnboxFloat : Float ( box:Object )

Unboxes a float. The box must have been previously created with BoxFloat.

See also

BoxFloat

Function UnboxInt : Int ( box:Object )

Unboxes an int. The box must have been previously created with BoxInt.

See also

BoxInt

Function UnboxString : String ( box:Object )

Unboxes a string. The box must have been previously created with BoxString.

See also

BoxString