|
From: Arvid N. <ar...@us...> - 2006-01-11 00:53:40
|
Update of /cvsroot/luabind/luabind/luabind/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv31961 Modified Files: Tag: luabind_rc_0_7 docs.html docs.rst Log Message: added sections about how to add file and line number to error messages, notes about how catch(...) can be worked around on msvc, created a new section called error handling and moved related topics together under it Index: docs.html =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.html,v retrieving revision 1.54.2.4 retrieving revision 1.54.2.5 diff -u -d -r1.54.2.4 -r1.54.2.5 --- docs.html 10 Jan 2006 00:36:47 -0000 1.54.2.4 +++ docs.html 11 Jan 2006 00:53:25 -0000 1.54.2.5 @@ -24,7 +24,7 @@ <tr><th class="docinfo-name">Date:</th> <td>2006-01-10</td></tr> <tr><th class="docinfo-name">Revision:</th> -<td>1.26.2.3</td></tr> +<td>1.26.2.4</td></tr> <tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation @@ -106,15 +106,19 @@ </ul> </li> <li><a class="reference" href="#splitting-up-the-registration" id="id85" name="id85">13 Splitting up the registration</a></li> -<li><a class="reference" href="#configuration" id="id86" name="id86">14 Configuration</a><ul class="auto-toc"> -<li><a class="reference" href="#build-options" id="id87" name="id87">14.1 Build options</a></li> +<li><a class="reference" href="#error-handling" id="id86" name="id86">14 Error Handling</a><ul class="auto-toc"> +<li><a class="reference" href="#pcall-errorfunc" id="id87" name="id87">14.1 pcall errorfunc</a></li> +<li><a class="reference" href="#file-and-line-numbers" id="id88" name="id88">14.2 file and line numbers</a></li> +<li><a class="reference" href="#lua-panic" id="id89" name="id89">14.3 lua panic</a></li> +<li><a class="reference" href="#msvc-exceptions" id="id90" name="id90">14.4 msvc exceptions</a></li> +<li><a class="reference" href="#error-messages" id="id91" name="id91">14.5 Error messages</a></li> </ul> </li> -<li><a class="reference" href="#implementation-notes" id="id88" name="id88">15 Implementation notes</a></li> -<li><a class="reference" href="#error-messages" id="id89" name="id89">16 Error messages</a></li> -<li><a class="reference" href="#faq" id="id90" name="id90">17 FAQ</a></li> -<li><a class="reference" href="#known-issues" id="id91" name="id91">18 Known issues</a></li> -<li><a class="reference" href="#acknowledgments" id="id92" name="id92">19 Acknowledgments</a></li> +<li><a class="reference" href="#build-options" id="id92" name="id92">15 Build options</a></li> +<li><a class="reference" href="#implementation-notes" id="id93" name="id93">16 Implementation notes</a></li> +<li><a class="reference" href="#faq" id="id94" name="id94">17 FAQ</a></li> +<li><a class="reference" href="#known-issues" id="id95" name="id95">18 Known issues</a></li> +<li><a class="reference" href="#acknowledgments" id="id96" name="id96">19 Acknowledgments</a></li> </ul> </div> <div class="section" id="introduction"> @@ -216,7 +220,7 @@ <p>When building luabind you have several options that may streamline the library to better suit your needs. It is extremely important that your application has the same settings as the library was built with. The available options are -found in the <a class="reference" href="#configuration">Configuration</a> section.</p> +found in the <a class="reference" href="#build-options">Build options</a> section.</p> <p>If you want to change the settings to differ from the default, it's recommended that you define the settings on the command line of all your files (in the project settings in visual studio).</p> @@ -479,7 +483,7 @@ int ret = call_function(L, "fun", boost::ref(val)); </pre> <p>If you want to use a custom error handler for the function call, see -<tt class="docutils literal"><span class="pre">set_pcall_callback</span></tt> under <a class="reference" href="#configuration">Configuration</a>.</p> +<tt class="docutils literal"><span class="pre">set_pcall_callback</span></tt> under <a class="reference" href="#pcall-errorfunc">pcall errorfunc</a>.</p> </div> <div class="section" id="using-lua-threads"> <h2><a name="using-lua-threads">7.4 Using Lua threads</a></h2> @@ -1078,15 +1082,13 @@ conversion from C++ value to Lua. If your <tt class="docutils literal"><span class="pre">luabind::object</span></tt> is a table you can access its members through the operator[] or the <a class="reference" href="#iterators">Iterators</a>. The value returned from the operator[] is a proxy object that can be used both for -reading and writing values into the table (using operator=). Note that it is -impossible to know if a Lua value is indexable or not (lua_gettable doesn't -fail, it succeeds or crashes). This means that if you're trying to index -something that cannot be indexed, you're on your own. Lua will call its -<tt class="docutils literal"><span class="pre">panic()</span></tt> function. You can define your own panic function using -<tt class="docutils literal"><span class="pre">lua_atpanic</span></tt>. Unless you want to terminate the application, the best way -to continue from the panic function is to make sure lua is compiled as C++ -and throw an exception from the panic function. There are also free functions -that can be used for indexing the table, see <a class="reference" href="#related-functions">Related functions</a>.</p> +reading and writing values into the table (using operator=).</p> +<p>Note that it is impossible to know if a Lua value is indexable or not +(<tt class="docutils literal"><span class="pre">lua_gettable</span></tt> doesn't fail, it succeeds or crashes). This means that if +you're trying to index something that cannot be indexed, you're on your own. +Lua will call its <tt class="docutils literal"><span class="pre">panic()</span></tt> function. See <a class="reference" href="#lua-panic">lua panic</a>.</p> +<p>There are also free functions that can be used for indexing the table, see +<a class="reference" href="#related-functions">Related functions</a>.</p> <p>The constructor that takes a <tt class="docutils literal"><span class="pre">from_stack</span></tt> object is used when you want to initialize the object with a value from the lua stack. The <tt class="docutils literal"><span class="pre">from_stack</span></tt> type has the following constructor:</p> @@ -1248,7 +1250,7 @@ <p>The <tt class="docutils literal"><span class="pre">object_cast</span></tt> function casts the value of an object to a C++ value. You can supply a policy to handle the conversion from lua to C++. If the cast cannot be made a <tt class="docutils literal"><span class="pre">cast_failed</span></tt> exception will be thrown. If you have -defined LUABIND_NO_ERROR_CHECKING (see configuration) no checking will occur, +defined LUABIND_NO_ERROR_CHECKING (see <a class="reference" href="#build-options">Build options</a>) no checking will occur, and if the cast is invalid the application may very well crash. The nothrow versions will return an uninitialized <tt class="docutils literal"><span class="pre">boost::optional<T></span></tt> object, to indicate that the cast could not be performed.</p> @@ -1662,16 +1664,16 @@ <div class="contents topic" id="policies-currently-implemented"> <p class="topic-title first"><a name="policies-currently-implemented">Policies currently implemented</a></p> <ul class="auto-toc simple"> -<li><a class="reference" href="#adopt" id="id93" name="id93">12.1 adopt</a></li> -<li><a class="reference" href="#dependency" id="id94" name="id94">12.2 dependency</a></li> -<li><a class="reference" href="#out-value" id="id95" name="id95">12.3 out_value</a></li> -<li><a class="reference" href="#pure-out-value" id="id96" name="id96">12.4 pure_out_value</a></li> -<li><a class="reference" href="#return-reference-to" id="id97" name="id97">12.5 return_reference_to</a></li> -<li><a class="reference" href="#copy" id="id98" name="id98">12.6 copy</a></li> -<li><a class="reference" href="#discard-result" id="id99" name="id99">12.7 discard_result</a></li> -<li><a class="reference" href="#return-stl-iterator" id="id100" name="id100">12.8 return_stl_iterator</a></li> -<li><a class="reference" href="#raw" id="id101" name="id101">12.9 raw</a></li> -<li><a class="reference" href="#yield" id="id102" name="id102">12.10 yield</a></li> +<li><a class="reference" href="#adopt" id="id97" name="id97">12.1 adopt</a></li> +<li><a class="reference" href="#dependency" id="id98" name="id98">12.2 dependency</a></li> +<li><a class="reference" href="#out-value" id="id99" name="id99">12.3 out_value</a></li> +<li><a class="reference" href="#pure-out-value" id="id100" name="id100">12.4 pure_out_value</a></li> +<li><a class="reference" href="#return-reference-to" id="id101" name="id101">12.5 return_reference_to</a></li> +<li><a class="reference" href="#copy" id="id102" name="id102">12.6 copy</a></li> +<li><a class="reference" href="#discard-result" id="id103" name="id103">12.7 discard_result</a></li> +<li><a class="reference" href="#return-stl-iterator" id="id104" name="id104">12.8 return_stl_iterator</a></li> +<li><a class="reference" href="#raw" id="id105" name="id105">12.9 raw</a></li> +<li><a class="reference" href="#yield" id="id106" name="id106">12.10 yield</a></li> </ul> </div> <div class="section" id="adopt"> @@ -2630,8 +2632,10 @@ } </pre> </div> -<div class="section" id="configuration"> -<h1><a name="configuration">14 Configuration</a></h1> +<div class="section" id="error-handling"> +<h1><a name="error-handling">14 Error Handling</a></h1> +<div class="section" id="pcall-errorfunc"> +<h2><a name="pcall-errorfunc">14.1 pcall errorfunc</a></h2> <p>As mentioned in the <a class="reference" href="http://www.lua.org/manual/5.0/manual.html">Lua documentation</a>, it is possible to pass an error handler function to <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt>. Luabind makes use of <tt class="docutils literal"><span class="pre">lua_pcall()</span></tt> internally when calling member functions and free functions. @@ -2657,8 +2661,133 @@ std::cout << error_msg << std::endl; } </pre> +</div> +<div class="section" id="file-and-line-numbers"> +<h2><a name="file-and-line-numbers">14.2 file and line numbers</a></h2> +<p>If you want to add file name and line number to the error messages generated +by luabind you can define your own <a class="reference" href="#pcall-errorfunc">pcall errorfunc</a>. You may want to modify +this callback to better suit your needs, but the basic functionality could be +implemented like this:</p> +<pre class="literal-block"> +int add_file_and_line(lua_State* L) +{ + lua_Debug d; + lua_getstack(L, 1, &d); + lua_getinfo(L, "Sln", &d); + std::string err = lua_tostring(L, -1); + lua_pop(L, 1); + std::stringstream msg; + msg << d.short_src << ":" << d.currentline; + + if (d.name != 0) + { + msg << "(" << d.namewhat << " " << d.name << ")"; + } + msg << " " << err; + lua_pushstring(L, msg.str().c_str()); + return 1; +} +</pre> +<p>For more information about what kind of information you can add to the error +message, see <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#4">the debug section of the lua manual</a>.</p> +<p>Note that the callback set by <tt class="docutils literal"><span class="pre">set_pcall_callback()</span></tt> will only be used when +luabind executes lua code. Anytime when you call <tt class="docutils literal"><span class="pre">lua_pcall</span></tt> yourself, you +have to supply your function if you want error messages translated.</p> +</div> +<div class="section" id="lua-panic"> +<h2><a name="lua-panic">14.3 lua panic</a></h2> +<p>When lua encounters a fatal error caused by a bug from the C/C++ side, it will +call its internal panic function. This can happen, for example, when you call +<tt class="docutils literal"><span class="pre">lua_gettable</span></tt> on a value that isn't a table. If you do the same thing from +within lua, it will of course just fail with an error message.</p> +<p>The default panic function will <tt class="docutils literal"><span class="pre">exit()</span></tt> the application. If you want to +handle this case without terminating your application, you can define your own +panic function using <tt class="docutils literal"><span class="pre">lua_atpanic</span></tt>. The best way to continue from the panic +function is to make sure lua is compiled as C++ and throw an exception from +the panic function. Throwing an exception instead of using <tt class="docutils literal"><span class="pre">setjmp</span></tt> and +<tt class="docutils literal"><span class="pre">longjmp</span></tt> will make sure the stack is correctly unwound.</p> +<p>For more information, see the <a class="reference" href="http://www.lua.org/manual/5.0/manual.html#3.19">lua manual section 3.19</a>.</p> +</div> +<div class="section" id="msvc-exceptions"> +<h2><a name="msvc-exceptions">14.4 msvc exceptions</a></h2> +<p>Since lua is generally built as a C library, any callbacks called from lua +cannot under any circumstance throw an exception. Because of that, luabind has +to catch all exceptions and translate them into proper lua errors (by calling +<tt class="docutils literal"><span class="pre">lua_error()</span></tt>). This means we have a <tt class="docutils literal"><span class="pre">catch(...)</span> <span class="pre">{}</span></tt> in there.</p> +<p>In VisualStudio, <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">(...)</span></tt> will not only catch C++ exceptions, it will +also catch hardware exceptions like Segmentation fault. This means that if +your function, that gets called from luabind, makes an invalid memory +adressing, you won't notice it. All that will happen is that lua will return +an error message saying "unknown exception".</p> +<p>To remedy this, you can create your own <em>exception translator</em>:</p> +<pre class="literal-block"> +void straight_to_debugger(unsigned int, _EXCEPTION_POINTERS*) +{ throw; } + +#ifdef _MSC_VER + ::_set_se_translator(straight_to_debugger); +#endif +</pre> +<p>This will make hardware exceptions, like segmentation fault, to actually get +caught by the debugger.</p> +</div> +<div class="section" id="error-messages"> +<h2><a name="error-messages">14.5 Error messages</a></h2> +<p>These are the error messages that can be generated by luabind, with a more +in-depth explanation.</p> +<ul> +<li><pre class="first literal-block"> +the attribute '<em>class-name.attribute-name</em>' is read only +</pre> +<p>There is no data member named <em>attribute-name</em> in the class <em>class-name</em>, +or there's no setter-function registered on that property name. See the +<a class="reference" href="#properties">Properties</a> section.</p> +</li> +<li><pre class="first literal-block"> +the attribute '<em>class-name.attribute-name</em>' is of type: (<em>class-name</em>) and does not match (<em>class_name</em>) +</pre> +<p>This error is generated if you try to assign an attribute with a value +of a type that cannot be converted to the attribute's type.</p> +</li> +<li><pre class="first literal-block"> +<em>class-name()</em> threw an exception, <em>class-name:function-name()</em> threw an exception +</pre> +<p>The class' constructor or member function threw an unknown exception. +Known exceptions are const char*, std::exception. See the +<a class="reference" href="#exceptions">exceptions</a> section.</p> +</li> +<li><pre class="first literal-block"> +no overload of '<em>class-name:function-name</em>' matched the arguments (<em>parameter-types</em>) +no match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>) +no constructor of <em>class-name</em> matched the arguments (<em>parameter-types</em>) +no operator <em>operator-name</em> matched the arguments (<em>parameter-types</em>) +</pre> +<p>No function/operator with the given name takes the parameters you gave +it. You have either misspelled the function name, or given it incorrect +parameters. This error is followed by a list of possible candidate +functions to help you figure out what parameter has the wrong type. If +the candidate list is empty there's no function at all with that name. +See the signature matching section.</p> +</li> +<li><pre class="first literal-block"> +call of overloaded '<em>class-name:function-name*(*parameter-types</em>)' is ambiguous +ambiguous match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>) +call of overloaded constructor '<em>class-name*(*parameter-types</em>)' is ambiguous +call of overloaded operator <em>operator-name</em> (<em>parameter-types</em>) is ambiguous +</pre> +<p>This means that the function/operator you are trying to call has at least +one other overload that matches the arguments just as good as the first +overload.</p> +</li> +<li><pre class="first literal-block"> +cannot derive from C++ class '<em>class-name</em>'. It does not have a wrapped type. +</pre> +</li> +</ul> +</div> +</div> <div class="section" id="build-options"> -<h2><a name="build-options">14.1 Build options</a></h2> +<h1><a name="build-options">15 Build options</a></h1> <p>There are a number of configuration options available when building luabind. It is very important that your project has the exact same configuration options as the ones given when the library was build! The exceptions are the @@ -2707,11 +2836,11 @@ </dd> <dt>LUA_API</dt> <dd>If you want to link dynamically against Lua, you can set this define to -the import-keyword on your compiler and platform. On windows in devstudio +the import-keyword on your compiler and platform. On windows in VisualStudio this should be <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> if you want to link against Lua as a dll.</dd> <dt>LUABIND_EXPORT, LUABIND_IMPORT</dt> -<dd>If you want to link against luabind as a dll (in devstudio), you can +<dd>If you want to link against luabind as a dll (in VisualStudio), you can define <tt class="docutils literal"><span class="pre">LUABIND_EXPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and <tt class="docutils literal"><span class="pre">LUABIND_IMPORT</span></tt> to <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> or <tt class="docutils literal"><span class="pre">__attribute__</span> <span class="pre">((visibility("default")))</span></tt> on GCC 4. @@ -2761,9 +2890,8 @@ build.</dd> </dl> </div> -</div> <div class="section" id="implementation-notes"> -<h1><a name="implementation-notes">15 Implementation notes</a></h1> +<h1><a name="implementation-notes">16 Implementation notes</a></h1> <p>The classes and objects are implemented as user data in Lua. To make sure that the user data really is the internal structure it is supposed to be, we tag their metatables. A user data who's metatable contains a boolean member named @@ -2791,58 +2919,6 @@ <p>Inside the luabind namespace, there's another namespace called detail. This namespace contains non-public classes and are not supposed to be used directly.</p> </div> -<div class="section" id="error-messages"> -<h1><a name="error-messages">16 Error messages</a></h1> -<ul> -<li><pre class="first literal-block"> -the attribute '<em>class-name.attribute-name</em>' is read only -</pre> -<p>There is no data member named <em>attribute-name</em> in the class <em>class-name</em>, -or there's no setter-function registered on that property name. See the -<a class="reference" href="#properties">Properties</a> section.</p> -</li> -<li><pre class="first literal-block"> -the attribute '<em>class-name.attribute-name</em>' is of type: (<em>class-name</em>) and does not match (<em>class_name</em>) -</pre> -<p>This error is generated if you try to assign an attribute with a value -of a type that cannot be converted to the attribute's type.</p> -</li> -<li><pre class="first literal-block"> -<em>class-name()</em> threw an exception, <em>class-name:function-name()</em> threw an exception -</pre> -<p>The class' constructor or member function threw an unknown exception. -Known exceptions are const char*, std::exception. See the -<a class="reference" href="#exceptions">exceptions</a> section.</p> -</li> -<li><pre class="first literal-block"> -no overload of '<em>class-name:function-name</em>' matched the arguments (<em>parameter-types</em>) -no match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>) -no constructor of <em>class-name</em> matched the arguments (<em>parameter-types</em>) -no operator <em>operator-name</em> matched the arguments (<em>parameter-types</em>) -</pre> -<p>No function/operator with the given name takes the parameters you gave -it. You have either misspelled the function name, or given it incorrect -parameters. This error is followed by a list of possible candidate -functions to help you figure out what parameter has the wrong type. If -the candidate list is empty there's no function at all with that name. -See the signature matching section.</p> -</li> -<li><pre class="first literal-block"> -call of overloaded '<em>class-name:function-name*(*parameter-types</em>)' is ambiguous -ambiguous match for function call '<em>function-name</em>' with the parameters (<em>parameter-types</em>) -call of overloaded constructor '<em>class-name*(*parameter-types</em>)' is ambiguous -call of overloaded operator <em>operator-name</em> (<em>parameter-types</em>) is ambiguous -</pre> -<p>This means that the function/operator you are trying to call has at least -one other overload that matches the arguments just as good as the first -overload.</p> -</li> -<li><pre class="first literal-block"> -cannot derive from C++ class '<em>class-name</em>'. It does not have a wrapped type. -</pre> -</li> -</ul> -</div> <div class="section" id="faq"> <h1><a name="faq">17 FAQ</a></h1> <dl class="docutils"> @@ -2860,9 +2936,6 @@ internal structure overflow. You should try to split that compilation unit up in smaller ones. See <a class="reference" href="#splitting-up-the-registration">Splitting up the registration</a> and <a class="reference" href="#splitting-class-registrations">Splitting class registrations</a>.</dd> -</dl> -<!-- the three entries above were removed, why? --> -<dl class="docutils"> <dt>What's wrong with precompiled headers in VC?</dt> <dd>Visual Studio doesn't like anonymous namespace's in its precompiled headers. If you encounter this problem you can disable precompiled @@ -2944,8 +3017,6 @@ <li>luabind does not support class hierarchies with virtual inheritance. Casts are done with static pointer offsets.</li> </ul> -<!-- remove? - Visual studio have problems selecting the correct overload of std::swap() -for luabind::object. --> </div> <div class="section" id="acknowledgments"> <h1><a name="acknowledgments">19 Acknowledgments</a></h1> Index: docs.rst =================================================================== RCS file: /cvsroot/luabind/luabind/luabind/doc/docs.rst,v retrieving revision 1.26.2.4 retrieving revision 1.26.2.5 diff -u -d -r1.26.2.4 -r1.26.2.5 --- docs.rst 10 Jan 2006 00:36:49 -0000 1.26.2.4 +++ docs.rst 11 Jan 2006 00:53:27 -0000 1.26.2.5 @@ -148,7 +148,7 @@ When building luabind you have several options that may streamline the library to better suit your needs. It is extremely important that your application has the same settings as the library was built with. The available options are -found in the `Configuration`_ section. +found in the `Build options`_ section. If you want to change the settings to differ from the default, it's recommended that you define the settings on the command line of all your files (in the @@ -441,7 +441,7 @@ If you want to use a custom error handler for the function call, see -``set_pcall_callback`` under Configuration_. +``set_pcall_callback`` under `pcall errorfunc`_. Using Lua threads ----------------- @@ -1060,15 +1060,15 @@ conversion from C++ value to Lua. If your ``luabind::object`` is a table you can access its members through the operator[] or the Iterators_. The value returned from the operator[] is a proxy object that can be used both for -reading and writing values into the table (using operator=). Note that it is -impossible to know if a Lua value is indexable or not (lua_gettable doesn't -fail, it succeeds or crashes). This means that if you're trying to index -something that cannot be indexed, you're on your own. Lua will call its -``panic()`` function. You can define your own panic function using -``lua_atpanic``. Unless you want to terminate the application, the best way -to continue from the panic function is to make sure lua is compiled as C++ -and throw an exception from the panic function. There are also free functions -that can be used for indexing the table, see `Related functions`_. +reading and writing values into the table (using operator=). + +Note that it is impossible to know if a Lua value is indexable or not +(``lua_gettable`` doesn't fail, it succeeds or crashes). This means that if +you're trying to index something that cannot be indexed, you're on your own. +Lua will call its ``panic()`` function. See `lua panic`_. + +There are also free functions that can be used for indexing the table, see +`Related functions`_. The constructor that takes a ``from_stack`` object is used when you want to initialize the object with a value from the lua stack. The ``from_stack`` @@ -1257,7 +1257,7 @@ The ``object_cast`` function casts the value of an object to a C++ value. You can supply a policy to handle the conversion from lua to C++. If the cast cannot be made a ``cast_failed`` exception will be thrown. If you have -defined LUABIND_NO_ERROR_CHECKING (see configuration) no checking will occur, +defined LUABIND_NO_ERROR_CHECKING (see `Build options`_) no checking will occur, and if the cast is invalid the application may very well crash. The nothrow versions will return an uninitialized ``boost::optional<T>`` object, to indicate that the cast could not be performed. @@ -2118,8 +2118,11 @@ } -Configuration -============= +Error Handling +============== + +pcall errorfunc +--------------- As mentioned in the `Lua documentation`_, it is possible to pass an error handler function to ``lua_pcall()``. Luabind makes use of @@ -2152,9 +2155,149 @@ .. _`pcall section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#3.15 .. _`the debug section of the lua manual`: http://www.lua.org/manual/5.0/manual.html#4 +file and line numbers +--------------------- + +If you want to add file name and line number to the error messages generated +by luabind you can define your own `pcall errorfunc`_. You may want to modify +this callback to better suit your needs, but the basic functionality could be +implemented like this:: + + int add_file_and_line(lua_State* L) + { + lua_Debug d; + lua_getstack(L, 1, &d); + lua_getinfo(L, "Sln", &d); + std::string err = lua_tostring(L, -1); + lua_pop(L, 1); + std::stringstream msg; + msg << d.short_src << ":" << d.currentline; + + if (d.name != 0) + { + msg << "(" << d.namewhat << " " << d.name << ")"; + } + msg << " " << err; + lua_pushstring(L, msg.str().c_str()); + return 1; + } + +For more information about what kind of information you can add to the error +message, see `the debug section of the lua manual`_. + +Note that the callback set by ``set_pcall_callback()`` will only be used when +luabind executes lua code. Anytime when you call ``lua_pcall`` yourself, you +have to supply your function if you want error messages translated. + +lua panic +--------- + +When lua encounters a fatal error caused by a bug from the C/C++ side, it will +call its internal panic function. This can happen, for example, when you call +``lua_gettable`` on a value that isn't a table. If you do the same thing from +within lua, it will of course just fail with an error message. + +The default panic function will ``exit()`` the application. If you want to +handle this case without terminating your application, you can define your own +panic function using ``lua_atpanic``. The best way to continue from the panic +function is to make sure lua is compiled as C++ and throw an exception from +the panic function. Throwing an exception instead of using ``setjmp`` and +``longjmp`` will make sure the stack is correctly unwound. + +For more information, see the `lua manual section 3.19`_. + +.. _`lua manual section 3.19`: http://www.lua.org/manual/5.0/manual.html#3.19 + +msvc exceptions +--------------- + +Since lua is generally built as a C library, any callbacks called from lua +cannot under any circumstance throw an exception. Because of that, luabind has +to catch all exceptions and translate them into proper lua errors (by calling +``lua_error()``). This means we have a ``catch(...) {}`` in there. + +In VisualStudio, ``catch (...)`` will not only catch C++ exceptions, it will +also catch hardware exceptions like Segmentation fault. This means that if +your function, that gets called from luabind, makes an invalid memory +adressing, you won't notice it. All that will happen is that lua will return +an error message saying "unknown exception". + +To remedy this, you can create your own *exception translator*:: + + void straight_to_debugger(unsigned int, _EXCEPTION_POINTERS*) + { throw; } + + #ifdef _MSC_VER + ::_set_se_translator(straight_to_debugger); + #endif + +This will make hardware exceptions, like segmentation fault, to actually get +caught by the debugger. + + +Error messages +-------------- + +These are the error messages that can be generated by luabind, with a more +in-depth explanation. + +- .. parsed-literal:: + + the attribute '*class-name.attribute-name*' is read only + + There is no data member named *attribute-name* in the class *class-name*, + or there's no setter-function registered on that property name. See the + Properties_ section. + +- .. parsed-literal:: + + the attribute '*class-name.attribute-name*' is of type: (*class-name*) and does not match (*class_name*) + + This error is generated if you try to assign an attribute with a value + of a type that cannot be converted to the attribute's type. + + +- .. parsed-literal:: + + *class-name()* threw an exception, *class-name:function-name()* threw an exception + + The class' constructor or member function threw an unknown exception. + Known exceptions are const char*, std::exception. See the + `exceptions`_ section. + +- .. parsed-literal:: + + no overload of '*class-name:function-name*' matched the arguments (*parameter-types*) + no match for function call '*function-name*' with the parameters (*parameter-types*) + no constructor of *class-name* matched the arguments (*parameter-types*) + no operator *operator-name* matched the arguments (*parameter-types*) + + No function/operator with the given name takes the parameters you gave + it. You have either misspelled the function name, or given it incorrect + parameters. This error is followed by a list of possible candidate + functions to help you figure out what parameter has the wrong type. If + the candidate list is empty there's no function at all with that name. + See the signature matching section. + +- .. parsed-literal:: + + call of overloaded '*class-name:function-name*(*parameter-types*)' is ambiguous + ambiguous match for function call '*function-name*' with the parameters (*parameter-types*) + call of overloaded constructor '*class-name*(*parameter-types*)' is ambiguous + call of overloaded operator *operator-name* (*parameter-types*) is ambiguous + + This means that the function/operator you are trying to call has at least + one other overload that matches the arguments just as good as the first + overload. + +- .. parsed-literal:: + + cannot derive from C++ class '*class-name*'. It does not have a wrapped type. + + Build options -------------- +============= There are a number of configuration options available when building luabind. It is very important that your project has the exact same configuration @@ -2210,12 +2353,12 @@ LUA_API If you want to link dynamically against Lua, you can set this define to - the import-keyword on your compiler and platform. On windows in devstudio + the import-keyword on your compiler and platform. On windows in VisualStudio this should be ``__declspec(dllimport)`` if you want to link against Lua as a dll. LUABIND_EXPORT, LUABIND_IMPORT - If you want to link against luabind as a dll (in devstudio), you can + If you want to link against luabind as a dll (in VisualStudio), you can define ``LUABIND_EXPORT`` to ``__declspec(dllexport)`` and ``LUABIND_IMPORT`` to ``__declspec(dllimport)`` or ``__attribute__ ((visibility("default")))`` on GCC 4. @@ -2303,63 +2446,6 @@ namespace contains non-public classes and are not supposed to be used directly. -Error messages -============== - -- .. parsed-literal:: - - the attribute '*class-name.attribute-name*' is read only - - There is no data member named *attribute-name* in the class *class-name*, - or there's no setter-function registered on that property name. See the - Properties_ section. - -- .. parsed-literal:: - - the attribute '*class-name.attribute-name*' is of type: (*class-name*) and does not match (*class_name*) - - This error is generated if you try to assign an attribute with a value - of a type that cannot be converted to the attribute's type. - - -- .. parsed-literal:: - - *class-name()* threw an exception, *class-name:function-name()* threw an exception - - The class' constructor or member function threw an unknown exception. - Known exceptions are const char*, std::exception. See the - `exceptions`_ section. - -- .. parsed-literal:: - - no overload of '*class-name:function-name*' matched the arguments (*parameter-types*) - no match for function call '*function-name*' with the parameters (*parameter-types*) - no constructor of *class-name* matched the arguments (*parameter-types*) - no operator *operator-name* matched the arguments (*parameter-types*) - - No function/operator with the given name takes the parameters you gave - it. You have either misspelled the function name, or given it incorrect - parameters. This error is followed by a list of possible candidate - functions to help you figure out what parameter has the wrong type. If - the candidate list is empty there's no function at all with that name. - See the signature matching section. - -- .. parsed-literal:: - - call of overloaded '*class-name:function-name*(*parameter-types*)' is ambiguous - ambiguous match for function call '*function-name*' with the parameters (*parameter-types*) - call of overloaded constructor '*class-name*(*parameter-types*)' is ambiguous - call of overloaded operator *operator-name* (*parameter-types*) is ambiguous - - This means that the function/operator you are trying to call has at least - one other overload that matches the arguments just as good as the first - overload. - -- .. parsed-literal:: - - cannot derive from C++ class '*class-name*'. It does not have a wrapped type. - - FAQ === @@ -2380,8 +2466,6 @@ unit up in smaller ones. See `Splitting up the registration`_ and `Splitting class registrations`_. -.. the three entries above were removed, why? - What's wrong with precompiled headers in VC? Visual Studio doesn't like anonymous namespace's in its precompiled headers. If you encounter this problem you can disable precompiled @@ -2470,9 +2554,6 @@ - luabind does not support class hierarchies with virtual inheritance. Casts are done with static pointer offsets. -.. remove? - Visual studio have problems selecting the correct overload of std::swap() - for luabind::object. - Acknowledgments =============== |
