Crate rivia 

Provides a unified, simplified systems api including essential macros and extensions to fill in gaps in Rust ergonomics to reduce the amount of boiler plate code required for common tasks. The intent is to provide this while keeping dependencies to a minimum.

Virtual FileSystem (VFS)

Switching out VFS backends

Using the power of Rust enums we can create a simple virtual file system with multiple backend implementations that can easily be switched out at compile time for testing purposes with almost zero additional overhead by simply passing in a vfs reference to functions needing to manipulate the filesystem. For those wishing for a truely seamless experience see the rivia-vfs crate for a global singleton that can be dynamically updated at runtime thus avoiding passing a vfs reference around.

use rivia::prelude::*;

fn main() {
    // Simply replace this line with `let vfs = Vfs::stdfs();` for the real filesystem
    let vfs = Vfs::memfs();
    let config = load_config(vfs);
    assert_eq!(config, "this is a test");
    println!("VFS test passed");
}

// Load an example application configuration file using VFS.
// This allows you to test with a memory backed VFS implementation during testing and with
// the real filesystem during production.
fn load_config(vfs: Vfs) -> String {
    let dir = PathBuf::from("/etc/xdg");
    vfs.mkdir_p(&dir).unwrap();
    let filepath = dir.mash("rivia.toml");
    vfs.write_all(&filepath, "this is a test").unwrap();
    assert_eq!(vfs.config_dir("rivia.toml").unwrap().to_str().unwrap(), "/etc/xdg");

    if let Some(config_dir) = vfs.config_dir("rivia.toml") {
        let path = config_dir.mash("rivia.toml");
        return vfs.read_all(&path).unwrap();
    }
    "".into()
}

Rejected Considerations

VfsPath

VfsPath was considered as a way to track and not repeat environment variable and absolute path resolution. Additionally it would be used in the VFS case to track the VFS backend being used to allow for extensions to a Path to chain call additional operations. However the relative amount of overhead of resolving paths is small when compared to disk IO which will usually be being done. What’s more the benefit of trackig the VFS for chain calling is dubious when you introduce the complexity of multiple ways to get access to VFS operations. Considering the ergonomic impact and commplexity of such a change. I won’t be implementing a notion of a VfsPath in favor of a single point of entry into the VFS operations and much cleaner ergonomics i.e. always use the Filesystem backend trait implementation via Vfs for every Filesystem related operation.

Using Rivia

use rivia::prelude::*;

Modules

core

Provides general extensions to common types like Option, Result and Iterator.

errors

Provides a common set of errors across the rivia crates to reduce the verbosity of error handling

prelude

All essential symbols in a simple consumable way

sys

Provides a unified, simplified systems api

testing

Provides a set of testing functions and macros to reduce testing boiler plate

Macros

assert_vfs_copyfile

Assert the copy of a file

assert_vfs_exists

Assert that a file or directory exists

assert_vfs_is_dir

Assert that the given path exists and is a directory

assert_vfs_is_file

Assert that the given path exists and is a file

assert_vfs_is_symlink

Assert that the given path exists and is a symlink

assert_vfs_mkdir_m

Assert the creation of the given directory with the given mode

assert_vfs_mkdir_p

Assert the creation of the given directory.

assert_vfs_mkfile

Assert the creation of a file. If the file exists no change is made

assert_vfs_no_dir

Assert that the given path isn’t a directory

assert_vfs_no_exists

Assert the given path doesn’t exist

assert_vfs_no_file

Assert that the given path isn’t a file

assert_vfs_no_symlink

Assert that the given path isn’t a symlink

assert_vfs_read_all

Assert data read from the file matches the input data

assert_vfs_readlink

Assert the reading of a link’s target relative path

assert_vfs_readlink_abs

Assert the reading of a link’s target absolute path

assert_vfs_remove

Assert the removal of the target file or directory

assert_vfs_remove_all

Assert the removal of the target path

assert_vfs_setup

Setup Vfs testing components

assert_vfs_symlink

Assert the creation of a symlink. If the symlink exists no change is made

assert_vfs_write_all

Assert data is written to the given file

cfgblock

Provides the ability to define #[cfg] statements for multiple items

defer

Ensure the given closure is executed once the surrounding scope closes

function

Expands to the current function’s name similar to the venerable file! or line!

function_fqn

Expands to the current functions’s fully qualified name

panic_compare_msg

Helper function for testing to simply panic with the given message in a repeatable formatting.

panic_msg

Helper function for testing to simply panic with the given message in a repeatable formatting.

trying

Return an iterator Err type conveniently

unwrap_or_false

Unwrap the value on Ok or return false on Err