webmcp

changeset 519:55a43a67e9ad

Further improvements to the documentation of the environment system
author jbe
date Mon Aug 21 15:01:21 2017 +0200 (2017-08-21)
parents 02d505b6090c
children ec1cca939315
files doc/autodoc-header.htmlpart
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Mon Aug 21 14:50:27 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Mon Aug 21 15:01:21 2017 +0200
     1.3 @@ -309,11 +309,19 @@
     1.4        To avoid accidental programming errors, WebMCP forbids setting of global variables by default. This is overridden by using the prefix "<tt>_G.</tt>" (<a href="#_G">see reference</a>) when setting the variable, e.g. <tt>_G.myvar = 7</tt>, or by setting the variable in a file with the same name of the global varaible (but suffixed with "<tt>.lua</tt>") in the <tt>env/</tt> directory of the framework or application. Note, however, that the lifetime of global variables is not predictable as it depends on process recycling of the Moonbridge webserver (one fork will handle more than one request) and because there may be multiple forks of the Lua machine which all have their own global variable space (there is usually more than one fork).
     1.5      </p>
     1.6      <p>
     1.7 +      If an application needs to store request related data, the global table <a href="#app"><tt>app</tt></a> should be used (e.g. <tt>app.myvar = true</tt> instead of <tt>_G.myvar = true</tt>). The <tt>app</tt> table gets automatically initialized (i.e. emptied) for each request.
     1.8 +    </p>
     1.9 +    <p>
    1.10        Global variables are still useful when providing access to libraries, for example. WebMCP automatically loads certain libraries and functions though an autoloader mechanism. On read-accessing any unknown variable, WebMCP will search the framework's and application's <tt>env/</tt> directories for an appropriate file (e.g. "<tt>my_func.lua</tt> if you invoke "<tt>my_func()</tt>") or a matching directory (e.g. "<tt>my_module/</tt> if you access "<tt>my_module.my_func()</tt>). In case of an existing directory in <tt>env/</tt>, an empty table with autoloading capabilities is automatically created as global variable with the name of the directory. The autoloading mechanism allows directories to contain further files which can be used to initialize variables within that table when accessed. Directories can also contain a special file called "<tt>__init.lua</tt>" that always gets executed when the table is accessed for the first time. The <tt>env/</tt> root directory can also contain a file ("<tt>env/__init__.lua</tt>") which gets executed before any configuration is loaded.
    1.11      </p>
    1.12      <p>
    1.13 -      If an application needs to store request related data, the global table <a href="#app"><tt>app</tt></a> should be used. This table gets automatically initialized (i.e. emptied) for each request.
    1.14 +      A good place to store utility functions is a global table called <tt>util</tt>. This table will be automatically accessible if you create a <tt>env/util/</tt> directory in your WebMCP application. To provide a function <tt>util.myfunc(...)</tt> simply create a file <tt>env/util/myfunc.lua</tt>, with the following function definition:
    1.15      </p>
    1.16 +    <pre>
    1.17 +-- filename: env/util/myfunc.lua
    1.18 +function util.myfunc()
    1.19 +  slot.put_into("hello", "Hello World!")
    1.20 +end</pre>
    1.21      <h2>Directory structure of a WebMCP application</h2>
    1.22      <p>
    1.23        Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
    1.24 @@ -385,9 +393,9 @@
    1.25              <tt>env/</tt>
    1.26              <ul>
    1.27                <li><tt>__init.lua</tt></li>
    1.28 -              <li><i>global_variable_name</i><tt>.lua</tt></li>
    1.29 +              <li><i>some_global_variable_name</i><tt>.lua</tt></li>
    1.30                <li>
    1.31 -                <i>global_variable_name</i><tt>/</tt>
    1.32 +                <i>another_global_variable_name</i><tt>/</tt>
    1.33                  <ul>
    1.34                    <li><tt>__init.lua</tt></li>
    1.35                    <li><i>attribute_name</i><tt>.lua</tt></li>

Impressum / About Us