[colobot] 208/377: Mostly finished CBotStack docs
Didier Raboud
odyx at moszumanska.debian.org
Wed Mar 30 13:34:17 UTC 2016
This is an automated email from the git hooks/post-receive script.
odyx pushed a commit to branch debian/master
in repository colobot.
commit 6b959a5606bd0c104d56c818a912b672c4014406
Author: krzys-h <krzys_h at interia.pl>
Date: Fri Dec 25 22:03:23 2015 +0100
Mostly finished CBotStack docs
---
src/CBot/CBotInstr/CBotFor.cpp | 2 +-
src/CBot/CBotInstr/CBotFunction.cpp | 14 +--
src/CBot/CBotInstr/CBotInstrMethode.cpp | 4 +-
src/CBot/CBotInstr/CBotListInstr.cpp | 2 +-
src/CBot/CBotStack.cpp | 32 +++---
src/CBot/CBotStack.h | 188 +++++++++++++++++++++++++++-----
6 files changed, 188 insertions(+), 54 deletions(-)
diff --git a/src/CBot/CBotInstr/CBotFor.cpp b/src/CBot/CBotInstr/CBotFor.cpp
index bc13636..78512f6 100644
--- a/src/CBot/CBotInstr/CBotFor.cpp
+++ b/src/CBot/CBotInstr/CBotFor.cpp
@@ -115,7 +115,7 @@ CBotInstr* CBotFor::Compile(CBotToken* &p, CBotCStack* pStack)
////////////////////////////////////////////////////////////////////////////////
bool CBotFor :: Execute(CBotStack* &pj)
{
- CBotStack* pile = pj->AddStack(this, CBotStack::IsBlock::BLOCK); // adds an item to the stack (variables locales)
+ CBotStack* pile = pj->AddStack(this, CBotStack::BlockVisibilityType::BLOCK); // adds an item to the stack (variables locales)
// or find in case of recovery
// if ( pile == EOX ) return true;
diff --git a/src/CBot/CBotInstr/CBotFunction.cpp b/src/CBot/CBotInstr/CBotFunction.cpp
index c83484a..c6bd8f4 100644
--- a/src/CBot/CBotInstr/CBotFunction.cpp
+++ b/src/CBot/CBotInstr/CBotFunction.cpp
@@ -335,7 +335,7 @@ bad:
////////////////////////////////////////////////////////////////////////////////
bool CBotFunction::Execute(CBotVar** ppVars, CBotStack* &pj, CBotVar* pInstance)
{
- CBotStack* pile = pj->AddStack(this, CBotStack::IsBlock::FUNCTION); // one end of stack local to this function
+ CBotStack* pile = pj->AddStack(this, CBotStack::BlockVisibilityType::FUNCTION); // one end of stack local to this function
// if ( pile == EOX ) return true;
pile->SetProgram(m_pProg); // bases for routines
@@ -397,7 +397,7 @@ void CBotFunction::RestoreState(CBotVar** ppVars, CBotStack* &pj, CBotVar* pInst
pile->SetProgram(m_pProg); // bases for routines
- if ( pile->GetBlock() != CBotStack::IsBlock::FUNCTION)
+ if ( pile->GetBlock() != CBotStack::BlockVisibilityType::FUNCTION)
{
CBotStack* pile2 = pile->RestoreStack(nullptr); // one end of stack local to this function
if ( pile2 == nullptr ) return;
@@ -600,14 +600,14 @@ int CBotFunction::DoCall(long& nIdent, const std::string& name, CBotVar** ppVars
if ( pt != nullptr )
{
- CBotStack* pStk1 = pStack->AddStack(pt, CBotStack::IsBlock::FUNCTION); // to put "this"
+ CBotStack* pStk1 = pStack->AddStack(pt, CBotStack::BlockVisibilityType::FUNCTION); // to put "this"
// if ( pStk1 == EOX ) return true;
pStk1->SetProgram(pt->m_pProg); // it may have changed module
if ( pStk1->IfStep() ) return false;
- CBotStack* pStk3 = pStk1->AddStack(nullptr, CBotStack::IsBlock::BLOCK); // parameters
+ CBotStack* pStk3 = pStk1->AddStack(nullptr, CBotStack::BlockVisibilityType::BLOCK); // parameters
// preparing parameters on the stack
@@ -682,7 +682,7 @@ void CBotFunction::RestoreCall(long& nIdent, const std::string& name, CBotVar**
pStk1->SetProgram(pt->m_pProg); // it may have changed module
- if ( pStk1->GetBlock() != CBotStack::IsBlock::FUNCTION)
+ if ( pStk1->GetBlock() != CBotStack::BlockVisibilityType::FUNCTION)
{
CBotStack* pStk2 = pStk1->RestoreStack(nullptr); // used more
if ( pStk2 == nullptr ) return;
@@ -733,11 +733,11 @@ int CBotFunction::DoCall(long& nIdent, const std::string& name, CBotVar* pThis,
{
// DEBUG( "CBotFunction::DoCall" + pt->GetName(), 0, pStack);
- CBotStack* pStk = pStack->AddStack(pt, CBotStack::IsBlock::FUNCTION);
+ CBotStack* pStk = pStack->AddStack(pt, CBotStack::BlockVisibilityType::FUNCTION);
// if ( pStk == EOX ) return true;
pStk->SetProgram(pt->m_pProg); // it may have changed module
- CBotStack* pStk3 = pStk->AddStack(nullptr, CBotStack::IsBlock::BLOCK); // to set parameters passed
+ CBotStack* pStk3 = pStk->AddStack(nullptr, CBotStack::BlockVisibilityType::BLOCK); // to set parameters passed
// preparing parameters on the stack
diff --git a/src/CBot/CBotInstr/CBotInstrMethode.cpp b/src/CBot/CBotInstr/CBotInstrMethode.cpp
index 98c1f5b..80edd54 100644
--- a/src/CBot/CBotInstr/CBotInstrMethode.cpp
+++ b/src/CBot/CBotInstr/CBotInstrMethode.cpp
@@ -106,7 +106,7 @@ CBotInstr* CBotInstrMethode::Compile(CBotToken* &p, CBotCStack* pStack, CBotVar*
bool CBotInstrMethode::ExecuteVar(CBotVar* &pVar, CBotStack* &pj, CBotToken* prevToken, bool bStep, bool bExtend)
{
CBotVar* ppVars[1000];
- CBotStack* pile1 = pj->AddStack(this, CBotStack::IsBlock::BLOCK); // a place for the copy of This
+ CBotStack* pile1 = pj->AddStack(this, CBotStack::BlockVisibilityType::BLOCK); // a place for the copy of This
if (pVar->GetPointer() == nullptr)
{
@@ -221,7 +221,7 @@ void CBotInstrMethode::RestoreStateVar(CBotStack* &pile, bool bMain)
bool CBotInstrMethode::Execute(CBotStack* &pj)
{
CBotVar* ppVars[1000];
- CBotStack* pile1 = pj->AddStack(this, CBotStack::IsBlock::BLOCK); // place for the copy of This
+ CBotStack* pile1 = pj->AddStack(this, CBotStack::BlockVisibilityType::BLOCK); // place for the copy of This
if (pile1->IfStep()) return false;
diff --git a/src/CBot/CBotInstr/CBotListInstr.cpp b/src/CBot/CBotInstr/CBotListInstr.cpp
index 3e1ab7d..a698898 100644
--- a/src/CBot/CBotInstr/CBotListInstr.cpp
+++ b/src/CBot/CBotInstr/CBotListInstr.cpp
@@ -80,7 +80,7 @@ CBotInstr* CBotListInstr::Compile(CBotToken* &p, CBotCStack* pStack, bool bLocal
bool CBotListInstr::Execute(CBotStack* &pj)
{
- CBotStack* pile = pj->AddStack(this, CBotStack::IsBlock::BLOCK); //needed for SetState()
+ CBotStack* pile = pj->AddStack(this, CBotStack::BlockVisibilityType::BLOCK); //needed for SetState()
if (pile->StackOver() ) return pj->Return( pile);
diff --git a/src/CBot/CBotStack.cpp b/src/CBot/CBotStack.cpp
index 7308e70..e914459 100644
--- a/src/CBot/CBotStack.cpp
+++ b/src/CBot/CBotStack.cpp
@@ -58,7 +58,7 @@ CBotStack* CBotStack::AllocateStack()
// completely empty
memset(p, 0, size);
- p-> m_bBlock = IsBlock::BLOCK;
+ p-> m_bBlock = BlockVisibilityType::BLOCK;
m_timer = m_initimer; // sets the timer at the beginning
CBotStack* pp = p;
@@ -107,7 +107,7 @@ void CBotStack::Delete()
// routine improved
////////////////////////////////////////////////////////////////////////////////
-CBotStack* CBotStack::AddStack(CBotInstr* instr, IsBlock bBlock)
+CBotStack* CBotStack::AddStack(CBotInstr* instr, BlockVisibilityType bBlock)
{
if (m_next != nullptr)
{
@@ -134,7 +134,7 @@ CBotStack* CBotStack::AddStack(CBotInstr* instr, IsBlock bBlock)
}
////////////////////////////////////////////////////////////////////////////////
-CBotStack* CBotStack::AddStackEOX(CBotExternalCall* instr, IsBlock bBlock)
+CBotStack* CBotStack::AddStackEOX(CBotExternalCall* instr, BlockVisibilityType bBlock)
{
if (m_next != nullptr)
{
@@ -152,7 +152,7 @@ CBotStack* CBotStack::AddStackEOX(CBotExternalCall* instr, IsBlock bBlock)
}
////////////////////////////////////////////////////////////////////////////////
-CBotStack* CBotStack::AddStack2(IsBlock bBlock)
+CBotStack* CBotStack::AddStack2(BlockVisibilityType bBlock)
{
if (m_next2 != nullptr)
{
@@ -176,7 +176,7 @@ CBotStack* CBotStack::AddStack2(IsBlock bBlock)
}
////////////////////////////////////////////////////////////////////////////////
-CBotStack::IsBlock CBotStack::GetBlock()
+CBotStack::BlockVisibilityType CBotStack::GetBlock()
{
return m_bBlock;
}
@@ -418,7 +418,7 @@ bool CBotStack::IncState(int limite)
////////////////////////////////////////////////////////////////////////////////
void CBotStack::SetError(CBotError n, CBotToken* token)
{
- if ( n!= 0 && m_error != 0) return; // does not change existing error
+ if (n != CBotNoErr && m_error != CBotNoErr) return; // does not change existing error
m_error = n;
if (token != nullptr)
{
@@ -514,7 +514,7 @@ void CBotStack::AddVar(CBotVar* pVar)
CBotStack* p = this;
// returns to the father element
- while (p != nullptr && p->m_bBlock == IsBlock::INSTRUCTION) p = p->m_prev;
+ while (p != nullptr && p->m_bBlock == BlockVisibilityType::INSTRUCTION) p = p->m_prev;
if ( p == nullptr ) return;
@@ -554,7 +554,7 @@ void CBotStack::SetUserPtr(void* user)
}
////////////////////////////////////////////////////////////////////////////////
-bool CBotStack::ExecuteCall(long& nIdent, CBotToken* token, CBotVar** ppVar, CBotTypResult& rettype)
+bool CBotStack::ExecuteCall(long& nIdent, CBotToken* token, CBotVar** ppVar, const CBotTypResult& rettype)
{
CBotTypResult res;
@@ -608,7 +608,7 @@ bool SaveVar(FILE* pf, CBotVar* pVar)
}
////////////////////////////////////////////////////////////////////////////////
-void CBotStack::GetRunPos(std::string& FunctionName, int& start, int& end)
+void CBotStack::GetRunPos(std::string& functionName, int& start, int& end)
{
CBotProgram* prog = m_prog; // Current program
@@ -633,7 +633,7 @@ void CBotStack::GetRunPos(std::string& FunctionName, int& start, int& end)
if ( funct == nullptr ) return;
CBotToken* t = funct->GetToken();
- FunctionName = t->GetString();
+ functionName = t->GetString();
// if ( p->m_instr != nullptr ) instr = p->m_instr;
@@ -643,10 +643,10 @@ void CBotStack::GetRunPos(std::string& FunctionName, int& start, int& end)
}
////////////////////////////////////////////////////////////////////////////////
-CBotVar* CBotStack::GetStackVars(std::string& FunctionName, int level)
+CBotVar* CBotStack::GetStackVars(std::string& functionName, int level)
{
CBotProgram* prog = m_prog; // current program
- FunctionName = "";
+ functionName = "";
// back the stack in the current module
CBotStack* p = this;
@@ -662,13 +662,13 @@ CBotVar* CBotStack::GetStackVars(std::string& FunctionName, int level)
// descends upon the elements of block
- while ( p != nullptr && p->m_bBlock == IsBlock::INSTRUCTION) p = p->m_prev;
+ while ( p != nullptr && p->m_bBlock == BlockVisibilityType::INSTRUCTION) p = p->m_prev;
// Now p is on the beggining of the top block (with local variables)
while ( p != nullptr && level++ < 0 )
{
p = p->m_prev;
- while ( p != nullptr && p->m_bBlock == IsBlock::INSTRUCTION) p = p->m_prev;
+ while ( p != nullptr && p->m_bBlock == BlockVisibilityType::INSTRUCTION) p = p->m_prev;
}
// Now p is on the block "level"
@@ -685,7 +685,7 @@ CBotVar* CBotStack::GetStackVars(std::string& FunctionName, int level)
if ( pp == nullptr || pp->m_instr == nullptr ) return nullptr;
CBotToken* t = pp->m_instr->GetToken();
- FunctionName = t->GetString();
+ functionName = t->GetString();
return p->m_listVar;
}
@@ -737,7 +737,7 @@ bool CBotStack::RestoreState(FILE* pf, CBotStack* &pStack)
}
if (!ReadWord(pf, w)) return false; // is a local block
- pStack->m_bBlock = static_cast<IsBlock>(w);
+ pStack->m_bBlock = static_cast<BlockVisibilityType>(w);
if (!ReadWord(pf, w)) return false; // in what state ?
pStack->SetState(static_cast<short>(w)); // in a good state
diff --git a/src/CBot/CBotStack.h b/src/CBot/CBotStack.h
index 3131a65..7438518 100644
--- a/src/CBot/CBotStack.h
+++ b/src/CBot/CBotStack.h
@@ -41,7 +41,16 @@ class CBotToken;
class CBotStack
{
public:
- enum class IsBlock : unsigned short { INSTRUCTION = 0, BLOCK = 1, FUNCTION = 2 }; // TODO: figure out what these mean ~krzys_h
+ /**
+ * \brief Block type this stack represents. This determines local variable visibility (you can only see up to top FUNCTION stack)
+ */
+ enum class BlockVisibilityType : unsigned short
+ {
+ INSTRUCTION = 0, //!< Instruction (default)
+ BLOCK = 1, //!< Code block between { ... }
+ FUNCTION = 2 //!< Function - variable visibility limit
+ };
+
enum class IsFunction : unsigned short { NO = 0, TRUE = 1, EXTERNAL_CALL = 2 }; // TODO: just guessing the meaning of values, should be verified ~krzys_h
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -71,7 +80,7 @@ public:
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/** \name Error management
*
- * Be careful - errors are stored in static variables!
+ * BE CAREFUL - errors are stored in static variables!
* \todo Refactor that
*/
//@{
@@ -101,12 +110,39 @@ public:
return m_error == CBotNoErr;
}
+ /**
+ * \brief Set execution error unless it's already set unless you are trying to reset it
+ *
+ * \param n Error to set
+ * \param token Token to take error position from
+ * \see ResetError() to force set error
+ */
+ void SetError(CBotError n, CBotToken* token = nullptr);
+ /**
+ * \brief Set error position to position of given token
+ *
+ * \param token Token to take error position from
+ */
+ void SetPosError(CBotToken* token);
+ /**
+ * \brief Set execution error even if it is already set
+ *
+ * \see SetError() to set error only if it is not set already
+ */
+ void ResetError(CBotError n, int start, int end);
+ /**
+ * \todo Document
+ *
+ * WARNING! Changes error to -val ...
+ */
+ void SetBreak(int val, const std::string& name);
+
//@}
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
/**
- * \brief Reset the stack - resets the error and timer
+ * \brief Reset the stack for execution resume - resets the error and timer
*/
void Reset();
@@ -179,7 +215,7 @@ public:
* \todo Document params
* \returns New stack element
*/
- CBotStack* AddStack(CBotInstr* instr = nullptr, IsBlock bBlock = IsBlock::INSTRUCTION);
+ CBotStack* AddStack(CBotInstr* instr = nullptr, BlockVisibilityType bBlock = BlockVisibilityType::INSTRUCTION);
/**
* \brief Creates or gets the secondary child stack
@@ -191,7 +227,7 @@ public:
* \see AddStack()
* \return New stack element
*/
- CBotStack* AddStack2(IsBlock bBlock = IsBlock::INSTRUCTION);
+ CBotStack* AddStack2(BlockVisibilityType bBlock = BlockVisibilityType::INSTRUCTION);
/**
* \brief Adds special EOX stack marker
@@ -201,7 +237,7 @@ public:
*
* \todo Document params & return
*/
- CBotStack* AddStackEOX(CBotExternalCall* instr = nullptr, IsBlock bBlock = IsBlock::INSTRUCTION);
+ CBotStack* AddStackEOX(CBotExternalCall* instr = nullptr, BlockVisibilityType bBlock = BlockVisibilityType::INSTRUCTION);
/**
* \brief Restore CBotInstr pointer after loading stack from file
@@ -233,11 +269,13 @@ public:
/**
* \todo Document
+ *
* in case of eventual break
*/
bool BreakReturn(CBotStack* pfils, const std::string& name = nullptr);
/**
* \todo Document
+ *
* or "continue"
*/
bool IfContinue(int state, const std::string& name);
@@ -251,23 +289,48 @@ public:
* When CBotInstr::Execute() is called, it continues execution from the point it finished at.
* See various CBotInstr::Execute() implementations for details.
*
- * Call CBotStack::Execute() to resume execution of the interrupted instruction
- *
- * \todo More detailed docs on functions
+ * Each state change causes one tick on the execution timer
*/
//@{
- bool SetState(int n, int lim = -10); // select a state
- int GetState() { return m_state; } // in what state am I?
- bool IncState(int lim = -10); // passes to the next state
- bool IfStep(); // do step by step
+ /**
+ * \brief Set execution state
+ * \param n New state
+ * \param lim Required amount of "ticks" on the timer required to allow to continue execution. By default allows a little overflow (up to 10 ticks)
+ * \return false if timer requests interruption (timer <= limit)
+ */
+ bool SetState(int n, int lim = -10);
+ /**
+ * \brief Return current execution state
+ *
+ * Used when resuming execution
+ *
+ * \return Execution state set before interruption by SetState() and IncState()
+ */
+ int GetState() { return m_state; }
+ /**
+ * \brief Increase the execution state by one
+ * \param lim Required amount of "ticks" on the timer required to allow to continue execution. By default allows a little overflow (up to 10 ticks)
+ * \return false if timer requests interruption (timer <= limit)
+ */
+ bool IncState(int lim = -10);
+
+ /**
+ * \brief Check if we are in step by step execution mode
+ * \return true if step by step, false otherwise
+ */
+ bool IfStep();
+
+ /**
+ * \brief Resumes execution of interrupted external call
+ * \return true if external call finished, false if interrupted again
+ */
bool Execute();
//@}
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
- // \name Result variable
-
+ //! \name Result variable
//@{
/**
@@ -280,16 +343,20 @@ public:
* \brief Set the result variable to copy of given variable
* \param var Variable to copy as result
*/
- void SetCopyVar( CBotVar* var );
+ void SetCopyVar(CBotVar* var);
/**
* \brief Return result variable
* \return Variable set with SetVar() or SetCopyVar()
*/
CBotVar* GetVar();
+
/**
* \todo Document
+ *
+ * Copies the result value from static m_retvar (m_var at a moment of SetBreak(3)) to this stack result
*/
bool GetRetVar(bool bRet);
+
/**
* \brief Return the result variable as int
* \deprecated Please use GetVar()->GetValInt() instead
@@ -302,28 +369,95 @@ public:
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
- void SetError(CBotError n, CBotToken* token = nullptr);
- void SetPosError(CBotToken* token);
- void ResetError(CBotError n, int start, int end);
- void SetBreak(int val, const std::string& name);
-
+ /**
+ * \brief 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
+ * \param p CBotProgram we are currently in
+ */
void SetProgram(CBotProgram* p);
- CBotProgram* GetProgram(bool bFirst = false);
+ /**
+ * \brief Get program we are currently in
+ * \param bFirst if true, get the main CBotProgram instance (the one that has the main function)
+ */
+ CBotProgram* GetProgram(bool bFirst = false);
+
+ /**
+ * \brief Set user pointer for external calls
+ *
+ * Execution calls only - see CBotExternalCallList::SetUserPtr() for compilation calls
+ *
+ * \param user User pointer to set
+ */
void SetUserPtr(void* user);
+ /**
+ * \brief Get user pointer for external calls
+ * \returns User pointer for external execution calls
+ * \see SetUserPtr()
+ */
void* GetUserPtr();
- IsBlock GetBlock();
+ /**
+ * \brief Get the block type this stack represents - instruction, code block or function
+ * \see BlockVisibilityType enum
+ */
+ BlockVisibilityType GetBlock();
+
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //! \name Function calls
+ //@{
- bool ExecuteCall(long& nIdent, CBotToken* token, CBotVar** ppVar, CBotTypResult& rettype);
+ /**
+ * \brief Execute a function call, either external or user-defined
+ * \param[in, out] nIdent Unique function identifier, if not found will be updated
+ * \param token Function name token
+ * \param ppVar Array of function arguments
+ * \param rettype Expected return type
+ */
+ bool ExecuteCall(long& nIdent, CBotToken* token, CBotVar** ppVar, const CBotTypResult& rettype);
+ /**
+ * \brief Restore a function call after the program state has been restored from a file
+ * \param[in, out] nIdent Unique function identifier, if not found will be updated
+ * \param token Function name token
+ * \param ppVar Array of function arguments
+ */
void RestoreCall(long& nIdent, CBotToken* token, CBotVar** ppVar);
+ //@}
+
+ ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+ //! \name Write to file
+ //@{
+
bool SaveState(FILE* pf);
bool RestoreState(FILE* pf, CBotStack* &pStack);
+ //@}
+
+ /**
+ * \brief 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
+ */
static void SetTimer(int n);
- void GetRunPos(std::string& FunctionName, int& start, int& end);
- CBotVar* GetStackVars(std::string& FunctionName, int level);
+ /**
+ * \brief Get current position in the program
+ * \param[out] functionName Current function name, nullptr if not found
+ * \param[out] start Start position of currently executed token
+ * \param[out] end End position of currently executed token
+ */
+ void GetRunPos(std::string& functionName, int& start, int& end);
+
+ /**
+ * \brief Get local variables at the given stack level
+ * \param[out] functionName Name of instruction being executed at this level
+ * \param level 0 for current level, -1, -2, -3 etc. for next levels
+ */
+ CBotVar* GetStackVars(std::string& functionName, int level);
private:
CBotStack* m_next;
@@ -342,7 +476,7 @@ private:
CBotVar* m_var; // result of the operations
CBotVar* m_listVar; // variables declared at this level
- IsBlock m_bBlock; // is part of a block (variables are local to this block)
+ BlockVisibilityType m_bBlock; // is part of a block (variables are local to this block)
bool m_bOver; // stack limits?
// bool m_bDontDelete; // special, not to destroy the variable during delete
CBotProgram* m_prog; // user-defined functions
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-games/colobot.git
More information about the Pkg-games-commits
mailing list