Trait disk::MessagePack

pub unsafe trait MessagePack: 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 mkdir() -> Result<(), Error> { ... }
    fn rm_rf() -> Result<(), Error> { ... }
    fn rm() -> Result<(), Error> { ... }
    fn exists() -> Result<bool, Error> { ... }
    fn file_size() -> Result<u64, Error> { ... }
    fn sub_dir_size() -> Result<u64, Error> { ... }
    fn project_dir_size() -> Result<u64, Error> { ... }
    fn project_dir_path() -> Result<PathBuf, Error> { ... }
    fn sub_dir_parent_path() -> Result<PathBuf, Error> { ... }
    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> { ... }
    unsafe fn from_file_memmap() -> 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() -> Result<(), Error> { ... }
    fn rm_atomic_gzip() -> Result<(), Error> { ... }
    fn rm_tmp() -> Result<(), Error> { ... }
    fn absolute_path_gzip() -> Result<PathBuf, Error> { ... }
    fn file_bytes(start: usize, end: usize) -> Result<Vec<u8>, Error> { ... }
    fn into_writable_fmt(&self) -> Result<Vec<u8>, Error> { ... }
    fn from_bytes(bytes: &[u8]) -> Result<Self, Error> { ... }
    fn to_bytes(&self) -> Result<Vec<u8>, Error> { ... }
}

MessagePack (binary) file format

File extension is .messagepack.

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

fn rm() -> Result<(), 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.

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 file_size() -> Result<u64, Error>

Returns the file size in bytes.

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

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

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

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

Returns the file’s project directory size in bytes (Self::PROJECT_DIRECTORY)

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.

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

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

Read the file using memmap2 and deserialize into Self.

Safety

Using this function can be much faster than Self::from_file but you must understand this all the invariants that memmap comes with.

When these invariants are broken, Undefined Behavior (UB) will occur.

More details here.

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

Try saving as a file.

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

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

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

Turn Self into bytes that can be written to disk.

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

Create a struct/enum from bytes.

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

Convert a struct/enum to bytes.

Implementors