"Fossies" - the Fresh Open Source Software Archive

Member "highlight-3.57-x64/src/include/Diluculum/LuaVariable.hpp" (12 May 2020, 17474 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 * LuaVariable.hpp                                                              *
    3 * A variable living in a Lua interpreter.                                      *
    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 #ifndef _DILUCULUM_LUA_VARIABLE_HPP_
   28 #define _DILUCULUM_LUA_VARIABLE_HPP_
   29 
   30 #include <vector>
   31 #include <Diluculum/LuaValue.hpp>
   32 
   33 
   34 namespace Diluculum
   35 {
   36    /** A variable living in a Lua state. Notice the crucial difference: unlike a
   37     *  \c LuaValue, a \c LuaVariable necessarily has a real counterpart in a Lua
   38     *  state. Thus, when something is assigned to a \c LuaVariable, the value of
   39     *  the corresponding variable in the Lua state is changed, too.
   40     *  <p><tt>LuaVariable</tt>s cannot be directly constructed. They are
   41     *  designed to be returned by <tt>LuaState</tt>'s subscript operator.
   42     */
   43    class LuaVariable
   44    {
   45       friend class LuaState;
   46 
   47       public:
   48          /** Assigns a new value to this \c LuaVariable. The corresponding
   49           *  variable in the Lua state is updated accordingly.
   50           *  @note Notice that this is the assignment of a new value to a
   51           *        variable. The user is also allowed to assign a
   52           *        \c LuaVariable to another \c LuaVariable (using the
   53           *        compiler-generated assignment operator). In that case, the
   54           *        \c LuaVariable at the left hand side will refer to the same
   55           *        variable as the \c LuaVariable at the right hand side, but no
   56           *        values will be changed.
   57           *  @param rhs The new value for the variable.
   58           *  @return \c rhs, so that a sequence of assignments, like
   59           *          <tt>a = b = c = 1;</tt> works. Actually, returning
   60           *          \c rhs is the same as returning <tt>this->value()</tt>,
   61           *          that perhaps make more sense.
   62           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
   63           *         something that is not a table.
   64           *  @note Part of this method's implementation is identical to the
   65           *        implementation of the \c DILUCULUM_REGISTER_OBJECT() macro.
   66           *        If someday the implementation here is replaced with something
   67           *        better, remember to change there, too.
   68           */
   69          const LuaValue& operator= (const LuaValue& rhs);
   70 
   71          /** Returns the value associated with this variable. If the variable
   72           *  does not exist, returns \c Nil.
   73           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
   74           *         something that is not a table.
   75           */
   76          LuaValue value() const;
   77 
   78          /** Assuming that this \c LuaVariable holds a table, returns the value
   79           *  whose index is \c key.
   80           *  @param key The key whose value is desired.
   81           *  @return The value whose index is \c key.
   82           *  @note This method doesn't throw anything, even if this
   83           *        \c LuaVariable doesn't hold a table. But an exception will
   84           *        be thrown if one tries to access the value of the returned
   85           *        variable (see \c value()).
   86           */
   87          LuaVariable operator[] (const LuaValue& key) const;
   88 
   89          /** Assuming that this \c LuaVariable holds a function, calls this
   90           *  function and returns its return values. Both "pure" Lua functions
   91           *  and functions written in C/C++ and "exported" to Lua are supported.
   92           *  @param params All the parameters to be passed to the function being
   93           *         called. The first parameter at index 0, the second at
   94           *         index 1 and so on.
   95           *  @return All the values returned by the called function. The first
   96           *          return value at index 0, the second at index 1 and so on.
   97           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
   98           *         something that is not a table.
   99           *  @throw LuaRunTimeError If something bad happens while executing the
  100           *         function.
  101           */
  102          LuaValueList operator()(const LuaValueList& params);
  103 
  104          /** Assuming that this \c LuaVariable holds a function, calls this
  105           *  function (without passing any parameter to it) and returns its
  106           *  return values. Both "pure" Lua functions and functions written in
  107           *  C/C++ and "exported" to Lua are supported.
  108           *  @return All the values returned by the called function. The first
  109           *          return value at index 0, the second at index 1 and so on.
  110           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  111           *         something that is not a table.
  112           *  @throw LuaRunTimeError If something bad happens while executing the
  113           *         function.
  114           */
  115          LuaValueList operator()();
  116 
  117          /** Assuming that this \c LuaVariable holds a function, calls this
  118           *  function and returns its return values. Both "pure" Lua functions
  119           *  and functions written in C/C++ and "exported" to Lua are supported.
  120           *  @param param The one and only parameter to be passed to the
  121           *         function being called
  122           *  @return All the values returned by the called function. The first
  123           *          return value at index 0, the second at index 1 and so on.
  124           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  125           *         something that is not a table.
  126           *  @throw LuaRunTimeError If something bad happens while executing the
  127           *         function.
  128           */
  129          LuaValueList operator() (const LuaValue& param);
  130 
  131          /** Assuming that this \c LuaVariable holds a function, calls this
  132           *  function and returns its return values. Both "pure" Lua functions
  133           *  and functions written in C/C++ and "exported" to Lua are supported.
  134           *  @param param1 The first parameter to be passed to the function
  135           *         being called
  136           *  @param param2 The second parameter to be passed to the function
  137           *         being called
  138           *  @return All the values returned by the called function. The first
  139           *          return value at index 0, the second at index 1 and so on.
  140           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  141           *         something that is not a table.
  142           *  @throw LuaRunTimeError If something bad happens while executing the
  143           *         function.
  144           */
  145          LuaValueList operator() (const LuaValue& param1,
  146                                   const LuaValue& param2);
  147 
  148          /** Assuming that this \c LuaVariable holds a function, calls this
  149           *  function and returns its return values. Both "pure" Lua functions
  150           *  and functions written in C/C++ and "exported" to Lua are supported.
  151           *  @param param1 The first parameter to be passed to the function
  152           *         being called
  153           *  @param param2 The second parameter to be passed to the function
  154           *         being called
  155           *  @param param3 The third parameter to be passed to the function
  156           *         being called
  157           *  @return All the values returned by the called function. The first
  158           *          return value at index 0, the second at index 1 and so on.
  159           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  160           *         something that is not a table.
  161           *  @throw LuaRunTimeError If something bad happens while executing the
  162           *         function.
  163           */
  164          LuaValueList operator() (const LuaValue& param1,
  165                                   const LuaValue& param2,
  166                                   const LuaValue& param3);
  167 
  168          /** Assuming that this \c LuaVariable holds a function, calls this
  169           *  function and returns its return values. Both "pure" Lua functions
  170           *  and functions written in C/C++ and "exported" to Lua are supported.
  171           *  @param param1 The first parameter to be passed to the function
  172           *         being called
  173           *  @param param2 The second parameter to be passed to the function
  174           *         being called
  175           *  @param param3 The third parameter to be passed to the function
  176           *         being called
  177           *  @param param4 The fourth parameter to be passed to the function
  178           *         being called
  179           *  @return All the values returned by the called function. The first
  180           *          return value at index 0, the second at index 1 and so on.
  181           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  182           *         something that is not a table.
  183           *  @throw LuaRunTimeError If something bad happens while executing the
  184           *         function.
  185           */
  186          LuaValueList operator() (const LuaValue& param1,
  187                                   const LuaValue& param2,
  188                                   const LuaValue& param3,
  189                                   const LuaValue& param4);
  190 
  191          /** Assuming that this \c LuaVariable holds a function, calls this
  192           *  function and returns its return values. Both "pure" Lua functions
  193           *  and functions written in C/C++ and "exported" to Lua are supported.
  194           *  @param param1 The first parameter to be passed to the function
  195           *         being called
  196           *  @param param2 The second parameter to be passed to the function
  197           *         being called
  198           *  @param param3 The third parameter to be passed to the function
  199           *         being called
  200           *  @param param4 The fourth parameter to be passed to the function
  201           *         being called
  202           *  @param param5 The fifth parameter to be passed to the function
  203           *         being called
  204           *  @return All the values returned by the called function. The first
  205           *          return value at index 0, the second at index 1 and so on.
  206           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  207           *         something that is not a table.
  208           *  @throw LuaRunTimeError If something bad happens while executing the
  209           *         function.
  210           */
  211          LuaValueList operator() (const LuaValue& param1,
  212                                   const LuaValue& param2,
  213                                   const LuaValue& param3,
  214                                   const LuaValue& param4,
  215                                   const LuaValue& param5);
  216 
  217          /** Checks whether the value stored in this variable is equal to the
  218           *  value at \c rhs.
  219           *  @param rhs The value against which the comparison will be done.
  220           *  @return \c true if this variable's value is equal to \c rhs.
  221           *          \c false otherwise.
  222           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  223           *         something that is not a table.
  224           */
  225          bool operator== (const LuaValue& rhs) const
  226          { return value() == rhs; }
  227 
  228          /** Checks whether this \c LuaVariable refers to the same variable as
  229           *  \c rhs.
  230           *  @param rhs The variable against which the comparison will be done.
  231           *  @return \c true if both involved <tt>LuaVariable</tt>s refer to the
  232           *          same variable. \c false otherwise.
  233           */
  234          bool operator== (const LuaVariable& rhs) const
  235          { return state_ == rhs.state_ && keys_ == rhs.keys_; }
  236 
  237          /** Checks whether this \c LuaVariable refers to a different variable
  238           *  than \c rhs.
  239           *  @param rhs The variable against which the comparison will be done.
  240           *  @return \c false if both involved <tt>LuaVariable</tt>s refer to the
  241           *          same variable. \c true otherwise.
  242           */
  243          bool operator!= (const LuaVariable& rhs) const
  244          { return state_ != rhs.state_ || keys_ != rhs.keys_; }
  245 
  246          /// A sequence of keys, used to access nested tables.
  247          typedef std::vector<LuaValue> KeyList;
  248 
  249          /** Returns the sequence of keys used to reach this variable.
  250           *  @note This method exists mostly to allow a nicer implementation of
  251           *        other Diluculum features. Users aren't expected to call this.
  252           */
  253          const KeyList& getKeys() const { return keys_; }
  254 
  255          /** Pushes into the Lua stack the table storing this variable. Now,
  256           *  let's try to make this clearer... First, every Lua variable is
  257           *  stored in a table (even global variables, because Lua stores them
  258           *  in a "table of globals"). So, this method will find the table where
  259           *  this variable is stored (traversing a sequence of nested tables, if
  260           *  necessary), and push it onto the Lua stack (of the \c state_ Lua
  261           *  state).
  262           *  @note This method exists mostly to allow a nicer implementation of
  263           *        other Diluculum features. Users aren't expected to call this.
  264           */
  265          void pushLastTable();
  266 
  267          /** Returns the LuaState in which this \c LuaVariable lives.
  268           *  @note This method exists mostly to allow a nicer implementation of
  269           *        other Diluculum features. Users aren't expected to call this.
  270           */
  271          lua_State* getState() { return state_; }
  272 
  273       private:
  274 
  275          /** Constructs a \c LuaVariable.
  276           *   @note This is private because no one is expected to construct a
  277           *         \c LuaVariable directly. For Diluculum users, the only
  278           *         allowed way to create a new \c LuaVariable is by using
  279           *         <tt>LuaState</tt>'s subscript operator.
  280           *   @param state The <tt>lua_State*</tt> in which the variable
  281           *          represented by this \c LuaVariable resides.
  282           *   @param key The "key" used to access the variable represented by
  283           *          this \c LuaVariable. This can be variable name (for the case
  284           *          of a global variable) or a "real" key (when it is a field in
  285           *          a possibly nested table).
  286           *   @param predKeys The sequence of keys used to access the table that
  287           *          contains the variable represented by this \c LuaVariable.
  288           *          For a global variable, this list will be empty. For a
  289           *          variable stored in a possibly nested table, the list can be
  290           *          arbitrarily long.
  291           */
  292          LuaVariable (lua_State* state, const LuaValue& key,
  293                       const KeyList& predKeys = KeyList());
  294 
  295          /** Pushes onto the Lua stack the value referenced by this
  296           *  \c LuaVariable.
  297           *  @throw TypeMismatchError If this \c LuaVariable tries to subscript
  298           *         something that is not a table.
  299           */
  300          void pushTheReferencedValue() const;
  301 
  302          /// The Lua state in which this \c LuaVariable lives.
  303          lua_State* state_;
  304 
  305          /** The sequence of keys used to get to this variable. For a global
  306           *  variable, this will consist of a single key; for variables inside
  307           *  nested tables, this sequence can be arbitrarily long.
  308           *  <p>Just to relate this with the parameters passed to the
  309           *  constructor: this sequence equals to \c predKeys parameter, with
  310           *  the \c key parameter appended to it.
  311           */
  312          KeyList keys_;
  313    };
  314 
  315 } // namespace Diluculum
  316 
  317 #endif // _DILUCULUM_LUA_VARIABLE_HPP_