This class is a helper class for loading and building scripts, with a basic pre-processor that supports conditional compilation, include directives, and metadata declarations.
By default the script builder resolves include directives by loading the included file from the relative directory of the file it is included from. If you want to do this in another way, then you should implement the include callback which will let you process the include directive in a custom way, e.g. to load the included file from memory, or to support multiple search paths. The include callback should call the AddSectionFromFile or AddSectionFromMemory to include the section in the current build.
If you do not want process metadata then you can compile the add-on with the define AS_PROCESS_METADATA 0, which will exclude the code for processing this. This define can be made in the project settings or directly in the header.
class CScriptBuilder { public: // Start a new module int StartNewModule(asIScriptEngine *engine, const char *moduleName); // Load a script section from a file on disk int AddSectionFromFile(const char *filename); // Load a script section from memory int AddSectionFromMemory(const char *scriptCode, const char *sectionName = ""); // Build the added script sections int BuildModule(); // Register the callback for resolving include directive void SetIncludeCallback(INCLUDECALLBACK_t callback, void *userParam); // Add a pre-processor define for conditional compilation void DefineWord(const char *word); // Get metadata declared for class types and interfaces const char *GetMetadataStringForType(int typeId); // Get metadata declared for functions const char *GetMetadataStringForFunc(int funcId); // Get metadata declared for global variables const char *GetMetadataStringForVar(int varIdx); };
// This callback will be called for each #include directive encountered by the // builder. The callback should call the AddSectionFromFile or AddSectionFromMemory // to add the included section to the script. If the include cannot be resolved // then the function should return a negative value to abort the compilation. typedef int (*INCLUDECALLBACK_t)(const char *include, const char *from, CScriptBuilder *builder, void *userParam);
#include "commonfuncs.as"
void main() { // Call a function from the included file CommonFunc(); }
This is especially useful when scripts are shared between different binaries, for example, in a client/server application.
Example script with conditional compilation:
class CObject { void Process() { #if SERVER // Do some server specific processing #endif
#if CLIENT // Do some client specific processing #endif
// Do some common processing } }
Exactly what the metadata looks like is up to the application. The builder class doesn't impose any rules, except that the metadata should be added between brackets []. After the script has been built the application can obtain the metadata strings and interpret them as it sees fit.
Example script with metadata:
[factory func = CreateOgre, editable: myPosition, editable: myStrength [10, 100]] class COgre { vector3 myPosition; int myStrength; }
[factory] COgre @CreateOgre() { return @COgre(); }
Example usage:
CScriptBuilder builder; int r = builder.StartNewModule(engine, "my module"); if( r >= 0 ) r = builder.AddSectionFromMemory(script); if( r >= 0 ) r = builder.BuildModule(); if( r >= 0 ) { // Find global variables that have been marked as editable by user asIScriptModule *mod = engine->GetModule("my module"); int count = mod->GetGlobalVarCount(); for( int n = 0; n < count; n++ ) { string metadata = builder.GetMetadataStringForVar(n); if( metadata == "editable" ) { // Show the global variable in a GUI ... } } }