BlitzMax/Modules/BASIC/Reflection

BlitzMax provides limited support for a form of runtime reflection. Using reflection, programs can 'inspect' objects and types at runtime. You can determine the fields and methods contained in an object or type, set and get object fields and invoke - or 'call' - object methods. To use reflection, you first need a TTypeId object. TTypeId objects correspond to BlitzMax user defined types, and there is a single TTypeId object for every user defined type in the program. There are also TTypeId objects for the 'primitive' types - byte, short, int, long, float, double and string. TTypeId objects are returned by the TTypeId.ForName and TTypeId.ForObject functions. Once you have a TTypeId object, you can inspect the fields and methods of a user defined type using the EnumFields and EnumMethods methods. These methods return TField and TMethod objects that describe the fields and methods within the type. For example: Strict Type TMyType Field x,y,z End Type Local id:TTypeId=TTypeId.ForName( "TMyType" ) For Local fld:TField=EachIn id.EnumFields() Print fld.Name()+":"+fld.TypeId().Name() Next This simple program will print "x:Int", "y:Int" and "z:Int" - the names and types of the fields within TMyType. Note that this is done without actually creating a new TMyType. The following example sets the fields of an object: Strict Type TMyType Field x,y,z End Type Local obj:TMyType=New TMyType Local id:TTypeId=TTypeId.ForObject( obj ) For Local fld:TField=EachIn id.EnumFields() fld.Set obj,String( Rand(10) ) Next Print obj.x+","+obj.y+","+obj.z In this case we need an actual instance of TMyType, otherwise we have nothing to set the fields of! Also, we have used TTypeId.ForObject instead of TTypeId.ForName to get a TTypeId. While in this case TTypeId.ForName could have been used to achieve the same result, in general we may not know the exact type of the object, and therefore we wont know its type name. Also note that the code that actually sets the fields uses String( Rand(10) ). This is because the Set method takes an object - but our fields are ints! BlitzMax reflection deals with this by using strings to represent numeric types. The same rule applies to the Get method. Any numeric fields will be returned as strings which you must then convert to the appropriate type if necessary. Finally, let's invoke an object method: Strict Type TMyType Method Update( t# ) Print "TMyType.Update:"+t End Method End Type Local obj:TMyType=New TMyType Local id:TTypeId=TTypeId.ForObject( obj ) Local update:TMethod=id.FindMethod( "Update" ) update.Invoke obj,[String( .25 )] This example uses FindMethod to locate a type method and Invoke to call it. Arguments to the method are contained in an object array, and again the float argument is converted to a string. In addition to the TTypeId, TField and TMethod types, the BlitzMax reflection module also declares a number of global TTypeId objects: ByteTypeId ShortTypeId IntTypeId LongTypeId FloatTypeId DoubleTypeId StringTypeId ObjectTypeId These may be used instead of the corresponding TTypeId.ForName call. For example, TTypeId.ForName( "Int" ) and IntTypeId will return the same object. Globals ByteTypeId Global ByteTypeId:TTypeId=New TTypeId.Init( "Byte",1 ) Description: Primitive byte type ShortTypeId Global ShortTypeId:TTypeId=New TTypeId.Init( "Short",2 ) Description: Primitive short type IntTypeId Global IntTypeId:TTypeId=New TTypeId.Init( "Int",4 ) Description: Primitive int type LongTypeId Global LongTypeId:TTypeId=New TTypeId.Init( "Long",8 ) Description: Primitive long type FloatTypeId Global FloatTypeId:TTypeId=New TTypeId.Init( "Float",4 ) Description: Primitive float type DoubleTypeId Global DoubleTypeId:TTypeId=New TTypeId.Init( "Double",8 ) Description: Primitive double type StringTypeId Global StringTypeId:TTypeId=New TTypeId.Init( "String",4,bbRefStringClass() ) Description: Primitive string type ObjectTypeId Global ObjectTypeId:TTypeId=New TTypeId.Init( "Object",4,bbRefObjectClass() ) Description: Primitive object type ArrayTypeId Global ArrayTypeId:TTypeId=New TTypeId.Init( "Null[]",4,bbRefArrayClass() ) Description: Primitive array type Types TMember Type member - field or method. Methods Name TypeId MetaData TMember: Methods Name Method Name$() Description: Get member name TypeId Method TypeId:TTypeId() Description: Get member type MetaData Method MetaData$( key$="" ) Description: Get member meta data TField Type field Methods Get GetInt GetLong GetFloat GetDouble GetString Set SetInt SetLong SetFloat SetDouble SetString TField: Methods Get Method Get:Object( obj:Object ) Description: Get field value GetInt Method GetInt:Int( obj:Object ) Description: Get int field value GetLong Method GetLong:Long( obj:Object ) Description: Get long field value GetFloat Method GetFloat:Float( obj:Object ) Description: Get float field value GetDouble Method GetDouble:Double( obj:Object ) Description: Get double field value GetString Method GetString$( obj:Object ) Description: Get string field value Set Method Set( obj:Object,value:Object ) Description: Set field value SetInt Method SetInt( obj:Object,value:Int ) Description: Set int field value SetLong Method SetLong( obj:Object,value:Long ) Description: Set long field value SetFloat Method SetFloat( obj:Object,value:Float ) Description: Set float field value SetDouble Method SetDouble( obj:Object,value:Double ) Description: Set double field value SetString Method SetString( obj:Object,value$ ) Description: Set string field value TMethod Type method Methods ArgTypes Invoke TMethod: Methods ArgTypes Method ArgTypes:TTypeId[]() Description: Get method arg types Invoke Method Invoke:Object( obj:Object,args:Object[] ) Description: Invoke method TTypeId Type id Methods Name MetaData SuperType ArrayType ElementType ExtendsType DerivedTypes NewObject Fields Methods FindField FindMethod EnumFields EnumMethods NewArray ArrayLength ArrayDimensions GetArrayElement SetArrayElement Functions ForName ForObject EnumTypes TTypeId: Methods Name Method Name$() Description: Get name of type MetaData Method MetaData$( key$="" ) Description: Get type meta data SuperType Method SuperType:TTypeId() Description: Get super type ArrayType Method ArrayType:TTypeId(dims:Int = 1) Description: Get array type ElementType Method ElementType:TTypeId() Description: Get element type ExtendsType Method ExtendsType( typeId:TTypeId ) Description: Determine if type extends a type DerivedTypes Method DerivedTypes:TList() Description: Get list of derived types NewObject Method NewObject:Object() Description: Create a new object Fields Method Fields:TList() Description: Get list of fields Information: Only returns fields declared in this type, not in super types. Methods Method Methods:TList() Description: Get list of methods Information: Only returns methods declared in this type, not in super types. FindField Method FindField:TField( name$ ) Description: Find a field by name Information: Searchs type hierarchy for field called name. FindMethod Method FindMethod:TMethod( name$ ) Description: Find a method by name Information: Searchs type hierarchy for method called name. EnumFields Method EnumFields:TList( list:TList=Null ) Description: Enumerate all fields Information: Returns a list of all fields in type hierarchy EnumMethods Method EnumMethods:TList( list:TList=Null ) Description: Enumerate all methods Information: Returns a list of all methods in type hierarchy - TO DO: handle overrides! NewArray Method NewArray:Object( length, dims:Int[] = Null ) Description: Create a new array ArrayLength Method ArrayLength( array:Object, dim:Int = 0 ) Description: Get array length ArrayDimensions Method ArrayDimensions:Int( array:Object ) Description: Get the number of dimensions GetArrayElement Method GetArrayElement:Object( array:Object,index ) Description: Get an array element SetArrayElement Method SetArrayElement( array:Object,index,value:Object ) Description: Set an array element TTypeId: Functions ForName Function ForName:TTypeId( name$ ) Description: Get Type by name ForObject Function ForObject:TTypeId( obj:Object ) Description: Get Type by object EnumTypes Function EnumTypes:TList() Description: Get list of all types