Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/libraries/core/command/TclBind.h @ 11247

Last change on this file since 11247 was 11071, checked in by landauf, 9 years ago

merged branch cpp11_v3 back to trunk

  • Property svn:eol-style set to native
File size: 5.5 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Fabian 'x3n' Landau
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup Tcl Tcl
31    @ingroup Command
32*/
33
34/**
35    @file
36    @ingroup Command Tcl
37    @brief Declaration of the TclBind class.
38
39    @anchor TclBindExample
40
41    orxonox::TclBind is a wrapper class for a Tcl interpreter. It is implemented as
42    singleton, so it can be accessed by everyone, but all share the same static
43    Tcl interpreter. If you need a Tcl interpreter at your own, see orxonox::TclThreadManager
44    for more information.
45
46    orxonox::TclBind is used by orxonox::CommandExecutor to execute Tcl commands. It can
47    also be used to execute Tcl commands from different sources, but note that they may
48    interfer with the ingame console if used improperly. By no means execute blocking
49    commands such as endless loops or the tcl command @c vwait. Use orxonox::TclThreadManager
50    and execute these commands in a multithreaded Tcl interpreter instead.
51
52    TclBind also defines different callback functions to return commands from the
53    Tcl interpreter back to Orxonox. Because of that it's possible to send a mixture
54    of Orxonox- and Tcl-commands to TclBind::eval() and still get the desired behavior.
55
56    Example:
57    @code
58    TclBind::eval("puts \"Hello World\"");                              // calls the tcl command "puts", prints "Hello World" to the console
59    TclBind::eval("log Hello World");                                   // calls the orxonox command "log", prints "Hello World" to the console
60
61    TclBind::eval("log [expr 1+1]");                                    // prints "2" to the console (which is the result of the tcl command "expr")
62
63    TclBind::eval("puts -nonewline Hello; log World");                  // prints "HelloWorld" to the console
64
65    TclBind::eval("for {set i 0} {$i < 10} {incr i} {log test: $i}");   // prints "test: 0", ..., "test: 9" to the console
66    @endcode
67
68    Note that @c puts and @c log behave slightly different, even though both can print
69    text to the console. @c puts needs quotation marks around multi-word output, while
70    @c log doesn't. @c puts on the other hand supports the flag @c -nonewline.
71
72    TclBind::eval() can also be used to obtain the return-value of a Tcl command:
73    @code
74    std::string result = TclBind::eval("expr 1+1");                     // result == "2"
75    @endcode
76*/
77
78#ifndef _TclBind_H__
79#define _TclBind_H__
80
81#include "core/CorePrereqs.h"
82
83#include <cassert>
84#include <string>
85#include "util/Singleton.h"
86
87namespace orxonox
88{
89    /**
90        @brief A wrapper class for a Tcl interpreter. Used to execute Tcl commands.
91
92        TclBind is used to execute Tcl commands, for example if sent to CommandExecutor::execute().
93        It also defines different callbacks for Tcl, which allows to combine Orxonox-console-commands
94        and Tcl-function without problems.
95
96        @see See @ref TclBindExample "TclBind.h" for more information and an example.
97    */
98    class _CoreExport TclBind : public Singleton<TclBind>
99    {
100        friend class Singleton<TclBind>;
101        public:
102            TclBind(const std::string& datapath);
103            ~TclBind();
104
105            static std::string tcl(const std::string& tclcode);
106            static void bgerror(const std::string& error);
107
108            void setDataPath(const std::string& datapath);
109            static std::string getTclLibraryPath();
110            /// Returns the path to the Orxonox-specific Tcl-files.
111            inline const std::string& getTclDataPath() const
112                { return this->tclDataPath_; }
113
114            void initializeTclInterpreter();
115            static Tcl::interpreter* createTclInterpreter();
116            /// Returns the Tcl-interpreter
117            inline Tcl::interpreter* getTclInterpreter() const
118                { return this->interpreter_; }
119
120            static std::string tcl_query(Tcl::object const &args);
121            static void tcl_execute(Tcl::object const &args);
122
123            static std::string eval(const std::string& tclcode, int* error = nullptr);
124
125        private:
126            // non-copyable:
127            TclBind(const TclBind&) = delete;
128            TclBind& operator=(const TclBind&) = delete;
129
130            static std::string tcl_helper(Tcl::object const &args, bool bQuery);
131
132            Tcl::interpreter* interpreter_;     ///< The wrapped Tcl interpreter
133            std::string tclDataPath_;           ///< The path to the directory that contains the Orxonox-specific Tcl-files
134            bool bSetTclDataPath_;              ///< True if tclDataPath_ was defined (after a call to setDataPath())
135
136            static TclBind* singletonPtr_s;     ///< The singleton pointer
137    };
138}
139
140#endif /* _TclBind_H__ */
Note: See TracBrowser for help on using the repository browser.