Crate dir_structure

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(())
}

Macros

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

Structs

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

Enums

• DeferredReadOrOwn
  A wrapper that defers the reading of a file until it is actually needed.
• Error

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

Derive Macros

• DirStructure