Commits

Harald Klimach committed f1315af

A little more doxygen documentation in the aotus_module

Comments (0)

Files changed (1)

source/aotus_module.f90

   ! Entities inherited from aot_top_module, published here to
   ! allow most functionality by "use aotus_module".
   public :: aoterr_Fatal, aoterr_NonExistent, aoterr_WrongType
+  public :: aot_err_handler
   public :: aot_top_get_val
 
   ! Inherited from the flu_binding module, publish for convenience.
   !!
   !! This provides a convenient direct access to
   !! global variables from the Lua script.
+  !! The interface is also used for other values than the global ones, and the
+  !! general shape of it looks like
+  !! <tt>call aot_{top}_get_val(<outputs>, <id>, default)</tt>.
+  !! Where the "outputs" are <tt>val</tt> and <tt>errCode</tt>. While "id" is
+  !! at least the Lua context <tt>L</tt>. For the global variables there has to
+  !! be a <tt>key</tt> for the identification of the variable.
+  !!
+  !! The <tt>errCode</tt> returns an error code with various bits set for
+  !! different errors, that might happen while retrieving the variable.
+  !! They can be checked by <tt>btest</tt> and the different error codes are:
+  !!- 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 a check for a fatal error can be done by
+  !! <tt>btest(errCode, aoterr_fatal)</tt>.
+  !!
+  !! For the access to global variables in the Lua script the interface
+  !! therefore looks like:
+  !! <tt>call aot_get_val(val, errCode, L, key, default)</tt>.
+  !! See for example aotus_module#get_config_real for a more detailed
+  !! description of the parameters.
   interface aot_get_val
     module procedure get_config_real
     module procedure get_config_double
 
 contains
 
+  !> Subroutine to load and execute a script from a file.
   subroutine open_config_file(L, filename, ErrCode, ErrString)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Name of file to load the Lua code from
     character(len=*), intent(in) :: filename
+
+    !> Error code returned by Lua during loading or executing the file.
+    !!
+    !! This optional parameter might be used to react on errors in the calling
+    !! side. If neither ErrCode nor ErrString are given, this subroutine will
+    !! stop the program execution and print the error message from Lua to the
+    !! stdout.
     integer, intent(out), optional :: ErrCode
+
+    !> Obtained error description from the Lua stack.
+    !!
+    !! This optional argument holds the Lua error message in case somehting
+    !! went wrong. It can be used to provide some feedback to the user in the
+    !! calling routine. If neither ErrCode nor ErrString are provided,
+    !! open_config() will print the error message and stop program execution.
     character(len=*), intent(out), optional :: ErrString
 
     integer :: err
     call aot_err_handler(L, err, 'Cannot load configuration file:', ErrString, &
       &                  ErrCode)
 
-    call fluL_openlibs(L)
+    if (err == 0) then
+      call fluL_openlibs(L)
 
-    err = flu_pcall(L, 0, 0, 0)
-    call aot_err_handler(L, err, 'Cannot run configuration file:', ErrString, &
-      &                  ErrCode)
+      err = flu_pcall(L, 0, 0, 0)
+      call aot_err_handler(L, err, 'Cannot run configuration file:',  &
+        &                  ErrString, ErrCode)
+    end if
 
   end subroutine open_config_file
 
 
-  subroutine close_config(L)
-    type(flu_State) :: L
+  !> Subroutine to load and execute a script given in a string.
+  subroutine open_config_chunk(L, chunk, ErrCode, ErrString)
+    type(flu_State) :: L !< Handle to the Lua script
 
-    call flu_close(L)
+    !> String with Lua code to load.
+    character(len=*), intent(in) :: chunk
 
-  end subroutine close_config
+    !> Error code returned by Lua during loading or executing the file.
+    !!
+    !! This optional parameter might be used to react on errors in the calling
+    !! side. If neither ErrCode nor ErrString are given, this subroutine will
+    !! stop the program execution and print the error message from Lua to the
+    !! stdout.
+    integer, intent(out), optional :: ErrCode
 
-
-  subroutine get_config_real(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    real(kind=single_k), intent(out) :: val
-    integer, intent(out) :: ErrCode
-    real(kind=single_k), optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_real
-
-
-  subroutine get_config_double(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    real(kind=double_k), intent(out) :: val
-    integer, intent(out) :: ErrCode
-    real(kind=double_k), optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_double
-
-
-  subroutine get_config_integer(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    integer, intent(out) :: val
-    integer, intent(out) :: ErrCode
-    integer, optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_integer
-
-
-  subroutine get_config_long(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    integer(kind=long_k), intent(out) :: val
-    integer, intent(out) :: ErrCode
-    integer(kind=long_k), optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_long
-
-
-  subroutine get_config_logical(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    logical, intent(out) :: val
-    integer, intent(out) :: ErrCode
-    logical, optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_logical
-
-
-  subroutine get_config_string(val, ErrCode, L, key, default)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: key
-    character(len=*) :: val
-    integer, intent(out) :: ErrCode
-    character(len=*), optional, intent(in) :: default
-
-    call flu_getglobal(L, key)
-    call aot_top_get_val(val, ErrCode, L, default)
-
-  end subroutine get_config_string
-
-
-  subroutine open_config_chunk(L, chunk, ErrCode, ErrString)
-    type(flu_State) :: L
-    character(len=*), intent(in) :: chunk
-    integer, intent(out), optional :: ErrCode
+    !> Obtained error description from the Lua stack.
+    !!
+    !! This optional argument holds the Lua error message in case somehting
+    !! went wrong. It can be used to provide some feedback to the user in the
+    !! calling routine. If neither ErrCode nor ErrString are provided,
+    !! open_config() will print the error message and stop program execution.
     character(len=*), intent(out), optional :: ErrString
 
     integer :: err
 
     call aot_err_handler(L, err, 'Cannot load chunk:', ErrString, ErrCode)
 
-    call fluL_openlibs(L)
+    if (err == 0) then
+      call fluL_openlibs(L)
 
-    err = flu_pcall(L, 0, 0, 0)
+      err = flu_pcall(L, 0, 0, 0)
 
-    call aot_err_handler(L, err, 'Cannot run chunk:', ErrString, ErrCode)
+      call aot_err_handler(L, err, 'Cannot run chunk:', ErrString, ErrCode)
+    end if
 
   end subroutine open_config_chunk
 
+
+  !> Close an opened Lua script again.
+  subroutine close_config(L)
+    type(flu_State) :: L !< Handle to the Lua script to close.
+
+    call flu_close(L)
+
+  end subroutine close_config
+
+
+  subroutine get_config_real(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    real(kind=single_k), intent(out) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    real(kind=single_k), optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_real
+
+
+  subroutine get_config_double(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    real(kind=double_k), intent(out) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    real(kind=double_k), optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_double
+
+
+  subroutine get_config_integer(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    integer, intent(out) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    integer, optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_integer
+
+
+  subroutine get_config_long(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    integer(kind=long_k), intent(out) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    integer(kind=long_k), optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_long
+
+
+  subroutine get_config_logical(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    logical, intent(out) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    logical, optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_logical
+
+
+  subroutine get_config_string(val, ErrCode, L, key, default)
+    type(flu_State) :: L !< Handle for the Lua script to get the value from.
+    character(len=*), intent(in) :: key !< Variable name to look for.
+
+    !> Value of the Variable in the script
+    character(len=*) :: val
+
+    !> ErrorCode to indicate what kind of problem might have occured.
+    integer, intent(out) :: ErrCode
+
+    !> Some default value that should be used, if the variable is not set in the
+    !! Lua script.
+    character(len=*), optional, intent(in) :: default
+
+    call flu_getglobal(L, key)
+    call aot_top_get_val(val, ErrCode, L, default)
+
+  end subroutine get_config_string
+
 end module aotus_module