Definition of high level file objects. More...

Data Types
type	file_handle
	`FILE_HANDLE` is the basic file handle object. It provides an unitary object oriented interface for operations with any supported file types. More...

Functions/Subroutines
logical function	file_operation_last_is_success (this)
	Get the success or error status of the latest file operation. Example: More...

character(len=:) function, allocatable	file_hangle_get_name_string (this)
	Get the file name associated with the file handle. If the file name is (yet) undefined, the latest operation success flag (see file_io::is_success()) is FALSE. Example: More...

integer function	file_object_get_associated_unit (this)
	A Low level function to get the Fortran unit number associated with the file handle object. More...

logical function	file_object_format_is_csv (this)
	Check if the file format is CSV. More...

logical function	file_object_format_is_txt (this)
	Check if the file format is CSV. More...

subroutine	csv_open_write_this (this, name, format)
	This is an object oriented wrapper for `CSV_OPEN_WRITE()`. For details see CSV_OPEN_WRITE. More...

subroutine	csv_close_this (this)
	This is an object oriented wrapper for `CSV_CLOSE()`. For details see CSV_CLOSE. More...

subroutine	csv_header_line_write_this (this, header)
	This is an object oriented wrapper for `CSV_HEADER_WRITE()`. See CSV_HEADER_WRITE for details. More...

subroutine	csv_record_string_write_this (this, csv_record)
	Physically write a single string CSV data record to the file. See CSV_RECORD_WRITE Example: More...

Public enumeration constants defining supported file types
Define the file types that are supported by this module.
enum

@, public	undefined

@, public	format_csv

@, public	format_txt

Detailed Description

Definition of high level file objects.

FILE_IO module

This module defines input and output to external files in various formats. The main format for output files for numerical data is CSV. It is useful for one-dimensional vectors and two-dimensional matrices. More complex data structures can be output in other formats (to be implemented) such as binary, XML or HDF. This module provides an unitary object-oriented interface to all file types and objects.

Current status: Only CSV and plain text (TXT) files are implemented so far. And even here, only the file object is implemented in the object oriented style, record (string) is used exactly as in the CSV_IO in HEDTOOLS.

CSV format

Notably, standard HEDTOOLS whole array procedure CSV_MATRIX_WRITE can save a single vector or 2D matrix into a separate CSV file.

Example:

! File handle object identifies a specific file.
type(FILE_HANDLE) :: test_file
! String variable that is used to build each record (row)
! it must fit the whole record into its length;
character(len=:), allocatable :: record_string
 
! Open the file for writing
call test_file%open_write( "test_file.csv", format_csv )
 
! Write optional header.
call test_file%header_write("Header is the first line of the file")
 
! The current record must be cleared before it is built. Note that
! if the record string is allocatable, it must be whole blank.
record_string=repeat(" ", max_len)
! Append values to the first record. The first record is
! here the variable names.
call csv_record_append( record_string, ["No", "V1", "V2", "V3"] )
! Write this record 'record_string' physically to the disk.
call test_file%record_write(record_string)
 
! Now write the data beyond the first row.
do i=1, 100
  record_string=repeat(" ", max_len)  ! clean each new record string
  ! Append values of various types to the current
  ! record string 'record_string'
  call csv_record_append( record_string, i )
  call csv_record_append( record_string, [ 1.1, 2.2 ] )
  call csv_record_append( record_string, 3.3 )
  ! Once the record is built, write it to the disk.
  call test_file%record_write(record_string)
end do
 
! Close file at the end.
call test_file%close()

See code of the the_population::population_save_data_all_agents_csv() for another example of writing data to CSV file. But note that these codes use the standard non-object-oriented procedures from HEDTOOLS, not these wrappers.

Plain text (TXT) format

The file handler object file_io::file_handle defined in this module can be easily used to write arbitrary plain text files. Here is an example.

Example:

! File handle object identifies a specific file.
type(FILE_HANDLE) :: test_file
 
! Open the file for writing
call test_file%open_write( "test_file.txt", format_txt )
 
! Write an arbitrary row of data to the file, character text string:
call test_file%record_write("This is a test string to output")
 
! Standard Fortran intrinsic 'write' can be combined with the 'get_unit()'
! accessor function for unit.
write( test_file%get_unit(), * ) "Raw string 1, success=", test_file%is_success()
write( test_file%get_unit(), * ) "Raw string 2, success=", test_file%is_success()
write( test_file%get_unit(), * ) "Raw string 3, success=", test_file%is_success()
 
! Close file at the end.
call test_file%close()

Thus, the wrappers implemented in this unit allow to use unitary file handler object to work with specific files, even though they are not fully object oriented. Using a single file handle is simpler and more understandable than different Fortran file identifiers (file name, unit).

The logger commondata::logger_init() is the standard normal method to report everything in the model during the runtime. Therefore, using separate plain text file(s) to output any reports should be very rare if needed at all.

Accessibility of objects

By default, all objects in FILE_IO are private.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

private

Definition at line 120 of file m_fileio.f90.

Function/Subroutine Documentation

◆ file_operation_last_is_success()

logical function file_io::file_operation_last_is_success ( class(file_handle), intent(inout) this )

Get the success or error status of the latest file operation. Example:

if ( data_file%is_success() ) then

Returns: TRUE if the latest file operation was successful, FALSE otherwise.

Definition at line 244 of file m_fileio.f90.

◆ file_hangle_get_name_string()

character(len=:) function, allocatable file_io::file_hangle_get_name_string ( class(file_handle), intent(inout) this )

private

Get the file name associated with the file handle. If the file name is (yet) undefined, the latest operation success flag (see file_io::is_success()) is FALSE. Example:

print *, data_file%get_name()

Returns: the name of the file.

Definition at line 260 of file m_fileio.f90.

◆ file_object_get_associated_unit()

integer function file_io::file_object_get_associated_unit ( class(file_handle), intent(inout) this )

private

A Low level function to get the Fortran unit number associated with the file handle object.

Note: This function is useful only for diagnostics because Fortran unit is treated automatically and transparently in all the routines of this module. Of course, it could also be useful for low-level code. Example:
print *, data_file%get_unit()

Returns: the Furtran file unit.

Definition at line 278 of file m_fileio.f90.

◆ file_object_format_is_csv()

logical function file_io::file_object_format_is_csv ( class(file_handle), intent(in) this )

private

Check if the file format is CSV.

Returns: TRUE if the file format is CSV, FALSE otherwise.

Definition at line 288 of file m_fileio.f90.

◆ file_object_format_is_txt()

logical function file_io::file_object_format_is_txt ( class(file_handle), intent(in) this )

private

Check if the file format is CSV.

Returns: TRUE if the file format is TXT, FALSE otherwise.

Definition at line 301 of file m_fileio.f90.

◆ csv_open_write_this()

subroutine file_io::csv_open_write_this	(	class(file_handle), intent(inout)	this,
		character(len=*), intent(in)	name,
		integer, intent(in), optional	format
	)

private

This is an object oriented wrapper for CSV_OPEN_WRITE(). For details see CSV_OPEN_WRITE.

Note: This procedure also automatically and transparently assigns the Fortran unit. Example:
call data_file%open_write( "file_001.csv" )

Parameters

[in]	name	name the name of the file.
[in]	format	format optional data format type of the file: FORMAT_CSV (default) FORMAT_TXT

Implementation notes

Set name from the mandatory name argument.

Default format is FORMAT_CSV.

Providing a non-supported format results in FALSE status flag.

Open the file for writing physically.

Definition at line 321 of file m_fileio.f90.

◆ csv_close_this()

subroutine file_io::csv_close_this ( class(file_handle), intent(inout) this )

private

This is an object oriented wrapper for CSV_CLOSE(). For details see CSV_CLOSE.

Note: This procedure also automatically ans transparently assigns the Fortran unit. Example:
call data_file%close()

Definition at line 373 of file m_fileio.f90.

◆ csv_header_line_write_this()

subroutine file_io::csv_header_line_write_this	(	class(file_handle), intent(inout)	this,
		character(len=*), intent(in), optional	header
	)

private

This is an object oriented wrapper for CSV_HEADER_WRITE(). See CSV_HEADER_WRITE for details.

Note: File header is optional in CSV files and is not used in most cases. Example:
call data_file%header_write("Agent data at start of the simulation")

Parameters

[in] header header is the optional header line for the CSV file. If header is absent, it is automatically generated from the file name.

Definition at line 387 of file m_fileio.f90.

◆ csv_record_string_write_this()

subroutine file_io::csv_record_string_write_this	(	class(file_handle), intent(inout)	this,
		character(len=*), intent(in)	csv_record
	)

private

Physically write a single string CSV data record to the file. See CSV_RECORD_WRITE Example:

call data_file%record_write( record_string )

Parameters

[in] csv_record csv_record character string that keeps the whole record (row) of the CSV data spreadsheet.

Definition at line 408 of file m_fileio.f90.

Variable Documentation

◆ undefined

@, public file_io::undefined

Definition at line 121 of file m_fileio.f90.

◆ format_csv

@, public file_io::format_csv

Definition at line 121 of file m_fileio.f90.

◆ format_txt

@, public file_io::format_txt

Definition at line 121 of file m_fileio.f90.

Data Types

Functions/Subroutines

Public enumeration constants defining supported file types

Detailed Description

FILE_IO module

CSV format

Plain text (TXT) format

Accessibility of objects

Enumeration Type Documentation

◆ anonymous enum

Function/Subroutine Documentation

◆ file_operation_last_is_success()

◆ file_hangle_get_name_string()

◆ file_object_get_associated_unit()

◆ file_object_format_is_csv()

◆ file_object_format_is_txt()

◆ csv_open_write_this()

Implementation notes

◆ csv_close_this()

◆ csv_header_line_write_this()

◆ csv_record_string_write_this()

Variable Documentation

◆ undefined

◆ format_csv

◆ format_txt