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]            |                                                                                                                                            |
| ----- | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [ ]   | 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.                                                                         |
| [ ]   | 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.                                                                                |
| [ ]   | write            | file::write           | Write a slice as the entire contents of a file.                                                                                            |
| [ ]   | try_exists       | path::exists          | Returns Ok(true) if the path points at an existing entity.                                                                                 |

### 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.