Colobot
Public Member Functions | Static Public Member Functions | Public Attributes | Friends | List of all members
CBot::CBotProgram Class Reference

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...
 
CBotVarGetStackVars (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...
 
CBotFunctionGetFunctions ()
 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 CBotExternalCallListGetExternalCalls ()
 Returns static list of all registered external calls. More...
 

Public Attributes

bool m_bCompileClass
 true while compiling class More...
 

Friends

class CBotFunction
 
class CBotDebug
 

Detailed Description

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

// Initialize the engine
// Add some standard functions
CBotProgram::AddFunction("message", rMessage, cMessage);
// Compile the program
std::vector<std::string> externFunctions;
CBotProgram* program = new CBotProgram();
bool ok = program->Compile(code.c_str(), externFunctions, nullptr);
if (!ok)
{
CBotError error;
int cursor1, cursor2;
program->GetError(error, cursor1, cursor2);
// Handle the error
}
// Run the program
program->Start(externFunctions[0]);
while (!program->Run());
// Cleanup

Constructor & Destructor Documentation

CBot::CBotProgram::CBotProgram ( )

Constructor.

CBot::CBotProgram::CBotProgram ( CBotVar thisVar)

Constructor.

Parameters
thisVarVariable to pass to the program as "this"
CBot::CBotProgram::~CBotProgram ( )

Destructor.

Member Function Documentation

void CBot::CBotProgram::Init ( )
static

Initializes the module, should be done once (and only once) at the beginning.

void CBot::CBotProgram::Free ( )
static

Frees the static memory areas.

int CBot::CBotProgram::GetVersion ( )
static

Returns version of the CBot library.

Returns
A number representing the current library version
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:

  1. Convert the code into "tokens" - see CBotToken::CompileTokens()
  2. First pass - getting declarations of all functions an classes for use later
  3. Second pass - compiling definitions of all functions and classes
Parameters
programCode to compile
[out]functionsReturns the names of functions declared as extern
pUserOptional 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
CBotError CBot::CBotProgram::GetError ( )

Returns the last error.

Returns
Error code
See also
GetError(CBotError&, int&, int&) for error location in the code
bool CBot::CBotProgram::GetError ( CBotError code,
int &  start,
int &  end 
)

Returns the last error.

Parameters
[out]codeError code
[out]startStarting position in the code string of this error
[out]endEnding position in the code string of this error
Returns
false if no error has occurred
bool CBot::CBotProgram::GetError ( CBotError code,
int &  start,
int &  end,
CBotProgram *&  pProg 
)

Returns the last error.

Parameters
[out]codeError code
[out]startStarting position in the code string of this error
[out]endEnding position in the code string of this error
[out]pProgProgram that caused the error (TODO: This always returns "this"... what?)
Returns
false if no error has occurred
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
nameName 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
bool CBot::CBotProgram::Run ( void *  pUser = nullptr,
int  timer = -1 
)

Executes the program.

Parameters
pUserCustom pointer to be passed to execute function (see AddFunction())
timer
Returns
true if the program execution finished, false if the program is suspended (you then have to call Run() again)
bool CBot::CBotProgram::GetRunPos ( std::string &  functionName,
int &  start,
int &  end 
)

Gives the current position in the executing program.

Parameters
[out]functionNameName of the currently executed function
[out]startStarting position in the code string of currently executed instruction
[out]endEnding position in the code string of currently executed instruction
Returns
false if it is not running (program completion)
CBotVar * CBot::CBotProgram::GetStackVars ( std::string &  functionName,
int  level 
)

Provides the pointer to the variables on the execution stack.

Parameters
[out]functionNameName of the function that this stack is part of
level0 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.
void CBot::CBotProgram::Stop ( )

Stops execution of the program.

void CBot::CBotProgram::SetTimer ( int  n)
static

Sets the number of steps (parts of instructions) to execute in Run() before suspending the program execution.

Parameters
nnew timer value

FIXME: Seems to be currently kind of broken (see issue #410)

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:

  1. 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

CBotTypResult cMessage(CBotVar* &var, void* user)
{
if (var == nullptr) return CBotTypResult(CBotErrLowParam); // Not enough parameters
if (var->GetType() != CBotTypString) return CBotTypResult(CBotErrBadString); // String expected
var = var->GetNext(); // Get the next parameter
if (var != nullptr) return CBotTypResult(CBotErrOverParam); // Too many parameters
return CBotTypResult(CBotTypFloat); // This function returns float (it may depend on parameters given!)
}
  1. 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::string message = var->GetValString();
std::cout << message << std::endl;
return true; // Execution finished
}
  1. Call AddFunction() to register the function in the CBot engine
AddFunction("message", rMessage, cMessage);

For more sophisticated examples, see the Colobot source code, mainly the src/script/scriptfunc.cpp file

Parameters
nameName of the function
rExecExecution function
rCompileCompilation function
Returns
true
bool CBot::CBotProgram::DefineNum ( const std::string &  name,
long  val 
)
static

Define a new constant.

Parameters
nameName of the constant
valValue of the constant
Returns
true on success, false if already defined
See also
CBotToken::DefineNum()
bool CBot::CBotProgram::SaveState ( FILE *  pf)

Save the current execution status into a file.

Parameters
pf

file handle

This file handle must have been opened by this library! Otherwise crashes on Windows

TODO: Verify this

Returns
true on success, false on write error
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

Parameters
pffile handle
Returns
true on success, false on read error
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
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
Linked list of CBotFunction instances
CBotExternalCallList * CBot::CBotProgram::GetExternalCalls ( )
static

Returns static list of all registered external calls.

Member Data Documentation

bool CBot::CBotProgram::m_bCompileClass

true while compiling class

TODO: refactor this


The documentation for this class was generated from the following files: