dir_structure/
lib.rs

1//! A library for reading and writing directory structures.
2//!
3//! This library provides a macro for defining directory structures, and a
4//! trait for reading and writing those structures to / from disk.
5//!
6//! [An intro guide.](https://nrx.dnbln.dev/docs/dx/dir-structure/guide)
7//!
8//! # Example
9//!
10//! ## Writing a structure to disk
11//!
12#![cfg_attr(feature = "derive", doc = "```rust")]
13#![cfg_attr(not(feature = "derive"), doc = "```rust,compile_fail")]
14//! use std::path::Path;
15//! fn main() -> Result<(), Box<dyn std::error::Error>> {
16//!     use dir_structure::traits::sync::DirStructureItem;
17//!     #[derive(dir_structure::DirStructure)]
18//!     struct Dir {
19//!         #[dir_structure(path = "f1.txt")]
20//!         f1: String,
21//!         #[dir_structure(path = "subdir/f2.txt")]
22//!         f2: String,
23//!         // default path is just a file name from the field's name.
24//!         f3: String,
25//!         // also works with nested structures
26//!         #[dir_structure(path = "subdir2")]
27//!         subdir: Subdir,
28//!     }
29//!     #[derive(dir_structure::DirStructure)]
30//!     struct Subdir {
31//!         #[dir_structure(path = "f4.txt")]
32//!         f4: String,
33//!     }
34//!
35//!     let d = Path::new("dir");
36//!     Dir {
37//!         f1: "f1".to_owned(),
38//!         f2: "f2".to_owned(),
39//!         f3: "f3".to_owned(),
40//!         subdir: Subdir {
41//!             f4: "f4".to_owned(),
42//!         },
43//!     }.write(&d)?;
44//!     assert_eq!(std::fs::read_to_string(d.join("f1.txt"))?, "f1");
45//!     assert_eq!(std::fs::read_to_string(d.join("subdir/f2.txt"))?, "f2");
46//!     assert_eq!(std::fs::read_to_string(d.join("f3"))?, "f3");
47//!     assert_eq!(std::fs::read_to_string(d.join("subdir2/f4.txt"))?, "f4");
48//!
49//!     # std::fs::remove_dir_all(&d)?;
50//!
51//!     Ok(())
52//! }
53//! ```
54//!
55//! ## Reading a structure from disk
56//!
57#![cfg_attr(feature = "derive", doc = "```rust")]
58#![cfg_attr(not(feature = "derive"), doc = "```rust,compile_fail")]
59//! use std::path::Path;
60//! fn main() -> Result<(), Box<dyn std::error::Error>> {
61//!     use dir_structure::traits::sync::DirStructureItem;
62//!     #[derive(dir_structure::DirStructure)]
63//!     struct Dir {
64//!         #[dir_structure(path = "f1.txt")]
65//!         f1: String,
66//!         #[dir_structure(path = "subdir/f2.txt")]
67//!         f2: String,
68//!         // default path is just a file name from the field's name.
69//!         f3: String,
70//!         // also works with nested structures
71//!         #[dir_structure(path = "subdir2")]
72//!         subdir: Subdir,
73//!     }
74//!     #[derive(dir_structure::DirStructure)]
75//!     struct Subdir {
76//!         #[dir_structure(path = "f4.txt")]
77//!         f4: String,
78//!     }
79//!     let d = Path::new("dir");
80//!     std::fs::create_dir_all(&d)?;
81//!     std::fs::create_dir_all(d.join("subdir"))?;
82//!     std::fs::create_dir_all(d.join("subdir2"))?;
83//!     std::fs::write(d.join("f1.txt"), "f1")?;
84//!     std::fs::write(d.join("subdir/f2.txt"), "f2")?;
85//!     std::fs::write(d.join("f3"), "f3")?;
86//!     std::fs::write(d.join("subdir2/f4.txt"), "f4")?;
87//!     let dir = Dir::read(&d)?;
88//!     assert_eq!(dir.f1, "f1");
89//!     assert_eq!(dir.f2, "f2");
90//!     assert_eq!(dir.f3, "f3");
91//!     assert_eq!(dir.subdir.f4, "f4");
92//!
93//!     # std::fs::remove_dir_all(&d)?;
94//!
95//!     Ok(())
96//! }
97//! ```
98
99#![cfg_attr(docsrs, feature(doc_cfg))]
100#![cfg_attr(feature = "resolve-path", feature(adt_const_params))]
101#![deny(missing_docs)]
102
103#[cfg(feature = "async")]
104pub extern crate pin_project;
105
106#[cfg(doctest)]
107mod __doc_check {
108    // mod guide {
109    //     include!("../../../../doc/docs/content/docs/dx/dir-structure/.guide.mdx.doctests");
110    // }
111
112    // mod plumbing_guide {
113    //     include!("../../../../doc/docs/content/docs/dx/dir-structure/.custom-impl.mdx.doctests");
114    // }
115
116    // need default features for README examples to work
117    #[cfg(feature = "derive")]
118    #[doc = include_str!("../../README.md")]
119    struct Readme;
120}
121
122#[cfg(feature = "derive")]
123pub use dir_structure_macros::DirStructure;
124#[cfg(all(feature = "derive", feature = "async"))]
125pub use dir_structure_macros::DirStructureAsync;
126#[cfg(all(feature = "derive", feature = "resolve-path"))]
127pub use dir_structure_macros::HasField;
128
129pub mod prelude {
130    //! A prelude for the most commonly used items in this crate.
131    #[cfg(feature = "derive")]
132    pub use crate::DirStructure;
133    #[cfg(feature = "async")]
134    pub use crate::traits::asy::ReadFromAsync;
135    #[cfg(feature = "async")]
136    pub use crate::traits::asy::WriteToAsync;
137    #[cfg(feature = "async")]
138    pub use crate::traits::asy::WriteToAsyncRef;
139    #[cfg(feature = "async")]
140    pub use crate::traits::async_vfs::VfsAsync;
141    #[cfg(feature = "async")]
142    pub use crate::traits::async_vfs::VfsAsyncExt;
143    #[cfg(feature = "async")]
144    pub use crate::traits::async_vfs::WriteSupportingVfsAsyncExt;
145    pub use crate::traits::sync::DirStructureItem;
146    pub use crate::traits::sync::ReadFrom;
147    pub use crate::traits::sync::WriteTo;
148    pub use crate::traits::vfs::PathType;
149    pub use crate::traits::vfs::Vfs;
150    pub use crate::traits::vfs::VfsCore;
151    pub use crate::traits::vfs::VfsExt;
152    pub use crate::traits::vfs::WriteSupportingVfsExt;
153}
154
155pub mod error;
156pub mod option;
157pub mod std_types;
158pub mod traits;
159pub mod vfs;
dir_structure/lib.rs

dir_structure/
lib.rs
