helper functions for Filesystem error handling

[wassup05]

Functions added are:

• fs_error: just sets the flag of state_type to STDLIB_FS_ERROR and passes the remaining 20 arguments to it
• fs_error_code: sets the flag as above and also prefixes the code (integer argument) accordingly.

I tried using an interface block to handle both of these together, but that introduces ambiguity for the compiler.

Could make code an optional argument and depending on if it's present or not pass 18 or 20 arguments to state_type but I feel that the 2 unused arguments in that case would not be correct.

Inspired from @perazz in #1006 (comment)

[jalvesz]

Thanks for this PR @wassup05. Question: is there a reason for using UPPER_CASE ? The style guide promotes snake_case for procedures and constants.

[wassup05]

Oh no, It was just because it was an error and I felt it was better to emphasize that, but I'll change it

[Copilot]

Pull Request Overview

This PR introduces two helper functions fs_error and fs_error_code to simplify filesystem error handling in the stdlib_system module. These functions provide convenient ways to create state_type objects with the STDLIB_FS_ERROR flag set.

• Adds fs_error function that accepts up to 20 optional arguments and creates a filesystem error state
• Adds fs_error_code function that prefixes an error code to the message and accepts up to 19 additional arguments
• Includes comprehensive tests, documentation, and example code

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/stdlib_system.F90	Implements the two new helper functions and adds required imports
test/system/test_filesystem.f90	Adds unit tests for both helper functions
doc/specs/stdlib_system.md	Documents the new functions with detailed specifications
example/system/example_fs_error.f90	Provides usage examples for both functions
example/system/CMakeLists.txt	Registers the new example in the build system

Comments suppressed due to low confidence (2)

test/system/test_filesystem.f90:25

• The subroutine name test_fs_error is inconsistent with the test name test_FS_ERROR used in new_unittest. Consider renaming to test_FS_ERROR for consistency.

    subroutine test_fs_error(error)

doc/specs/stdlib_system.md:472

• The syntax example shows fs_error but should be fs_error_code since this is documenting the fs_error_code function.

`err = fs_error(code [, a1,a2,a3,a4...... a19])`

[jalvesz]

Thanks @wassup05 LGTM

[perazz]

Thanks for this PR @wassup05. I added a few comments.

[perazz]

LGTM, thank you @wassup05. With two approvals, I will merge this one.