diff --git a/doc/specs/index.md b/doc/specs/index.md index de3eb8f38..b965b006f 100644 --- a/doc/specs/index.md +++ b/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 diff --git a/doc/specs/stdlib_filesystem.md b/doc/specs/stdlib_filesystem.md new file mode 100644 index 000000000..90b48eeed --- /dev/null +++ b/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. diff --git a/doc/specs/stdlib_io.md b/doc/specs/stdlib_io.md index 19c5e3712..aaf90715d 100644 --- a/doc/specs/stdlib_io.md +++ b/doc/specs/stdlib_io.md @@ -123,114 +123,6 @@ Provides a text file called `filename` that contains the rank-2 `array`. {!example/io/example_savetxt.f90!} ``` -## `exists` - -### Status - -Experimental - -### Description - -Determines if a file or directory exists at the given path by returning a logical value. - -### Syntax - -`exists = ` [[stdlib_io_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_io_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_io_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_io_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_io_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. - ## `load_npy` ### Status diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 3141f9b33..9e1723c92 100644 --- a/src/CMakeLists.txt +++ b/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 @@ -17,7 +18,6 @@ set(fppFiles stdlib_hash_64bit_pengy.fypp stdlib_hash_64bit_spookyv2.fypp stdlib_io.fypp - stdlib_io_filesystem.fypp stdlib_io_npy.fypp stdlib_io_npy_load.fypp stdlib_io_npy_save.fypp diff --git a/src/stdlib_io_filesystem.fypp b/src/stdlib_filesystem.fypp similarity index 89% rename from src/stdlib_io_filesystem.fypp rename to src/stdlib_filesystem.fypp index e0043ac59..9d022baa0 100644 --- a/src/stdlib_io_filesystem.fypp +++ b/src/stdlib_filesystem.fypp @@ -1,7 +1,7 @@ ! SPDX-Identifier: MIT !> Interaction with the filesystem. -module stdlib_io_filesystem +module stdlib_filesystem use stdlib_string_type, only: string_type implicit none private @@ -9,10 +9,14 @@ module stdlib_io_filesystem 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 @@ -22,7 +26,7 @@ contains !> Version: experimental !> !> Whether a file or directory exists at the given path. - !> [Specification](../page/specs/stdlib_io.html#exists) + !> [Specification](../page/specs/stdlib_filesystem.html#exists) logical function exists(path) !> Path to a file or directory. character(len=*), intent(in) :: path @@ -37,7 +41,7 @@ contains !> Version: experimental !> !> List files and directories of a directory. Does not list hidden files. - !> [Specification](../page/specs/stdlib_io.html#list_dir) + !> [Specification](../page/specs/stdlib_filesystem.html#list_dir) subroutine list_dir(dir, files, iostat, iomsg) !> Directory to list. character(len=*), intent(in) :: dir @@ -95,7 +99,7 @@ contains !> Version: experimental !> !> Create a directory. - !> [Specification](../page/specs/stdlib_io.html#mkdir) + !> [Specification](../page/specs/stdlib_filesystem.html#mkdir) subroutine mkdir(dir, iostat, iomsg) character(len=*), intent(in) :: dir integer, optional, intent(out) :: iostat @@ -111,7 +115,7 @@ contains !> Version: experimental !> !> Remove a directory including its contents. - !> [Specification](../page/specs/stdlib_io.html#rmdir) + !> [Specification](../page/specs/stdlib_filesystem.html#rmdir) subroutine rmdir(dir) character(len=*), intent(in) :: dir @@ -125,7 +129,7 @@ contains !> Version: experimental !> !> Run a command in the shell. - !> [Specification](../page/specs/stdlib_io.html#run) + !> [Specification](../page/specs/stdlib_filesystem.html#run) subroutine run(command, iostat, iomsg) !> Command to run. character(len=*), intent(in) :: command diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 4d83548db..737938a64 100644 --- a/test/CMakeLists.txt +++ b/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) diff --git a/test/filesystem/CMakeLists.txt b/test/filesystem/CMakeLists.txt new file mode 100644 index 000000000..48d7eb893 --- /dev/null +++ b/test/filesystem/CMakeLists.txt @@ -0,0 +1 @@ +ADDTEST(filesystem) diff --git a/test/io/test_filesystem.f90 b/test/filesystem/test_filesystem.f90 similarity index 99% rename from test/io/test_filesystem.f90 rename to test/filesystem/test_filesystem.f90 index c05cf2fb0..373da053c 100644 --- a/test/io/test_filesystem.f90 +++ b/test/filesystem/test_filesystem.f90 @@ -1,5 +1,5 @@ module test_filesystem - use stdlib_io_filesystem + use stdlib_filesystem use stdlib_string_type, only: char, string_type use testdrive, only: new_unittest, unittest_type, error_type, check, test_failed implicit none diff --git a/test/io/CMakeLists.txt b/test/io/CMakeLists.txt index 77a12c323..98794cd88 100644 --- a/test/io/CMakeLists.txt +++ b/test/io/CMakeLists.txt @@ -13,7 +13,6 @@ ADDTEST(savetxt_qp) set_tests_properties(loadtxt_qp PROPERTIES LABELS quadruple_precision) set_tests_properties(savetxt_qp PROPERTIES LABELS quadruple_precision) -ADDTEST(filesystem) ADDTEST(getline) ADDTEST(npy) ADDTEST(open)