feat: creating and removing empty directories (#1011)

Author: perazz

doc/specs/stdlib_system.md

@@ -535,6 +535,117 @@ The function returns a `logical` value:
 
 ---
 
+## `make_directory` - Creates an empty directory
+
+### Status
+
+Experimental
+
+### Description
+
+It creates an empty directory with default permissions.
+It is designed to work across multiple platforms. On Windows, paths with both forward `/` and backward `\` slashes are accepted.
+
+### Syntax
+
+`call [[stdlib_system(module):make_directory(subroutine)]] (path [,err])`
+
+### Class
+
+Subroutine
+
+### Arguments
+
+`path`: Shall be a character string containing the path of the directory to create. It is an `intent(in)` argument.
+
+`err`(optional): Shall be of type `state_type`, and is used for error handling. It is an `optional, intent(out)` argument.
+
+### Return values
+
+`err` is an optional state return flag. If not requested and an error occurs, an `FS_ERROR` will trigger an error stop.
+
+### Example
+
+```fortran
+{!example/system/example_make_directory.f90!}
+```
+
+---
+
+## `make_directory_all` - Creates an empty directory with all its parent directories
+
+### Status
+
+Experimental
+
+### Description
+
+It creates an empty directory with default permissions.
+It also creates all the necessary parent directories in the path if they do not exist already.
+
+### Syntax
+
+`call [[stdlib_system(module):make_directory_all(subroutine)]] (path [,err])`
+
+### Class
+
+Subroutine
+
+### Arguments
+
+`path`: Shall be a character string containing the path of the directory to create. It is an `intent(in)` argument.
+
+`err`(optional): Shall be of type `state_type`, and is used for error handling. It is an `optional, intent(out)` argument.
+
+### Return values
+
+`err` is an optional state return flag. If not requested and an error occurs, an `FS_ERROR` will trigger an error stop.
+
+### Example
+
+```fortran
+{!example/system/example_make_directory.f90!}
+```
+
+---
+
+## `remove_directory` - Removes an empty directory
+
+### Status
+
+Experimental
+
+### Description
+
+It deletes an empty directory.
+It is designed to work across multiple platforms. On Windows, paths with both forward `/` and backward `\` slashes are accepted.
+
+### Syntax
+
+`call [[stdlib_system(module):remove_directory(subroutine)]] (path, err)`
+
+### Class
+
+Subroutine
+
+### Arguments
+
+`path`: Shall be a character string containing the path of the directory to create. It is an `intent(in)` argument.
+
+`err`(optional): Shall be of type `state_type`, and is used for error handling. It is an `optional, intent(out)` argument.
+
+### Return values
+
+`err` is an optional state return flag. On error if not requested, an `FS_ERROR` will trigger an error stop.
+
+### Example
+
+```fortran
+{!example/system/example_remove_directory.f90!}
+```
+
+---
+
 ## `null_device` - Return the null device file path
 
 ### Status

example/system/CMakeLists.txt

@@ -16,4 +16,5 @@ ADD_EXAMPLE(path_join)
 ADD_EXAMPLE(path_split_path)
 ADD_EXAMPLE(path_base_name)
 ADD_EXAMPLE(path_dir_name)
-
+ADD_EXAMPLE(make_directory)
+ADD_EXAMPLE(remove_directory)

example/system/example_make_directory.f90

@@ -0,0 +1,25 @@
+! Illustrate the usage of `make_directory`, `make_directory_all`
+program example_make_directory
+    use stdlib_system, only: make_directory, make_directory_all
+    use stdlib_error, only: state_type
+    implicit none
+
+    type(state_type) :: err
+
+    call make_directory("temp_dir", err)
+
+    if (err%error()) then
+        print *, err%print()
+    else
+        print *, "directory created sucessfully"
+    end if
+
+    call make_directory_all("d1/d2/d3/d4", err)
+
+    if (err%error()) then
+        print *, err%print()
+    else
+        print *, "nested directories created sucessfully"
+    end if
+
+end program example_make_directory

example/system/example_remove_directory.f90

@@ -0,0 +1,17 @@
+! Illustrate the usage of `remove_directory`
+program example_remove_directory
+    use stdlib_system, only: remove_directory
+    use stdlib_error, only: state_type
+    implicit none
+
+    type(state_type) :: err
+
+    call remove_directory("directory_to_be_removed", err)
+
+    if (err%error()) then
+        print *, err%print()
+    else
+        print *, "directory removed successfully"
+    end if
+
+end program example_remove_directory

src/CMakeLists.txt

@@ -56,7 +56,7 @@ set(fppFiles
     stdlib_specialfunctions_gamma.fypp
     stdlib_specialfunctions.fypp
     stdlib_specialmatrices.fypp
-    stdlib_specialmatrices_tridiagonal.fypp    
+    stdlib_specialmatrices_tridiagonal.fypp
     stdlib_stats.fypp
     stdlib_stats_corr.fypp
     stdlib_stats_cov.fypp
@@ -118,6 +118,7 @@ set(SRC
     stdlib_system_subprocess.c
     stdlib_system_subprocess.F90
     stdlib_system_path.f90
+    stdlib_system.c
     stdlib_system.F90
     stdlib_sparse.f90
     stdlib_specialfunctions_legendre.f90

src/stdlib_system.F90

@@ -2,8 +2,9 @@ module stdlib_system
 use, intrinsic :: iso_c_binding, only : c_int, c_long, c_ptr, c_null_ptr, c_int64_t, c_size_t, &
     c_f_pointer
 use stdlib_kinds, only: int64, dp, c_bool, c_char
-use stdlib_strings, only: to_c_char, to_string
+use stdlib_strings, only: to_c_char, find
 use stdlib_string_type, only: string_type
+use stdlib_optval, only: optval
 use stdlib_error, only: state_type, STDLIB_SUCCESS, STDLIB_FS_ERROR
 implicit none
 private
@@ -109,6 +110,52 @@ module stdlib_system
 !!
 public :: is_directory
 
+!! version: experimental
+!!
+!! Makes an empty directory.
+!! ([Specification](../page/specs/stdlib_system.html#make_directory))
+!!
+!! ### Summary
+!! Creates an empty directory with default permissions.
+!!
+!! ### Description
+!! This function makes an empty directory according to the path provided.
+!! Relative paths are supported. On Windows, paths involving either `/` or `\` are accepted.
+!! An appropriate error message is returned whenever any error occurs.
+!!
+public :: make_directory
+
+!! version: experimental
+!!
+!! Makes an empty directory, also creating all the parent directories required.
+!! ([Specification](../page/specs/stdlib_system.html#make_directory))
+!!
+!! ### Summary
+!! Creates an empty directory with all the parent directories required to do so.
+!!
+!! ### Description
+!! This function makes an empty directory according to the path provided.
+!! It also creates all the necessary parent directories in the path if they do not exist already.
+!! Relative paths are supported.
+!! An appropriate error message is returned whenever any error occurs.
+!!
+public :: make_directory_all
+
+!! version: experimental
+!!
+!! Removes an empty directory.
+!! ([Specification](../page/specs/stdlib_system.html#remove_directory))
+!!
+!! ### Summary
+!! Removes an empty directory.
+!!
+!! ### Description
+!! This function Removes an empty directory according to the path provided.
+!! Relative paths are supported. On Windows paths involving either `/` or `\` are accepted.
+!! An appropriate error message is returned whenever any error occurs.
+!!
+public :: remove_directory
+
 !! version: experimental
 !!
 !! Deletes a specified file from the filesystem.
@@ -849,6 +896,134 @@ end function stdlib_is_directory
 
 end function is_directory
 
+! A helper function to get the result of the C function `strerror`.
+! `strerror` is a function provided by `<string.h>`. 
+! It returns a string describing the meaning of `errno` in the C header `<errno.h>`
+function c_get_strerror() result(str)
+    character(len=:), allocatable :: str
+
+    interface
+        type(c_ptr) function strerror(len) bind(C, name='stdlib_strerror')
+            import c_size_t, c_ptr
+            implicit none
+            integer(c_size_t), intent(out) :: len
+        end function strerror
+    end interface
+
+    type(c_ptr) :: c_str_ptr
+    integer(c_size_t) :: len, i
+    character(kind=c_char), pointer :: c_str(:)
+
+    c_str_ptr = strerror(len)
+
+    call c_f_pointer(c_str_ptr, c_str, [len])
+
+    allocate(character(len=len) :: str)
+
+    do concurrent (i=1:len)
+        str(i:i) = c_str(i)
+    end do
+end function c_get_strerror
+
+!! makes an empty directory
+subroutine make_directory(path, err)
+    character(len=*), intent(in) :: path
+    type(state_type), optional, intent(out) :: err
+
+    integer :: code
+    type(state_type) :: err0
+
+    interface
+        integer function stdlib_make_directory(cpath) bind(C, name='stdlib_make_directory')
+            import c_char
+            character(kind=c_char), intent(in) :: cpath(*)
+        end function stdlib_make_directory
+    end interface
+
+    code = stdlib_make_directory(to_c_char(trim(path)))
+
+    if (code /= 0) then
+        err0 = FS_ERROR_CODE(code, c_get_strerror())
+        call err0%handle(err)
+    end if
+
+end subroutine make_directory
+
+subroutine make_directory_all(path, err)
+    character(len=*), intent(in) :: path
+    type(state_type), optional, intent(out) :: err
+
+    integer :: i, indx
+    type(state_type) :: err0
+    character(len=1) :: sep
+    logical :: is_dir, check_is_dir
+
+    sep = path_sep()
+    i = 1
+    indx = find(path, sep, i)
+    check_is_dir = .true.
+
+    do
+        ! Base case to exit the loop
+        if (indx == 0) then
+            is_dir = is_directory(path)
+
+            if (.not. is_dir) then
+                call make_directory(path, err0)
+
+                if (err0%error()) then
+                    call err0%handle(err)
+                end if
+            end if
+
+            return
+        end if
+
+        if (check_is_dir) then
+            is_dir = is_directory(path(1:indx))
+        end if
+
+        if (.not. is_dir) then
+            ! no need for further `is_dir` checks
+            ! all paths going forward need to be created
+            check_is_dir = .false.
+            call make_directory(path(1:indx), err0)
+
+            if (err0%error()) then
+                call err0%handle(err)
+                return
+            end if
+        end if
+
+        i = i + 1 ! the next occurence of `sep`
+        indx = find(path, sep, i)
+    end do
+end subroutine make_directory_all
+
+!! removes an empty directory
+subroutine remove_directory(path, err)
+    character(len=*), intent(in) :: path
+    type(state_type), optional, intent(out) :: err
+
+    integer :: code
+    type(state_type) :: err0
+
+    interface
+        integer function stdlib_remove_directory(cpath) bind(C, name='stdlib_remove_directory')
+            import c_char
+            character(kind=c_char), intent(in) :: cpath(*)
+        end function stdlib_remove_directory
+    end interface
+
+    code = stdlib_remove_directory(to_c_char(trim(path)))
+
+    if (code /= 0) then
+        err0 = FS_ERROR_CODE(code, c_get_strerror())
+        call err0%handle(err)
+    end if
+
+end subroutine remove_directory
+
 !> Returns the file path of the null device for the current operating system.
 !>
 !> Version: Helper function.