kxio/README.md

## kxio

[![status-badge](https://ci.kemitix.net/api/badges/53/status.svg)](https://ci.kemitix.net/repos/53)

Provides injectable Filesystem and Network resources to make code more testable.

### FileSystem

There are two FileSystem implementation: [filesystem] and [fs].

- [filesystem] is the legacy implementation and will be removed in a future version.
- [fs] is the current version and is intended to stand-in for and extend the [std::fs] module from the Standard Library.

#### std::fs alternatives

| To Do | [std::fs]        | [kxio::fs::FileSystem] |                                                                                                                                            |
| ----- | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [ ]   | canonicalize     | path_canonicalize      | Returns the canonical, absolute form of a path with all intermediate components normalized and symbolic links resolved.                    |
| [ ]   | copy             | file_copy              | Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file. |
| [ ]   | create_dir       | dir_create             | Creates a new, empty directory at the provided path                                                                                        |
| [ ]   | create_dir_all   | dir_create_all         | Recursively create a directory and all of its parent components if they are missing.                                                       |
| [ ]   | hard_link        | link_create            | Creates a new hard link on the filesystem.                                                                                                 |
| [ ]   | metadata         | path_metadata          | Given a path, query the file system to get information about a file, directory, etc.                                                       |
| [ ]   | read             | file_read              | Read the entire contents of a file into a bytes vector.                                                                                    |
| [ ]   | read_dir         | dir_read               | Returns an iterator over the entries within a directory.                                                                                   |
| [ ]   | read_link        | link_read              | Reads a symbolic link, returning the file that the link points to.                                                                         |
| [x]   | read_to_string   | file_read_to_string    | Read the entire contents of a file into a string.                                                                                          |
| [ ]   | remove_dir       | dir_remove             | Removes an empty directory.                                                                                                                |
| [ ]   | remove_dir_all   | dir_remove_all         | Removes a directory at this path, after removing all its contents. Use carefully!                                                          |
| [ ]   | remove_file      | file_remove            | Removes a file from the filesystem.                                                                                                        |
| [ ]   | rename           | path_rename            | Rename a file or directory to a new name, replacing the original file if to already exists.                                                |
| [ ]   | set_permissions  | path_set_permissions   | Changes the permissions found on a file or a directory.                                                                                    |
| [ ]   | symlink_metadata | link_metadata          | Query the metadata about a file without following symlinks.                                                                                |
| [x]   | write            | file_write             | Write a slice as the entire contents of a file.                                                                                            |

### Network

The entire [network] module needs to be completly rewritten
It's use is strongly discouraged.
A new [net] module will likely be its replacement.