Trait disk::Yaml

pub unsafe trait Yaml: Serialize + DeserializeOwned {
    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 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 into_writeable_fmt(&self) -> Result<String, Error> { ... }
    fn read_to_string() -> Result<String, Error> { ... }
    fn read_to_bytes() -> Result<Vec<u8>, Error> { ... }
    fn read_to_bytes_gzip() -> Result<Vec<u8>, Error> { ... }
    fn exists_gzip() -> Result<Metadata, Error> { ... }
    fn from_file() -> Result<Self, Error> { ... }
    fn from_file_gzip() -> Result<Self, Error> { ... }
    unsafe fn from_file_memmap() -> Result<Self, Error> { ... }
    unsafe fn from_file_gzip_memmap() -> Result<Self, Error> { ... }
    fn save(&self) -> Result<Metadata, Error> { ... }
    unsafe fn save_memmap(&self) -> Result<Metadata, Error> { ... }
    fn save_gzip(&self) -> Result<Metadata, Error> { ... }
    unsafe fn save_gzip_memmap(&self) -> Result<Metadata, Error> { ... }
    fn save_atomic(&self) -> Result<Metadata, Error> { ... }
    fn save_atomic_gzip(&self) -> Result<Metadata, Error> { ... }
    unsafe fn save_atomic_memmap(&self) -> Result<Metadata, Error> { ... }
    unsafe fn save_atomic_gzip_memmap(&self) -> Result<Metadata, Error> { ... }
    fn rm_atomic() -> Result<Metadata, Error> { ... }
    fn rm_atomic_gzip() -> Result<Metadata, Error> { ... }
    fn rm_tmp() -> Result<(), Error> { ... }
    fn absolute_path_gzip() -> Result<PathBuf, Error> { ... }
    fn file_size_gzip() -> Result<Metadata, Error> { ... }
    fn file_bytes(start: usize, end: usize) -> Result<Vec<u8>, Error> { ... }
    fn file_bytes_memmap(start: usize, end: usize) -> Result<Vec<u8>, 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_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> { ... }
}

YAML file format

File extension is .yml.

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 to_bytes(&self) -> Result<Vec<u8>, Error>

Convert Self to bytes.

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

Create Self from bytes.

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

Convert Self to a String.

This uses toml_edit::ser::to_string_pretty;

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

Create Self from String.

fn into_writeable_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 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<Metadata, Error>

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

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

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

Read the file as bytes and deserialize into Self.

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

Read the file as bytes, decompress with gzip and deserialize into Self.

unsafe fn from_file_memmap() -> Result<Self, Error>

Same as Self::from_file but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

unsafe fn from_file_gzip_memmap() -> Result<Self, Error>

Same as Self::from_file_gzip but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

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

Try saving as a file.

This will return the amount of bytes saved and the PathBuf on success.

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

unsafe fn save_memmap(&self) -> Result<Metadata, Error>

Same as Self::save but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

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

Try saving as a compressed file using gzip.

On success, this will return:

• The amount of compressed bytes saved to disk
• The PathBuf of the file

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.

unsafe fn save_gzip_memmap(&self) -> Result<Metadata, Error>

Same as Self::save_gzip but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

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

Try saving 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.

This will return the amount of bytes saved and the PathBuf on success.

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

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

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

unsafe fn save_atomic_memmap(&self) -> Result<Metadata, Error>

Same as Self::save_atomic() but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

unsafe fn save_atomic_gzip_memmap(&self) -> Result<Metadata, Error>

Same as Self::save_atomic_gzip() but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

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

Rename the associated file before attempting to delete it.

This lowers the chance for data corruption on interrupt.

On success, this returns:

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

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() -> Result<Metadata, 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 file_size_gzip() -> Result<Metadata, Error>

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

fn file_bytes(start: usize, end: usize) -> Result<Vec<u8>, Error>

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

Errors

If start is greater than end, this returns error.

fn file_bytes_memmap(start: usize, end: usize) -> Result<Vec<u8>, Error>

Same as Self::file_bytes but with memmap2.

Safety

You must understand all the invariants that memmap comes with.

More details here.

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

Implementors