Commits

Manuel Hasert committed 6668524 Merge

merge

Comments (0)

Files changed (2)

source/aot_out_module.f90

 !> A module to produce Lua scripts with nested tables.
 !!
 !! This module eases the output of readable Lua scripts.
-!! It takes care of indentation with nested tables, and
-!! provides a concise interface to output Fortran data
-!! into Lua scripts.
-!! Therefore this module is somehow the counter-part to
-!! the reading functions, however it is almost completely
-!! independent and relies purely on Fortran output methods.
+!! It takes care of indentation with nested tables, and provides a concise
+!! interface to output Fortran data into Lua tables.
+!! Therefore this module is somehow the counter-part to the reading functions,
+!! however it is almost completely independent and relies purely on Fortran
+!! output methods. Thus this module could stand alone, along with the
+!! aot_kinds_module without the Lua library.
 module aot_out_module
 
   use aot_kinds_module
   end type
 
   !> Put Fortran intrinsic types into the script.
+  !!
+  !! Scalar values and one-dimensional arrays are supported.
+  !! Supported data-types are
+  !! - integer
+  !! - integer(kind=long_k)
+  !! - real
+  !! - real(kind=double_k)
+  !! - logical
+  !! - character(len=*)
+  !! complex values are not supported, as they are indistinguishable from
+  !! arrays with two entries on the Lua side.
   interface aot_out_val
+    ! scalars
     module procedure aot_out_val_int
     module procedure aot_out_val_long
     module procedure aot_out_val_real
     module procedure aot_out_val_double
     module procedure aot_out_val_logical
     module procedure aot_out_val_string
+
+    ! arrays
     module procedure aot_out_val_arr_int
     module procedure aot_out_val_arr_long
     module procedure aot_out_val_arr_real
     module procedure aot_out_val_arr_double
+    module procedure aot_out_val_arr_logical
+    module procedure aot_out_val_arr_string
   end interface
 
   private
 contains
 
 !******************************************************************************!
-!> Open the file to write to and return a handle (put_conf) to it.
-!!
-!! This will overwrite the given file, if it already exists.
-!! Either filename of outUnit has to be specified, use outUnit to write to a
-!! pre-connected file.
-!! If both are given, the file will be opened and connected to a new unit,
-!! outUnit is ignored in this case.
+  !> Open the file to write to and return a handle (put_conf) to it.
+  !!
+  !! This will overwrite the given file, if it already exists.
+  !! Either filename of outUnit has to be specified, use outUnit to write to a
+  !! pre-connected file.
+  !! If both are given, the file will be opened and connected to a new unit,
+  !! outUnit is ignored in this case.
   subroutine aot_out_open(put_conf, filename, outUnit, indentation)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(out) :: put_conf !< Handle for the file
       open(unit = put_conf%outunit, file = trim(filename), action = 'write', &
         &  status='replace', recl=360)
       put_conf%externalOpen = .false.
-    else if ( present(outUnit) ) then
+    else if (present(outUnit)) then
       put_conf%externalOpen = .true.
       put_conf%outunit = outUnit
-!HK!    else
-!HK!       write(*,*) 'Error, no unit or filename specified for aot_open_put'
-!HK!       stop
-!HK: Return an error code instead.
     end if
 
     put_conf%indent = 0
 
 
 !******************************************************************************!
-!>  Close the script again.
-!!
+  !>  Close the opened script again.
+  !!
+  !! This will close the file, if the data was not written to a pre-connected
+  !! unit (that is the file for the script was opened in the aot_out_open).
   subroutine aot_out_close(put_conf)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!> Start a new table to write to.
-!!
+  !> Start a new table to write to.
+  !!
+  !! You can give the table a name with the tname argument.
+  !! If the table definition should NOT start on a new line, you have to pass
+  !! in an advance_previous = .false.
   subroutine aot_out_open_table(put_conf, tname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Close the current table.
-!!
+  !>  Close the current table.
+  !!
+  !! The table on the current table is closed with a curly bracket.
+  !! If this bracket should be put to the same line as the last entry of the
+  !! table, you have to set advance_previous = .false.
   subroutine aot_out_close_table(put_conf, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put integer variables into the Lua script.
-!!
+  !>  Put integer variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_int(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put long variables into the Lua script.
-!!
+  !>  Put long variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_long(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put real variables into the Lua script.
-!!
+  !>  Put real variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_real(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put double variables into the Lua script.
-!!
+  !>  Put double variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_double(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put logical variables into the Lua script.
-!!
+  !>  Put logical variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_logical(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put string variables into the Lua script.
-!!
+  !>  Put string variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_string(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_int(put_conf, val, vname, advance_previous, &
     &                            max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_long(put_conf, val, vname, advance_previous, &
     &                             max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_real(put_conf, val, vname, advance_previous, &
     &                             max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_double(put_conf, val, vname, advance_previous, &
     &                               max_per_line)
     !------------------------------------------------------------------------
 !******************************************************************************!
 
 
+!******************************************************************************!
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
+  subroutine aot_out_val_arr_logical(put_conf, val, vname, advance_previous, &
+    &                                max_per_line)
+    !------------------------------------------------------------------------
+    !> Lua script to write the array into.
+    type(aot_out_type), intent(inout)  :: put_conf
+
+    !> Name for this array
+    character(len=*), optional, intent(in) :: vname
+
+    !> Actual data to write into the script
+    logical, intent(in) :: val(:)
+
+    !> Flag if this array should be put on the same line as the last entry of
+    !! the parent table.
+    logical, optional, intent(in) :: advance_previous
+
+    !> Maximal number of entries to put into a single line.
+    !! Defaults to 10.
+    integer, optional, intent(in) :: max_per_line
+    !------------------------------------------------------------------------
+    integer :: i
+    integer :: nVals
+    integer :: mpl
+    logical :: bline
+    !------------------------------------------------------------------------
+
+    if (present(max_per_line)) then
+      mpl = max_per_line
+    else
+      mpl = 10
+    end if
+
+    ! Opening the table(subtable for array actually)
+    call aot_out_open_table(put_conf, vname, &
+      &                     advance_previous = advance_previous)
+
+    nVals = size(val)
+    if (nVals > 0) then
+      ! Always put the first entry on the same line as the opening brace.
+      call aot_out_val(put_conf, val(1), advance_previous = .false.)
+
+      do i=2,nVals
+        ! Output each entry and break the line after mpl entries on a line.
+        bline = (mod(i-1, mpl) == 0)
+        call aot_out_val(put_conf, val(i), advance_previous = bline)
+      end do
+    end if
+
+    ! Always put the closing brace on the same line as the last entry.
+    call aot_out_close_table(put_conf, advance_previous = .false.)
+
+  end subroutine aot_out_val_arr_logical
+!******************************************************************************!
+
 
 !******************************************************************************!
-!> This subroutine takes care of the proper linebreaking in Lua-Tables.
-!!
-!! It takes care of a proper line-continuation, depending on the optional
-!! advance_previous flag and increases the count of elements in the current
-!! table.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
+  subroutine aot_out_val_arr_string(put_conf, val, vname, advance_previous, &
+    &                                max_per_line)
+    !------------------------------------------------------------------------
+    !> Lua script to write the array into.
+    type(aot_out_type), intent(inout)  :: put_conf
+
+    !> Name for this array
+    character(len=*), optional, intent(in) :: vname
+
+    !> Actual data to write into the script
+    character(len=80), intent(in) :: val(:)
+
+    !> Flag if this array should be put on the same line as the last entry of
+    !! the parent table.
+    logical, optional, intent(in) :: advance_previous
+
+    !> Maximal number of entries to put into a single line.
+    !! Defaults to 1.
+    integer, optional, intent(in) :: max_per_line
+    !------------------------------------------------------------------------
+    integer :: i
+    integer :: nVals
+    integer :: mpl
+    logical :: bline
+    !------------------------------------------------------------------------
+
+    if (present(max_per_line)) then
+      mpl = max_per_line
+    else
+      mpl = 1
+    end if
+
+    ! Opening the table(subtable for array actually)
+    call aot_out_open_table(put_conf, vname, &
+      &                     advance_previous = advance_previous)
+
+    nVals = size(val)
+    if (nVals > 0) then
+      ! Always put the first entry on the same line as the opening brace.
+      call aot_out_val(put_conf, trim(val(1)), advance_previous = .false.)
+
+      do i=2,nVals
+        ! Output each entry and break the line after mpl entries on a line.
+        bline = (mod(i-1, mpl) == 0)
+        call aot_out_val(put_conf, trim(val(i)), advance_previous = bline)
+      end do
+    end if
+
+    ! Always put the closing brace on the same line as the last entry.
+    call aot_out_close_table(put_conf, advance_previous = .false.)
+
+  end subroutine aot_out_val_arr_string
+!******************************************************************************!
+
+
+
+!******************************************************************************!
+  !> This subroutine takes care of the proper linebreaking in Lua-Tables.
+  !!
+  !! It takes care of a proper line-continuation, depending on the optional
+  !! advance_previous flag and increases the count of elements in the current
+  !! table.
+  !! The default is to put each entry on a new line, if it should be on the
+  !! same line advance_previous = .false. has to be set.
   subroutine aot_out_breakline(put_conf, advance_previous)
     type(aot_out_type), intent(inout)  :: put_conf
     logical, optional, intent(in) :: advance_previous

source/aot_path_module.f90

-!> The aot_path can be used to track the position of a Lua entity
-!! in nested tables, which is mainly useful to lookup a function
-!! reference again after closing and opening the script.
+!> The aot_path can be used to track the position of a Lua entity in nested
+!! tables.
+!!
+!! It is mainly useful to lookup a function reference again after closing and
+!! opening the script.
+!! The idea is to initialize the path in the very beginning and then append a
+!! node whenever a table is opened. Thus you pass down the growing path object
+!! and store at in the level, to which you might need to return later.
 module aot_path_module
   use flu_binding, only: flu_State
   use aotus_module, only: open_config, close_config
 
   private
 
+  !> This data structure describes a node in the path through nested tables.
   type aot_path_node_type
     !> What type of node is this?
     !! Currently supported are function and table
     character(len=16) :: NodeType
+
     !> How to look up this node, by key or position?
     character(len=16) :: ID_kind
+
     !> Identifying key
     character(len=80) :: key
+
     !> Identifying position
     integer :: pos
+
     !> Link to possible child of this node
     type(aot_path_node_type), pointer :: child => NULL()
   end type
 
+  !> This type is the main data structure of the module and describes the path.
+  !!
+  !! It contains a linked list of all nodes, as well as the name of the Lua
+  !! script where this path is recorded in.
   type aot_path_type
+    !> Name of the file where this path object is found in.
     character(len=256) :: LuaFilename
+
+    !> Handle to the topmost table opened for the path.
     integer :: rootHandle
+
+    !> Entry level of the path on the global scope of the Lua script.
     type(aot_path_node_type), pointer :: GlobalNode => NULL()
+
+    !> Moving head through the linked list of path nodes.
     type(aot_path_node_type), pointer :: head => NULL()
   end type
 
+  !> Taking care of the linked list in a copying routine for the assignment of
+  !! aot_path_type.
   interface assignment(=)
     module procedure aot_path_copy
   end interface
   public :: assignment(=)
   public :: aot_path_open, aot_path_close
 
+  !> Re-open a previously recorded path through nested Lua tables.
+  !!
+  !! This opens all the tables recursively down to the last node in the path.
+  !! It might be used to open a table, or a function.
   interface aot_path_open
     module procedure aot_path_open_fun
     module procedure aot_path_open_table
   end interface aot_path_open
 
+  ! Close all tables, that were opened for the given path.
   interface aot_path_close
     module procedure aot_path_close_fun
     module procedure aot_path_close_table
 
 contains
 
-  !> This subroutine initializes a path object by setting the
-  !! given file name as reference to the script, to look the
-  !! path up in.
+  !> This subroutine initializes a path object.
+  !!
+  !! This is done by setting the given file name as reference to the script,
+  !! to look the path up in and emptying the path completely.
   subroutine aot_init_path(me, Filename)
     !> Path object to initialize
     type(aot_path_type), intent(out) :: me
     !> Filename of the Lua script, this path is located in
     character(len=*), intent(in) :: Filename
 
+    ! Finalize the path first, just in case it might have had any entries.
+    call aot_fin_path(me)
     me%LuaFilename = adjustl(trim(Filename))
     me%rootHandle = 0
   end subroutine aot_init_path
 
   !> With this subroutine a node is appended to the end of
   !! the list of nodes of the given path.
+  !!
   !! You need to provide a NodeType (table or function),
   !! and either its position of key to identify it in the
   !! parent object.
   end subroutine aot_path_addNode
 
 
-  !> The delNode removes the last node from the list
-  !! of nodes of the given path. With the optional
-  !! isEmpty argument, it can be tested, if the list
+  !> The delNode removes the last node from the list of nodes of the given path.
+  !!
+  !! With the optional isEmpty argument, it can be tested, if the list
   !! is completely empty after this operation.
   subroutine aot_path_delNode(me, isEmpty)
     !> Path to delet the last node from
   end subroutine aot_path_delNode
 
 
-  !> Copy a given path object, this is the implementation
-  !! of the assignment left = right
+  !> Copy a given path object, this is the implementation of the
+  !! assignment left = right.
   subroutine aot_path_copy(left, right)
     !> Object to assign a path to
     type(aot_path_type), intent(inout) :: left
   end subroutine aot_path_copy
 
 
-  !> This subroutine opens all the tables on the way to
-  !! the final head node, which ought to be a function.
+  !> This subroutine opens all the tables on the way to the final head node,
+  !! which ought to be a function.
+  !!
   !! The given fun object is then filled by an aot_fun_open
   !! on the head of the given path.
   !! The handle can be either passed in, to be used for the
 
   end subroutine aot_path_open_fun
 
-  !> This subroutine opens all the tables on the way to
-  !! the final head node of the given path.
+  !> This subroutine opens all the tables on the way to the final head node of
+  !! the given path.
+  !!
   !! The handle can be either passed in, to be used for the
   !! look up of the path, or, when specifying the optional
   !! openLua argument as true, it will return the handle to
 
   end subroutine aot_path_open_table
 
-  !> This routine closes function and all other tables opened
-  !! along the path
+  !> This routine closes function and all other tables opened along the path.
   subroutine aot_path_close_fun(me, conf, fun, closeLua)
     !> The path object to open as a function
     type(aot_path_type), intent(inout) :: me
 
   end subroutine aot_path_close_fun
 
-  !> this routine closes all the table opened in aot_path_open_table
+  !> This routine closes all the table opened in aot_path_open_table.
   subroutine aot_path_close_table(me, conf, closeLua)
     !> The path object to open as a function
     type(aot_path_type), intent(inout) :: me
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.