feat: exists to return the type of a path

[wassup05]

User facing stuff added are

• integer function exists (path [, err]) to check if a file exists and return it's type.
• integer parameters, type_unknown, type_regular_file, type_directory, type_symlink which are the return values of the exists function.

To accomplish this, on unix lstat is used and on windows GetFileAttributesA is used.

1. If any errors, type_unknown is returned
2. the code and the string describing the code are provided through FS_ERROR_CODE (using strerror on unix and FormatMessageA on windows).
3. and to accomplish this platform based error handling c_getstrerr now takes a logical winapi argument to switch between these two functions (strerror and FormatMessageA).

[sebastian-mutz]

Thanks for this PR, @wassup05!
Functionality seems fine; would strongly recommend commenting the code a little more here and there to make it easier to maintain down the line by people other than those intimately familiar with the system modules.

[perazz]

Thank you for this PR @wassup05, I think the implementation is almost ready. The biggest comment I have is about harmonization with the rest of the library.

We already have is_directory, so I think we should introduce similar functionality to is_link and is_file. Same thing for delete_file and remove_directory , we probably need unlink (or remove_link) and create_link?

[perazz]

Should we differentiate between a missing and an invalid object? What do other libraries do in this respect?

[wassup05]

I don't think it is possible to do that, because the respective syscalls may error out, then we don't truly know the status of the path, whether it is missing or invalid, also windows only returns INVALID_FILE_ATTRIBUTES, not differentiating between some runtime error or the path not existing, that part is done by the GetLastError and I think we could also keep it that way for simplicity.

[perazz]

Ok so for now, I agree to just leave it unknown and assume we cannot differentiate between an actually missing entity and a malformed path yet.

[wassup05]

We already have is_directory, so I think we should introduce similar functionality to is_link and is_file. Same thing for delete_file and remove_directory , we probably need unlink (or remove_link) and create_link?

Regarding this there is one thing I wanted to discuss.. in unix all the types such as S_IFDIR etc are mutually exclusive, meaning only one of the 6 types will be set, but in windows they are not, which means a file CAN have more than one attributes set... This could lead to a potential misunderstanding that just because a path is fs_type_symlink it cannot be fs_type_directory which is in fact not true, this is how directory symlinks work on windows...

So I wonder if we should go ahead with these is_ functions instead of trying to assign a unique type to a path? Also should we include more is_ functions that are not really cross platform? Like Python's os.path.is_junction

[perazz]

This is the way that feels most natural to me:

• regular file -> is_file = .true., is_directory = .false., is_symlink=.false., exists = type_file
• regular dir -> is_file = .false., is_directory = .true., is_symlink=.false., exists = type_dir
• link to file -> is_file = .true., is_directory = .false., is_symlink=.true., exists = type_link
• link to dir -> is_file = .false., is_directory = .true., is_symlink=.true., exists = type_link

But of course I suggest further ideas about this be discussed.

[wassup05]

That seems reasonable @perazz, I have added is_symlink and is_regular_file.
Let me know if it looks good and I will add the specs and examples

[sebastian-mutz]

Thanks, @wassup05. The reworked and new docs and addition of is_regular_file and is_symlink look good to me. Let's wait a little to see what others think.

[perazz]

LGTM @wassup05 @sebastian-mutz, except I is_file looks more natural to me than is_regular_file, and in line with is_directory (we don't have is_regular_dir there). What do you think?

[wassup05]

is_file does feel better and concise, but because of the parameter fs_type_regular_file and to be consistent with that I have named it is_regular_file.. I don't have a particular preference as such

[sebastian-mutz]

Hi @wassup05. Perhaps this consistency matters a little less than having a slightly more intuitive is_file, which users will be more exposed to? That said, I see your logic and honestly have no strong opinion either way.

[wassup05]

Another point to discuss I feel is, should these is_ functions provide optional error handling capabilities using the usual state_type instead of just being logical?

[sebastian-mutz]

Can you highlight some specific advantages you see in using state_type/what error handling capabilities you think would be beneficial to these?

[wassup05]

It's the same as many other functions that have been added over time, let's say exists in this current PR itself, it takes an optional, intent(out) argument of type state_type and let's say there is some error like the many errors described here (in the ERRORS section) the err argument properly describes what happened.

The same reasoning can be applied to is_directory, is_file, is_symlink.. instead of just a plain .false as the return value regardless of any ERROR that may have occured, we could properly provide the user with the specific details of what actually went wrong.

[perazz]

LGTM with the attached comment @wassup05, thank you for this PR.
Regarding the logical functions, I agree that (separation of concerns) they should not return a state flag, but just match the underlying logic such is done already.

Think about condition "value>0"
-> true if value = 1.0, 1234.5, +Inf
-> false if value = 0.0, -123. NaN, -Inf

So it seems consistent to me that the edge cases are already considered by the boolean condition.

[perazz]

Since we are advertising it, would it be reaonable to add a test that checks ./test_file on all systems, and also .\test_file on Windows

[wassup05]

I don't think I understand what you mean, do you mean a sort of utility test function to make the tests simpler and extensive by checking both the kinds of paths for all the tests?

[perazz]

I believe it would be useful if the tests tested filename but also ./filename (on all OSes) and .\filename (on Windows only)