type renaming + docs

Author: wassup05

doc/specs/stdlib_system.md

@@ -666,7 +666,7 @@ Any encountered errors are handled using `state_type`.
 
 ### Syntax
 
-`res = [[stdlib_system(module):exists(function)]] (path [, err])`
+`fs_type = [[stdlib_system(module):exists(function)]] (path [, err])`
 
 ### Class
 
@@ -680,7 +680,13 @@ Function
 
 ### Return values
 
-`err` is an optional state return flag. If not requested and an error occurs, an `FS_ERROR` will trigger an error stop.
+`fs_type`: An `intent(out), integer` parameter indicating the type. The possible values are:
+- `fs_type_unknown`: 0      => an unknown type
+- `fs_type_regular_file`: 1 => a regular file
+- `fs_type_directory`: 2    => a directory 
+- `fs_type_symlink`: 3      => a symbolic link
+
+`err`(optional): It is an optional state return flag. If not requested and an error occurs, an `FS_ERROR` will trigger an error stop.
 
 ### Example
 

example/system/example_exists.f90

@@ -1,7 +1,7 @@
 ! Illustrate the usage of `exists`
 program example_exists
-    use stdlib_system, only: exists, type_unknown, type_regular_file, &
-        type_directory, type_symlink
+    use stdlib_system, only: exists, fs_type_unknown, fs_type_regular_file, &
+        fs_type_directory, fs_type_symlink
     use stdlib_error, only: state_type
     implicit none
 
@@ -19,12 +19,12 @@ program example_exists
         print *, err%print()
     end if
 
-    ! switching on the types returned by `exists`
+    ! switching on the type returned by `exists`
     select case (t)
-    case (type_unknown); print *, "Unknown type!"
-    case (type_regular_file); print *, "Regular File!"
-    case (type_directory); print *, "Directory!"
-    case (type_symlink); print *, "Symbolic Link!"
+    case (fs_type_unknown); print *, "Unknown type!"
+    case (fs_type_regular_file); print *, "Regular File!"
+    case (fs_type_directory); print *, "Directory!"
+    case (fs_type_symlink); print *, "Symbolic Link!"
     end select
 end program example_exists
 

src/stdlib_system.F90

@@ -211,13 +211,13 @@ module stdlib_system
 !> ([Specification](../page/specs/stdlib_system.html))
 integer, parameter, public :: &
     !> Represents an unknown path type
-    type_unknown      = 0, &
+    fs_type_unknown      = 0, &
     !> Represents a regular file
-    type_regular_file = 1, &
+    fs_type_regular_file = 1, &
     !> Represents a directory
-    type_directory    = 2, &
+    fs_type_directory    = 2, &
     !> Represents a symbolic link
-    type_symlink      = 3
+    fs_type_symlink      = 3
 
 !! version: experimental
 !!

src/stdlib_system.c

@@ -78,27 +78,27 @@ int stdlib_remove_directory(const char* path){
 // Returns the `type` of the path, and sets the `stat`(if any errors).
 int stdlib_exists(const char* path, int* stat){
     // All the valid types
-    const int type_unknown = 0;
-    const int type_regular_file = 1;
-    const int type_directory = 2;
-    const int type_symlink = 3;
+    const int fs_type_unknown = 0;
+    const int fs_type_regular_file = 1;
+    const int fs_type_directory = 2;
+    const int fs_type_symlink = 3;
 
-    int type = type_unknown;
+    int type = fs_type_unknown;
     *stat = 0;
 
 #ifdef _WIN32
     DWORD attrs = GetFileAttributesA(path);
 
     if (attrs == INVALID_FILE_ATTRIBUTES) {
         *stat = (int) GetLastError();
-        return type_unknown;
+        return fs_type_unknown;
     }
 
     // Let's assume it is a regular file
-    type = type_regular_file;
+    type = fs_type_regular_file;
 
-    if (attrs & FILE_ATTRIBUTE_REPARSE_POINT) type = type_symlink;
-    if (attrs & FILE_ATTRIBUTE_DIRECTORY) type = type_directory;
+    if (attrs & FILE_ATTRIBUTE_REPARSE_POINT) type = fs_type_symlink;
+    if (attrs & FILE_ATTRIBUTE_DIRECTORY) type = fs_type_directory;
 #else
     struct stat buf = {0};
     int status;
@@ -107,14 +107,14 @@ int stdlib_exists(const char* path, int* stat){
     if (status == -1) {
         // `lstat` failed
         *stat = errno;
-        return type_unknown;
+        return fs_type_unknown;
     }
 
     switch (buf.st_mode & S_IFMT) {
-        case S_IFREG: type = type_regular_file; break;
-        case S_IFDIR: type = type_directory;    break;
-        case S_IFLNK: type = type_symlink;      break;
-        default:      type = type_unknown;      break;
+        case S_IFREG: type = fs_type_regular_file; break;
+        case S_IFDIR: type = fs_type_directory;    break;
+        case S_IFLNK: type = fs_type_symlink;      break;
+        default:      type = fs_type_unknown;      break;
     }
 #endif /* ifdef _WIN32 */
     return type;

test/system/test_filesystem.f90

@@ -2,7 +2,7 @@ module test_filesystem
     use testdrive, only : new_unittest, unittest_type, error_type, check, skip_test
     use stdlib_system, only: is_directory, delete_file, FS_ERROR, FS_ERROR_CODE, &
         make_directory, remove_directory, make_directory_all, is_windows, OS_TYPE, &
-        OS_WINDOWS, exists, type_unknown, type_regular_file, type_directory, type_symlink
+        OS_WINDOWS, exists, fs_type_unknown, fs_type_regular_file, fs_type_directory, fs_type_symlink
     use stdlib_error, only: state_type, STDLIB_FS_ERROR
     use stdlib_strings, only: to_string
 
@@ -89,7 +89,7 @@ subroutine test_exists_reg_file(error)
             return
         end if
 
-        call check(error, t == type_regular_file, "exists incorrectly identifies type of &
+        call check(error, t == fs_type_regular_file, "exists incorrectly identifies type of &
             reg files!: type=" // to_string(t))
 
         if (allocated(error)) then
@@ -130,7 +130,7 @@ subroutine test_exists_dir(error)
             return
         end if
 
-        call check(error, t == type_directory, "exists incorrectly identifies type of &
+        call check(error, t == fs_type_directory, "exists incorrectly identifies type of &
             directories!: type=" // to_string(t))
 
         if (allocated(error)) then
@@ -193,7 +193,7 @@ subroutine test_exists_symlink(error)
             return
         end if
 
-        call check(error, t == type_symlink, "exists incorrectly identifies type of &
+        call check(error, t == fs_type_symlink, "exists incorrectly identifies type of &
             symlinks!: type=" // to_string(t))
 
         if (allocated(error)) then