Class that manages a CBot program. This is the main entry point into the CBot engine.
More...
#include <src/CBot/CBotProgram.h>
|
| CBotProgram () |
| Constructor. More...
|
|
| CBotProgram (CBotVar *thisVar) |
| Constructor. More...
|
|
| ~CBotProgram () |
| Destructor. More...
|
|
bool | Compile (const std::string &program, std::vector< std::string > &externFunctions, 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 (std::ostream &ostr) |
| Save the current execution status into a file. More...
|
|
bool | RestoreState (std::istream &istr) |
| 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...
|
|
const std::list< CBotFunction * > & | GetFunctions () |
| Returns the list of all user-defined functions in this program as instances of CBotFunction. More...
|
|
bool | ClassExists (std::string name) |
| Check if class with that name was created in this program. More...
|
|
|
class | CBotFunction |
|
class | CBotDebug |
|
Class that manages a CBot program. This is the main entry point into the CBot engine.
Engine initialization / destruction
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().
Example usage
std::vector<std::string> externFunctions;
bool ok = program->
Compile(code.c_str(), externFunctions,
nullptr);
if (!ok)
{
int cursor1, cursor2;
program->
GetError(error, cursor1, cursor2);
}
program->
Start(externFunctions[0]);
Class that manages a CBot program. This is the main entry point into the CBot engine.
Definition: CBotProgram.h:87
bool Start(const std::string &name)
Starts the program using given function as an entry point. The function must be declared as "extern".
Definition: CBotProgram.cpp:150
CBotError GetError()
Returns the last error.
Definition: CBotProgram.cpp:246
static void Free()
Frees the static memory areas.
Definition: CBotProgram.cpp:413
CBotProgram()
Constructor.
Definition: CBotProgram.cpp:39
bool Compile(const std::string &program, std::vector< std::string > &externFunctions, void *pUser=nullptr)
Compile compiles the program given as string.
Definition: CBotProgram.cpp:61
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.
Definition: CBotProgram.cpp:313
bool Run(void *pUser=nullptr, int timer=-1)
Executes the program.
Definition: CBotProgram.cpp:177
static void Init()
Initializes the module, should be done once (and only once) at the beginning.
Definition: CBotProgram.cpp:389
CBotError
This enum contains possible CBot error values. Values in range 5000-5999 are compile errors,...
Definition: CBotEnums.h:198
◆ CBotProgram() [1/2]
CBot::CBotProgram::CBotProgram |
( |
| ) |
|
◆ CBotProgram() [2/2]
CBot::CBotProgram::CBotProgram |
( |
CBotVar * |
thisVar | ) |
|
Constructor.
- Parameters
-
thisVar | Variable to pass to the program as "this" |
◆ ~CBotProgram()
CBot::CBotProgram::~CBotProgram |
( |
| ) |
|
◆ Init()
void CBot::CBotProgram::Init |
( |
| ) |
|
|
static |
Initializes the module, should be done once (and only once) at the beginning.
◆ Free()
void CBot::CBotProgram::Free |
( |
| ) |
|
|
static |
Frees the static memory areas.
◆ GetVersion()
int CBot::CBotProgram::GetVersion |
( |
| ) |
|
|
static |
Returns version of the CBot library.
- Returns
- A number representing the current library version
◆ Compile()
bool CBot::CBotProgram::Compile |
( |
const std::string & |
program, |
|
|
std::vector< std::string > & |
externFunctions, |
|
|
void * |
pUser = nullptr |
|
) |
| |
Compile compiles the program given as string.
Compilation is done in a few steps:
- Convert the code into "tokens" - see CBotToken::CompileTokens()
- First pass - getting declarations of all functions an classes for use later
- Second pass - compiling definitions of all functions and classes
- Parameters
-
| program | Code to compile |
[out] | externFunctions | Returns the names of functions declared as extern |
| pUser | Optional pointer to be passed to compile function (see AddFunction()) |
- Returns
- true if compilation is successful, false if an compilation error occurs
- See also
- GetError() to retrieve the error
◆ GetError() [1/3]
◆ GetError() [2/3]
bool CBot::CBotProgram::GetError |
( |
CBotError & |
code, |
|
|
int & |
start, |
|
|
int & |
end |
|
) |
| |
Returns the last error.
- Parameters
-
[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 |
- Returns
- false if no error has occurred
◆ GetError() [3/3]
Returns the last error.
- Parameters
-
[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?) |
- Returns
- false if no error has occurred
◆ Start()
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".
- Parameters
-
name | Name of function to start |
- Returns
- true if the program was started, false if the function name is not found
- See also
- Compile() returns list of extern functions found in the code
◆ Run()
bool CBot::CBotProgram::Run |
( |
void * |
pUser = nullptr , |
|
|
int |
timer = -1 |
|
) |
| |
Executes the program.
- Parameters
-
pUser | Custom pointer to be passed to execute function (see AddFunction()) |
timer |
- timer < 0 do nothing
- timer >= 0 call SetTimer(int timer) before executing
|
- Returns
- true if the program execution finished, false if the program is suspended (you then have to call Run() again)
◆ GetRunPos()
bool CBot::CBotProgram::GetRunPos |
( |
std::string & |
functionName, |
|
|
int & |
start, |
|
|
int & |
end |
|
) |
| |
Gives the current position in the executing program.
- Parameters
-
[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 |
- Returns
- false if it is not running (program completion)
◆ GetStackVars()
CBotVar * CBot::CBotProgram::GetStackVars |
( |
std::string & |
functionName, |
|
|
int |
level |
|
) |
| |
Provides the pointer to the variables on the execution stack.
- Parameters
-
[out] | functionName | Name of the function that this stack is part of |
| level | 0 for the last level, -1, -2 etc. for previous ones |
- Returns
- Variables on the given stack level. Process using CBotVar::GetNext(). If the stack level is invalid, returns nullptr.
◆ Stop()
void CBot::CBotProgram::Stop |
( |
| ) |
|
Stops execution of the program.
◆ AddFunction()
bool CBot::CBotProgram::AddFunction |
( |
const std::string & |
name, |
|
|
bool |
rExecCBotVar *pVar, CBotVar *pResult, int &Exception, void *pUser, |
|
|
CBotTypResult |
rCompileCBotVar *&pVar, void *pUser |
|
) |
| |
|
static |
Add a function that can be called from CBot.
To define an external function, proceed as follows:
- Define a function for compilation
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
{
}
T * GetNext()
Returns the next variable in the linked list.
Definition: CBotUtils.h:110
Class to define the complete type of a variable.
Definition: CBotTypResult.h:48
A CBot variable.
Definition: CBotVar.h:44
CBotType GetType(GetTypeMode mode=GetTypeMode::NORMAL)
GetType Returns the base type of the variable (CBotType)
Definition: CBotVar.cpp:358
@ CBotErrOverParam
too many parameters
Definition: CBotEnums.h:228
@ CBotErrBadString
expected string
Definition: CBotEnums.h:241
@ CBotErrLowParam
not enough parameters
Definition: CBotEnums.h:230
@ CBotTypString
string
Definition: CBotEnums.h:46
@ CBotTypFloat
float
Definition: CBotEnums.h:43
- Define a function for execution
This function should take:
- a list of parameters
- pointer to a result variable (a variable of type given at compilation time will be provided)
- pointer to an exception variable
- user-defined pointer (can be passed in Run())
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".
bool rMessage(
CBotVar* var,
CBotVar* result,
int& exception,
void* user)
{
std::cout << message << std::endl;
return true;
}
virtual std::string GetValString()
Get value as string.
Definition: CBotVar.cpp:825
- Call AddFunction() to register the function in the CBot engine
For more sophisticated examples, see the Colobot source code, mainly the src/script/scriptfunc.cpp file
- Parameters
-
name | Name of the function |
rExec | Execution function |
rCompile | Compilation function |
- Returns
- true
◆ DefineNum()
bool CBot::CBotProgram::DefineNum |
( |
const std::string & |
name, |
|
|
long |
val |
|
) |
| |
|
static |
Define a new constant.
- Parameters
-
name | Name of the constant |
val | Value of the constant |
- Returns
- true on success, false if already defined
- See also
- CBotToken::DefineNum()
◆ SaveState()
bool CBot::CBotProgram::SaveState |
( |
std::ostream & |
ostr | ) |
|
Save the current execution status into a file.
- Parameters
-
- Returns
- true on success, false on write error
◆ RestoreState()
bool CBot::CBotProgram::RestoreState |
( |
std::istream & |
istr | ) |
|
Restore the execution state from a file.
The previous program code must already have been recompiled with Compile() before calling this function
- Parameters
-
- Returns
- true on success, false on read error
◆ GetPosition()
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
- Parameters
-
name | |
start | |
stop | |
modestart | |
modestop | |
- Returns
◆ GetFunctions()
const std::list< 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)
- Returns
- List of CBotFunction instances
◆ ClassExists()
bool CBot::CBotProgram::ClassExists |
( |
std::string |
name | ) |
|
Check if class with that name was created in this program.
- Returns
- True if class was defined in this program, otherwise, false
◆ GetExternalCalls()
Returns static list of all registered external calls.
The documentation for this class was generated from the following files:
- src/CBot/CBotProgram.h
- src/CBot/CBotProgram.cpp