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

The execution stack. More...

#include <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 }
 

Public Member Functions

void Reset ()
 Reset the stack for execution resume - resets the error and timer. 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...
 
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 ()
 

Static Public Member Functions

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

Stack memory management

static CBotStackAllocateStack ()
 Allocate the stack. More...
 
void Delete ()
 Remove the current stack. More...
 
 CBotStack ()=delete
 
 ~CBotStack ()=delete
 
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)
 

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

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

bool SaveState (FILE *pf)
 
bool RestoreState (FILE *pf, CBotStack *&pStack)
 

Detailed Description

The execution stack.

Member Enumeration Documentation

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.

Member Function Documentation

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

Allocate the stack.

Returns
pointer to created stack
void CBot::CBotStack::Delete ( )

Remove the current stack.

bool CBot::CBotStack::StackOver ( )

Check for stack overflow and set error status as needed.

Returns
true on stack overflow
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
CBotError CBot::CBotStack::GetError ( )
inline

Get last error.

Returns
Error number
See also
GetError(int&, int&) for error position in code
bool CBot::CBotStack::IsOk ( )
inline

Check if there was an error.

Returns
false if an error occurred
See also
GetError()
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
void CBot::CBotStack::SetPosError ( CBotToken token)

Set error position to position of given token.

Parameters
tokenToken to take error position from
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
void CBot::CBotStack::SetBreak ( int  val,
const std::string &  name 
)
Todo:
Document

WARNING! Changes error to -val ...

void CBot::CBotStack::Reset ( )

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

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

Adds a local variable.

Parameters
varVariable to be added
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
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
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
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
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
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
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
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
CBotStack * CBot::CBotStack::RestoreStack ( CBotInstr instr = nullptr)

Restore CBotInstr pointer after loading stack from file.

Todo:
Check what this does exactly
CBotStack * CBot::CBotStack::RestoreStackEOX ( CBotExternalCall instr = nullptr)

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

Todo:
Check what this does exactly
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()
bool CBot::CBotStack::ReturnKeep ( CBotStack pFils)

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

Parameters
pFilsStack to copy result from
Returns
IsOk()
bool CBot::CBotStack::BreakReturn ( CBotStack pfils,
const std::string &  name = "" 
)
Todo:
Document

in case of eventual break

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

or "continue"

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)
int CBot::CBotStack::GetState ( )
inline

Return current execution state.

Used when resuming execution

Returns
Execution state set before interruption by SetState() and 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)
bool CBot::CBotStack::IfStep ( )

Check if we are in step by step execution mode.

Returns
true if step by step, false otherwise
bool CBot::CBotStack::Execute ( )

Resumes execution of interrupted external call.

Returns
true if external call finished, false if interrupted again
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
void CBot::CBotStack::SetCopyVar ( CBotVar var)

Set the result variable to copy of given variable.

Parameters
varVariable to copy as result
CBotVar * CBot::CBotStack::GetVar ( )

Return result variable.

Returns
Variable set with SetVar() or SetCopyVar()
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

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
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
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)
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
void * CBot::CBotStack::GetUserPtr ( )

Get user pointer for external calls.

Returns
User pointer for external execution calls
See also
SetUserPtr()
CBotStack::BlockVisibilityType CBot::CBotStack::GetBlock ( )

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

See also
BlockVisibilityType enum
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
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
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
int CBot::CBotStack::GetTimer ( )
static

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

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

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