Commits

Harald Klimach  committed 0d05566

More details on the aotus interface and typical usage

  • Participants
  • Parent commits 08e91bc

Comments (0)

Files changed (1)

 * aot_fun_module: provides some convenience functions to work with Lua functions in Fortran
 * aotus_module: provides the high end level to easily retrieve data from a Lua script
 
+=== Reading a Lua Script ===
+
+You need a handle for the Lua context of type *flu_state*, and you can get that by opening and processing a Lua script with *open_config*:
+{{{
+#!fortran
+call open_config(conf, filename)
+}}}
+
+In the end, after getting all configuration values, close it again with *close_config*:
+{{{
+#!fortran
+call close_config(conf)
+}}}
+
+=== Global Variables ===
+
+After the Lua context is available, gobally declared variables can be retrieved by:
+{{{
+#!fortran
+call get_config_val(conf, var, conf_val, errCode, 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 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. They can be checked by ibset, and the different error codes are encoded in parameters:
+** aoterr_fatal: Something went irrecoverably wrong
+** aoterr_nonExistent: The requested variable is not set in the Lua script
+** aoterr_wrongType: The requested variable in the Lua script  does not meet the requested data type
+** For example you can check for a fatal error by using "ibset(errCode, aoterr_fatal)
+* //optional// **default**: A default value to put into the variable, if the variable is not provided in the Lua script
+
+h2. 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).
+
+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
+{{{
+#!fortran
+call aot_table_open(L, thandle, key)
+}}}
+Where:
+* **L**: is the Lua context of type flu_state
+* **thandle**: a handle to reference this table
+* **key**: is the name of the globally defined table to retrieve
+
+For a table within an already opened table use:
+{{{
+#!fortran
+call aot_table_open(L, parent, thandle, key, pos)
+}}}
+Where the additional arguments are:
+* **parent**: the handle of the table, this table should be looked up in
+* **pos**: Referring to the table to retrive by position instead of name
+
+The handle will be 0, if the variable does not exist, or is not a table.
+After you have the handle to the table you can its components with
+{{{
+#!fortran
+call get_table_val(conf, thandle, tab_val, ErrCode, var, 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 variables either purely by their order, or their name.
+
+After all values are read from the table, the table should be closed again by calling
+{{{
+#!fortran
+call aot_table_close(L, thandle)
+}}}
+
+h2. Functions
+
+Again functions try to resemble the usage of files, however in this case its slightly more complicated,
+as you first need to "write" the input parameters into the function, then execute it and finally retrieve
+the results.
+
+To use a function, that is globally defined, open it with:
+{{{
+#!fortran
+call aot_fun_open(L, fun, key)
+}}}
+Where:
+* **L**: is the Lua context
+* **fun**: is the handle to the opened function
+* **key**: is the name of the function you want to access
+
+To access a function, which is within a table, use:
+{{{
+#!fortran
+call aot_fun_open(L, parent, fun, key, pos)
+}}}
+Where the additional arguments are:
+* **parent**: the table handle of the table, the function should be looked up in
+* //optional// *pos*: Refer to the function by position instead of name (key is also optional)
+
+After the function is opened, its arguments need to be filled with:
+{{{
+#!fortran
+call aot_fun_put(L, fun, arg)
+}}}
+Where:
+* **L**: Lua context
+* **fun**: handle to the function to put the arguments in
+* **arg**: argument to provide to the function
+
+When all arguments are written, the function needs to be executed with:
+{{{
+#!fortran
+call aot_fun_do(L, fun, nresults)
+}}}
+Where:
+* **L**: Lua context
+* **fun**: opened function to execute
+* **nresults**: number of results you want to retrieve from that function
+
+After the function is executed, the results can be read, using:
+{{{
+#!fortran
+call get_top_val(conf, top_val, ErrCode, default)
+}}}
+Where:
+* **conf**: Lua context
+* **top_val**: value to return
+* **ErrCode**: an error code, if something went wrong
+* //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.
+That is the first call to get_top_val will return the last result returned
+from the function, the next the second to last, and so on.
+
+You may then go on and put new arguments into the function, execute
+it and retrieve the corresponding results.
+
+After you are done with the evaluation of the function it has to be closed
+with:
+{{{
+#!fortran
+call aot_fun_close(L, fun)
+}}}
+
 ----
 
 Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.