# flibs/m_vfile(n) 1.0 "flibs"

## NAME

flibs/m_vfile - Processing files

## TABLE OF CONTENTS

TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
Portability
How to use it
Error management
Intel Fortran portability
RENAME and GETCWD fortran extension
Dynamic or static buffer
Preprocessing
Example of compiler settings
METHODS
STATIC METHODS
COPYRIGHT

## SYNOPSIS

vfile_rootname ( filename) result ( rootname )
vfile_rootname ( filename) result ( rootname )
vfile_extension ( filename) result ( extension )
vfile_extension ( filename) result ( extension )
vfile_tail ( filename) result ( filetail )
vfile_tail ( filename) result ( filetail )
vfile_dirname ( filename) result ( dirname )
vfile_dirname ( filename) result ( dirname )
vfile_first_separator_index ( filename) result ( sepindex )
vfile_first_separator_index ( filename) result ( sepindex )
vfile_last_separator_index ( filename) result ( sepindex )
vfile_last_separator_index ( filename) result ( sepindex )
vfile_join ( dirname filename) result ( fullname )
vfile_join ( dirname , filename) result ( fullname )
vfile_add_extension ( filename , extension ) result ( newname )
vfile_separator ( ) result ( separator )
vfile_pwd ( pwd ?, status? )
vfile_exists ( filename ) result ( exists )
vfile_exists ( filename ) result ( exists )
vfile_rename ( filename , newfn ?, status? )
vfile_rename ( filename , newfn ?, status? )
vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )
vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )
vfile_delete ( filename ?, force? ?, status? )
vfile_delete ( filename ?, force? ?, status? )
vfile_isdirectory ( filename) result ( isdirectory )
vfile_isdirectory ( filename) result ( isdirectory )
vfile_isfile ( filename) result ( isfile )
vfile_isfile ( filename) result ( isfile )
vfile_size ( filename ?, status?) result ( vfile_size )
vfile_size ( filename ?, status?) result ( vfile_size )
vfile_atime ( filename ?, status?) result ( vfile_atime )
vfile_atime ( filename ?, status?) result ( vfile_atime )
vfile_mtime ( filename ?, status?) result ( vfile_mtime )
vfile_mtime ( filename ?, status?) result ( vfile_mtime )
vfile_normalize ( filename ) result ( vfile_normalize )
vfile_normalize ( filename ) result ( vfile_normalize )
vfile_find ( ?basedir? ) result ( listOfFiles )
vfile_find ( basedir ) result ( listOfFiles )
vfile_find ( ?basedir? , filtercmd ) result ( listOfFiles )
vfile_find ( basedir , filtercmd ) result ( listOfFiles )
vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )
vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )
vfile_listfiles ( ?directory? ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )
vfile_listfiles ( directory ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )
vfile_type ( filename ?, status?) result ( filetype )
vfile_type ( filename ?, status?) result ( filetype )
vfile_split ( filename) result ( listOfComponents )
vfile_split ( filename) result ( listOfComponents )
vfile_touch ( filename ?, status?)
vfile_touch ( filename ?, status?)
vfile_pathtype ( filename) result ( pathtype )
vfile_pathtype ( filename) result ( pathtype )
vfile_nativename ( filename) result ( nativename )
vfile_nativename ( filename) result ( nativename )
vfile_mkdir ( filename ?, status?)
vfile_mkdir ( filename ?, status?)
vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )
vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )
vfile_startup ()
vfile_shutdown ()
vfile_set_stoponerror ( stoponerror )
vfile_tempdir () result ( tempdir )
vfile_tempfile result ( tempfile )
vfile_volumes result ( listofvolumes )

## DESCRIPTION

The module m_vfile provides OO services to process files and directories. This component is based on a dynamic strings so that the file or directory name may be defined with no limit in the number of characters.

## OVERVIEW

This component allows to manage the file system, by providing services to create, move and destroy files and directories, and to get informations about files and directories. The services provided are based either on standard fortran, or on fortran extensions.

### Portability

One of the main interest of this component is to separate the client-side application from platform-specific file management or from compiler-specific fortran extensions.

This separation is possible because m_vfile deals for the platform directly, by using the m_platform module. This allows to design a client source code which portable on several operating systems (for example windows, linux) without any change. For example, the several file separators used on the various operating systems are taken into account internally : "/" on linux systems, "\" on windows systems and ":" on Mac OS.

The portability is also ensured with respect to the fortran compiler used to create the executable. All fortran compilers provide commands to rename the files or get the working directory. But not all fortran compilers define these commands the same way : some provide subroutines, some provide functions, etc... The current component can be configured at compile-time with pre-processing commands. This allows to configure the component with compiler specific settings, to make so that the component know what features your particular compiler knows about.

<your application> > m_vfile (operating system , fortran compiler) > m_platform (operating system , fortran compiler)

### How to use it

Before using the services provided by m_vfile, the client code must call vfile_startup which initializes platform-specific commands. After using these services, the client code should call vfile_shutdown.

The commands vfile_delete, vfile_copy, vfile_rename allow to delete, copy and rename files or directories. To inquire about a file or directory, one can use vfile_exists or vfile_isdirectory.

In the following example, one creates a new file with vfile_touch, rename that file and finally delete it.

         call vfile_startup ()
         call vstring_new ( file , "foo.txt" )
         call vfile_touch ( file )
         call vfile_rename ( file , "toto.txt" )
         call vfile_delete ( file )
         call vstring_free ( file )
         call vfile_shutdown ()

The component makes no differences between file names and directory names, except for methods which are specific for file or for directory.

The vfile_separator method returns the platform-specific character used on the current operating system.

The commands vfile_nativename , vfile_normalize , vfile_pathtype provide ways to manage file names and paths. The vfile_nativename function returns the platform-specific name of the file. The vfile_pathtype command returns one of VFILE_PATHTYPE_ABSOLUTE, VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE which correspond to the current file. The VFILE_PATHTYPE_VOLUMERELATIVE only exist on windows. The vfile_normalize command returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it.

The vfile_split and vfile_join services allows to separate or concatenate the components of a file. This can be useful when dealing with relative file or directories. The vfile_split command splits a file into pieces each time the platform-specific separator is found. The vfile_join command concatenate a list of strings with the platform-specific separator and returns the concatenated file name.

In the following example, extracted from the unit tests included in flibs, the file "declaration.txt" is first normalized, so that the normalized dynamic string may have the value "/home/bill/flibs/tests/filedir/declaration.txt" under Windows or "C:/workbench/flibs/tests/filedir/declaration.txt" under Linux. Then the file name is split into a list of strings, for example "home", "bill", "flibs", "tests", "filedir", "declaration.txt". The number of strings in the list is then computed with the method vstrlist_length.

         use m_vstring
         use m_vstringlist
         use m_vfile
         type ( t_vstring ) :: normalized
         type ( t_vstringlist ) :: listOfFiles
         integer :: numberOfStrings
         normalized = vfile_normalize ( "declaration.txt" )
         listOfFiles = vfile_split ( normalized )
         numberOfStrings = vstrlist_length ( listOfFiles )

One particularly useful command when dealing with files is vfile_findbypattern. The command takes a string as an input file pattern. It then computes the list of all files which match that pattern. The string matching system is based on the vstring_match method of the m_vstring module.

In the following example, extracted again from the unit tests of flibs, one computes the list of files in the directory "testfindbypattern" matching the pattern "*dec*.txt".

         type ( t_vstringlist ) :: listOfFiles
         listOfFiles = vfile_findbypattern ( "testfindbypattern" , pattern = "*dec*.txt" )

### Error management

The file management may raise errors, for example when the user want to rename a file which does not exist. Many of the provided commands have an optional integer output argument "status" which is zero when no error occurred and non-zero in case of error. If the status argument is not provided and an error is generated, then the program stops and a message is displayed on standard output. These are the public error flags that the current component may generate :

         VFILE_ERROR_OK
         VFILE_ERROR_UNABLE_TO_OPEN_SOURCE
         VFILE_ERROR_UNABLE_TO_OPEN_TARGET
         VFILE_ERROR_UNABLE_TO_WRITE_TARGET
         VFILE_ERROR_SOURCE_FILE_DOES_NOT_EXIST

### Intel Fortran portability

Several methods of this component are based on Fortran extensions, which requires compiler-specific settings. For Intel Fortran compiler, the current implementation was based on IFPORT.F90 file in the Intel release for details on the interfaces provided. If the client code use these routines, it must define the pre-processing macro _VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES

### RENAME and GETCWD fortran extension

Depending on the compiler, the "RENAME" fortran extension is provided as a subroutine or a function. For example, this is a short list of compilers and their particular RENAME provided :

- function : Intel Fortran, g95
- subroutine : gfortran

To inform the m_vfile module of the particular RENAME extension, one of the following pre-processing macro must be defined :

- _VFILE_RENAME_FUNCTION
- _VFILE_RENAME_SUBROUTINE

The same situation happens with the GETCWD fortran extension. To inform the m_vfile module of the particular GETCWD extension, one of the following pre-processing macro must be defined :

- _VFILE_GETCWD_FUNCTION
- _VFILE_GETCWD_SUBROUTINE

### Dynamic or static buffer

The internal algorithms provided by m_vstrings are based on basic fortran character strings. In several situations, the dynamic vstring has to be converted into a basic fortran character buffer string, which size has to be given explicitly in the source code, with "character ( len = <something>)" statement. Two solutions are provided, and the user can define the pre-processing macro _VFILE_STATIC_BUFFER to configure that :

- the first solution is to set the size of the buffer statically, to a constant integer value VSTRING_BUFFER_SIZE.
- the second solution is to compute the size of the buffer dynamically, with the fortran 90 len = vstring_length(this) statement.

If the _VFILE_STATIC_BUFFER is defined, then character strings of constant size are used as buffers. If the _VFILE_STATIC_BUFFER is not defined (which is the default), then character strings of dynamic size are used as buffers. The second solution is more efficient, because the strings are not oversized or undersized, depending on the real number of characters in the dynamic string. But the feature may not be provided by the compiler at hand. For example, problems with the dynamic length character string have been experienced with Intel Fortran 8.

### Preprocessing

The following preprocessing macro must be considered :

- _VFILE_STATIC_BUFFER : see the section "Dynamic or static buffer"
- _VFILE_RENAME_FUNCTION or _VFILE_RENAME_SUBROUTINE : see the section "RENAME and GETCWD fortran extension"
- _VFILE_GETCWD_FUNCTION or _VFILE_GETCWD_SUBROUTINE : see the section "RENAME and GETCWD fortran extension"

### Example of compiler settings

This is an abstract of all macros for several compilers.

Compiler : Intel Fortran V8.0

- _VFILE_INTEL_FORTRAN_PORTABILITY_ROUTINES
- _VFILE_RENAME_FUNCTION
- _VFILE_STATIC_BUFFER
- _VFILE_GETCWD_FUNCTION

Compiler : g95

- _VFILE_RENAME_FUNCTION
- _VFILE_GETCWD_FUNCTION

Compiler : gfortran

- _VFILE_RENAME_SUBROUTINE
- _VFILE_GETCWD_SUBROUTINE

## METHODS

vfile_rootname ( filename) result ( rootname )
  type ( t_vstring ) , intent(in) :: filename
  type ( t_vstring ) :: rootname
  Returns the name without the extension (if any), that is, The part of the name _before_ the last "." in filename or the whole name if no "." is present in filename. Example : if filename is "declaration.txt", the file root name is "declaration".
vfile_rootname ( filename) result ( rootname )
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: rootname
  Same as previous but with filename as a character string.
vfile_extension ( filename) result ( extension )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ) :: extension
  Returns the extension (if any), that is the part of the name after and including the last "." or empty if none present. Example : if filename is "declaration.txt", the file extension is ".txt".
vfile_extension ( filename) result ( extension )
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: extension
  Same as previous but with filename as a character string.
vfile_tail ( filename) result ( filetail )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ) :: filetail
  Returns all of the characters in name after the last directory separator. If filename contains no separators then returns filename. Example : if filename is "dir1/declaration.txt", the file tail is "declaration.txt".
vfile_tail ( filename) result ( filetail )
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: filetail
  Same as previous but with filename as a character string.
vfile_dirname ( filename) result ( dirname )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ) :: dirname
  Return the directory, that is, the part of the name before the last directory separator. Example : if filename is "dir1/declaration.txt", the directory name is "dir1".
vfile_dirname ( filename) result ( dirname )
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: dirname
  Same as previous but with filename as a character string.
vfile_first_separator_index ( filename) result ( sepindex )
  type ( t_vstring ), intent(in) :: filename
  integer :: sepindex
  Returns the index of the first separator in the given filename or 0 if there is no separator in the given file name.
vfile_first_separator_index ( filename) result ( sepindex )
  character(len=*), intent(in) :: filename
  integer :: sepindex
  Same as previous but with filename as a character string.
vfile_last_separator_index ( filename) result ( sepindex )
  type ( t_vstring ), intent(in) :: filename
  integer :: sepindex
  Returns the index of the last separator in the given filename or 0 if there is no separator in the given file name.
vfile_last_separator_index ( filename) result ( sepindex )
  character(len=*), intent(in) :: filename
  integer :: sepindex
  Same as previous but with filename as a character string.
vfile_join ( dirname filename) result ( fullname )
  type ( t_vstring ), intent(in) :: dirname
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ) :: fullname
  Join the current file with the given file name, using the platform-specific separator as the joining character. The result is always canonical for the current platform: / for Unix and Windows, and : for Macintosh. If a particular name is relative, then it will be joined to the previous file name argument. Otherwise, any earlier arguments will be discarded, and joining will proceed from the current argument.
vfile_join ( dirname , filename) result ( fullname )
  type ( t_vstring ), intent(in) :: dirname
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: fullname
  Same as previous but with filename as a character string.
vfile_add_extension ( filename , extension ) result ( newname )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ), intent(in) :: extension
  type ( t_vstring ) :: newname
  Return a new file name with the given extension concatenated. If the given file name ends with a dot and the given extension begins with a dot, only one dot is kept. Note that the extension of one file begins with a dot : ".txt" is a file extension while "txt" is not.
vfile_separator ( ) result ( separator )
  type ( t_vstring ) :: separator
  Return the native separator for the current platform The separator depends on the platform :
  - "/" on Unix, Linux systems,
  - "\" on Windows systems,
  - ":" on Macintosh.
vfile_pwd ( pwd ?, status? )
  type ( t_vstring ) :: pwd
  integer , intent(out) , optional :: status
  Returns the name of the current directory by using the fortran extension GETCWD. The separator used here is the platform-independent "/".
vfile_exists ( filename ) result ( exists )
  type ( t_vstring ), intent(in) :: filename
  logical :: exists
  Returns .true. if file name exists, .false. otherwise.
vfile_exists ( filename ) result ( exists )
  character(len=*), intent(in) :: filename
  logical :: exists
  Same as previous but with filename as a character string.
vfile_rename ( filename , newfn ?, status? )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ), intent(in) :: newfn
  integer, intent(out) , optional :: status
  Renames the file ofdln to newfn by using the RENAME fortran extension. If status is supplied, it contains 0 on success or nonzero error code upon return.
vfile_rename ( filename , newfn ?, status? )
  type ( t_vstring ), intent(in) :: filename
  character(len=*), intent(in) :: newfn
  integer, intent(out) , optional :: status
  Same as previous but with newfn as a character string.
vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ), intent(in) :: targetfn
  integer, intent(out) , optional :: status
  character(len=*), intent(in), optional :: mode
  logical, intent(in) , optional :: force
  logical, intent(in) , optional :: trimline
  Copy the ascii file ofdln to targetfn. If the source file does not exists, generates an error. If the target file allready exists and force option is undefined or defined to false, generates an error. If status is supplied, it contains 0 on success or nonzero error code upon return
  - status = 1 when one was unable to open the source file
  - status = 2 when one was unable to open the target file
  - status = 3 when there was a problem while writing the target file
  - status = 4 when the source file does not exist
  If mode is not supplied or supplied and equals to "system", then the copy is made using an operating system command. If mode is supplied and equals to "ascii", then the copy is made using standard fortran. The force option is available only in "ascii" mode. If force is supplied and true, if the target file allready exists, delete it before making the copy. The trimline option is available only in "ascii" mode. If trimline is supplied and true, or not supplied, the lines of the file copy are trimmed. If trimline is supplied and false, the number of columns in the file copy are all of maximum possible length.
  The "ascii" mode may not behave as expected :
  - The maximum number of columns in the source filename is 1000.
  - After execution, the target file is not an exact copy of the source file. Because of the fortran format used, all the lines of the target file are of length 1000 : blank spaces are appended at the end of the string.
vfile_copy ( filename , targetfn ?, status? ?, mode? ?, force? ?, trimline? )
  type ( t_vstring ), intent(in) :: filename
  character(len=*), intent(in) :: targetfn
  integer, intent(out) , optional :: status
  character(len=*), intent(in), optional :: mode
  logical, intent(in) , optional :: force
  logical, intent(in) , optional :: trimline
  Same as previous but with targetfn as a character string.
vfile_delete ( filename ?, force? ?, status? )
  type ( t_vstring ), intent(in) :: filename
  logical, intent(in) , optional :: force
  integer, intent(out) , optional :: status
  Removes the file or directory filename. Non-empty directories will be removed only if the force option is specified. If force is supplied and true, forces to delete the directory, even if it is empty. If force is not supplied or supplied and false, the directory is not deleted if it is empty. If status is supplied, it contains 0 on success or nonzero error code upon return.
vfile_delete ( filename ?, force? ?, status? )
  character(len=*), intent(in) :: filename
  logical, intent(in) , optional :: force
  integer, intent(out) , optional :: status
  Same as previous but with filename as a character string.
vfile_isdirectory ( filename) result ( isdirectory )
  type ( t_vstring ), intent(in) :: filename
  logical :: isdirectory
  Returns .true. if file name is a directory, .false. otherwise.
vfile_isdirectory ( filename) result ( isdirectory )
  character(len=*), intent(in) :: filename
  logical :: isdirectory
  Same as previous but with filename as a character string.
vfile_isfile ( filename) result ( isfile )
  type ( t_vstring ), intent(in) :: filename
  logical :: isfile
  Returns .true. if file name is a file, .false. otherwise.
vfile_isfile ( filename) result ( isfile )
  character(len=*), intent(in) :: filename
  logical :: isfile
  Same as previous but with filename as a character string.
vfile_size ( filename ?, status?) result ( vfile_size )
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_size
  Returns .true. if file name is a file, .false. otherwise. Returns an integer giving the size of file name in bytes. If the file doesn't exist or its size cannot be queried then an error is generated. If status is supplied, it contains 0 on success or nonzero error code upon return.
vfile_size ( filename ?, status?) result ( vfile_size )
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_size
  Same as previous but with filename as a character string.
vfile_atime ( filename ?, status?) result ( vfile_atime )
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_atime
  Returns an integer representing the time at which file name was last accessed. If status is supplied, it contains 0 on success or nonzero error code upon return.
vfile_atime ( filename ?, status?) result ( vfile_atime )
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_atime
  Same as previous but with filename as a character string.
vfile_mtime ( filename ?, status?) result ( vfile_mtime )
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_mtime
  Returns an integer representing the time at which file name was last modified. If status is supplied, it contains 0 on success or nonzero error code upon return.
vfile_mtime ( filename ?, status?) result ( vfile_mtime )
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: status
  integer :: vfile_mtime
  Same as previous but with filename as a character string.
vfile_normalize ( filename ) result ( vfile_normalize )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstring ) :: vfile_normalize
  Returns a unique normalized path representation for the file-system object (file, directory, link, etc), whose string value can be used as a unique identifier for it. A normalized path is an absolute path which has all '../', './' removed. Also it is one which is in the ``standard'' format for the native platform. On Windows or Mac, any platform-specific separator in the path is replaced by the platform-independent separator "/". On Windows it also means we want the long form with that form's case-dependence (which gives us a unique, case-dependent path).
vfile_normalize ( filename ) result ( vfile_normalize )
  character(len=*), intent(in) :: filename
  type ( t_vstring ) :: vfile_normalize
  Same as previous but with filename as a character string.
vfile_find ( ?basedir? ) result ( listOfFiles )
  type ( t_vstring ), intent(in), optional :: basedir
  type ( t_vstringlist ) :: listOfFiles
  An implementation of the unix command find. Returns a list of files or directories which are located in the given basedir directory, and, recursively, in all sub-directories. Each file in the resulting list has a path relative to the given basedir directory. If basedir is provided, this is the name of the base directory into which the search is done. If basedir is not provided, the current directory is used by default.
vfile_find ( basedir ) result ( listOfFiles )
  character(len=*), intent(in) :: basedir
  type ( t_vstringlist ) :: listOfFiles
  Same as previous but with basedir as a character string.
vfile_find ( ?basedir? , filtercmd ) result ( listOfFiles )
  type ( t_vstring ), intent(in), optional :: basedir
  type ( t_vstringlist ) :: listOfFiles

          interface
             function filtercmd ( filename ) result ( keepfile )
               use m_vstring, only : t_vstring
               type ( t_vstring ), intent(in) :: filename
               logical :: keepfile
             end function filtercmd
          end interface

  An implementation of the unix command find. Returns a list of files or directories which are located in the given basedir directory, and, recursively, in all sub-directories. Each file in the resulting list has a path relative to the given basedir directory. If basedir is provided, this is the name of the base directory into which the search is done. If basedir is not provided, the current directory is used by default. The filtercmd command, if provided, is interpreted as a command prefix and one argument is passed to it, the name of the file or directory find is currently looking at. Note that this name is not fully qualified. It has to be joined it with the result of pwd to get an absolute filename. The result of filtercmd is a boolean value that indicates if the current file should be included in the list of interesting files.
vfile_find ( basedir , filtercmd ) result ( listOfFiles )
  character(len=*), intent(in) :: basedir
  type ( t_vstringlist ) :: listOfFiles

          interface
             function filtercmd ( filename ) result ( keepfile )
               use m_vstring, only : t_vstring
               type ( t_vstring ), intent(in) :: filename
               logical :: keepfile
             end function filtercmd
          end interface

  Same as previous but with basedir as a character string.
vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )
  type ( t_vstring ), intent(in), optional :: basedir
  type ( t_vstring ), intent(in) :: pattern
  type ( t_vstringlist ) :: listOfFiles
  Returns a list of files which match the given pattern. Internally, this command is based on vfile_find, with a particular filter command applied. If basedir is provided, this is the name of the base directory into which the search is done. If basedir is not provided, the current directory is used by default. The pattern is the pattern for the file names (like: *.f90) against which each file name is compared. The method used for string matching is vstring_match, so that all features available is vstring_match are available in vfile_findbypattern.
vfile_findbypattern ( ?basedir? , pattern ) result ( listOfFiles )
  character(len=*), intent(in), optional :: basedir
  character(len=*), intent(in) :: pattern
  type ( t_vstringlist ) :: listOfFiles
  Same as previous but with basedir and pattern as a character string.
vfile_listfiles ( ?directory? ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )
  type ( t_vstring ), intent(in), optional :: basedir
  type ( t_vstringlist ), intent(in), optional :: pattern
  type ( t_vstring ), intent(in), optional :: pattern
  logical, intent(in), optional :: tails
  type ( t_vstringlist ) :: listOfFiles
  Returns a list of files in one directory. Only the file tails are in the list. If directory is provided, the directory into which the list is to be computed. If directory is not provided, the current directory is used and only the file names are file tails. If directory is provided, the computed files names are relative and begin with the given directory (following the template directory/filetail). If filetypes is provided, only list files or directories which match filetypes, with d (directory), f (plain file). If filetypes is not provided, the filetypes "d" , "f" list is used. If pattern is provided, only list files which match the given pattern. If pattern is not provided, the "*" pattern is used. The vstring_match command is used to compare the file against the pattern so that all the pattern types available in vstring_match are available in vfile_listfiles. If tails is provided and true, only return the part of each file found which follows the last directory named in directory. Thus the statement

      listoffiles = vfile_listfile ( tails = .true. , directory = directory , pattern = "*" )

  is equivalent to

      call vfile_pwd ( cwd )
      call vstrplatform_cd ( directory )
      listoffiles = vfile_listfile ( tails = .true. , pattern = "*" )
      call vstrplatform_cd ( cwd )

  If tails is provided and false, or not provided, the files are left as specified by the directory argument.
vfile_listfiles ( directory ?, filetypes? ?, pattern? ?, tails?) result ( listOfFiles )
  character(len=*), intent(in) :: basedir
  type ( t_vstringlist ), intent(in), optional :: pattern
  character(len=*), intent(in), optional :: pattern
  logical, intent(in), optional :: tails
  type ( t_vstringlist ) :: listOfFiles
  Same as previous but with directory and pattern as a character string.
vfile_type ( filename ?, status?) result ( filetype )
  type ( t_vstring ), intent(in) :: filename
  integer , intent(out), optional :: status
  type ( t_vstring ) :: filetype
  Returns a string giving the type of file name, which will be one of "file" or "directory". If status is provided and the file type could be computed, the status is set to 0. If status is provided and the file type could not be computed, the status is set to VFILE_ERROR_UNKNOWN_FILE_TYPE. If status is not provided and the file type could not be computed, an error is generated.
vfile_type ( filename ?, status?) result ( filetype )
  character(len=*), intent(in) :: filename
  integer , intent(out), optional :: status
  type ( t_vstring ) :: filetype
  Same as previous but with filename as a character string.
vfile_split ( filename) result ( listOfComponents )
  type ( t_vstring ), intent(in) :: filename
  type ( t_vstringlist ) :: listOfComponents
  Returns a list of strings where elements are the path components in name.
vfile_split ( filename) result ( listOfComponents )
  character(len=*), intent(in) :: filename
  type ( t_vstringlist ) :: listOfComponents
  Same as previous but with filename as a character string.
vfile_touch ( filename ?, status?)
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: status
  Implementation of touch. Alter the atime and mtime of the specified files. If status is supplied, it contains 0 on success or nonzero error code upon return. If status is not provided and the process could not be done, an error is generated.
vfile_touch ( filename ?, status?)
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: status
  Same as previous but with filename as a character string.
vfile_pathtype ( filename) result ( pathtype )
  type ( t_vstring ), intent(in) :: filename
  integer :: pathtype
  Returns one of VFILE_PATHTYPE_ABSOLUTE, VFILE_PATHTYPE_RELATIVE, VFILE_PATHTYPE_VOLUMERELATIVE. If filename refers to a specific file on a specific volume, the path type will be absolute. If filename refers to a file relative to the current working directory, then the path type will be relative. If name refers to a file relative to the current working directory on a specified volume, or to a specific file on the current working volume, then the path type is volumerelative.
  Examples :
  - "." is relative on all platforms
  - ".." is relative on all platforms
  - "/" is absolute on Linux/Unix
  - "C:/" is absolute on Windows (if the C:/ exists)
  - "/" is volumerelative on windows and refers to the current volume (for example C:/)
  - "toto.txt" is relative on all platforms
  - "./toto.txt" is relative on all platforms
vfile_pathtype ( filename) result ( pathtype )
  character(len=*), intent(in) :: filename
  integer :: pathtype
  Same as previous but with filename as a character string.
vfile_nativename ( filename) result ( nativename )
  type ( t_vstring ), intent(in) :: filename
  ( t_vstring ) :: nativename
  Returns the platform-specific name of the file. filename is useful if the filename is needed to pass to a platform-specific call, such as the execution of a system command under Windows or AppleScript on the Macintosh.
vfile_nativename ( filename) result ( nativename )
  character(len=*), intent(in) :: filename
  ( t_vstring ) :: nativename
  Same as previous but with filename as a character string.
vfile_mkdir ( filename ?, status?)
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: status
  Create a directory. If status is supplied, it contains 0 on success or nonzero error code upon return. If status is not provided and the process could not be done, an error is generated.
vfile_mkdir ( filename ?, status?)
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: status
  Same as previous but with filename as a character string.
vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )
  type ( t_vstring ), intent(in) :: filename
  integer, intent(out) , optional :: fileunit
  character(len=*) , intent(in) , optional :: action
  character(len=*) , intent(in) , optional :: status
  character(len=*) , intent(in) , optional :: access
  character(len=*) , intent(in) , optional :: form
  character(len=*) , intent(in) , optional :: blank
  character(len=*) , intent(in) , optional :: position
  character(len=*) , intent(in) , optional :: delim
  character(len=*) , intent(in) , optional :: pad
  integer , intent(in) , optional :: recl
  integer , intent(out) , optional :: iostat
  integer :: fileunit_real
  Open a file and returns the unit associated with the opened file. The command is based on fortran intrinsic "open". If the optional argument fileunit is provided, it is used to open the file. If not provided, a file unit is automatically computed on the base of currently free logical units.
  Note:
  All the options of the intrinsic "open" are provided with the same behaviour and default values, with some exceptions.
  - The file name is mandatory in vfile_open, even if the "file=" specifier is not mandatory in fortran "open". This behaviour allows the fortran to manage a status="scratch" specifier, which provides a way to manage for temporary files internally. Instead, the m_vfile component provides the vfile_tempfile service.
  - The "err=" option with an error label as argument is not provided. The client code may use the iostat option instead.
vfile_open ( filename ?, fileunit? ?, iostat? ?, status? ?, access? ?, form? ?, recl? ?, blank? ?, position? ?, action? ?, delim? ?, pad?) result ( fileunit_real )
  character(len=*), intent(in) :: filename
  integer, intent(out) , optional :: fileunit
  character(len=*) , intent(in) , optional :: action
  character(len=*) , intent(in) , optional :: status
  character(len=*) , intent(in) , optional :: access
  character(len=*) , intent(in) , optional :: form
  character(len=*) , intent(in) , optional :: blank
  character(len=*) , intent(in) , optional :: position
  character(len=*) , intent(in) , optional :: delim
  character(len=*) , intent(in) , optional :: pad
  integer , intent(in) , optional :: recl
  integer , intent(out) , optional :: iostat
  integer :: fileunit_real
  Same as previous but with filename as a character string.

## STATIC METHODS

vfile_startup ()
  Initialize module internal state. This routine must be called once before calling any method of the module.
vfile_shutdown ()
  Shutdown module internal state.
vfile_set_stoponerror ( stoponerror )
  logical , intent(in) :: stoponerror
  Configure the behaviour of the component whenever an error is met. If stoponerror is true, then the execution stops if an error is encountered. If stoponerror is false, then the execution continues if an error is encountered. In both cases, a message is displayed on standard output.
vfile_tempdir () result ( tempdir )
  type ( t_vstring ) :: tempdir
  Returns the temporary directory for the current platform. The command returns the path of a directory where the caller can place temporary files, such as "/tmp" on Unix systems. The algorithm we use to find the correct directory is as follows:
  1. The directory named in the TMPDIR environment variable.
  2. The directory named in the TEMP environment variable.
  3. The directory named in the TMP environment variable.
  4. A platform specific location:
     - Windows "C:\TEMP", "C:\TMP", "\TEMP", and "\TMP" are tried in that order. (classic) Macintosh The TRASH_FOLDER environment variable is used. filename is most likely not correct.
     - Unix The directories "/tmp", "/var/tmp", and "/usr/tmp" are tried in that order.
vfile_tempfile result ( tempfile )
  type ( t_vstring ) :: tempfile
  Returns the name of a temporary file name suitable for writing to. The tempfile name is unique, and the file will be writable and contained in the appropriate system specific temp directory.
vfile_volumes result ( listofvolumes )
  type ( t_vstringlist ) :: listofvolumes
  Returns the absolute paths to the volumes mounted on the system, as a proper string list. On UNIX, the command will always return "/", since all filesystems are locally mounted. On Windows, it will return a list of the available local drives (e.g. {a:/ c:/}).
  Note:
  With Intel Fortran, the portability routines provide the "GETDRIVESQQ" function, which returns the list of current drive as a 26 letters string.

## COPYRIGHT

Copyright © 2008 Michael Baudin michael.baudin@gmail.com
Copyright © 2008 Arjen Markus arjenmarkus@sourceforge.net