Trait disk::Empty

pub trait Empty: Serialize + DeserializeOwned {
    const OS_DIRECTORY: Dir;
    const PROJECT_DIRECTORY: &'static str;
    const SUB_DIRECTORIES: &'static str;
    const FILE_NAME: &'static str;

    // Provided methods
    fn mkdir() -> Result<(), Error> { ... }
    fn rm_rf() -> Result<(), Error> { ... }
    fn rm() -> Result<(), Error> { ... }
    fn exists() -> Result<bool, Error> { ... }
    fn project_dir() -> &'static str { ... }
    fn sub_dirs() -> &'static str { ... }
    fn file_name() -> &'static str { ... }
    fn base_path() -> Result<PathBuf, Error> { ... }
    fn absolute_path() -> Result<PathBuf, Error> { ... }
    fn touch() -> Result<(), Error> { ... }
}

Empty file

This is a an empty file. It contains no data, but it inherits useful PATH methods. Typically used for file-based signals.

If you implement this on a struct that contains data, the data will be ignored and an empty file will always be created.

The file created will have no file extension, e.g:

empty_file!(Hello, Dir::Data, "disk_test", "signal", "hello");
#[derive(Serialize, Deserialize)]
struct Hello {
    data: bool,
}

// The filename should be "hello".
assert!(Hello::file_name() == "hello");

// Create the file.
Hello::touch().unwrap();

// Make sure it (and the directories) exist.
assert!(Hello::exists().unwrap());

// Delete the project directory.
Hello::rm_rf().unwrap();

// Make sure the file no longer exist.
assert!(!Hello::exists().unwrap());

This creates a file called hello, containing no data. The bool is ignored.

The PATH on Linux would be: ~/.local/share/disk_test/signal/hello.

Required Associated Constants

const OS_DIRECTORY: Dir

Which OS directory it will be saved in.

const PROJECT_DIRECTORY: &'static str

What the main project directory will be.

const SUB_DIRECTORIES: &'static str

Optional sub directories in between the project directory and file.

const FILE_NAME: &'static str

What the filename will be.

Provided Methods

fn mkdir() -> Result<(), Error>

Create the directories leading up-to the file.

This is not necessary when using any variant of Self::save() as the directories are created implicitly.

fn rm_rf() -> Result<(), Error>

Recursively remove this file’s project directory.

This deletes all directories starting from Self::PROJECT_DIRECTORY. For example:

toml_file!(State, Dir::Data, "MyProject", "sub_dir", "state");

This project’s file would be located at ~/.local/share/myproject. This is the PATH that gets removed recursively.

This is akin to running:

rm -rf ~/.local/share/myproject

The input to all *_file! macros are sanity checked. The worst you can do with this function is delete your project’s directory.

WARNING

If you manually implement disk traits, you are able to specify / or C:. disk will delete your entire drive if you tell it to.

fn rm() -> Result<(), Error>

Try deleting the current file associated with the Rust structure.

This will return success if the file doesn’t exist or if deleted.

It will return failure if the file existed but could not be deleted or if any other error occurs.

fn exists() -> Result<bool, Error>

Check if the file exists.

true == The file exists. false == The file does not exist. anyhow::Error == There was an error, existance is unknown.

fn project_dir() -> &'static str

The main project directory.

You can also access this directly on your type:

toml_file!(Data, Dir::Cache, "MyProject", "", "data");
#[derive(Serialize, Deserialize)]
struct Data(u64);

assert!(Data::project_dir() == Data::PROJECT_DIRECTORY);

fn sub_dirs() -> &'static str

The directories after the main project directory, before the file. (the first directory specified in the SUB_DIRECTORIES constant).

You can also access this directly on your type:

toml_file!(Data, Dir::Cache, "MyProject", "sub_directory", "data");
#[derive(Serialize, Deserialize)]
struct Data(u64);

assert!(Data::sub_dirs() == Data::SUB_DIRECTORIES);

fn file_name() -> &'static str

The filename + extension associated with this struct.

You can also access this directly on your type:

toml_file!(Data, Dir::Cache, "MyProject", "", "data");
#[derive(Serialize, Deserialize)]
struct Data(u64);

assert!(Data::file_name() == Data::FILE_NAME);

fn base_path() -> Result<PathBuf, Error>

The base path associated with this struct (PATH leading up to the file).

fn absolute_path() -> Result<PathBuf, Error>

The absolute PATH of the file associated with this struct.

fn touch() -> Result<(), Error>

Try creating an empty file associated with this struct.

Calling this will automatically create the directories leading up to the file.

Implementors