Loading...
Searching...
No Matches
CBot::CBotProgram Class Reference

Class that manages a CBot program. This is the main entry point into the CBot engine. More...

`#include <src/CBot/CBotProgram.h>`

## Public Member Functions

| CBotProgram ()
| Constructor.
| CBotProgram (CBotVar *thisVar)
| Constructor.
| ~CBotProgram ()
| Destructor.
bool | Compile (const std::string &program, std::vector< std::string > &externFunctions, void *pUser=nullptr)
| Compile compiles the program given as string.
CBotError | GetError ()
| Returns the last error.
bool | GetError (CBotError &code, int &start, int &end)
| Returns the last error.
bool | GetError (CBotError &code, int &start, int &end, CBotProgram *&pProg)
| Returns the last error.
bool | Start (const std::string &name)
| Starts the program using given function as an entry point. The function must be declared as "extern".
bool | Run (void *pUser=nullptr, int timer=-1)
| Executes the program.
bool | GetRunPos (std::string &functionName, int &start, int &end)
| Gives the current position in the executing program.
CBotVar * | GetStackVars (std::string &functionName, int level)
| Provides the pointer to the variables on the execution stack.
void | Stop ()
| Stops execution of the program.
bool | SaveState (std::ostream &ostr)
| Save the current execution status into a file.
bool | RestoreState (std::istream &istr)
| Restore the execution state from a file.
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.
const std::list< CBotFunction * > & | GetFunctions ()
| Returns the list of all user-defined functions in this program as instances of CBotFunction.
bool | ClassExists (std::string name)
| Check if class with that name was created in this program.

## Static Public Member Functions

static void | Init ()
| Initializes the module, should be done once (and only once) at the beginning.
static void | Free ()
| Frees the static memory areas.
static int | GetVersion ()
| Returns version of the CBot library.
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.
static bool | DefineNum (const std::string &name, long val)
| Define a new constant.
static const std::unique_ptr< CBotExternalCallList > & | GetExternalCalls ()
| Returns static list of all registered external calls.

## 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:

- CBotProgram::AddFunction()
- CBotProgram::DefineNum()
- CBotClass::Create()

Next, compile and run programs.

- Compile()
- Start()
- Run()
- Stop()

After you are finished, free the memory used by the CBot engine by calling CBotProgram::Free().

# Example usage

// Initialize the engine
CBotProgram::Init();
// 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
CBotProgram::Free();
CBot::CBotProgram::Start
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
CBot::CBotProgram::GetError
CBotError GetError()
Returns the last error.
Definition CBotProgram.cpp:246
CBot::CBotProgram::Free
static void Free()
Frees the static memory areas.
Definition CBotProgram.cpp:413
CBot::CBotProgram::CBotProgram
CBotProgram()
Constructor.
Definition CBotProgram.cpp:39
CBot::CBotProgram::Compile
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
CBot::CBotProgram::AddFunction
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
CBot::CBotProgram::Run
bool Run(void *pUser=nullptr, int timer=-1)
Executes the program.
Definition CBotProgram.cpp:177
CBot::CBotProgram::Init
static void Init()
Initializes the module, should be done once (and only once) at the beginning.
Definition CBotProgram.cpp:389
CBot::CBotError
CBotError
This enum contains possible CBot error values. Values in range 5000-5999 are compile errors,...
Definition CBotEnums.h:198

## Constructor & Destructor Documentation

## CBotProgram() [1/2]

CBot::CBotProgram::CBotProgram | ( |  | ) |

Constructor.

## CBotProgram() [2/2]

CBot::CBotProgram::CBotProgram | ( | CBotVar * | thisVar | ) |

Constructor.

Parameters

  thisVar | Variable to pass to the program as "this"

## ~CBotProgram()

CBot::CBotProgram::~CBotProgram | ( |  | ) |

Destructor.

## Member Function Documentation

## 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:

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

  | 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]

CBotError CBot::CBotProgram::GetError | ( |  | ) |

Returns the last error.

Returns
  Error code

See also
  GetError(CBotError&, int&, int&) for error location in the code

## 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]

bool CBot::CBotProgram::GetError | ( | CBotError & | code,
|  | int & | start,
|  | int & | end,
|  | CBotProgram *& | pProg )

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:

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!)
}
CBot::CBotLinkedList::GetNext
T * GetNext()
Returns the next variable in the linked list.
Definition CBotUtils.h:110
CBot::CBotTypResult
Class to define the complete type of a variable.
Definition CBotTypResult.h:48
CBot::CBotVar
A CBot variable.
Definition CBotVar.h:44
CBot::CBotVar::GetType
CBotType GetType(GetTypeMode mode=GetTypeMode::NORMAL) const
GetType Returns the base type of the variable (CBotType).
Definition CBotVar.cpp:358
CBot::CBotErrOverParam
@ CBotErrOverParam
too many parameters
Definition CBotEnums.h:228
CBot::CBotErrBadString
@ CBotErrBadString
expected string
Definition CBotEnums.h:241
CBot::CBotErrLowParam
@ CBotErrLowParam
not enough parameters
Definition CBotEnums.h:230
CBot::CBotTypString
@ CBotTypString
string
Definition CBotEnums.h:46
CBot::CBotTypFloat
@ CBotTypFloat
float
Definition CBotEnums.h:43

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
}
CBot::CBotVar::GetValString
virtual std::string GetValString() const
Get value as string.
Definition CBotVar.cpp:825

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

  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

  ostr | Output stream

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

  istr | Input stream

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()

const std::unique_ptr< CBotExternalCallList > & CBot::CBotProgram::GetExternalCalls | ( |  | ) |

static

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