Add filesystem interaction

CMakeLists.txt

@@ -65,6 +65,7 @@ list(
   "-DPROJECT_VERSION_MAJOR=${PROJECT_VERSION_MAJOR}"
   "-DPROJECT_VERSION_MINOR=${PROJECT_VERSION_MINOR}"
   "-DPROJECT_VERSION_PATCH=${PROJECT_VERSION_PATCH}"
+  "-DOS=\\\"${CMAKE_SYSTEM_NAME}\\\""
   "-I${PROJECT_SOURCE_DIR}/include"
 )
 

config/fypp_deployment.py

@@ -1,4 +1,5 @@
 import os
+import platform
 import fypp
 import argparse
 from joblib import Parallel, delayed
@@ -42,6 +43,7 @@ def pre_process_fypp(args):
         kwd.append("-DWITH_QP=True")
     if args.with_xdp:
         kwd.append("-DWITH_XDP=True")
+    kwd.append("-DOS=\"{}\"".format(platform.system()))
 
     optparser = fypp.get_option_parser()
     options, leftover = optparser.parse_args(args=kwd)

doc/specs/index.md

@@ -17,6 +17,7 @@ This is an index/directory of the specifications (specs) for each new module/fea
  - [constants](./stdlib_constants.html) - Constants
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors
+ - [filesystem](./stdlib_filesystem.html) - Filesystem interactions
  - [hash](./stdlib_hash_procedures.html) - Hashing integer
  vectors or character strings
  - [hashmaps](./stdlib_hashmaps.html) - Hash maps/tables

doc/specs/stdlib_filesystem.md

@@ -0,0 +1,131 @@
+---
+title: filesystem
+---
+
+# The `stdlib_filesystem` module
+
+[TOC]
+
+## Introduction
+
+Module for filesystem interactions.
+
+## Constants
+
+### `is_windows``
+
+Boolean constant indicating whether the current platform is Windows.
+
+### `path_separator``
+
+Character constant representing the path separator for the current platform. On Windows, it is `\`. On other platforms, it is `/`.
+
+## Procedures
+
+### `exists`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Determines if a file or directory exists at the given path by returning a logical value.
+
+#### Syntax
+
+`exists = ` [[stdlib_filesystem(module):exists(function)]] `(path)`
+
+#### Arguments
+
+`path`: Shall be a character expression containing the path to a file or directory to check for existence.
+
+#### Return value
+
+A logical value indicating whether a file or directory exists at the given path.
+
+### `list_dir`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Lists the contents of a directory.
+
+#### Syntax
+
+`call ` [[stdlib_filesystem(module):list_dir(subroutine)]] `(dir, files[, iostat][, iomsg])`
+
+#### Arguments
+
+`dir`: Shall be a character expression containing the path to the directory to list.
+
+`files`: Shall be an allocatable rank-1 array of type `string_type` that will contain the names of the files and directories in the directory.
+
+`iostat`: Shall be a scalar of type `integer` that receives the error status of `list_dir`. Optional argument.
+
+`iomsg`: Shall be a deferred length character variable that receives the error message of `list_dir`. Optional argument.
+
+### `mkdir`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Creates a new directory.
+
+#### Syntax
+
+`call ` [[stdlib_filesystem(module):mkdir(subroutine)]] `(dir[, iostat][, iomsg])`
+
+#### Arguments
+
+`dir`: Shall be a character expression containing the path to the directory to create.
+
+`iostat`: Shall be a scalar of type `integer` that receives the error status of `mkdir`. Optional argument.
+
+`iomsg`: Shall be a deferred length character variable that receives the error message of `mkdir`. Optional argument.
+
+### `rmdir`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Removes a directory.
+
+#### Syntax
+
+`call ` [[stdlib_filesystem(module):rmdir(subroutine)]] `(dir)`
+
+#### Arguments
+
+`dir`: Shall be a character expression containing the path to the directory to remove.
+
+### `run`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Runs a command in the shell.
+
+#### Syntax
+
+`call ` [[stdlib_filesystem(module):run(subroutine)]] `(command[, iostat][, iomsg])`
+
+#### Arguments
+
+`command`: Shall be a character expression containing the command to run in the shell.
+
+`iostat`: Shall be a scalar of type `integer` that receives the error status of `run`. Optional argument.
+
+`iomsg`: Shall be a deferred length character variable that receives the error message of `run`. Optional argument.

src/CMakeLists.txt

@@ -8,6 +8,7 @@ set(fppFiles
     stdlib_bitsets_large.fypp
     stdlib_codata_type.fypp
     stdlib_constants.fypp
+    stdlib_filesystem.fypp
     stdlib_hash_32bit.fypp
     stdlib_hash_32bit_fnv.fypp
     stdlib_hash_32bit_nm.fypp

src/stdlib_filesystem.fypp

@@ -0,0 +1,159 @@
+! SPDX-Identifier: MIT
+
+!> Interaction with the filesystem.
+module stdlib_filesystem
+    use stdlib_string_type, only: string_type
+    implicit none
+    private
+
+    public :: temp_dir, is_windows, exists, path_separator, list_dir, mkdir, rmdir, run
+
+#: if OS == 'Windows'
+    !> Whether the operating system is Windows.
+    logical, parameter :: is_windows = .true.
+    !> Path separator for Windows.
+    character, parameter :: path_separator = '\'
+#: else
+    !> Whether the operating system is Windows.
+    logical, parameter :: is_windows = .false.
+    !> Path separator for filesystems on non-Windows operating systems.
+    character, parameter :: path_separator = '/'
+#: endif
+
+    character(*), parameter :: temp_dir = 'temp'
+
+contains
+    !> Version: experimental
+    !>
+    !> Whether a file or directory exists at the given path.
+    !> [Specification](../page/specs/stdlib_filesystem.html#exists)
+    logical function exists(path)
+        !> Path to a file or directory.
+        character(len=*), intent(in) :: path
+
+        inquire(file=path, exist=exists)
+
+#if defined(__INTEL_COMPILER)
+        if (.not. exists) inquire(directory=path, exist=exists)
+#endif
+    end function
+
+    !> Version: experimental
+    !>
+    !> List files and directories of a directory. Does not list hidden files.
+    !> [Specification](../page/specs/stdlib_filesystem.html#list_dir)
+    subroutine list_dir(dir, files, iostat, iomsg)
+        !> Directory to list.
+        character(len=*), intent(in) :: dir
+        !> List of files and directories.
+        type(string_type), allocatable, intent(out) :: files(:)
+        !> Status of listing.
+        integer, optional, intent(out) :: iostat
+        !> Error message.
+        character(len=:), allocatable, optional, intent(out) :: iomsg
+
+        integer :: unit, stat
+        character(len=256) :: line
+        character(:), allocatable :: listed_contents
+
+        stat = 0
+
+        if (.not. exists(temp_dir)) then
+            call mkdir(temp_dir, stat)
+            if (stat /= 0) then
+                if (present(iostat)) iostat = stat
+                if (present(iomsg)) iomsg = "Failed to create temporary directory '"//temp_dir//"'."
+                return
+            end if
+        end if
+
+        listed_contents = temp_dir//path_separator//'listed_contents.txt'
+
+        if (is_windows) then
+            call run('dir /b '//dir//' > '//listed_contents, stat)
+        else
+            call run('ls '//dir//' > '//listed_contents, stat)
+        end if
+        if (stat /= 0) then
+            if (present(iostat)) iostat = stat
+            if (present(iomsg)) iomsg = "Failed to list files in directory '"//dir//"'."
+            return
+        end if
+
+        open(newunit=unit, file=listed_contents, status='old', action='read', iostat=stat)
+        if (stat /= 0) then
+            if (present(iostat)) iostat = stat
+            if (present(iomsg)) iomsg = "Failed to open file '"//listed_contents//"'."
+            return
+        end if
+
+        allocate(files(0))
+        do
+            read(unit, '(A)', iostat=stat) line
+            if (stat /= 0) exit
+            files = [files, string_type(line)]
+        end do
+        close(unit, status="delete")
+    end subroutine
+
+    !> Version: experimental
+    !>
+    !> Create a directory.
+    !> [Specification](../page/specs/stdlib_filesystem.html#mkdir)
+    subroutine mkdir(dir, iostat, iomsg)
+        character(len=*), intent(in) :: dir
+        integer, optional, intent(out) :: iostat
+        character(len=:), allocatable, optional, intent(out) :: iomsg
+
+        if (is_windows) then
+            call run('mkdir '//dir, iostat, iomsg)
+        else
+            call run('mkdir -p '//dir, iostat, iomsg)
+        end if
+    end subroutine
+
+    !> Version: experimental
+    !>
+    !> Remove a directory including its contents.
+    !> [Specification](../page/specs/stdlib_filesystem.html#rmdir)
+    subroutine rmdir(dir)
+        character(len=*), intent(in) :: dir
+
+        if (is_windows) then
+            call run('rmdir /s/q '//dir)
+        else
+            call run('rm -rf '//dir)
+        end if
+    end subroutine
+
+    !> Version: experimental
+    !>
+    !> Run a command in the shell.
+    !> [Specification](../page/specs/stdlib_filesystem.html#run)
+    subroutine run(command, iostat, iomsg)
+        !> Command to run.
+        character(len=*), intent(in) :: command
+        !> Status of the operation.
+        integer, intent(out), optional :: iostat
+        !> Error message.
+        character(len=:), allocatable, intent(out), optional :: iomsg
+
+        integer :: exitstat, cmdstat
+        character(len=256) :: cmdmsg
+
+        if (present(iostat)) iostat = 0
+        exitstat = 0; cmdstat = 0
+
+        call execute_command_line(command, exitstat=exitstat, cmdstat=cmdstat, cmdmsg=cmdmsg)
+        if (exitstat /= 0 .or. cmdstat /= 0) then
+            if (present(iostat)) then
+                if (exitstat /= 0) then
+                    iostat = exitstat
+                else
+                    iostat = cmdstat
+                end if
+            end if
+            if (present(iomsg) .and. trim(adjustl(cmdmsg)) /= '') iomsg = cmdmsg
+        end if
+    end subroutine
+end module

test/CMakeLists.txt

@@ -14,6 +14,7 @@ add_subdirectory(array)
 add_subdirectory(ascii)
 add_subdirectory(bitsets)
 add_subdirectory(constants)
+add_subdirectory(filesystem)
 add_subdirectory(hash_functions)
 add_subdirectory(hash_functions_perf)
 add_subdirectory(hashmaps)

test/filesystem/CMakeLists.txt

@@ -0,0 +1 @@
+ADDTEST(filesystem)