docs: Update in order to show latest changes to advanced stack interaction

docs/mkdocs/advanced.md → docs/mkdocs/advanced-stack-interaction.md

@@ -3,10 +3,11 @@ Instead of extracting every Lua value seperately and pushing the result of your
 onto the stack again, you can use one of the following functions to make this process easier for
 you.
 
-## Invoke a Callable with Lua values
+## Manual stack layout
 The function [direct][luwra-direct] lets you specify a *stack signature* in order to extract the
 values and invoke a `Callable` with them.
 
+### Without returning to Lua
 Consider the following:
 
 ```c++
@@ -19,8 +20,16 @@ It could be rewritting like this:
 string result = luwra::direct<string(string, int)>(lua, n, foo);
 ```
 
-**Note:** The result of `foo` is not pushed onto the stack. Except for the extraction of Lua values,
-everything happens on the C++ side.
+This will read all the required values off the stack, invoke `foo` with them and return its value to
+you.
+
+### Returning values to the stack
+An alternative to [direct][luwra-direct] is [map][luwra-map]. It does exactly the same, with the
+exception that it returns the resulting value back to the Lua stack.
+
+```c++
+luwra::map<string(string, int)>(lua, n, foo);
+```
 
 ## Invoke a function with Lua values
 [apply][luwra-apply] is similiar to [direct][luwra-direct]. It differs from `direct` by providing
@@ -43,5 +52,14 @@ One would use `foo` like this:
 string result = luwra::apply(lua, n, foo);
 ```
 
+It also works with Lambdas, because they are function objects aswell.
+
+```c++
+string result = luwra::apply(lua, n, [](string a, int b) -> string {
+	// Magic
+});
+```
+
 [luwra-direct]: /reference/namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a
 [luwra-apply]: /reference/namespaceluwra.html#a839077ddd9c3d0565a40c574bc8e9555
+[luwra-map]: /reference/namespaceluwra.html#a9f24fc70cb48531cf1e3da6a3a741971

docs/output/advanced/index.html → docs/output/advanced-stack-interaction/index.html

@@ -24,8 +24,8 @@
   <script>
     // Current page data
     var mkdocs_page_name = "Advanced Stack Interaction";
-    var mkdocs_page_input_path = "advanced.md";
-    var mkdocs_page_url = "/advanced/";
+    var mkdocs_page_input_path = "advanced-stack-interaction.md";
+    var mkdocs_page_url = "/advanced-stack-interaction/";
   </script>
   
   <script src="../js/jquery-2.1.1.min.js"></script>
@@ -76,7 +76,7 @@
             
                 <li class="toctree-l3"><a href="#advanced-stack-interaction">Advanced stack interaction</a></li>
                 
-                    <li><a class="toctree-l4" href="#invoke-a-callable-with-lua-values">Invoke a Callable with Lua values</a></li>
+                    <li><a class="toctree-l4" href="#manual-stack-layout">Manual stack layout</a></li>
                 
                     <li><a class="toctree-l4" href="#invoke-a-function-with-lua-values">Invoke a function with Lua values</a></li>
                 
@@ -140,9 +140,10 @@
 <p>Instead of extracting every Lua value seperately and pushing the result of your C++ function back
 onto the stack again, you can use one of the following functions to make this process easier for
 you.</p>
-<h2 id="invoke-a-callable-with-lua-values">Invoke a Callable with Lua values</h2>
+<h2 id="manual-stack-layout">Manual stack layout</h2>
 <p>The function <a href="../reference/namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> lets you specify a <em>stack signature</em> in order to extract the
 values and invoke a <code>Callable</code> with them.</p>
+<h3 id="without-returning-to-lua">Without returning to Lua</h3>
 <p>Consider the following:</p>
 <pre><code class="c++">string result = foo(luwra::read&lt;string&gt;(lua, n), luwra::read&lt;int&gt;(lua, n + 1));
 </code></pre>
@@ -151,8 +152,14 @@ values and invoke a <code>Callable</code> with them.</p>
 <pre><code class="c++">string result = luwra::direct&lt;string(string, int)&gt;(lua, n, foo);
 </code></pre>
 
-<p><strong>Note:</strong> The result of <code>foo</code> is not pushed onto the stack. Except for the extraction of Lua values,
-everything happens on the C++ side.</p>
+<p>This will read all the required values off the stack, invoke <code>foo</code> with them and return its value to
+you.</p>
+<h3 id="returning-values-to-the-stack">Returning values to the stack</h3>
+<p>An alternative to <a href="../reference/namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> is <a href="../reference/namespaceluwra.html#a9f24fc70cb48531cf1e3da6a3a741971">map</a>. It does exactly the same, with the
+exception that it returns the resulting value back to the Lua stack.</p>
+<pre><code class="c++">luwra::map&lt;string(string, int)&gt;(lua, n, foo);
+</code></pre>
+
 <h2 id="invoke-a-function-with-lua-values">Invoke a function with Lua values</h2>
 <p><a href="../reference/namespaceluwra.html#a839077ddd9c3d0565a40c574bc8e9555">apply</a> is similiar to <a href="../reference/namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a>. It differs from <code>direct</code> by providing
 specific overloads for function pointers and function objects. Although <code>direct</code> works with function pointers
@@ -167,6 +174,12 @@ function&lt;string(string, int)&gt; foo = /* magic */;
 
 <p>One would use <code>foo</code> like this:</p>
 <pre><code class="c++">string result = luwra::apply(lua, n, foo);
+</code></pre>
+
+<p>It also works with Lambdas, because they are function objects aswell.</p>
+<pre><code class="c++">string result = luwra::apply(lua, n, [](string a, int b) -&gt; string {
+    // Magic
+});
 </code></pre>
               
             </div>

docs/output/index.html

@@ -83,7 +83,7 @@
           
             <li>
     <li class="toctree-l1 ">
-        <a class="" href="advanced/">Advanced Stack Interaction</a>
+        <a class="" href="advanced-stack-interaction/">Advanced Stack Interaction</a>
         
     </li>
 <li>
@@ -200,5 +200,5 @@ means that all functions and classes can operate on <a href="http://www.lua.org/
 
 <!--
 MkDocs version : 0.15.3
-Build Date UTC : 2016-05-21 18:56:55.799005
+Build Date UTC : 2016-05-21 19:54:12.975518
 -->

docs/output/reference/namespaceluwra.html

@@ -169,12 +169,12 @@ Functions</h2></td></tr>
 <tr class="memitem:ae5412e502815db7aa2a10e6c84394457"><td class="memTemplParams" colspan="2">template&lt;typename R , typename... A&gt; </td></tr>
 <tr class="memitem:ae5412e502815db7aa2a10e6c84394457"><td class="memTemplItemLeft" align="right" valign="top">static R&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#ae5412e502815db7aa2a10e6c84394457">apply</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, R(*fun)(A...))</td></tr>
 <tr class="separator:ae5412e502815db7aa2a10e6c84394457"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:a983092513bfded87189613f8dc27ebbe"><td class="memTemplParams" colspan="2">template&lt;typename R , typename... A&gt; </td></tr>
-<tr class="memitem:a983092513bfded87189613f8dc27ebbe"><td class="memTemplItemLeft" align="right" valign="top">static R&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#a983092513bfded87189613f8dc27ebbe">apply</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, int pos, const std::function&lt; R(A...)&gt; &amp;fun)</td></tr>
-<tr class="separator:a983092513bfded87189613f8dc27ebbe"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:a9a121cbb3ba2b4fb7ee8b2c12472ab51"><td class="memTemplParams" colspan="2">template&lt;typename R , typename... A&gt; </td></tr>
-<tr class="memitem:a9a121cbb3ba2b4fb7ee8b2c12472ab51"><td class="memTemplItemLeft" align="right" valign="top">static R&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#a9a121cbb3ba2b4fb7ee8b2c12472ab51">apply</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, const std::function&lt; R(A...)&gt; &amp;fun)</td></tr>
-<tr class="separator:a9a121cbb3ba2b4fb7ee8b2c12472ab51"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="memitem:a8d726851173a305be65e763d989d0756"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
+<tr class="memitem:a8d726851173a305be65e763d989d0756"><td class="memTemplItemLeft" align="right" valign="top">static internal::FunctionObjectReturnType&lt; T &gt;&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#a8d726851173a305be65e763d989d0756">apply</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, int pos, const T &amp;obj)</td></tr>
+<tr class="separator:a8d726851173a305be65e763d989d0756"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="memitem:a816acd63f544fe4418ef4ac8e9d968e7"><td class="memTemplParams" colspan="2">template&lt;typename T &gt; </td></tr>
+<tr class="memitem:a816acd63f544fe4418ef4ac8e9d968e7"><td class="memTemplItemLeft" align="right" valign="top">static internal::FunctionObjectReturnType&lt; T &gt;&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#a816acd63f544fe4418ef4ac8e9d968e7">apply</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, const T &amp;obj)</td></tr>
+<tr class="separator:a816acd63f544fe4418ef4ac8e9d968e7"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a9f24fc70cb48531cf1e3da6a3a741971"><td class="memTemplParams" colspan="2">template&lt;typename S , typename F , typename... A&gt; </td></tr>
 <tr class="memitem:a9f24fc70cb48531cf1e3da6a3a741971"><td class="memTemplItemLeft" align="right" valign="top">static size_t&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="namespaceluwra.html#a9f24fc70cb48531cf1e3da6a3a741971">map</a> (<a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *state, int pos, F &amp;&amp;hook, A &amp;&amp;...args)</td></tr>
 <tr class="separator:a9f24fc70cb48531cf1e3da6a3a741971"><td class="memSeparator" colspan="2">&#160;</td></tr>
@@ -304,7 +304,7 @@ template&lt;typename R , typename... A&gt; </div>
   </tr>
 </table>
 </div><div class="memdoc">
-<p>Synonym for <a class="el" href="namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> with a function pointer which lets you omit all template parameters. The stack layout will be inferred using the signature of the given function pointer. </p>
+<p>A version of <a class="el" href="namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> which is specialized for function pointers; therefore allows you to omit the template parameters since the compiler can infer its parameter and return types. </p>
 
 </div>
 </div>
@@ -345,17 +345,17 @@ template&lt;typename R , typename... A&gt; </div>
 
 </div>
 </div>
-<a class="anchor" id="a983092513bfded87189613f8dc27ebbe"></a>
+<a class="anchor" id="a8d726851173a305be65e763d989d0756"></a>
 <div class="memitem">
 <div class="memproto">
 <div class="memtemplate">
-template&lt;typename R , typename... A&gt; </div>
+template&lt;typename T &gt; </div>
 <table class="mlabels">
   <tr>
   <td class="mlabels-left">
       <table class="memname">
         <tr>
-          <td class="memname">static R luwra::apply </td>
+          <td class="memname">static internal::FunctionObjectReturnType&lt;T&gt; luwra::apply </td>
           <td>(</td>
           <td class="paramtype"><a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *&#160;</td>
           <td class="paramname"><em>state</em>, </td>
@@ -369,8 +369,8 @@ template&lt;typename R , typename... A&gt; </div>
         <tr>
           <td class="paramkey"></td>
           <td></td>
-          <td class="paramtype">const std::function&lt; R(A...)&gt; &amp;&#160;</td>
-          <td class="paramname"><em>fun</em>&#160;</td>
+          <td class="paramtype">const T &amp;&#160;</td>
+          <td class="paramname"><em>obj</em>&#160;</td>
         </tr>
         <tr>
           <td></td>
@@ -384,21 +384,21 @@ template&lt;typename R , typename... A&gt; </div>
   </tr>
 </table>
 </div><div class="memdoc">
-<p>Synonym for <a class="el" href="namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> with a function object which lets you omit all template parameters. The stack layout will be inferred using the template parameter to your <code>std::function</code> object. </p>
+<p>A version of <a class="el" href="namespaceluwra.html#aa20e363f38b3ae5a168cf40365f5646a">direct</a> which tries to infer the stack layout from the given <code>Callable</code>. </p>
 
 </div>
 </div>
-<a class="anchor" id="a9a121cbb3ba2b4fb7ee8b2c12472ab51"></a>
+<a class="anchor" id="a816acd63f544fe4418ef4ac8e9d968e7"></a>
 <div class="memitem">
 <div class="memproto">
 <div class="memtemplate">
-template&lt;typename R , typename... A&gt; </div>
+template&lt;typename T &gt; </div>
 <table class="mlabels">
   <tr>
   <td class="mlabels-left">
       <table class="memname">
         <tr>
-          <td class="memname">static R luwra::apply </td>
+          <td class="memname">static internal::FunctionObjectReturnType&lt;T&gt; luwra::apply </td>
           <td>(</td>
           <td class="paramtype"><a class="el" href="namespaceluwra.html#a2c037b44385367826eb4e931b5b8197d">State</a> *&#160;</td>
           <td class="paramname"><em>state</em>, </td>
@@ -406,8 +406,8 @@ template&lt;typename R , typename... A&gt; </div>
         <tr>
           <td class="paramkey"></td>
           <td></td>
-          <td class="paramtype">const std::function&lt; R(A...)&gt; &amp;&#160;</td>
-          <td class="paramname"><em>fun</em>&#160;</td>
+          <td class="paramtype">const T &amp;&#160;</td>
+          <td class="paramname"><em>obj</em>&#160;</td>
         </tr>
         <tr>
           <td></td>
@@ -421,7 +421,7 @@ template&lt;typename R , typename... A&gt; </div>
   </tr>
 </table>
 </div><div class="memdoc">
-<p>Same as <code>apply(state, 1, fun)</code>. </p>
+<p>Same as <code>apply(state, 1, obj)</code>. </p>
 
 </div>
 </div>

docs/output/search.html

@@ -66,7 +66,7 @@
           
             <li>
     <li class="toctree-l1 ">
-        <a class="" href="advanced/">Advanced Stack Interaction</a>
+        <a class="" href="advanced-stack-interaction/">Advanced Stack Interaction</a>
         
     </li>
 <li>

docs/output/sitemap.xml

@@ -19,7 +19,7 @@
 
     
     <url>
-     <loc>None/advanced/</loc>
+     <loc>None/advanced-stack-interaction/</loc>
      <lastmod>2016-05-21</lastmod>
      <changefreq>daily</changefreq>
     </url>

docs/output/stack-interaction/index.html

@@ -85,7 +85,7 @@
           
             <li>
     <li class="toctree-l1 ">
-        <a class="" href="../advanced/">Advanced Stack Interaction</a>
+        <a class="" href="../advanced-stack-interaction/">Advanced Stack Interaction</a>
         
     </li>
 <li>
@@ -414,7 +414,7 @@ information.</p>
   
     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
       
-        <a href="../advanced/" class="btn btn-neutral float-right" title="Advanced Stack Interaction">Next <span class="icon icon-circle-arrow-right"></span></a>
+        <a href="../advanced-stack-interaction/" class="btn btn-neutral float-right" title="Advanced Stack Interaction">Next <span class="icon icon-circle-arrow-right"></span></a>
       
       
         <a href=".." class="btn btn-neutral" title="Home"><span class="icon icon-circle-arrow-left"></span> Previous</a>
@@ -448,7 +448,7 @@ information.</p>
         <span><a href=".." style="color: #fcfcfc;">&laquo; Previous</a></span>
       
       
-        <span style="margin-left: 15px"><a href="../advanced/" style="color: #fcfcfc">Next &raquo;</a></span>
+        <span style="margin-left: 15px"><a href="../advanced-stack-interaction/" style="color: #fcfcfc">Next &raquo;</a></span>
       
     </span>
 </div>

docs/output/user-types/index.html

@@ -70,7 +70,7 @@
           
             <li>
     <li class="toctree-l1 ">
-        <a class="" href="../advanced/">Advanced Stack Interaction</a>
+        <a class="" href="../advanced-stack-interaction/">Advanced Stack Interaction</a>
         
     </li>
 <li>

docs/output/wrapping/index.html

@@ -70,7 +70,7 @@
           
             <li>
     <li class="toctree-l1 ">
-        <a class="" href="../advanced/">Advanced Stack Interaction</a>
+        <a class="" href="../advanced-stack-interaction/">Advanced Stack Interaction</a>
         
     </li>
 <li>
@@ -239,7 +239,7 @@ scale(my_point, 2)
         <a href="../user-types/" class="btn btn-neutral float-right" title="User Types">Next <span class="icon icon-circle-arrow-right"></span></a>
       
       
-        <a href="../advanced/" class="btn btn-neutral" title="Advanced Stack Interaction"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+        <a href="../advanced-stack-interaction/" class="btn btn-neutral" title="Advanced Stack Interaction"><span class="icon icon-circle-arrow-left"></span> Previous</a>
       
     </div>
   
@@ -267,7 +267,7 @@ scale(my_point, 2)
           <a href="https://github.com/vapourismo/luwra" class="icon icon-github" style="float: left; color: #fcfcfc"> GitHub</a>
       
       
-        <span><a href="../advanced/" style="color: #fcfcfc;">&laquo; Previous</a></span>
+        <span><a href="../advanced-stack-interaction/" style="color: #fcfcfc;">&laquo; Previous</a></span>
       
       
         <span style="margin-left: 15px"><a href="../user-types/" style="color: #fcfcfc">Next &raquo;</a></span>

mkdocs.yml

@@ -4,7 +4,7 @@ repo_url: https://github.com/vapourismo/luwra
 pages:
   - 'Home': index.md
   - 'Stack Interaction': stack-interaction.md
-  - 'Advanced Stack Interaction': advanced.md
+  - 'Advanced Stack Interaction': advanced-stack-interaction.md
   - 'Wrapping': wrapping.md
   - 'User Types': user-types.md
 theme: readthedocs