Colobot
Public Types | List of all members
CBot::CBotStack Class Reference

The execution stack. More...

#include <src/CBot/CBotStack.h>

Public Types

enum  BlockVisibilityType : unsigned short { BlockVisibilityType::INSTRUCTION = 0, BlockVisibilityType::BLOCK = 1, BlockVisibilityType::FUNCTION = 2 }
 Block type this stack represents. This determines local variable visibility (you can only see up to top FUNCTION stack) More...
 
enum  IsFunction : unsigned short { NO = 0, YES = 1, EXTERNAL_CALL = 2 }
 

Stack memory management

static CBotStackAllocateStack ()
 Allocate the stack. More...
 
void Delete ()
 Remove the current stack. More...
 
 CBotStack ()=delete
 Allocate the stack. More...
 
 ~CBotStack ()=delete
 Allocate the stack. More...
 
bool StackOver ()
 Check for stack overflow and set error status as needed. More...
 

Error management

BE CAREFUL - errors are stored in static variables!

Todo:
Refactor that
CBotError GetError (int &start, int &end)
 Get last error. More...
 
CBotError GetError ()
 Get last error. More...
 
bool IsOk ()
 Check if there was an error. More...
 
void SetError (CBotError n, CBotToken *token=nullptr)
 Set execution error unless it's already set unless you are trying to reset it. More...
 
void SetPosError (CBotToken *token)
 Set error position to position of given token. More...
 
void ResetError (CBotError n, int start, int end)
 Set execution error even if it is already set. More...
 
void SetBreak (int val, const std::string &name)
 
void Reset ()
 Reset the stack for execution resume - resets the error and timer. More...
 

Local variables

void AddVar (CBotVar *var)
 Adds a local variable. More...
 
CBotVarFindVar (CBotToken *&pToken, bool bUpdate)
 Fetch a variable by its token. More...
 
CBotVarFindVar (CBotToken &pToken, bool bUpdate)
 Fetch a variable by its token. More...
 
CBotVarFindVar (const std::string &name)
 Fetch variable by its name. More...
 
CBotVarFindVar (long ident, bool bUpdate)
 Fetch a variable on the stack according to its unique identifier. More...
 
CBotVarCopyVar (CBotToken &pToken, bool bUpdate=false)
 Find variable by its token and returns a copy of it. More...
 

Child stacks

When you enter a new code block or instruction, child stack is created for managing everything that happens inside that block / instruction.

CBotStackAddStack (CBotInstr *instr=nullptr, BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
 Creates or gets the primary child stack. More...
 
CBotStackAddStack2 (BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
 Creates or gets the secondary child stack. More...
 
CBotStackAddStackExternalCall (CBotExternalCall *instr=nullptr, BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
 Adds special EOX stack marker. More...
 
CBotStackRestoreStack (CBotInstr *instr=nullptr)
 Restore CBotInstr pointer after loading stack from file. More...
 
CBotStackRestoreStackEOX (CBotExternalCall *instr=nullptr)
 Restores CBotExternalCall in the EOX marker after loading stack from file. More...
 
bool Return (CBotStack *pFils)
 Return to this point - copy the result from given stack, and destroy all child stacks from here. More...
 
bool ReturnKeep (CBotStack *pFils)
 Like Return() but doesn't destroy the stacks. More...
 
bool BreakReturn (CBotStack *pfils, const std::string &name="")
 
bool IfContinue (int state, const std::string &name)
 

Preserving execution status

A "state" is a number that determines how much of CBotInstr::Execute() has been already executed. When CBotInstr::Execute() is called, it continues execution from the point it finished at. See various CBotInstr::Execute() implementations for details.

Each state change causes one tick on the execution timer

bool SetState (int n, int lim=-10)
 Set execution state. More...
 
int GetState ()
 Return current execution state. More...
 
bool IncState (int lim=-10)
 Increase the execution state by one. More...
 
bool IfStep ()
 Check if we are in step by step execution mode. More...
 
bool Execute ()
 Resumes execution of interrupted external call. More...
 

Result variable

void SetVar (CBotVar *var)
 Set the result variable. More...
 
void SetCopyVar (CBotVar *var)
 Set the result variable to copy of given variable. More...
 
CBotVarGetVar ()
 Return result variable. More...
 
bool GetRetVar (bool bRet)
 
long GetVal ()
 Return the result variable as int. More...
 
void SetProgram (CBotProgram *p)
 Set program this stack level is in. Additionally marks this block as function block. Note: for public functions different stack levels might be in different programs. More...
 
CBotProgramGetProgram (bool bFirst=false)
 Get program we are currently in. More...
 
void SetUserPtr (void *user)
 Set user pointer for external calls. More...
 
void * GetUserPtr ()
 Get user pointer for external calls. More...
 
BlockVisibilityType GetBlock ()
 Get the block type this stack represents - instruction, code block or function. More...
 

Function calls

bool ExecuteCall (long &nIdent, CBotToken *token, CBotVar **ppVar, const CBotTypResult &rettype)
 Execute a function call, either external or user-defined. More...
 
void RestoreCall (long &nIdent, CBotToken *token, CBotVar **ppVar)
 Restore a function call after the program state has been restored from a file. More...
 

Write to file

static void SetTimer (int n)
 Set the maximum number of "timer ticks" (parts of instructions) to execute. More...
 
static int GetTimer ()
 Get the current configured maximum number of "timer ticks" (parts of instructions) to execute. More...
 
bool SaveState (FILE *pf)
 CBotProgram instance the execution is in in this stack level. More...
 
bool RestoreState (FILE *pf, CBotStack *&pStack)
 CBotProgram instance the execution is in in this stack level. More...
 
void GetRunPos (std::string &functionName, int &start, int &end)
 Get current position in the program. More...
 
CBotVarGetStackVars (std::string &functionName, int level)
 Get local variables at the given stack level. More...
 
bool IsCallFinished ()
 CBotProgram instance the execution is in in this stack level. More...
 

Detailed Description

The execution stack.

Member Enumeration Documentation

◆ BlockVisibilityType

enum CBot::CBotStack::BlockVisibilityType : unsigned short
strong

Block type this stack represents. This determines local variable visibility (you can only see up to top FUNCTION stack)

Enumerator
INSTRUCTION 

Instruction (default)

BLOCK 

Code block between { ... }.

FUNCTION 

Function - variable visibility limit.

Constructor & Destructor Documentation

◆ CBotStack()

CBot::CBotStack::CBotStack ( )
delete

Allocate the stack.

Returns
pointer to created stack

◆ ~CBotStack()

CBot::CBotStack::~CBotStack ( )
delete

Allocate the stack.

Returns
pointer to created stack

Member Function Documentation

◆ AllocateStack()

CBotStack * CBot::CBotStack::AllocateStack ( )
static

Allocate the stack.

Returns
pointer to created stack

◆ Delete()

void CBot::CBotStack::Delete ( )

Remove the current stack.

◆ StackOver()

bool CBot::CBotStack::StackOver ( )

Check for stack overflow and set error status as needed.

Returns
true on stack overflow

◆ GetError() [1/2]

CBotError CBot::CBotStack::GetError ( int &  start,
int &  end 
)
inline

Get last error.

Parameters
[out]startStarting position in code of the error
[out]endEnding position in code of the error
Returns
Error number

◆ GetError() [2/2]

CBotError CBot::CBotStack::GetError ( )
inline

Get last error.

Returns
Error number
See also
GetError(int&, int&) for error position in code

◆ IsOk()

bool CBot::CBotStack::IsOk ( )
inline

Check if there was an error.

Returns
false if an error occurred
See also
GetError()

◆ SetError()

void CBot::CBotStack::SetError ( CBotError  n,
CBotToken token = nullptr 
)

Set execution error unless it's already set unless you are trying to reset it.

Parameters
nError to set
tokenToken to take error position from
See also
ResetError() to force set error

◆ SetPosError()

void CBot::CBotStack::SetPosError ( CBotToken token)

Set error position to position of given token.

Parameters
tokenToken to take error position from

◆ ResetError()

void CBot::CBotStack::ResetError ( CBotError  n,
int  start,
int  end 
)

Set execution error even if it is already set.

See also
SetError() to set error only if it is not set already

◆ SetBreak()

void CBot::CBotStack::SetBreak ( int  val,
const std::string &  name 
)
Todo:
Document

WARNING! Changes error to -val ...

◆ Reset()

void CBot::CBotStack::Reset ( )

Reset the stack for execution resume - resets the error and timer.

◆ AddVar()

void CBot::CBotStack::AddVar ( CBotVar var)

Adds a local variable.

Parameters
varVariable to be added

◆ FindVar() [1/4]

CBotVar * CBot::CBotStack::FindVar ( CBotToken *&  pToken,
bool  bUpdate 
)

Fetch a variable by its token.

Parameters
pTokenToken upon which search is performed
bUpdatetrue to automatically call update function for classes, see CBotClass::SetUpdateFunc()
Returns
Found variable, nullptr if not found

◆ FindVar() [2/4]

CBotVar * CBot::CBotStack::FindVar ( CBotToken pToken,
bool  bUpdate 
)

Fetch a variable by its token.

Parameters
pTokenToken upon which search is performed
bUpdatetrue to automatically call update function for classes, see CBotClass::SetUpdateFunc()
Returns
Found variable, nullptr if not found

◆ FindVar() [3/4]

CBotVar * CBot::CBotStack::FindVar ( const std::string &  name)

Fetch variable by its name.

Parameters
nameName of variable to find
Returns
Found variable, nullptr if not found

◆ FindVar() [4/4]

CBotVar * CBot::CBotStack::FindVar ( long  ident,
bool  bUpdate 
)

Fetch a variable on the stack according to its unique identifier.

This is faster than comparing names

Parameters
identUnique identifier of a variable
bUpdatetrue to automatically call update function for classes, see CBotClass::SetUpdateFunc()
Returns
Found variable, nullptr if not found

◆ CopyVar()

CBotVar * CBot::CBotStack::CopyVar ( CBotToken pToken,
bool  bUpdate = false 
)

Find variable by its token and returns a copy of it.

Parameters
pTokenToken upon which search is performed
bUpdatetrue to automatically call update function for classes, see CBotClass::SetUpdateFunc()
Returns
Found variable, nullptr if not found

◆ AddStack()

CBotStack * CBot::CBotStack::AddStack ( CBotInstr instr = nullptr,
BlockVisibilityType  bBlock = BlockVisibilityType::INSTRUCTION 
)

Creates or gets the primary child stack.

If the stack already exists, it is returned. Otherwise, a new stack is created.

Todo:
Document params
Returns
New stack element

◆ AddStack2()

CBotStack * CBot::CBotStack::AddStack2 ( BlockVisibilityType  bBlock = BlockVisibilityType::INSTRUCTION)

Creates or gets the secondary child stack.

Todo:
What is it used for?

If the stack already exists, it is returned. Otherwise, a new stack is created.

See also
AddStack()
Returns
New stack element

◆ AddStackExternalCall()

CBotStack * CBot::CBotStack::AddStackExternalCall ( CBotExternalCall instr = nullptr,
BlockVisibilityType  bBlock = BlockVisibilityType::INSTRUCTION 
)

Adds special EOX stack marker.

Todo:
What is this thing? Used by external calls
Todo:
Document params & return

◆ RestoreStack()

CBotStack * CBot::CBotStack::RestoreStack ( CBotInstr instr = nullptr)

Restore CBotInstr pointer after loading stack from file.

Todo:
Check what this does exactly

◆ RestoreStackEOX()

CBotStack * CBot::CBotStack::RestoreStackEOX ( CBotExternalCall instr = nullptr)

Restores CBotExternalCall in the EOX marker after loading stack from file.

Todo:
Check what this does exactly

◆ Return()

bool CBot::CBotStack::Return ( CBotStack pFils)

Return to this point - copy the result from given stack, and destroy all child stacks from here.

Todo:
Better description
Parameters
pFilsStack to copy result from
Returns
IsOk()

◆ ReturnKeep()

bool CBot::CBotStack::ReturnKeep ( CBotStack pFils)

Like Return() but doesn't destroy the stacks.

Parameters
pFilsStack to copy result from
Returns
IsOk()

◆ BreakReturn()

bool CBot::CBotStack::BreakReturn ( CBotStack pfils,
const std::string &  name = "" 
)
Todo:
Document

in case of eventual break

◆ IfContinue()

bool CBot::CBotStack::IfContinue ( int  state,
const std::string &  name 
)
Todo:
Document

or "continue"

◆ SetState()

bool CBot::CBotStack::SetState ( int  n,
int  lim = -10 
)

Set execution state.

Parameters
nNew state
limRequired amount of "ticks" on the timer required to allow to continue execution. By default allows a little overflow (up to 10 ticks)
Returns
false if timer requests interruption (timer <= limit)

◆ GetState()

int CBot::CBotStack::GetState ( )
inline

Return current execution state.

Used when resuming execution

Returns
Execution state set before interruption by SetState() and IncState()

◆ IncState()

bool CBot::CBotStack::IncState ( int  lim = -10)

Increase the execution state by one.

Parameters
limRequired amount of "ticks" on the timer required to allow to continue execution. By default allows a little overflow (up to 10 ticks)
Returns
false if timer requests interruption (timer <= limit)

◆ IfStep()

bool CBot::CBotStack::IfStep ( )

Check if we are in step by step execution mode.

Returns
true if step by step, false otherwise

◆ Execute()

bool CBot::CBotStack::Execute ( )

Resumes execution of interrupted external call.

Returns
true if external call finished, false if interrupted again

◆ SetVar()

void CBot::CBotStack::SetVar ( CBotVar var)

Set the result variable.

Todo:
CBotStack takes over the ownership - use std::unique_ptr here
Parameters
varResult variable to set

◆ SetCopyVar()

void CBot::CBotStack::SetCopyVar ( CBotVar var)

Set the result variable to copy of given variable.

Parameters
varVariable to copy as result

◆ GetVar()

CBotVar * CBot::CBotStack::GetVar ( )

Return result variable.

Returns
Variable set with SetVar() or SetCopyVar()

◆ GetRetVar()

bool CBot::CBotStack::GetRetVar ( bool  bRet)
Todo:
Document

Copies the result value from static m_retvar (m_var at a moment of SetBreak(3)) to this stack result

◆ GetVal()

long CBot::CBotStack::GetVal ( )

Return the result variable as int.

Deprecated:
Please use GetVar()->GetValInt() instead
Todo:
Remove
Returns
GetVar()->GetValInt(), or 0 if GetVar() == nullptr

◆ SetProgram()

void CBot::CBotStack::SetProgram ( CBotProgram p)

Set program this stack level is in. Additionally marks this block as function block. Note: for public functions different stack levels might be in different programs.

Todo:
Refactor this two-in-one thing
Parameters
pCBotProgram we are currently in

◆ GetProgram()

CBotProgram * CBot::CBotStack::GetProgram ( bool  bFirst = false)

Get program we are currently in.

Parameters
bFirstif true, get the main CBotProgram instance (the one that has the main function)

◆ SetUserPtr()

void CBot::CBotStack::SetUserPtr ( void *  user)

Set user pointer for external calls.

Execution calls only - see CBotExternalCallList::SetUserPtr() for compilation calls

Parameters
userUser pointer to set

◆ GetUserPtr()

void * CBot::CBotStack::GetUserPtr ( )

Get user pointer for external calls.

Returns
User pointer for external execution calls
See also
SetUserPtr()

◆ GetBlock()

CBotStack::BlockVisibilityType CBot::CBotStack::GetBlock ( )

Get the block type this stack represents - instruction, code block or function.

See also
BlockVisibilityType enum

◆ ExecuteCall()

bool CBot::CBotStack::ExecuteCall ( long &  nIdent,
CBotToken token,
CBotVar **  ppVar,
const CBotTypResult rettype 
)

Execute a function call, either external or user-defined.

Parameters
[in,out]nIdentUnique function identifier, if not found will be updated
tokenFunction name token
ppVarArray of function arguments
rettypeExpected return type

◆ RestoreCall()

void CBot::CBotStack::RestoreCall ( long &  nIdent,
CBotToken token,
CBotVar **  ppVar 
)

Restore a function call after the program state has been restored from a file.

Parameters
[in,out]nIdentUnique function identifier, if not found will be updated
tokenFunction name token
ppVarArray of function arguments

◆ SaveState()

bool CBot::CBotStack::SaveState ( FILE *  pf)

CBotProgram instance the execution is in in this stack level.

◆ RestoreState()

bool CBot::CBotStack::RestoreState ( FILE *  pf,
CBotStack *&  pStack 
)

CBotProgram instance the execution is in in this stack level.

◆ SetTimer()

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

Set the maximum number of "timer ticks" (parts of instructions) to execute.

This setting gets applied on next call to Reset()

Todo:
Full documentation of the timer

◆ GetTimer()

int CBot::CBotStack::GetTimer ( )
static

Get the current configured maximum number of "timer ticks" (parts of instructions) to execute.

◆ GetRunPos()

void CBot::CBotStack::GetRunPos ( std::string &  functionName,
int &  start,
int &  end 
)

Get current position in the program.

Parameters
[out]functionNameCurrent function name, nullptr if not found
[out]startStart position of currently executed token
[out]endEnd position of currently executed token

◆ GetStackVars()

CBotVar * CBot::CBotStack::GetStackVars ( std::string &  functionName,
int  level 
)

Get local variables at the given stack level.

Parameters
[out]functionNameName of instruction being executed at this level
level0 for current level, -1, -2, -3 etc. for next levels

◆ IsCallFinished()

bool CBot::CBotStack::IsCallFinished ( )

CBotProgram instance the execution is in in this stack level.


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