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

The execution stack. More...

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

## Classes

struct | Data

## Public Types

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

## Write to file

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

## Stack memory management

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

## Error management

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

## Local variables

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

## Child stacks

When you enter a new code block or instruction, child stack is created for managing everything that happens inside that block / instruction.
CBotStack * | AddStack (CBotInstr *instr=nullptr, BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
| Creates or gets the primary child stack.
CBotStack * | AddStack2 (BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
| Creates or gets the secondary child stack.
CBotStack * | AddStackExternalCall (CBotExternalCall *instr=nullptr, BlockVisibilityType bBlock=BlockVisibilityType::INSTRUCTION)
| Adds special EOX stack marker.
CBotStack * | RestoreStack (CBotInstr *instr=nullptr)
| Restore CBotInstr pointer after loading stack from file.
CBotStack * | RestoreStackEOX (CBotExternalCall *instr=nullptr)
| Restores CBotExternalCall in the EOX marker after loading stack from file.
bool | Return (CBotStack *pFils)
| Return to this point - copy the result from given stack, and destroy all child stacks from here.
bool | ReturnKeep (CBotStack *pFils)
| Like Return() but doesn't destroy the stacks.
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.
int | GetState ()
| Return current execution state.
bool | IncState (int lim=-10)
| Increase the execution state by one.
bool | IfStep ()
| Check if we are in step by step execution mode.
bool | Execute ()
| Resumes execution of interrupted external call.

## Result variable

void | SetVar (CBotVar *var)
| Set the result variable.
void | SetCopyVar (CBotVar *var)
| Set the result variable to copy of given variable.
CBotVar * | GetVar ()
| Return result variable.
bool | GetRetVar (bool bRet)
long | GetVal ()
| Return the result variable as int.
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.
CBotProgram * | GetProgram (bool bFirst=false)
| Get program we are currently in.
void | SetUserPtr (void *user)
| Set user pointer for external calls.
void * | GetUserPtr ()
| Get user pointer for external calls.
BlockVisibilityType | GetBlock ()
| Get the block type this stack represents - instruction, code block or function.

## Function calls

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

## Detailed Description

The execution stack.

## Member Enumeration Documentation

## BlockVisibilityType

enum class 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 )

Get last error.

Parameters

  [out] | start | Starting position in code of the error
  [out] | end | Ending position in code of the error

Returns
  Error number

## GetError() [2/2]

CBotError CBot::CBotStack::GetError | ( |  | ) |

Get last error.

Returns
  Error number

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

## IsOk()

bool CBot::CBotStack::IsOk | ( |  | ) |

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

  n | Error to set
  token | Token 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

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

  var | Variable to be added

## FindVar() [1/4]

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

Fetch a variable by its token.

Parameters

  pToken | Token upon which search is performed
  bUpdate | true 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

  pToken | Token upon which search is performed
  bUpdate | true 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

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

  ident | Unique identifier of a variable
  bUpdate | true 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

  pToken | Token upon which search is performed
  bUpdate | true 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

  pFils | Stack to copy result from

Returns
  IsOk()

## ReturnKeep()

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

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

Parameters

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

  n | New state
  lim | Required 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

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

  var | Result variable to set

## SetCopyVar()

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

Set the result variable to copy of given variable.

Parameters

  var | Variable 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 m_data->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

  p | CBotProgram we are currently in

## GetProgram()

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

Get program we are currently in.

Parameters

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

  user | User 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] | nIdent | Unique function identifier, if not found will be updated
  | token | Function name token
  | ppVar | Array of function arguments
  | rettype | Expected 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] | nIdent | Unique function identifier, if not found will be updated
  | token | Function name token
  | ppVar | Array of function arguments

## SaveState()

bool CBot::CBotStack::SaveState | ( | std::ostream & | ostr | ) |

CBotProgram instance the execution is in in this stack level.

## RestoreState()

bool CBot::CBotStack::RestoreState | ( | std::istream & | istr,
|  | CBotStack *& | pStack )

CBotProgram instance the execution is in in this stack level.

## SetTimer()

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

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

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] | functionName | Current function name, nullptr if not found
  [out] | start | Start position of currently executed token
  [out] | end | End 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] | functionName | Name of instruction being executed at this level
  | level | 0 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:

- src/CBot/CBotStack.h
- src/CBot/CBotStack.cpp