Crate dir_structure

Expand description

A library for reading and writing directory structures.

This library provides a macro for defining directory structures, and a trait for reading and writing those structures to / from disk.

§Example

§Writing a structure to disk

use std::path::Path;
fn main() -> Result<(), Box<dyn std::error::Error>> {
    use dir_structure::DirStructureItem;
    #[derive(dir_structure::DirStructure)]
    struct Dir {
        #[dir_structure(path = "f1.txt")]
        f1: String,
        #[dir_structure(path = "subdir/f2.txt")]
        f2: String,
        // default path is just a file name from the field's name.
        f3: String,
        // also works with nested structures
        #[dir_structure(path = "subdir2")]
        subdir: Subdir,
    }
    #[derive(dir_structure::DirStructure)]
    struct Subdir {
        #[dir_structure(path = "f4.txt")]
        f4: String,
    }

    let d = Path::new("dir");
    Dir {
        f1: "f1".to_owned(),
        f2: "f2".to_owned(),
        f3: "f3".to_owned(),
        subdir: Subdir {
            f4: "f4".to_owned(),
        },
    }.write(&d)?;
    assert_eq!(std::fs::read_to_string(d.join("f1.txt"))?, "f1");
    assert_eq!(std::fs::read_to_string(d.join("subdir/f2.txt"))?, "f2");
    assert_eq!(std::fs::read_to_string(d.join("f3"))?, "f3");
    assert_eq!(std::fs::read_to_string(d.join("subdir2/f4.txt"))?, "f4");


    Ok(())
}

§Reading a structure from disk

use std::path::Path;
fn main() -> Result<(), Box<dyn std::error::Error>> {
    use dir_structure::DirStructureItem;
    #[derive(dir_structure::DirStructure)]
    struct Dir {
        #[dir_structure(path = "f1.txt")]
        f1: String,
        #[dir_structure(path = "subdir/f2.txt")]
        f2: String,
        // default path is just a file name from the field's name.
        f3: String,
        // also works with nested structures
        #[dir_structure(path = "subdir2")]
        subdir: Subdir,
    }
    #[derive(dir_structure::DirStructure)]
    struct Subdir {
        #[dir_structure(path = "f4.txt")]
        f4: String,
    }
    let d = Path::new("dir");
    std::fs::create_dir_all(&d)?;
    std::fs::create_dir_all(d.join("subdir"))?;
    std::fs::create_dir_all(d.join("subdir2"))?;
    std::fs::write(d.join("f1.txt"), "f1")?;
    std::fs::write(d.join("subdir/f2.txt"), "f2")?;
    std::fs::write(d.join("f3"), "f3")?;
    std::fs::write(d.join("subdir2/f4.txt"), "f4")?;
    let dir = Dir::read(&d)?;
    assert_eq!(dir.f1, "f1");
    assert_eq!(dir.f2, "f2");
    assert_eq!(dir.f3, "f3");
    assert_eq!(dir.subdir.f4, "f4");


    Ok(())
}

Modules§

jsonjson: With the json feature, this module provides the Json type,
ronron: With the ron feature, this module provides the Ron type,
tomltoml: With the toml feature, this module provides the Toml type,
yamlyaml: With the yaml feature, this module provides the Yaml type,

Macros§

dir_children_wrapper: A simple macro that generates a DirChildren newtype, together with a few impls to make it easy to use.

Structs§

CleanDir: A newtype that will clean the directory it is written to, before writing the value.
CleanDirRefWr: WriteTo impl for CleanDir
DeferredRead: A wrapper that defers the reading of a file until it is actually needed.
DirChild: A single child of a DirChildren structure.
DirChildren: A directory structure where we don’t know the names of the folders at compile-time, and as such we cannot use the derive macro.
DirChildrenIter: A DirChildren iterator. It iterates over the children of a DirChildren structure.
FileBytes: A newtype around a Vec<u8>.
FileBytesRefWr: The WriteTo wrapper around a reference to a [u8].
FileStrWr: The WriteTo wrapper around a reference to a str.
FileString: A newtype around a String.
FmtWrapper: A wrapper around a type which will use the Display and FromStr implementations for serialization / deserialization.
FmtWrapperRefWr: A WriteTo wrapper around a reference to a type which will use the Display implementation to write the value.
NoFilter: A Filter that allows all paths.
Versioned: A versioned value. This is a wrapper around a value that will keep track of how many times it has been changed. This is useful to not write the value to disk if it hasn’t changed.

Enums§

DeferredReadOrOwn: A wrapper that defers the reading of a file until it is actually needed, but can also store the value.
Error: The error type for this library.

Traits§

DirStructure: The main trait. This is implemented for all directory structures by the derive macro.
DirStructureItem: Helper trait, implemented for all types that have a ReadFrom and WriteTo implementation.
Filter: A filter for the children of a DirChildren structure.
FromRefForWriter: Trait to use when using the with_newtype attribute.
NewtypeToInner: Trait to use when using the with_newtype attribute.
ReadFrom: Trait for types / structures that can be read from disk, either from a file or a directory.
WriteTo: Trait for types / structures that can be written to disk. All types in the library that write to files first check that the parent directories exist, so implementations of this that create the whole directory are not necessary (unless used empty children directories, in which case no directories will really be created).

Type Aliases§

Result
VersionedBytes
VersionedString

Derive Macros§

DirStructure

Crate dir_structureCopy item path