[Orxonox-commit 2656] r7361 - in code/branches/doc: doc/api src/libraries/core src/libraries/core/command src/libraries/util
landauf at orxonox.net
landauf at orxonox.net
Sun Sep 5 22:51:55 CEST 2010
Author: landauf
Date: 2010-09-05 22:51:55 +0200 (Sun, 05 Sep 2010)
New Revision: 7361
Modified:
code/branches/doc/doc/api/Groups.dox
code/branches/doc/src/libraries/core/CommandLineParser.h
code/branches/doc/src/libraries/core/command/IOConsole.h
code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h
code/branches/doc/src/libraries/core/command/IOConsoleWindows.h
code/branches/doc/src/libraries/core/command/IRC.cc
code/branches/doc/src/libraries/core/command/IRC.h
code/branches/doc/src/libraries/core/command/Shell.cc
code/branches/doc/src/libraries/core/command/Shell.h
code/branches/doc/src/libraries/core/command/TclBind.cc
code/branches/doc/src/libraries/core/command/TclBind.h
code/branches/doc/src/libraries/core/command/TclThreadList.h
code/branches/doc/src/libraries/core/command/TclThreadManager.cc
code/branches/doc/src/libraries/core/command/TclThreadManager.h
code/branches/doc/src/libraries/util/Debug.h
Log:
added documentation
Modified: code/branches/doc/doc/api/Groups.dox
===================================================================
--- code/branches/doc/doc/api/Groups.dox 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/doc/api/Groups.dox 2010-09-05 20:51:55 UTC (rev 7361)
@@ -58,12 +58,6 @@
*/
/**
- @defgroup CmdArgs Commandline Arguments
- @ingroup Command
- @brief For a reference see @ref cmdargspage
-*/
-
-/**
@defgroup Config Config
@ingroup Core
*/
@@ -79,11 +73,6 @@
*/
/**
- @defgroup Output Output
- @ingroup Core
-*/
-
-/**
@defgroup XML XML
@ingroup Core
*/
Modified: code/branches/doc/src/libraries/core/CommandLineParser.h
===================================================================
--- code/branches/doc/src/libraries/core/CommandLineParser.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/CommandLineParser.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,17 @@
*
*/
+/**
+ @defgroup CmdArgs Commandline Arguments
+ @ingroup Config
+ @brief For a reference of all commandline arguments see @ref cmdargspage
+*/
+
+/**
+ @file
+ @ingroup Config CmdArgs
+*/
+
#ifndef _CommandLine_H__
#define _CommandLine_H__
Modified: code/branches/doc/src/libraries/core/command/IOConsole.h
===================================================================
--- code/branches/doc/src/libraries/core/command/IOConsole.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/IOConsole.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @ingroup Command ShellConsole
+*/
+
#include "OrxonoxConfig.h"
#if defined(ORXONOX_PLATFORM_UNIX)
Modified: code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h
===================================================================
--- code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/IOConsolePOSIX.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -27,6 +27,11 @@
*
*/
+/**
+ @file
+ @ingroup Command ShellConsole
+*/
+
#ifndef _IOConsole_H__
#define _IOConsole_H__
Modified: code/branches/doc/src/libraries/core/command/IOConsoleWindows.h
===================================================================
--- code/branches/doc/src/libraries/core/command/IOConsoleWindows.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/IOConsoleWindows.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @ingroup Command ShellConsole
+*/
+
#ifndef _IOConsole_H__
#define _IOConsole_H__
Modified: code/branches/doc/src/libraries/core/command/IRC.cc
===================================================================
--- code/branches/doc/src/libraries/core/command/IRC.cc 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/IRC.cc 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @brief Implementation of the IRC class and the IRC console commands.
+*/
+
#include "IRC.h"
#include <cpptcl/cpptcl.h>
@@ -38,17 +43,34 @@
namespace orxonox
{
- static const unsigned int IRC_TCL_THREADID = 1421421421;
+ static const unsigned int IRC_TCL_THREADID = 1421421421; ///< The ID of the thread in TclThreadManager that is used for the IRC connection
SetConsoleCommand("IRC", "say", &IRC::say);
SetConsoleCommand("IRC", "msg", &IRC::msg);
SetConsoleCommand("IRC", "nick", &IRC::nick);
+ /**
+ @brief Returns the only existing instance of IRC.
+ */
+ IRC& IRC::getInstance()
+ {
+ static IRC instance;
+ return instance;
+ }
+
+ /**
+ @brief Constructor: Doesn't yet connect to IRC nor does it create a Tcl interpreter.
+ The IRC object will automatically connect to the IRC server if one of the registered
+ console commands is used the first time.
+ */
IRC::IRC()
{
this->interpreter_ = 0;
}
+ /**
+ @brief Creates and initializes a new multithreaded Tcl-interpreter and defines some callbacks to display IRC-messages in the console.
+ */
void IRC::initialize()
{
unsigned int threadID = IRC_TCL_THREADID;
@@ -69,12 +91,9 @@
TclThreadManager::execute(threadID, "source irc.tcl");
}
- IRC& IRC::getInstance()
- {
- static IRC instance;
- return instance;
- }
-
+ /**
+ @brief Executes a Tcl-command on the Tcl-interpreter.
+ */
bool IRC::eval(const std::string& command)
{
if (!IRC::getInstance().interpreter_)
@@ -95,39 +114,46 @@
return false;
}
+ /// Console command: Sends a message to the current channel on the IRC server.
void IRC::say(const std::string& message)
{
if (IRC::eval("irk::say $conn #orxonox {" + message + '}'))
IRC::tcl_say(Tcl::object(), Tcl::object(IRC::getInstance().nickname_), Tcl::object(message));
}
+ /// Console command: Sends a message to a given channel or nickname on the IRC server.
void IRC::msg(const std::string& channel, const std::string& message)
{
if (IRC::eval("irk::say $conn " + channel + " {" + message + '}'))
IRC::tcl_privmsg(Tcl::object(channel), Tcl::object(IRC::getInstance().nickname_), Tcl::object(message));
}
+ /// Console command: Changes the nickname on the IRC server.
void IRC::nick(const std::string& nickname)
{
if (IRC::eval("irk::nick $conn " + nickname))
IRC::getInstance().nickname_ = nickname;
}
+ /// Tcl-callback: Prints a message that was received from the current IRC channel to the console.
void IRC::tcl_say(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
{
COUT(0) << "IRC> " << nick.get() << ": " << stripEnclosingBraces(args.get()) << std::endl;
}
+ /// Tcl-callback: Prints a private message that was received from a user to the console.
void IRC::tcl_privmsg(Tcl::object const &query, Tcl::object const &nick, Tcl::object const &args)
{
COUT(0) << "IRC (" << query.get() << ")> " << nick.get() << ": " << stripEnclosingBraces(args.get()) << std::endl;
}
+ /// Tcl-callback: Prints an action-message (usually /me ...) that was received from the current IRC channel to the console.
void IRC::tcl_action(Tcl::object const &channel, Tcl::object const &nick, Tcl::object const &args)
{
COUT(0) << "IRC> * " << nick.get() << ' ' << stripEnclosingBraces(args.get()) << std::endl;
}
+ /// Tcl-callback: Prints all kinds of information that were received from the IRC server or channel (connection info, join, part, modes, ...) to the console.
void IRC::tcl_info(Tcl::object const &channel, Tcl::object const &args)
{
COUT(0) << "IRC> --> " << stripEnclosingBraces(args.get()) << std::endl;
Modified: code/branches/doc/src/libraries/core/command/IRC.h
===================================================================
--- code/branches/doc/src/libraries/core/command/IRC.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/IRC.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,12 @@
*
*/
+/**
+ @file
+ @ingroup Command Tcl
+ @brief Declaration of IRC helper class, used for IRC connections using Tcl.
+*/
+
#ifndef _IRC_H__
#define _IRC_H__
@@ -35,6 +41,10 @@
namespace orxonox
{
+ /**
+ @brief The IRC class creates a Tcl-thread (see TclThreadManager) and connects to an IRC server.
+ It provides different console commands to send messages and to perform other actions on the IRC server.
+ */
class _CoreExport IRC
{
public:
@@ -54,11 +64,11 @@
void initialize();
IRC();
- IRC(const IRC& other);
- ~IRC() {}
+ IRC(const IRC& other); ///< Copy-constructor: Not implemented
+ ~IRC() {} ///< Destructor
- Tcl::interpreter* interpreter_;
- std::string nickname_;
+ Tcl::interpreter* interpreter_; ///< The Tcl interpreter that is used for the IRC connection
+ std::string nickname_; ///< The user's nickname on the IRC server
};
}
Modified: code/branches/doc/src/libraries/core/command/Shell.cc
===================================================================
--- code/branches/doc/src/libraries/core/command/Shell.cc 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/Shell.cc 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @brief Implementation of the Shell class.
+*/
+
#include "Shell.h"
#include "util/OutputHandler.h"
@@ -47,6 +52,11 @@
unsigned int Shell::cacheSize_s;
+ /**
+ @brief Constructor: Initializes the values and registers itself at OutputHandler.
+ @param consoleName The name of the shell - used to define the name of the soft-debug-level config-value
+ @param bScrollable If true, the user is allowed to scroll through the output-lines
+ */
Shell::Shell(const std::string& consoleName, bool bScrollable)
: OutputListener(consoleName)
, inputBuffer_(new InputBuffer())
@@ -87,12 +97,18 @@
OutputHandler::getInstance().registerOutputListener(this);
}
+ /**
+ @brief Destructor: Unregisters the shell from OutputHandler.
+ */
Shell::~Shell()
{
OutputHandler::getInstance().unregisterOutputListener(this);
this->inputBuffer_->destroy();
}
+ /**
+ @brief Defines the config values.
+ */
void Shell::setConfigValues()
{
SetConfigValue(maxHistoryLength_, 100)
@@ -112,12 +128,18 @@
this->setSoftDebugLevel(this->softDebugLevel_);
}
+ /**
+ @brief Config-value callback: Called when the history offset has changed in the config-file.
+ */
void Shell::commandHistoryOffsetChanged()
{
if (this->historyOffset_ >= this->maxHistoryLength_)
this->historyOffset_ = 0;
}
+ /**
+ @brief Config-value callback: Called when the length of the command history has changed in the config-file.
+ */
void Shell::commandHistoryLengthChanged()
{
this->commandHistoryOffsetChanged();
@@ -130,6 +152,9 @@
}
}
+ /**
+ @brief Registers this object as listener for different key-events at the input buffer.
+ */
void Shell::configureInputBuffer()
{
this->inputBuffer_->registerListener(this, &Shell::inputChanged, true);
@@ -158,23 +183,17 @@
}
}
- /*
- void Shell::history()
- {
- Shell& instance = Shell::getInstance();
-
- for (unsigned int i = instance.historyOffset_; i < instance.commandHistory_.size(); ++i)
- instance.addOutput(instance.commandHistory_[i] + '\n', -1);
- for (unsigned int i = 0; i < instance.historyOffset_; ++i)
- instance.addOutput(instance.commandHistory_[i] + '\n', -1);
- }
+ /**
+ @brief Registers a shell listener which listens for changes in this shell.
*/
-
void Shell::registerListener(ShellListener* listener)
{
this->listeners_.push_back(listener);
}
+ /**
+ @brief Unregisters a shell listener.
+ */
void Shell::unregisterListener(ShellListener* listener)
{
for (std::list<ShellListener*>::iterator it = this->listeners_.begin(); it != this->listeners_.end(); )
@@ -186,18 +205,27 @@
}
}
+ /**
+ @brief Changes the position of the cursor in the input buffer.
+ */
void Shell::setCursorPosition(unsigned int cursor)
{
this->inputBuffer_->setCursorPosition(cursor);
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /**
+ @brief Sends output to the internal output buffer.
+ */
void Shell::addOutput(const std::string& text, LineType type)
{
this->outputBuffer_ << text;
this->outputChanged(type);
}
+ /**
+ @brief Clears the list of output-lines.
+ */
void Shell::clearOutput()
{
this->outputLines_.clear();
@@ -209,6 +237,9 @@
this->updateListeners<&ShellListener::linesChanged>();
}
+ /**
+ @brief Returns an iterator to the newest line of output (except if the user is currently scrolling through the output).
+ */
Shell::LineList::const_iterator Shell::getNewestLineIterator() const
{
if (this->scrollPosition_)
@@ -217,11 +248,17 @@
return this->outputLines_.begin();
}
+ /**
+ @brief Returns the end() iterator of the list of output-lines.
+ */
Shell::LineList::const_iterator Shell::getEndIterator() const
{
return this->outputLines_.end();
}
+ /**
+ @brief Adds a command to the history of entered commands and writes it to the config-file.
+ */
void Shell::addToHistory(const std::string& command)
{
if (command == "")
@@ -236,6 +273,9 @@
ModifyConfigValue(historyOffset_, set, (this->historyOffset_ + 1) % this->maxHistoryLength_);
}
+ /**
+ @brief Returns a command from the history of entered commands (usually the most recent history entry, but the user can scroll through the history).
+ */
const std::string& Shell::getFromHistory() const
{
unsigned int index = mod(static_cast<int>(this->historyOffset_) - static_cast<int>(this->historyPosition_), this->maxHistoryLength_);
@@ -245,50 +285,64 @@
return BLANKSTRING;
}
+ /**
+ @brief Called by OutputHandler or internally whenever output was sent to the output buffer. Reads from the buffer and writes the new output-lines to the list.
+ */
void Shell::outputChanged(int lineType)
{
bool newline = false;
do
{
+ // get the first line from the buffer
std::string output;
std::getline(this->outputBuffer_, output);
+ // check the state of the buffer
bool eof = this->outputBuffer_.eof();
bool fail = this->outputBuffer_.fail();
if (eof)
- this->outputBuffer_.flush();
+ this->outputBuffer_.flush(); // check if more output was received in the meantime
if (eof || fail)
- this->outputBuffer_.clear();
+ this->outputBuffer_.clear(); // clear the error flags
+
+ // the line is terminated with a line-break if neither an error occurred nor the end of the file was reached
newline = (!eof && !fail);
+ // no output retrieved - break the loop
if (!newline && output.empty())
break;
+ // check if the last line was terminated with a line-break
if (this->bFinishedLastLine_)
{
+ // yes it was - push the new line to the list
this->outputLines_.push_front(std::make_pair(output, static_cast<LineType>(lineType)));
+ // adjust the scroll position if needed
if (this->scrollPosition_)
this->scrollPosition_++;
else
this->scrollIterator_ = this->outputLines_.begin();
- this->bFinishedLastLine_ = newline;
-
if (!this->scrollPosition_)
this->updateListeners<&ShellListener::lineAdded>();
}
else
{
+ // no it wasn't - add the new output to the last line
this->outputLines_.front().first += output;
- this->bFinishedLastLine_ = newline;
this->updateListeners<&ShellListener::onlyLastLineChanged>();
}
+
+ // remember if the last line was terminated with a line-break
this->bFinishedLastLine_ = newline;
- } while (newline);
+ } while (newline); // loop as long as more lines are in the buffer
}
+ /**
+ @brief Clears the text in the input buffer.
+ */
void Shell::clearInput()
{
this->inputBuffer_->clear();
@@ -297,21 +351,19 @@
this->updateListeners<&ShellListener::cursorChanged>();
}
- void Shell::setPromptPrefix(const std::string& str)
- {
- }
-
// ##########################################
// ### InputBuffer callback functions ###
// ##########################################
+ /// InputBuffer callback: Called if the input changes.
void Shell::inputChanged()
{
this->updateListeners<&ShellListener::inputChanged>();
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that executes a command (usually [return]).
void Shell::execute()
{
this->addToHistory(this->inputBuffer_->get());
@@ -339,6 +391,7 @@
this->clearInput();
}
+ /// InputBuffer callback: Called if a key was pressed that shows hints and completes a command (usually [tab]).
void Shell::hintAndComplete()
{
this->inputBuffer_->set(CommandExecutor::evaluate(this->inputBuffer_->get()).complete());
@@ -348,6 +401,7 @@
this->inputChanged();
}
+ /// InputBuffer callback: Called if a key was pressed that deletes the character before the cursor (usually [backspace]).
void Shell::backspace()
{
this->inputBuffer_->removeBehindCursor();
@@ -355,51 +409,42 @@
this->updateListeners<&ShellListener::cursorChanged>();
}
- void Shell::exit()
- {
- if (this->inputBuffer_->getSize() > 0)
- {
- this->clearInput();
- return;
- }
-
- this->clearInput();
- this->scrollPosition_ = 0;
- this->scrollIterator_ = this->outputLines_.begin();
-
- this->updateListeners<&ShellListener::exit>();
- }
-
+ /// InputBuffer callback: Called if a key was pressed that deletes the character after the cursor (usually [delete]).
void Shell::deleteChar()
{
this->inputBuffer_->removeAtCursor();
this->updateListeners<&ShellListener::inputChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that moves the input cursor the right (usually [arrow right]).
void Shell::cursorRight()
{
this->inputBuffer_->increaseCursor();
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that moves the input cursor the left (usually [arrow left]).
void Shell::cursorLeft()
{
this->inputBuffer_->decreaseCursor();
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that moves the input cursor the end of the input line (usually [end]).
void Shell::cursorEnd()
{
this->inputBuffer_->setCursorToEnd();
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that moves the input cursor the beginning of the input line (usually [home]).
void Shell::cursorHome()
{
this->inputBuffer_->setCursorToBegin();
this->updateListeners<&ShellListener::cursorChanged>();
}
+ /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the history of entered commands (usually [arrow up]).
void Shell::historyUp()
{
if (this->historyPosition_ < this->commandHistory_.size())
@@ -409,6 +454,7 @@
}
}
+ /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the history of entered commands (usually [arrow down]).
void Shell::historyDown()
{
if (this->historyPosition_ > 0)
@@ -418,6 +464,7 @@
}
}
+ /// InputBuffer callback: Called if a key was pressed that searches upwards through the history for a command stat starts like the one the user is currently typing (usually [page up]). Only if the shell is not scrollable.
void Shell::historySearchUp()
{
if (this->historyPosition_ == this->historyOffset_)
@@ -436,6 +483,7 @@
}
}
+ /// InputBuffer callback: Called if a key was pressed that searches downwards through the history for a command stat starts like the one the user is currently typing (usually [page down]). Only if the shell is not scrollable.
void Shell::historySearchDown()
{
if (this->historyPosition_ == 0)
@@ -454,6 +502,7 @@
}
}
+ /// InputBuffer callback: Called if a key was pressed that scrolls upwards through the output history (usually [page up]). Only if the shell is scrollable.
void Shell::scrollUp()
{
if (this->scrollIterator_ != this->outputLines_.end())
@@ -465,6 +514,7 @@
}
}
+ /// InputBuffer callback: Called if a key was pressed that scrolls downwards through the output history (usually [page down]). Only if the shell is scrollable.
void Shell::scrollDown()
{
if (this->scrollIterator_ != this->outputLines_.begin())
@@ -475,4 +525,20 @@
this->updateListeners<&ShellListener::linesChanged>();
}
}
+
+ /// InputBuffer callback: Called if a key was pressed that clears the text in the input buffer or closes the shell (usually [esc]).
+ void Shell::exit()
+ {
+ if (this->inputBuffer_->getSize() > 0)
+ {
+ this->clearInput();
+ return;
+ }
+
+ this->clearInput();
+ this->scrollPosition_ = 0;
+ this->scrollIterator_ = this->outputLines_.begin();
+
+ this->updateListeners<&ShellListener::exit>();
+ }
}
Modified: code/branches/doc/src/libraries/core/command/Shell.h
===================================================================
--- code/branches/doc/src/libraries/core/command/Shell.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/Shell.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,17 @@
*
*/
+/**
+ @defgroup ShellConsole Shell and console
+ @ingroup Command
+*/
+
+/**
+ @file
+ @ingroup Command ShellConsole
+ @brief Declaration of the Shell and ShellListener classes.
+*/
+
#ifndef _Shell_H__
#define _Shell_H__
@@ -42,6 +53,9 @@
namespace orxonox
{
+ /**
+ @brief An interface, used to get a notification if the state of the Shell changes.
+ */
class _CoreExport ShellListener
{
friend class Shell;
@@ -50,19 +64,30 @@
virtual ~ShellListener() {}
private:
- virtual void linesChanged() {}
- virtual void onlyLastLineChanged() {}
- virtual void lineAdded() {}
- virtual void inputChanged() {}
- virtual void cursorChanged() {}
- virtual void executed() {}
- virtual void exit() {}
+ virtual void linesChanged() {} ///< Called if all output-lines have changed
+ virtual void onlyLastLineChanged() {} ///< Called if only the last output-line has changed
+ virtual void lineAdded() {} ///< Called if a new line was added to the output
+ virtual void inputChanged() {} ///< Called if the input has changed
+ virtual void cursorChanged() {} ///< Called if the cursor in the input line has changed
+ virtual void executed() {} ///< Called if a command from the input line was executed
+ virtual void exit() {} ///< Called if the console should be closed
};
+ /**
+ @brief The Shell is the logical component of the console that displays output to the user and allows him to enter commands.
+
+ The Shell gathers output sent from OutputHandler by inheriting from OutputListener.
+ The output-lines are stored in the shell, so they can be displayed in a graphical
+ console. Additionally the Shell has an InputBuffer which is needed by the user to
+ enter commands.
+
+ Different graphical consoles build upon a Shell, for example InGameConsole and IOConsole.
+ */
class _CoreExport Shell : virtual public OrxonoxClass, public OutputListener
{
public:
+ /// Defines the type of a line of text in the Shell - some types depend on the output level, others are of internal use.
enum LineType
{
None = OutputLevel::None,
@@ -87,13 +112,16 @@
void registerListener(ShellListener* listener);
void unregisterListener(ShellListener* listener);
+ /// Returns the input buffer which is needed by the user to enter text into the shell.
inline InputBuffer* getInputBuffer()
{ return this->inputBuffer_; }
void setCursorPosition(unsigned int cursor);
+ /// Returns the current position of the cursor in the input buffer.
inline unsigned int getCursorPosition() const
{ return this->inputBuffer_->getCursorPosition(); }
+ /// Returns the current content of the input buffer (the text which was entered by the user)
inline const std::string& getInput() const
{ return this->inputBuffer_->get(); }
@@ -104,14 +132,14 @@
void addOutput(const std::string& text, LineType type = None);
void clearOutput();
+ /// Returns the number of output-lines that are displayed in the shell.
inline unsigned int getNumLines() const
{ return this->outputLines_.size(); }
+ /// Returns the line which is currently viewed if the user scrolls through the older output-lines in the shell.
inline unsigned int getScrollPosition() const
{ return this->scrollPosition_; }
- inline const std::string& getPromptPrefix() const { return this->promptPrefix_; }
- void setPromptPrefix(const std::string& str);
-
+ /// Returns the cache size that is actually used in CommandExecutor, but placed here for better readability of the config file.
static inline unsigned int getCacheSize()
{ return Shell::cacheSize_s; }
@@ -144,6 +172,7 @@
void scrollDown();
void exit();
+ /// Iterates through all registered @ref ShellListener "shell listeners" and calls the function @a F.
template <void (ShellListener::*F)()>
void updateListeners()
{
@@ -151,25 +180,24 @@
((*(it++))->*F)();
}
- std::list<ShellListener*> listeners_;
- InputBuffer* inputBuffer_;
- std::stringstream outputBuffer_;
- bool bFinishedLastLine_;
- LineList outputLines_;
- LineList::const_iterator scrollIterator_;
- unsigned int scrollPosition_;
- unsigned int historyPosition_;
+ std::list<ShellListener*> listeners_; ///< The registered shell listeners
+ InputBuffer* inputBuffer_; ///< The input buffer that is needed by the user to enter text
+ std::stringstream outputBuffer_; ///< The output buffer that is used to retrieve lines of output from OutputListener
+ bool bFinishedLastLine_; ///< Stores if the most recent output-line was terminated with a line-break or if more output is expected for this line
+ LineList outputLines_; ///< A list of all output-lines that were displayed in the shell so far
+ LineList::const_iterator scrollIterator_; ///< An iterator to an entry of the list of output-lines, changes if the user scrolls through the output in the shell
+ unsigned int scrollPosition_; ///< The number of the line that is currently being referenced by scrollIterator_
+ unsigned int historyPosition_; ///< If the user scrolls through the history of entered commands (stored in commandHistory_), this contains the currently viewed history entry
- std::string promptPrefix_;
- const std::string consoleName_;
- const bool bScrollable_;
+ const std::string consoleName_; ///< The name of this shell - used to define the name of the soft-debug-level config-value
+ const bool bScrollable_; ///< If true, the user can scroll through the output-lines
// Config values
- unsigned int maxHistoryLength_;
- unsigned int historyOffset_;
- std::vector<std::string> commandHistory_;
- int softDebugLevel_;
- static unsigned int cacheSize_s;
+ unsigned int maxHistoryLength_; ///< The maximum number of saved commands
+ unsigned int historyOffset_; ///< The command history is a circular buffer, this variable defines the current write-offset
+ std::vector<std::string> commandHistory_; ///< The history of commands that were entered by the user
+ int softDebugLevel_; ///< The maximum level of output that is displayed in the shell (will be passed to OutputListener to filter output)
+ static unsigned int cacheSize_s; ///< The maximum cache size of the CommandExecutor - this is stored here for better readability of the config file and because CommandExecutor is no OrxonoxClass
};
}
Modified: code/branches/doc/src/libraries/core/command/TclBind.cc
===================================================================
--- code/branches/doc/src/libraries/core/command/TclBind.cc 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/TclBind.cc 2010-09-05 20:51:55 UTC (rev 7361)
@@ -48,6 +48,10 @@
TclBind* TclBind::singletonPtr_s = 0;
+ /**
+ @brief Constructor: Initializes the Tcl-interpreter with a given data path.
+ @param datapath Path to the directory that contains the Orxonox-specific Tcl-files
+ */
TclBind::TclBind(const std::string& datapath)
{
this->interpreter_ = 0;
@@ -55,12 +59,18 @@
this->setDataPath(datapath);
}
+ /**
+ @brief Destructor: Deletes the Tcl-interpreter.
+ */
TclBind::~TclBind()
{
if (this->interpreter_)
delete this->interpreter_;
}
+ /**
+ @brief Defines the path to the directory that contains the Orxonox-specific Tcl-files and initializes the Tcl-interpreter accordingly.
+ */
void TclBind::setDataPath(const std::string& datapath)
{
// String has POSIX slashes
@@ -70,6 +80,9 @@
this->initializeTclInterpreter();
}
+ /**
+ @brief Creates and initializes the Tcl-interpreter by registering all callbacks and defining some useful functions.
+ */
void TclBind::initializeTclInterpreter()
{
if (this->bSetTclDataPath_ && !this->interpreter_)
@@ -95,6 +108,10 @@
}
}
+ /**
+ @brief Creates and initializes a new Tcl-interpreter and calls the Orxonox-specific
+ init.tcl script that defines some special functions which are required by Orxonox.
+ */
Tcl::interpreter* TclBind::createTclInterpreter()
{
Tcl::interpreter* interpreter = new Tcl::interpreter();
@@ -115,6 +132,9 @@
return interpreter;
}
+ /**
+ @brief Returns the path to the Tcl-library (not the Orxonox-specific Tcl-files).
+ */
std::string TclBind::getTclLibraryPath()
{
#ifdef DEPENDENCY_PACKAGE_ENABLE
@@ -127,6 +147,9 @@
#endif
}
+ /**
+ @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor and to send its result back to Tcl.
+ */
std::string TclBind::tcl_query(Tcl::object const &args)
{
COUT(4) << "Tcl_query: " << args.get() << std::endl;
@@ -150,6 +173,9 @@
return result;
}
+ /**
+ @brief Callback: Used to send an Orxonox-command from Tcl to the CommandExecutor.
+ */
void TclBind::tcl_execute(Tcl::object const &args)
{
COUT(4) << "Tcl_execute: " << args.get() << std::endl;
@@ -161,6 +187,10 @@
}
}
+ /**
+ @brief Console command, executes Tcl code. Can be used to bind Tcl-commands to a key, because native
+ Tcl-commands can not be evaluated and are thus not supported by the key-binder.
+ */
std::string TclBind::tcl(const std::string& tclcode)
{
if (TclBind::getInstance().interpreter_)
@@ -181,11 +211,21 @@
return "";
}
+ /**
+ @brief Console command and implementation of the Tcl-feature "bgerror" which is called if an error
+ occurred in the background of a Tcl-script.
+ */
void TclBind::bgerror(const std::string& error)
{
COUT(1) << "Tcl background error: " << stripEnclosingBraces(error) << std::endl;
}
+ /**
+ @brief Executes Tcl-code and returns the return-value.
+ @param tclcode A string that contains Tcl-code
+ @param error A pointer to an integer (or NULL) that is used to write an error-code (see @ref CommandExecutorErrorCodes "CommandExecutor error codes")
+ @return Returns the return-value of the executed code (or an empty string if there's no return-value)
+ */
std::string TclBind::eval(const std::string& tclcode, int* error)
{
if (error)
@@ -193,6 +233,7 @@
try
{
+ // execute the code
return TclBind::getInstance().interpreter_->eval(tclcode);
}
catch (Tcl::tcl_error const &e)
Modified: code/branches/doc/src/libraries/core/command/TclBind.h
===================================================================
--- code/branches/doc/src/libraries/core/command/TclBind.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/TclBind.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,55 @@
*
*/
+/**
+ @defgroup Tcl Tcl
+ @ingroup Command
+*/
+
+/**
+ @file
+ @ingroup Command Tcl
+ @brief Declaration of the TclBind class.
+
+ @anchor TclBindExample
+
+ orxonox::TclBind is a wrapper class for a Tcl interpreter. It is implemented as
+ singleton, so it can be accessed by everyone, but all share the same static
+ Tcl interpreter. If you need a Tcl interpreter at your own, see orxonox::TclThreadManager
+ for more information.
+
+ orxonox::TclBind is used by orxonox::CommandExecutor to execute Tcl commands. It can
+ also be used to execute Tcl commands from different sources, but note that they may
+ interfer with the ingame console if used improperly. By no means execute blocking
+ commands such as endless loops or the tcl command @c vwait. Use orxonox::TclThreadManager
+ and execute these commands in a multithreaded Tcl interpreter instead.
+
+ TclBind also defines different callback functions to return commands from the
+ Tcl interpreter back to Orxonox. Because of that it's possible to send a mixture
+ of Orxonox- and Tcl-commands to TclBind::eval() and still get the desired behavior.
+
+ Example:
+ @code
+ TclBind::eval("puts \"Hello World\""); // calls the tcl command "puts", prints "Hello World" to the console
+ TclBind::eval("log Hello World"); // calls the orxonox command "log", prints "Hello World" to the console
+
+ TclBind::eval("log [expr 1+1]"); // prints "2" to the console (which is the result of the tcl command "expr")
+
+ TclBind::eval("puts -nonewline Hello; log World"); // prints "HelloWorld" to the console
+
+ TclBind::eval("for {set i 0} {$i < 10} {incr i} {log test: $i}"); // prints "test: 0", ..., "test: 9" to the console
+ @endcode
+
+ Note that @c puts and @c log behave slightly different, even though both can print
+ text to the console. @c puts needs quotation marks around multi-word output, while
+ @c log doesn't. @c puts on the other hand supports the flag @c -nonewline.
+
+ TclBind::eval() can also be used to obtain the return-value of a Tcl command:
+ @code
+ std::string result = TclBind::eval("expr 1+1"); // result == "2"
+ @endcode
+*/
+
#ifndef _TclBind_H__
#define _TclBind_H__
@@ -37,6 +86,15 @@
namespace orxonox
{
+ /**
+ @brief A wrapper class for a Tcl interpreter. Used to execute Tcl commands.
+
+ TclBind is used to execute Tcl commands, for example if sent to CommandExecutor::execute().
+ It also defines different callbacks for Tcl, which allows to combine Orxonox-console-commands
+ and Tcl-function without problems.
+
+ @see See @ref TclBindExample "TclBind.h" for more information and an example.
+ */
class _CoreExport TclBind : public Singleton<TclBind>
{
friend class Singleton<TclBind>;
@@ -48,12 +106,16 @@
static void bgerror(const std::string& error);
void setDataPath(const std::string& datapath);
- const std::string& getTclDataPath() const { return this->tclDataPath_; }
static std::string getTclLibraryPath();
+ /// Returns the path to the Orxonox-specific Tcl-files.
+ inline const std::string& getTclDataPath() const
+ { return this->tclDataPath_; }
void initializeTclInterpreter();
static Tcl::interpreter* createTclInterpreter();
- Tcl::interpreter* getTclInterpreter() const { return this->interpreter_; }
+ /// Returns the Tcl-interpreter
+ inline Tcl::interpreter* getTclInterpreter() const
+ { return this->interpreter_; }
static std::string tcl_query(Tcl::object const &args);
static void tcl_execute(Tcl::object const &args);
@@ -61,13 +123,13 @@
static std::string eval(const std::string& tclcode, int* error = 0);
private:
- TclBind(const TclBind& other);
+ TclBind(const TclBind& other); ///< Copy-constructor, not implemented
- Tcl::interpreter* interpreter_;
- std::string tclDataPath_;
- bool bSetTclDataPath_;
+ Tcl::interpreter* interpreter_; ///< The wrapped Tcl interpreter
+ std::string tclDataPath_; ///< The path to the directory that contains the Orxonox-specific Tcl-files
+ bool bSetTclDataPath_; ///< True if tclDataPath_ was defined (after a call to setDataPath())
- static TclBind* singletonPtr_s;
+ static TclBind* singletonPtr_s; ///< The singleton pointer
};
}
Modified: code/branches/doc/src/libraries/core/command/TclThreadList.h
===================================================================
--- code/branches/doc/src/libraries/core/command/TclThreadList.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/TclThreadList.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,12 @@
*
*/
+/**
+ @file
+ @ingroup Command Tcl
+ @brief Definition of TclThreadList.
+*/
+
#ifndef _TclThreadList_H__
#define _TclThreadList_H__
@@ -39,6 +45,9 @@
namespace orxonox
{
+ /**
+ @brief A thread-safe implementation of a message queue, used by TclThreadManager.
+ */
template <class T>
class TclThreadList
{
Modified: code/branches/doc/src/libraries/core/command/TclThreadManager.cc
===================================================================
--- code/branches/doc/src/libraries/core/command/TclThreadManager.cc 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/TclThreadManager.cc 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,11 @@
*
*/
+/**
+ @file
+ @brief Implementation of TclThreadManager.
+*/
+
#include "TclThreadManager.h"
#include <boost/bind.hpp>
@@ -386,7 +391,7 @@
@param source_id The id of the calling thread
@param target_id The id of the target thread
@param command The command to send as a query
- @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query and false when called by tcl_crossquery.
+ @param bUseCommandExecutor Only used if the target_id is 0 (which references the main interpreter). In this case it means if the command should be passed to the CommandExecutor (true) or to the main Tcl interpreter (false). This is true when called by tcl_query() and false when called by tcl_crossquery().
*/
std::string TclThreadManager::_query(unsigned int source_id, unsigned int target_id, const std::string& command, bool bUseCommandExecutor)
{
Modified: code/branches/doc/src/libraries/core/command/TclThreadManager.h
===================================================================
--- code/branches/doc/src/libraries/core/command/TclThreadManager.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/core/command/TclThreadManager.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -26,6 +26,12 @@
*
*/
+/**
+ @file
+ @ingroup Command Tcl
+ @brief Declaration of TclThreadManager, used to create multithreaded Tcl interpreters.
+*/
+
#ifndef _TclThreadManager_H__
#define _TclThreadManager_H__
Modified: code/branches/doc/src/libraries/util/Debug.h
===================================================================
--- code/branches/doc/src/libraries/util/Debug.h 2010-09-05 20:36:36 UTC (rev 7360)
+++ code/branches/doc/src/libraries/util/Debug.h 2010-09-05 20:51:55 UTC (rev 7361)
@@ -29,7 +29,7 @@
/**
@defgroup COUT COUT(x) output macro
- @ingroup Util Output
+ @ingroup Util
*/
/**
More information about the Orxonox-commit
mailing list