"Fossies" - the Fresh Open Source Software Archive

Member "highlight-3.57-x64/src/include/Diluculum/LuaState.hpp" (12 May 2020, 9702 Bytes) of package /windows/www/highlight-3.57-x64.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 /******************************************************************************\
    2 * LuaState                                                                     *
    3 * A pleasant way to use a Lua state in C++.                                    *
    4 *                                                                              *
    5 *                                                                              *
    6 * Copyright (C) 2005-2013 by Leandro Motta Barros.                             *
    7 *                                                                              *
    8 * Permission is hereby granted, free of charge, to any person obtaining a copy *
    9 * of this software and associated documentation files (the "Software"), to     *
   10 * deal in the Software without restriction, including without limitation the   *
   11 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or  *
   12 * sell copies of the Software, and to permit persons to whom the Software is   *
   13 * furnished to do so, subject to the following conditions:                     *
   14 *                                                                              *
   15 * The above copyright notice and this permission notice shall be included in   *
   16 * all copies or substantial portions of the Software.                          *
   17 *                                                                              *
   18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   *
   19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,     *
   20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE *
   21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       *
   22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      *
   23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS *
   24 * IN THE SOFTWARE.                                                             *
   25 \******************************************************************************/
   26 
   27 
   28 #ifndef _DILUCULUM_LUA_STATE_HPP_
   29 #define _DILUCULUM_LUA_STATE_HPP_
   30 
   31 #include <lua.hpp>
   32 #include <string>
   33 #include <vector>
   34 #include <Diluculum/LuaExceptions.hpp>
   35 #include <Diluculum/LuaValue.hpp>
   36 #include <Diluculum/LuaVariable.hpp>
   37 #include <Diluculum/Types.hpp>
   38 
   39 
   40 namespace Diluculum
   41 {
   42 
   43    /** \c LuaState: The Next Generation. The pleasant way to do perform relevant
   44     *  operations on a Lua state.
   45     *  <p>(My previous implementation of a class named \c LuaState was pretty
   46     *  low-level. It was essentially a C++ wrapper around a <tt>lua_State*</tt>,
   47     *  without higher level operations. This is an attempt to allow me to do
   48     *  the kind of things I do most of the time without much effort.)
   49     */
   50    class LuaState
   51    {
   52       public:
   53          /** Constructs a \c LuaState that owns a <tt>lua_State*</tt>. In other
   54           *  words, this will create the underlying Lua state on construction
   55           *  and destroy it when this \c LuaState is destroyed.
   56           *  @param loadStdLib If \c true (the default), makes all
   57           *         the Lua standard libraries available.
   58           *  @throw LuaError If something goes wrong.
   59           */
   60          explicit LuaState (bool loadStdLib = true);
   61 
   62          /** Constructs a \c LuaState that doesn't own the underlying Lua state.
   63           *  In other words, this \c LuaState will use a user-supplied
   64           *  <tt>lua_State*</tt> and its destructor will not \c lua_close() it.
   65           *  @param state The <tt>lua_State*</tt> that will be used by this
   66           *         \c LuaState.
   67           *  @param loadStdLib If \c true, makes all the Lua standard libraries
   68           *         available (default is \c false, because it is very likely
   69           *         that the libraries are already opened in the Lua state
   70           *         passed as the first parameter).
   71           *  @throw LuaError If something goes wrong.
   72           */
   73          explicit LuaState (lua_State* state, bool loadStdLib = false);
   74 
   75          /** Destructs a \c LuaState. If this \c LuaState owns the underlying \c
   76           *  lua_State*, \c lua_close() will be called on it. See the
   77           *  constructors' documentation for details on the \c lua_State*
   78           *  ownership.
   79           */
   80          virtual ~LuaState();
   81 
   82          /** Executes the file passed as parameter and returns all the values
   83           *  returned by this execution. Notice that when a \c LuaValueList is
   84           *  assigned to a \c LuaValue, just the first value in the list is
   85           *  assigned, so this is handy for situations when only the first
   86           *  return value is desired.
   87           *  @param fileName The file to be executed.
   88           *  @return All the values returned by the file execution.
   89           *  @throw LuaError \c LuaError or any of its subclasses can be thrown.
   90           *         In particular, \c LuaTypeError will be thrown if the
   91           *         execution returns a type not supported by \c LuaType.
   92           */
   93          LuaValueList doFile (const std::string& fileName)
   94          { return doStringOrFile (false, fileName); }
   95 
   96          /** Executes the string passed as parameter and returns all the values
   97           *  returned by this execution. Notice that when a \c LuaValueList is
   98           *  assigned to a \c LuaValue, just the first value in the list is
   99           *  assigned, so this is handy for situations when only the first
  100           *  return value is desired.
  101           *  @param what The string to be interpreted.
  102           *  @return All the values returned by the execution of \c what.
  103           *  @throw LuaError \c LuaError or any of its subclasses can be thrown.
  104           *         In particular, \c LuaTypeError will be thrown if the
  105           *         execution returns a type not supported by \c LuaType.
  106           */
  107          LuaValueList doString (const std::string& what)
  108          { return doStringOrFile (true, what); }
  109 
  110          /** Calls a given Lua function on this Lua state.
  111           *  @param func The function to be called.
  112           *  @param params the list of parameters to pass to the function.
  113           *  @param chunkName The string to use as the "chunk name" in the
  114           *         call. This is something added to error messages, in order to
  115           *         make easier to stop where the error was.
  116           *  @throw LuaError (or any of its subclasses), if some error is found
  117           *         during the function execution.
  118           */
  119          LuaValueList call (LuaFunction& func,
  120                             const LuaValueList& params,
  121                             const std::string& chunkName = "Diluculum chunk");
  122 
  123          /** Returns a \c LuaVariable representing the global variable named
  124           *  \c variable. Since the returned value also has a subscript
  125           *  operator, this is a handy way to access variables stored in tables.
  126           *  Also, since the \c LuaVariable has read/write support, this can be
  127           *  used even to modify the variables stored in the \c LuaState.
  128           *  @param variable The name of the global variable to be accessed.
  129           *  @returns The global variable named \c variable. If no such variable
  130           *           exists, returns a variable containing \c Nil.
  131           *  @note This operator does not throw exceptions.
  132           *  @note Trying to access "_G" (the Lua globals table) with
  133           *        <tt>LuaState::operator[]</tt> will not work (debug builds
  134           *        will \c assert()). Please use \c globals() instead.
  135           */
  136          LuaVariable operator[] (const std::string& variable);
  137 
  138          /**
  139           * Provides access to the table of global variables.
  140           * @note The returned table will not contain "_G" not "package",
  141           *       because including them would result in tables referencing
  142           *       themselves in a infinitely recursive manner. In Lua, tables
  143           *       are reference types, so this recursion is OK. In Diluculum,
  144           *       tables are value types, so this would result in a crash.
  145           * @return The table of global variables in this Lua state.
  146           */
  147          LuaValueMap globals();
  148 
  149          /// Returns the encapsulated <tt>lua_State*</tt>.
  150          lua_State* getState() { return state_; }
  151 
  152       private:
  153          /** Since The implementation of \c doString and \c doFile() are quite
  154           *  similar, it looked like a good idea to use the same function to
  155           *  implement both at a lower level. This is it.
  156           *  @param isString If \c true, means that it is desired to execute the
  157           *         contents of a string. If \c false, means that it is desired
  158           *         to execute the contents of a file.
  159           *  @param str Can be either a string of Lua code to be executed or a
  160           *         file with Lua code to be executed. The exact interpretation
  161           *         of this parameter depends on the first parameter,
  162           *         \c isString.
  163           *  @throw LuaError \c LuaError or any of its subclasses can be thrown.
  164           *         In particular, \c LuaTypeError will be thrown if the
  165           *         execution returns a type not supported by \c LuaType.
  166           */
  167          LuaValueList doStringOrFile (bool isString, const std::string& str);
  168 
  169          /// The underlying \c lua_State*.
  170          lua_State* state_;
  171 
  172          /** Does this \c LuaState owns \c state_? (This used by the destructor
  173           *  to decide whether it has to \c lua_close() it or not.)
  174           */
  175          const bool ownsState_;
  176    };
  177 
  178 } // namespace Diluculum
  179 
  180 #endif // #ifndef _DILUCULUM_LUA_STATE_HPP_