The interface to the script modules. More...
Public Member Functions | |
Miscellaneous | |
virtual asIScriptEngine * | GetEngine () const =0 |
Returns a pointer to the engine. | |
virtual void | SetName (const char *name)=0 |
Sets the name of the module. | |
virtual const char * | GetName () const =0 |
Gets the name of the module. | |
virtual void | Discard ()=0 |
Discards the module. | |
Compilation | |
virtual int | AddScriptSection (const char *name, const char *code, size_t codeLength=0, int lineOffset=0)=0 |
Add a script section for the next build. | |
virtual int | Build ()=0 |
Build the previously added script sections. | |
virtual int | CompileFunction (const char *sectionName, const char *code, int lineOffset, asDWORD compileFlags, asIScriptFunction **outFunc)=0 |
Compile a single function. | |
virtual int | CompileGlobalVar (const char *sectionName, const char *code, int lineOffset)=0 |
Compile a single global variable and add it to the scope of the module. | |
virtual asDWORD | SetAccessMask (asDWORD accessMask)=0 |
Sets the access mask that should be used during the compilation. | |
virtual int | SetDefaultNamespace (const char *nameSpace)=0 |
Sets the default namespace that should be used in the following calls. | |
virtual const char * | GetDefaultNamespace () const =0 |
Returns the current default namespace. | |
Functions | |
virtual asUINT | GetFunctionCount () const =0 |
Returns the number of global functions in the module. | |
virtual asIScriptFunction * | GetFunctionByIndex (asUINT index) const =0 |
Returns the function by index. | |
virtual asIScriptFunction * | GetFunctionByDecl (const char *decl) const =0 |
Returns the function by its declaration. | |
virtual asIScriptFunction * | GetFunctionByName (const char *name) const =0 |
Returns the function by its name. | |
virtual int | RemoveFunction (asIScriptFunction *func)=0 |
Remove a single function from the scope of the module. | |
Global variables | |
virtual int | ResetGlobalVars (asIScriptContext *ctx=0)=0 |
Reset the global variables of the module. | |
virtual asUINT | GetGlobalVarCount () const =0 |
Returns the number of global variables in the module. | |
virtual int | GetGlobalVarIndexByName (const char *name) const =0 |
Returns the global variable index by name. | |
virtual int | GetGlobalVarIndexByDecl (const char *decl) const =0 |
Returns the global variable index by declaration. | |
virtual const char * | GetGlobalVarDeclaration (asUINT index, bool includeNamespace=false) const =0 |
Returns the global variable declaration. | |
virtual int | GetGlobalVar (asUINT index, const char **name, const char **nameSpace=0, int *typeId=0, bool *isConst=0) const =0 |
Returns the global variable properties. | |
virtual void * | GetAddressOfGlobalVar (asUINT index)=0 |
Returns the pointer to the global variable. | |
virtual int | RemoveGlobalVar (asUINT index)=0 |
Remove the global variable from the scope of the module. | |
Type identification | |
virtual asUINT | GetObjectTypeCount () const =0 |
Returns the number of object types. | |
virtual asITypeInfo * | GetObjectTypeByIndex (asUINT index) const =0 |
Returns the object type interface by index. | |
virtual int | GetTypeIdByDecl (const char *decl) const =0 |
Returns a type id by declaration. | |
virtual asITypeInfo * | GetTypeInfoByName (const char *name) const =0 |
Returns the type interface by name. | |
virtual asITypeInfo * | GetTypeInfoByDecl (const char *decl) const =0 |
Returns a type by declaration. | |
Enums | |
virtual asUINT | GetEnumCount () const =0 |
Returns the number of enum types declared in the module. | |
virtual asITypeInfo * | GetEnumByIndex (asUINT index) const =0 |
Returns the enum type. | |
Typedefs | |
virtual asUINT | GetTypedefCount () const =0 |
Returns the number of typedefs in the module. | |
virtual asITypeInfo * | GetTypedefByIndex (asUINT index) const =0 |
Returns the typedef. | |
Dynamic binding between modules | |
virtual asUINT | GetImportedFunctionCount () const =0 |
Returns the number of functions declared for import. | |
virtual int | GetImportedFunctionIndexByDecl (const char *decl) const =0 |
Returns the imported function index by declaration. | |
virtual const char * | GetImportedFunctionDeclaration (asUINT importIndex) const =0 |
Returns the imported function declaration. | |
virtual const char * | GetImportedFunctionSourceModule (asUINT importIndex) const =0 |
Returns the declared imported function source module. | |
virtual int | BindImportedFunction (asUINT importIndex, asIScriptFunction *func)=0 |
Binds an imported function to the function from another module. | |
virtual int | UnbindImportedFunction (asUINT importIndex)=0 |
Unbinds an imported function. | |
virtual int | BindAllImportedFunctions ()=0 |
Binds all imported functions in a module, by searching their equivalents in the declared source modules. | |
virtual int | UnbindAllImportedFunctions ()=0 |
Unbinds all imported functions. | |
Byte code saving and loading | |
virtual int | SaveByteCode (asIBinaryStream *out, bool stripDebugInfo=false) const =0 |
Save compiled byte code to a binary stream. | |
virtual int | LoadByteCode (asIBinaryStream *in, bool *wasDebugInfoStripped=0)=0 |
Load pre-compiled byte code from a binary stream. | |
User data | |
virtual void * | SetUserData (void *data, asPWORD type=0)=0 |
Register the memory address of some user data. | |
virtual void * | GetUserData (asPWORD type=0) const =0 |
Returns the address of the previously registered user data. | |
A script module can be thought of a library of script functions, classes, and global variables.
A pointer to the module interface is obtained by calling asIScriptEngine::GetModule. The module can then be built from a single or multiple script files, also known as script sections. Alternatively pre-built bytecode can be loaded, if it has been saved from a previous build.
|
pure virtual |
[in] | name | The name of the script section |
[in] | code | The script code buffer |
[in] | codeLength | The length of the script code |
[in] | lineOffset | An offset that will be added to compiler message line numbers |
asINVALID_ARG | The code argument is null. |
asNOT_SUPPORTED | Compiler support is disabled in the engine. |
asOUT_OF_MEMORY | The necessary memory to hold the script code couldn't be allocated. |
This adds a script section to the module. The script section isn't processed with this call. Only when Build is called will the script be parsed and compiled into executable byte code.
Error messages from the compiler will refer to the name of the script section and the position within it. Normally each section is the content of a source file, so it is recommended to name the script sections as the name of the source file.
The code added is copied by the engine, so there is no need to keep the original buffer after the call. Note that this can be changed by setting the engine property asEP_COPY_SCRIPT_SECTIONS with asIScriptEngine::SetEngineProperty.
|
pure virtual |
asERROR | An error occurred. |
asCANT_BIND_ALL_FUNCTIONS | Not all functions where bound. |
This functions tries to bind all imported functions in the module by searching for matching functions in the suggested modules. If a function cannot be bound the function will give an error asCANT_BIND_ALL_FUNCTIONS, but it will continue binding the rest of the functions.
|
pure virtual |
[in] | importIndex | The index of the imported function. |
[in] | func | The true function that will be bound to the imported function. |
asNO_FUNCTION | importIndex or func is incorrect. |
asINVALID_ARG | importIndex is invalid or func is null. |
asNOT_SUPPORTED | func is not a script function or registered function. |
asINVALID_INTERFACE | The signature of function doesn't match the import statement. |
The imported function is only bound if the functions have the exact same signature, i.e the same return type, and parameters.
Delegate objects are not supported.
|
pure virtual |
asINVALID_CONFIGURATION | The engine configuration is invalid. |
asERROR | The script failed to build. |
asBUILD_IN_PROGRESS | Another thread is currently building. |
asINIT_GLOBAL_VARS_FAILED | It was not possible to initialize at least one of the global variables. |
asNOT_SUPPORTED | Compiler support is disabled in the engine. |
asMODULE_IS_IN_USE | The code in the module is still being used and and cannot be removed. |
Builds the script based on the previously added sections, registered types and functions. After the build is complete the script sections are removed to free memory.
Before starting the build the Build method removes any previously compiled script content, including the dynamically added content from CompileFunction and CompileGlobalVar. If the script module needs to be rebuilt all of the script sections needs to be added again.
Compiler messages are sent to the message callback function set with asIScriptEngine::SetMessageCallback. If there are no errors or warnings, no messages will be sent to the callback function.
Any global variables found in the script will be initialized by the compiler if the engine property asEP_INIT_GLOBAL_VARS_AFTER_BUILD is set. If you get the error asINIT_GLOBAL_VARS_FAILED, then it is probable that one of the global variables during the initialization is trying to access another global variable before it has been initialized.
|
pure virtual |
[in] | sectionName | The name of the script section |
[in] | code | The script code buffer |
[in] | lineOffset | An offset that will be added to compiler message line numbers |
[in] | compileFlags | One of asECompileFlags values |
[out] | outFunc | Optional parameter to receive the compiled function descriptor |
asINVALID_ARG | One or more arguments have invalid values. |
asINVALID_CONFIGURATION | The engine configuration is invalid. |
asBUILD_IN_PROGRESS | Another build is in progress. |
asERROR | The compilation failed. |
asNOT_SUPPORTED | Compiler support is disabled in the engine. |
Use this to compile a single function. Any existing compiled code in the module can be used by the function.
The newly compiled function can be optionally added to the scope of the module where it can later be referred to by the application or used in subsequent compilations. If not added to the module the function can still be returned in the output parameter, which will allow the application to execute it and then discard it when it is no longer needed.
If the output function parameter is set, remember to release the function object when you're done with it.
|
pure virtual |
[in] | sectionName | The name of the script section |
[in] | code | The script code buffer |
[in] | lineOffset | An offset that will be added to compiler message line numbers |
asINVALID_ARG | One or more arguments have invalid values. |
asINVALID_CONFIGURATION | The engine configuration is invalid. |
asBUILD_IN_PROGRESS | Another build is in progress. |
asERROR | The compilation failed. |
asNOT_SUPPORTED | Compiler support is disabled in the engine. |
Use this to add a single global variable to the scope of a module. The variable can then be referred to by the application and subsequent compilations.
The script code may contain an initialization expression, which will be executed by the compiler if the engine property asEP_INIT_GLOBAL_VARS_AFTER_BUILD is set.
Any existing compiled code in the module can be used in the initialization expression.
|
pure virtual |
This method is used to discard the module and any compiled bytecode it has. After calling this method the module pointer is no longer valid and shouldn't be used by the application.
|
pure virtual |
[in] | index | The index of the global variable. |
This method should be used to retrieve the pointer of a variable that you wish to access.
|
pure virtual |
|
pure virtual |
|
pure virtual |
[in] | index | The index of the enum type. |
|
pure virtual |
|
pure virtual |
[in] | decl | The function declaration. |
|
pure virtual |
[in] | index | The index of the function |
|
pure virtual |
[in] | name | The function name |
The search for functions will be performed in the default namespace as given by SetDefaultNamespace unless the name is prefixed with a scope, using the scoping operator ::. If the scope starts with :: it will be used as the absolute scope, otherwise it will be relative to the default namespace.
|
pure virtual |
This method retrieves the number of compiled script functions.
|
pure virtual |
[in] | index | The index of the global variable. |
[out] | name | The name of the variable. |
[out] | nameSpace | The namespace of the variable. |
[out] | typeId | The type of the variable. |
[out] | isConst | Whether or not the variable is const. |
asINVALID_ARG | The index is out of range. |
|
pure virtual |
|
pure virtual |
[in] | index | The index of the global variable. |
[in] | includeNamespace | Set to true if the namespace should be included in the declaration. |
This method can be used to retrieve the variable declaration of the script variables that the host application will access. Verifying the declaration is important because, even though the script may compile correctly the user may not have used the variable types as intended.
|
pure virtual |
[in] | decl | The global variable declaration. |
asERROR | The module was not built successfully. |
asNO_GLOBAL_VAR | No matching global variable was found. |
asINVALID_DECLARATION | The given declaration is invalid. |
This method should be used to retrieve the index of the script variable that you wish to access.
The method will find the script variable with the exact same declaration.
If the variable is declared in a namespace first call SetDefaultNamespace to set the namespace that should be searched first for the variable.
|
pure virtual |
[in] | name | The name of the global variable. |
asINVALID_ARG | The name and scope for search cannot be determined |
asNO_GLOBAL_VAR | The matching global variable was found. |
This method should be used to retrieve the index of the script variable that you wish to access.
The search for global variables will be performed in the default namespace as given by SetDefaultNamespace unless the name is prefixed with a scope, using the scoping operator ::. If the scope starts with :: it will be used as the absolute scope, otherwise it will be relative to the default namespace.
|
pure virtual |
This function returns the number of functions that are imported in a module. These functions need to be bound before they can be used, or a script exception will be thrown.
|
pure virtual |
[in] | importIndex | The index of the imported function. |
Use this function to get the declaration of the imported function. The returned declaration can be used to find a matching function in another module that can be bound to the imported function.
|
pure virtual |
[in] | decl | The function declaration of the imported function. |
asERROR | The module was not built successfully. |
asMULTIPLE_FUNCTIONS | Found multiple matching functions. |
asNO_FUNCTION | Didn't find any matching function. |
This function is used to find a specific imported function by its declaration.
|
pure virtual |
[in] | importIndex | The index of the imported function. |
Use this function to get the name of the suggested module to import the function from.
|
pure virtual |
|
pure virtual |
[in] | index | The index of the type. |
This does not increase the reference count of the returned object.
|
pure virtual |
|
pure virtual |
[in] | index | The index of the typedef. |
|
pure virtual |
|
pure virtual |
[in] | decl | The declaration of the type. |
asINVALID_TYPE | decl is not a valid type. |
Translates a type declaration into a type id. The returned type id is valid for as long as the type is valid, so you can safely store it for later use to avoid potential overhead from calling this function each time. Just remember to update the type id, any time the type is changed within the engine, e.g. when recompiling script declared classes, or changing the engine configuration.
The type id is based on a sequence number and depends on the order in which the type ids are queried, thus is not guaranteed to always be the same for each execution of the application. The asETypeIdFlags can be used to obtain some information about the type directly from the id.
A base type yields the same type id whether the declaration is const or not, however if the const is for the subtype then the type id is different, e.g. string@ isn't the same as const string@ but string is the same as const string.
|
pure virtual |
[in] | decl | The declaration of the type. |
Translates a type declaration into the type info. The returned type is valid for as long as the type is valid, so you can safely store it for later use to avoid potential overhead from calling this function each time. Just remember to update the type info pointer any time the type is changed within the engine, e.g. when recompiling script declared classes, or changing the engine configuration.
|
pure virtual |
[in] | name | The name of the type. |
The search for types will be performed in the default namespace as given by SetDefaultNamespace unless the name is prefixed with a scope, using the scoping operator ::. If the scope starts with :: it will be used as the absolute scope, otherwise it will be relative to the default namespace.
|
pure virtual |
[in] | type | An identifier specifying the user data to set. |
|
pure virtual |
[in] | in | The input stream. |
[out] | wasDebugInfoStripped | Set to true if the byte code was saved without debug information. |
asINVALID_ARG | The stream object wasn't specified. |
asBUILD_IN_PROGRESS | Another thread is currently building. |
asOUT_OF_MEMORY | The engine ran out of memory while loading the byte code. |
asMODULE_IS_IN_USE | The code in the module is still being used and and cannot be removed. |
asERROR | It was not possible to load the byte code. |
This method is used to load pre-compiled byte code from disk or memory. The application must implement an object that inherits from asIBinaryStream to provide the necessary stream operations.
It is expected that the application performs the necessary validations to make sure the pre-compiled byte code is from a trusted source. The application should also make sure the pre-compiled byte code is compatible with the current engine configuration, i.e. that the engine has been configured in the same way as when the byte code was first compiled.
If the method returns asERROR it is either because the byte code is incorrect, e.g. corrupted due to disk failure, or it has been compiled with a different engine configuration. If possible the engine provides information about the type of error that caused the failure while loading the byte code to the message stream.
|
pure virtual |
[in] | func | The pointer to the function that should be removed. |
asNO_FUNCTION | The function is not part of the scope. |
This method allows the application to remove a single function from the scope of the module. The function is not destroyed immediately though, only when no more references point to it.
|
pure virtual |
[in] | index | The index of the global variable. |
asINVALID_ARG | The index is out of range. |
The global variable is removed from the scope of the module, but it is not destroyed until all functions that access it are freed.
|
pure virtual |
[in] | ctx | Optional script context. |
asERROR | The module was not compiled successfully. |
asINIT_GLOBAL_VARS_FAILED | The initialization of the global variables failed. |
Resets the global variables declared in this module to their initial value. The context should be informed if the application needs to have extra control over how the initialization is done, for example for debugging, or for catching exceptions.
|
pure virtual |
[in] | out | The output stream. |
[in] | stripDebugInfo | Set to true to skip saving the debug information. |
asINVALID_ARG | The stream object wasn't specified. |
asNOT_SUPPORTED | Compiler support is disabled in the engine. |
asERROR | Nothing has been compiled in the module. |
This method is used to save pre-compiled byte code to disk or memory, for a later restoral. The application must implement an object that inherits from asIBinaryStream to provide the necessary stream operations.
[in] | accessMask | The access bit mask |
The module's access mask with be bitwise and-ed with the registered entity's access mask in order to determine if the module is allowed to access the entity. If the result is 0 then the script in the module will not be able to use the entity.
This can be used to provide different interfaces to scripts that serve different purposes in the application.
|
pure virtual |
[in] | nameSpace | The namespace that should be used. |
asINVALID_ARG | The namespace is null. |
asINVALID_DECLARATION | The namespace is invalid. |
Set the default namespace that should be used in the following calls for searching for declared entities, or when compiling new individual entities.
|
pure virtual |
[in] | name | The new name. |
Sets the name of the script module.
|
pure virtual |
[in] | data | A pointer to the user data. |
[in] | type | An identifier specifying the user data to set. |
This method allows the application to associate a value, e.g. a pointer, with the module instance.
The type values 1000 through 1999 are reserved for use by the official add-ons.
Optionally, a callback function can be registered to clean up the user data when the module is destroyed.
|
pure virtual |
Unbinds all imported functions in the module.
|
pure virtual |
[in] | importIndex | The index of the imported function. |
asINVALID_ARG | The index is not valid. |
Unbinds the imported function.