Trait Empty

pub unsafe trait Empty {
    const OS_DIRECTORY: Dir;
    const PROJECT_DIRECTORY: &'static str;
    const SUB_DIRECTORIES: &'static str;
    const FILE: &'static str;
    const FILE_EXT: &'static str;
    const FILE_NAME: &'static str;
    const FILE_NAME_GZIP: &'static str;
    const FILE_NAME_TMP: &'static str;
    const FILE_NAME_GZIP_TMP: &'static str;

    // Provided methods
    fn touch() -> Result<(), Error> { ... }
    fn mkdir() -> Result<PathBuf, Error> { ... }
    fn exists() -> Result<Metadata, Error> { ... }
    fn file_size() -> Result<Metadata, Error> { ... }
    fn base_path() -> Result<PathBuf, Error> { ... }
    fn absolute_path() -> Result<PathBuf, Error> { ... }
    fn rm() -> Result<Metadata, Error> { ... }
    fn rm_base() -> Result<Metadata, Error> { ... }
    fn rm_sub() -> Result<Metadata, Error> { ... }
    fn rm_project() -> Result<Metadata, Error> { ... }
    fn sub_dir_size() -> Result<Metadata, Error> { ... }
    fn project_dir_size() -> Result<Metadata, Error> { ... }
    fn project_dir_path() -> Result<PathBuf, Error> { ... }
    fn sub_dir_parent_path() -> Result<PathBuf, Error> { ... }
}

Available on crate feature empty only.

Empty file

This is a an empty file that

• Contains no data
• Doesn’t need serde
• 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:

disk::empty!(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().is_ok());

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

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

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.

Safety

When manually implementing, you are promising that the PATH’s manually specified are correct.

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: &'static str

What the raw file name will be (no extension).

const FILE_EXT: &'static str

What the file extension will be.

const FILE_NAME: &'static str

What the full filename + extension will be.

const FILE_NAME_GZIP: &'static str

What the gzip variant of the filename will be.

const FILE_NAME_TMP: &'static str

What the tmp variant of the filename will be.

const FILE_NAME_GZIP_TMP: &'static str

What the gzip + tmp variant of the filename will be.

Provided Methods

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.

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

Create the directories leading up-to the file.

Returns the PathBuf created on success.

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

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

Check if the file exists.

On success, this returns:

• The file size in bytes
• The PathBuf it’s located at

fn file_size() -> Result<Metadata, Error>

Returns the file size in bytes and it’s PathBuf.

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

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

In contrast to Self::sub_dir_parent_path, this returns all sub-directories, e.g: my/sub/dirs would return /.../my/sub/dirs

This includes Self::PROJECT_DIRECTORY, Self::SUB_DIRECTORIES and excludes Self::FILE_NAME.

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

Returns the absolute PATH of the file associated with this struct.

This includes Self::PROJECT_DIRECTORY, Self::SUB_DIRECTORIES and Self::FILE_NAME.

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

Try deleting the file.

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.

On success, this returns:

• The amount of bytes removed
• The PathBuf that was removed

fn rm_base() -> Result<Metadata, Error>

Recursively remove this file’s basepath.

This deletes all directories starting from the last Self::SUB_DIRECTORIES.

AKA, the directory returned from Self::base_path.

For example:

disk::toml!(State, disk::Dir::Data, "MyProject", "some/sub/dirs", "state");

Everything starting from ~/.local/share/myproject/some/sub/dirs gets removed recursively.

This is akin to running:

rm -rf ~/.local/share/myproject/some/sub/dirs

This function calls std::fs::remove_dir_all, which does not follow symlinks.

On success, this returns:

• The amount of bytes removed
• The PathBuf that was removed

fn rm_sub() -> Result<Metadata, Error>

Recursively remove this file’s sub-directories.

This deletes all directories starting from the parent Self::SUB_DIRECTORIES. For example:

disk::toml!(State, disk::Dir::Data, "MyProject", "some/sub/dirs", "state");

Everything starting from ~/.local/share/myproject/some gets removed recursively.

This is akin to running:

rm -rf ~/.local/share/myproject/some

This function calls std::fs::remove_dir_all, which does not follow symlinks.

On success, this returns:

• The amount of bytes removed
• The PathBuf that was removed

fn rm_project() -> Result<Metadata, Error>

Recursively remove this file’s project directory.

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

disk::toml!(State, disk::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 disk macros are sanity checked. The worst you can do with this function is delete your project’s directory.

This function calls std::fs::remove_dir_all, which does not follow symlinks.

On success, this returns:

• The amount of bytes removed
• The PathBuf that was removed

fn sub_dir_size() -> Result<Metadata, Error>

Returns the file’s parent sub-directory size in bytes and it’s PathBuf.

This errors if the PATH does not exist.

This starts from the first Self::SUB_DIRECTORIES, and does not include the Self::PROJECT_DIRECTORY.

fn project_dir_size() -> Result<Metadata, Error>

Returns the file’s project directory size in bytes (Self::PROJECT_DIRECTORY) and it’s PathBuf.

This errors if the PATH does not exist.

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

Return the full parent project directory associated with this struct.

This is the PATH leading up to Self::PROJECT_DIRECTORY.

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

Returns the top-level parent sub-directory associated with this struct.

This only returns the top level sub-directory, so if multiple are defined, only the first will be returned, e.g: my/sub/dirs would return /.../my

If no sub-directory is defined, this will return the PATH leading up to Self::PROJECT_DIRECTORY.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors