changeset 518:02d505b6090c

Added section about global variables and the environment to WebMCP's documentation
author jbe
date Mon Aug 21 14:50:27 2017 +0200 (2017-08-21)
parents 39ee5d9a90a0
children 55a43a67e9ad
files doc/autodoc-header.htmlpart
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Mon Aug 21 14:37:35 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Mon Aug 21 14:50:27 2017 +0200
     1.3 @@ -304,6 +304,16 @@
     1.4      <p>
     1.5        Such translation files can be automatically created with the <tt>langtool.lua</tt> program, found in the framework's <tt>bin/</tt> directory.
     1.6      </p>
     1.7 +    <h2>Global variables and the environment</h2>
     1.8 +    <p>
     1.9 +      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.10 +    </p>
    1.11 +    <p>
    1.12 +      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.13 +    </p>
    1.14 +    <p>
    1.15 +      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.16 +    </p>
    1.17      <h2>Directory structure of a WebMCP application</h2>
    1.18      <p>
    1.19        Summarizing information from the previous section, we get the following directory structure for a WebMCP application:
    1.20 @@ -372,6 +382,23 @@
    1.21              </ul>
    1.22            </li>
    1.23            <li>
    1.24 +            <tt>env/</tt>
    1.25 +            <ul>
    1.26 +              <li><tt>__init.lua</tt></li>
    1.27 +              <li><i>global_variable_name</i><tt>.lua</tt></li>
    1.28 +              <li>
    1.29 +                <i>global_variable_name</i><tt>/</tt>
    1.30 +                <ul>
    1.31 +                  <li><tt>__init.lua</tt></li>
    1.32 +                  <li><i>attribute_name</i><tt>.lua</tt></li>
    1.33 +                  <li>
    1.34 +                    <i>another_attibute_name</i><tt>/</tt>
    1.35 +                    <ul><li>&hellip;</li></ul>
    1.36 +                  </li>
    1.37 +                </ul>
    1.38 +              </li>
    1.39 +            </ul>
    1.40 +          <li>
    1.41              <tt>locale/</tt> (translation files used by the <a href="#_">underscore function</a>")
    1.42              <ul>
    1.43                <li>

Impressum / About Us