Commits

Harald Klimach committed 2176116

Updated to latest interface changes

Comments (0)

Files changed (2)

CompilerSupport.wiki

 
 === PGI ===
 
-Known to work in version 10.9.
+Does not correctly resolve the generic aot_get_val interface!
 [[CompilerSupport]].
 
 **An example, showing the usage of this library in a Fortran application is
-given in <<file test/aotus_test.f90>>.**
+given in <<file sample/aotus_sample.f90>>, the corresponding Lua script is given
+in <<file sample/config.lua>>**
 
 === Reading a Lua Script ===
 
 that by opening and processing a Lua script with **open_config**:
 {{{
 #!fortran
-call open_config(conf, filename)
+call open_config(L, filename)
 }}}
 
 In the end, after getting all configuration values, close it again with
 **close_config**:
 {{{
 #!fortran
-call close_config(conf)
+call close_config(L)
 }}}
 
-=== Global Variables ===
+=== Retrieving Variables from the Script ===
 
-After the Lua context is available, gobally declared variables can be retrieved
-by:
+From configuration files you usually want to obtain some parameters to steer
+your application. The most important interface for this functionality is
+**aot_get_val**, it is a generic interface to different functions, which allow
+you to obtain global values, values within tables and complete vectors as
+tables. Sometimes, especially in the context of evaluating functions, you might
+also need **aot_top_get_val**, which always tries to obtain the topmost value
+on the Lua stack.
+
+The **aot_get_val** interface is provided by the //aotus_module// and
+generically looks like this:
 {{{
 #!fortran
-call get_config_val(conf, var, conf_val, errCode, default)
+call aot_get_val(val, errCode, L, key, default)
 }}}
 Where:
-* **conf**: is the Lua context of type flu_state
-* **var**: is a string identifying the variable you want to retrieve
-* **conf_val**: is the variable the value should be stored in, all intrinsic
+* **val**: is the variable the value should be stored in, all intrinsic
 data types should be supported, reals with kind single and double precision
 * **errCode**: Returns an error code with various bits set for different errors,
 that might happen, while retrieving the variable.
 requested data type
 ** For example you can check for a fatal error by using "btest(errCode,
 aoterr_fatal)"
+* **L**: is the Lua context of type flu_state
+* **key**: is a string identifying the variable you want to retrieve
 * //optional// **default**: A default value to put into the variable, if the
 variable is not provided in the Lua script
 
+In general we get the following shape for the interface:
+{{{
+#!fortran
+call aot_{top}_get_val(<outputs>, <id>, default)
+}}}
+
+Where //outputs// is: **val** and **errCode**, and //id// is at least the Lua
+context (**L**) for the //aot_top// variant. For global variables there has
+to be a **key** in the //id// and for tables there has to be a **thandle**.
+In tables the **key** might be replaced by a **pos** argument.
+
 === Tables ===
 
 The interface to work with tables is trying to resemble IO, thus you could think
 of a table as a file, which you can open and read values out of it by
 referencing its unit (handle).
+Opening and closing tables is provided by the //aot_table_module//.
 
 To work with a table, you first need to get an handle to identify the table.
 For globally defined tables this can be done by using
 After you have the handle to the table, you can access its components with
 {{{
 #!fortran
-call get_table_val(conf, thandle, tab_val, ErrCode, var, pos, default)
+call aot_table_get_val(val, errCode, L, thandle, key, pos, default)
 }}}
 
 Which is essentially the same interface as for get_config_val, except for the
-optional argument **pos**, by which the unnamed entries in the tabe are
-accessible by their position.
-Both **pos** and **var** are optional, providing the ability to access the
+optional argument **pos**, by which the unnamed entries in the table are
+accessible by their position and the handle to the table, where the component
+is to be looked up.
+Both **pos** and **key** are optional, providing the ability to access the
 variables either purely by their order, or their name.
+If both are provided, the key takes precedence.
+The handling of positional or named addressing is a little bit similar to
+the Fortran convention, that is, as soon as there is a named component in the
+table, all following components should also be named. Positional references are
+only valid up to this position.
 
 After all values are read from the table, the table should be closed again by
 calling
 After the function is executed, the results can be read, using:
 {{{
 #!fortran
-call get_top_val(conf, top_val, ErrCode, default)
+call aot_top_get_val(val, errCode, L, default)
 }}}
 Where:
-* **conf**: Lua context
-* **top_val**: value to return
+* **val**: value to return
 * **ErrCode**: an error code, if something went wrong
+* **L**: Lua context
 * //optional// **default**: a default value to use, if no value can be retrieved
 
 You will get the results in reversed order, if there are multiple results.
 
 {{{
 #!fortran
-call get_config_val(conf, var, conf_val, errCode, default)
+call aot_get_val(val, errCode, L, key, default)
 }}}
 Where:
-* **conf**: is the Lua context of type flu_state
-* **var**: is a string identifying the variable you want to retrieve
-* **conf_val(:)**: is the array the vector should be stored in
+* **L**: is the Lua context of type flu_state
+* **key**: is a string identifying the variable you want to retrieve
+* **val(:)**: is the array the vector should be stored in
 * **errCode(:)**: Returns an error code with various bits set for different errors,
 that might happen, while retrieving each component of the vector.
 They can be checked by btest, and the different error codes are encoded in