Trait disk::Plain

pub trait Plain: 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 read_to_bytes() -> Result<Vec<u8>, Error> { ... }
    fn read_to_bytes_gzip() -> Result<Vec<u8>, Error> { ... }
    fn exists_gzip() -> Result<bool, Error> { ... }
    fn from_file() -> Result<Self, Error> { ... }
    fn from_file_gzip() -> Result<Self, Error> { ... }
    fn save(&self) -> Result<(), Error> { ... }
    fn save_gzip(&self) -> Result<(), Error> { ... }
    fn save_atomic(&self) -> Result<(), Error> { ... }
    fn save_atomic_gzip(&self) -> Result<(), Error> { ... }
    fn rm_atomic(&self) -> Result<(), Error> { ... }
    fn rm_atomic_gzip(&self) -> Result<(), Error> { ... }
    fn rm_tmp() -> Result<(), Error> { ... }
    fn absolute_path_gzip() -> Result<PathBuf, Error> { ... }
    fn into_writable_fmt(&self) -> Result<String, Error> { ... }
    fn read_to_string() -> Result<String, Error> { ... }
    fn info_dash(string: &str) { ... }
    fn to_bytes(&self) -> Result<Vec<u8>, Error> { ... }
    fn from_bytes(bytes: &[u8]) -> Result<Self, Error> { ... }
    fn to_string(&self) -> Result<String, Error> { ... }
    fn from_string(string: &str) -> Result<Self, Error> { ... }
    fn file_bytes(range: Range<u16>) -> Result<Vec<u8>, Error> { ... }
}

Plain text file format

This is a plain text file with the file extension .txt. Typically used for small and simple data types like integers, strings, and enums.

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:

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 *_file! 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.

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:

disk::toml!(Data, disk::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:

disk::toml!(Data, disk::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:

disk::toml!(Data, disk::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 read_to_bytes() -> Result<Vec<u8>, Error>

Read the file directly as bytes.

fn read_to_bytes_gzip() -> Result<Vec<u8>, Error>

Read the file directly as bytes, and attempt gzip decompression.

This assumes the file is suffixed with .gz, for example:

config.json    // What `.read_to_bytes()` will look for
config.json.gz // What `.read_to_bytes_gzip()` will look for

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

Same as Self::exists() but checks if the gzip file exists.

• Self::exists() checks for file.toml.
• Self::exists_gzip() checks forfile.toml.gz.

fn from_file() -> Result<Self, Error>

Read the file directly as bytes and turn into a Rust structure.

fn from_file_gzip() -> Result<Self, Error>

Read the file directly as bytes, decompress with gzip and turn into a Rust structure.

fn save(&self) -> Result<(), Error>

Try saving a Rust structure as a file.

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

fn save_gzip(&self) -> Result<(), Error>

Try saving a Rust structure as a compressed file using gzip.

This will suffix the file with .gz, for example:

config.json    // Normal file name with `.save()`
config.json.gz // File name when using `.save_gzip()`

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

fn save_atomic(&self) -> Result<(), Error>

Note: This may not truely be atomic on Windows.

Try saving a Rust structure to a TEMPORARY file first, then renaming it to the associated file.

This lowers the chance for data corruption on interrupt.

The temporary file is removed if the rename fails.

The temporary file name is: file_name + extension + .tmp, for example:

config.toml     // <- Real file
config.toml.tmp // <- Temporary version

Already existing .tmp files will be overwritten.

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

fn save_atomic_gzip(&self) -> Result<(), Error>

Combines Self::save_gzip() and Self::save_atomic().

fn rm_atomic(&self) -> Result<(), Error>

Note: This may not truely be atomic on Windows.

Rename the associated file before attempting to delete it.

This lowers the chance for data corruption on interrupt.

The temporary file name is: file_name + extension + .tmp, for example:

config.toml     // <- Real file
config.toml.tmp // <- Temporary version

Already existing .tmp files will be overwritten.

fn rm_atomic_gzip(&self) -> Result<(), Error>

Same as Self::rm_atomic() but looks for the .gz extension.

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

Try deleting any leftover .tmp files from Self::save_atomic() or Self::save_atomic_gzip()

This will return success if the files don’t exist or if deleted.

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

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

The absolute PATH of the file associated with this struct WITH the .gz extension.

fn into_writable_fmt(&self) -> Result<String, Error>

Turn Self into a String, maintaining formatting if possible.

fn read_to_string() -> Result<String, Error>

Read the file directly as a String.

fn info_dash(string: &str)

Print the file’s contents to console surrounded by dashes with the log crate.

fn to_bytes(&self) -> Result<Vec<u8>, Error>

fn from_bytes(bytes: &[u8]) -> Result<Self, Error>

fn to_string(&self) -> Result<String, Error>

This uses toml_edit::ser::to_string_pretty;

fn from_string(string: &str) -> Result<Self, Error>

fn file_bytes(range: Range<u16>) -> Result<Vec<u8>, Error>

Reads a range of bytes of the associated file of Self.

Implementors