Crate disk

Disk: serde + directories + a whole bunch of file formats as Traits.

This crate is for (de)serializing to/from various file formats (provided by serde) to/from disk locations that follow OS-specific specifications/conventions (provided by directories). All errors returned will be an anyhow::Error.

Example of data being saved on the user’s disk for future use:

use disk::prelude::*;       // Necessary imports to get things working.
use disk::{Toml,toml_file}; // <- TOML trait & macro.
use serde::{Serialize, Deserialize};

#[derive(Serialize,Deserialize)] // <- Your data must implement `serde`.
struct State {
	string: String,
	number: u32,
}
// To make this struct a file, use the following macro:
//
// |- 1. The file format used will be TOML.
// |
// |          |- 2. The struct "State" will be used.
// |          |
// |          |      |- 3. It will be saved in the OS Data directory.
// |          |      |
// |          |      |          |- 4. The main project directory is called "MyProject".
// |          |      |          |
// |          |      |          |            |- 6. It won't be in any sub-directories.
// |          |      |          |            |
// |          |      |          |            |   |- 7. The file name will be "state.toml".
// v          v      v          v            v   v
   toml_file!(State, Dir::Data, "MyProject", "", "state");

// Now our `State` struct implements the `Toml` trait.
//
// The PATH would look something like:
// Windows | C:\Users\Alice\AppData\Roaming\My_Project\state.toml
// macOS   | /Users/Alice/Library/Application Support/My-Project/state.toml
// Linux   | /home/alice/.local/share/myproject/state.toml

// I'd like to save this to disk, since I'll use it next time.
let my_state = State { string: "Hello".to_string(), number: 123 };

// Since our `State` struct implements the `Toml` trait, it can do that:
match my_state.save() {
	Ok(_) => println!("We saved to disk"),
	Err(e) => eprintln!("We failed to save to disk"),
}

// Let's create a new `State` by reading the file that we just created:
let new_state = State::from_file().expect("Failed to read disk");

// These should be the same.
assert!(my_state == new_state);

Manually implementing these traits is possible as well, it requires 4 constants to be defined.

The file extension (.bin, .toml, .json, .bson, etc) is inferred based on what trait you use.

impl disk::Toml for State {
    // Which OS directory it will be saved in.
	const OS_DIRECTORY: disk::Dir = disk::Dir::Data;
    // Which the main project directory is called.
	const PROJECT_DIRECTORY: &'static str = "MyProject";
    // If it should be in any sub-directories.
    const SUB_DIRECTORIES: &'static str = ""
    // What the saved filename will be.
	const FILE_NAME: &'static str = "state";
}

Either a single or multiple sub-directories can be specified with a / delimiter.

\ is also allowed but ONLY if building on Windows.

An empty string "" means NO sub directories.

// Windows ... C:\Users\Alice\AppData\Roaming\My_Project\sub1\sub2\state.toml
toml_file!(State, Data, "MyProject", r"sub1\sub2", "state");

// macOS ... /Users/Alice/Library/Application Support/My-Project/sub1/sub2/state.json
json_file!(State, Data, "MyProject", "sub1/sub2", "state");

// Linux ... /home/alice/.local/share/myproject/sub1/sub2/state.yml
yaml_file!(State, Data, "MyProject", "sub1/sub2", "state");

// NO sub directory:
toml_file!(State, Data, "MyProject", "", "state");

File Formats

Use the feature flag full to enable everything.

File Format	Feature flag to enable
Bincode	bincode
Postcard	postcard
JSON	json
TOML	toml
YAML	yaml
Pickle	pickle
MessagePack	messagepack
BSON	bson
Plain Text	plain
Empty File	empty

Modules

• prelude

Macros

• bincode_file
  Quickly implement the Bincode trait.
• bson_file
  Quickly implement the Bson trait.
• empty_file
  Quickly implement the Empty trait.
• json_file
  Quickly implement the Json trait.
• messagepack_file
  Quickly implement the MessagePack trait.
• pickle_file
  Quickly implement the Pickle trait.
• plain_file
  Quickly implement the Plain trait.
• postcard_file
  Quickly implement the Postcard trait.
• toml_file
  Quickly implement the Toml trait.
• yaml_file
  Quickly implement the Yaml trait.

Traits

• Bincode
  Bincode (binary) file format
• Bson
  Bson (binary) file format
• Empty
  Empty file
• Json
  JSON file format
• MessagePack
  MessagePack (binary) file format
• Pickle
  Pickle (binary) file format
• Plain
  Plain text file format
• Postcard
  Postcard (binary) file format
• Toml
  TOML file format
• Yaml
  YAML file format