Colobot
|
Class that manages a CBot program. This is the main entry point into the CBot engine. More...
#include <CBotProgram.h>
Public Member Functions | |
CBotProgram () | |
Constructor. More... | |
CBotProgram (CBotVar *thisVar) | |
Constructor. More... | |
~CBotProgram () | |
Destructor. More... | |
bool | Compile (const std::string &program, std::vector< std::string > &functions, void *pUser=nullptr) |
Compile compiles the program given as string. More... | |
CBotError | GetError () |
Returns the last error. More... | |
bool | GetError (CBotError &code, int &start, int &end) |
Returns the last error. More... | |
bool | GetError (CBotError &code, int &start, int &end, CBotProgram *&pProg) |
Returns the last error. More... | |
bool | Start (const std::string &name) |
Starts the program using given function as an entry point. The function must be declared as "extern". More... | |
bool | Run (void *pUser=nullptr, int timer=-1) |
Executes the program. More... | |
bool | GetRunPos (std::string &functionName, int &start, int &end) |
Gives the current position in the executing program. More... | |
CBotVar * | GetStackVars (std::string &functionName, int level) |
Provides the pointer to the variables on the execution stack. More... | |
void | Stop () |
Stops execution of the program. More... | |
bool | SaveState (FILE *pf) |
Save the current execution status into a file. More... | |
bool | RestoreState (FILE *pf) |
Restore the execution state from a file. More... | |
bool | GetPosition (const std::string &name, int &start, int &stop, CBotGet modestart=GetPosExtern, CBotGet modestop=GetPosBloc) |
GetPosition Gives the position of a routine in the original text the user can select the item to find from the beginning to the end see the above modes in CBotGet. More... | |
CBotFunction * | GetFunctions () |
Returns the list of all user-defined functions in this program as instances of CBotFunction. More... | |
Static Public Member Functions | |
static void | Init () |
Initializes the module, should be done once (and only once) at the beginning. More... | |
static void | Free () |
Frees the static memory areas. More... | |
static int | GetVersion () |
Returns version of the CBot library. More... | |
static void | SetTimer (int n) |
Sets the number of steps (parts of instructions) to execute in Run() before suspending the program execution. More... | |
static bool | AddFunction (const std::string &name, bool rExec(CBotVar *pVar, CBotVar *pResult, int &Exception, void *pUser), CBotTypResult rCompile(CBotVar *&pVar, void *pUser)) |
Add a function that can be called from CBot. More... | |
static bool | DefineNum (const std::string &name, long val) |
Define a new constant. More... | |
static CBotExternalCallList * | GetExternalCalls () |
Returns static list of all registered external calls. More... | |
Public Attributes | |
bool | m_bCompileClass |
true while compiling class More... | |
Friends | |
class | CBotFunction |
class | CBotDebug |
Class that manages a CBot program. This is the main entry point into the CBot engine.
To initialize the CBot engine, call CBotProgram::Init(). This function should be only called once.
Afterwards, you can start defining custom functions, constants and classes. See:
Next, compile and run programs.
After you are finished, free the memory used by the CBot engine by calling CBotProgram::Free().
CBot::CBotProgram::CBotProgram | ( | ) |
Constructor.
CBot::CBotProgram::CBotProgram | ( | CBotVar * | thisVar | ) |
Constructor.
thisVar | Variable to pass to the program as "this" |
CBot::CBotProgram::~CBotProgram | ( | ) |
Destructor.
|
static |
Initializes the module, should be done once (and only once) at the beginning.
|
static |
Frees the static memory areas.
|
static |
Returns version of the CBot library.
bool CBot::CBotProgram::Compile | ( | const std::string & | program, |
std::vector< std::string > & | functions, | ||
void * | pUser = nullptr |
||
) |
Compile compiles the program given as string.
Compilation is done in a few steps:
program | Code to compile | |
[out] | functions | Returns the names of functions declared as extern |
pUser | Optional pointer to be passed to compile function (see AddFunction()) |
CBotError CBot::CBotProgram::GetError | ( | ) |
Returns the last error.
bool CBot::CBotProgram::GetError | ( | CBotError & | code, |
int & | start, | ||
int & | end | ||
) |
Returns the last error.
[out] | code | Error code |
[out] | start | Starting position in the code string of this error |
[out] | end | Ending position in the code string of this error |
bool CBot::CBotProgram::GetError | ( | CBotError & | code, |
int & | start, | ||
int & | end, | ||
CBotProgram *& | pProg | ||
) |
Returns the last error.
[out] | code | Error code |
[out] | start | Starting position in the code string of this error |
[out] | end | Ending position in the code string of this error |
[out] | pProg | Program that caused the error (TODO: This always returns "this"... what?) |
bool CBot::CBotProgram::Start | ( | const std::string & | name | ) |
Starts the program using given function as an entry point. The function must be declared as "extern".
name | Name of function to start |
bool CBot::CBotProgram::Run | ( | void * | pUser = nullptr , |
int | timer = -1 |
||
) |
Executes the program.
pUser | Custom pointer to be passed to execute function (see AddFunction()) |
timer |
|
bool CBot::CBotProgram::GetRunPos | ( | std::string & | functionName, |
int & | start, | ||
int & | end | ||
) |
Gives the current position in the executing program.
[out] | functionName | Name of the currently executed function |
[out] | start | Starting position in the code string of currently executed instruction |
[out] | end | Ending position in the code string of currently executed instruction |
CBotVar * CBot::CBotProgram::GetStackVars | ( | std::string & | functionName, |
int | level | ||
) |
Provides the pointer to the variables on the execution stack.
[out] | functionName | Name of the function that this stack is part of |
level | 0 for the last level, -1, -2 etc. for previous ones |
void CBot::CBotProgram::Stop | ( | ) |
Stops execution of the program.
|
static |
Sets the number of steps (parts of instructions) to execute in Run() before suspending the program execution.
n | new timer value |
FIXME: Seems to be currently kind of broken (see issue #410)
|
static |
Add a function that can be called from CBot.
To define an external function, proceed as follows:
This function should take a list of function arguments (types only, no values!) and a user-defined void* pointer (can be passed in Compile()) as parameters, and return CBotTypResult.
Usually, name of this function is prefixed with "c".
The function should iterate through the provided parameter list and verify that they match.
If they don't, then return CBotTypResult with an appropariate error code (see CBotError).
If they do, return CBotTypResult with the function's return type
This function should take:
This function returns true if execution of this function is finished, or false to suspend the program and call this function again on next Run() cycle.
Usually, execution functions are prefixed with "r".
For more sophisticated examples, see the Colobot source code, mainly the src/script/scriptfunc.cpp file
name | Name of the function |
rExec | Execution function |
rCompile | Compilation function |
|
static |
Define a new constant.
name | Name of the constant |
val | Value of the constant |
bool CBot::CBotProgram::SaveState | ( | FILE * | pf | ) |
Save the current execution status into a file.
pf | file handle This file handle must have been opened by this library! Otherwise crashes on Windows TODO: Verify this |
bool CBot::CBotProgram::RestoreState | ( | FILE * | pf | ) |
Restore the execution state from a file.
The previous program code must already have been recompiled with Compile() before calling this function
pf | file handle |
bool CBot::CBotProgram::GetPosition | ( | const std::string & | name, |
int & | start, | ||
int & | stop, | ||
CBotGet | modestart = GetPosExtern , |
||
CBotGet | modestop = GetPosBloc |
||
) |
GetPosition Gives the position of a routine in the original text the user can select the item to find from the beginning to the end see the above modes in CBotGet.
TODO: Document this
name | |
start | |
stop | |
modestart | |
modestop |
CBotFunction * CBot::CBotProgram::GetFunctions | ( | ) |
Returns the list of all user-defined functions in this program as instances of CBotFunction.
This list includes all the functions (not only extern)
|
static |
Returns static list of all registered external calls.
bool CBot::CBotProgram::m_bCompileClass |
true while compiling class
TODO: refactor this