Debian Codegraph @

src/lib.rs

raw
1 #![deny(
2 future_incompatible,
3 keyword_idents,
4 let_underscore,
5 nonstandard_style,
6 unused
7 )]
8 #![warn(unknown_lints)]
9
10 //! # fsio
11 //!
12 //! File System and Path utility functions.
13 //!
14 //! # Usage
15 //!
16 //! There are multiple main modules for fsio:
17 //!
18 //! * fsio::path - Holds path related functions and traits. They do not directly modify the file system.
19 //! * fsio::file - File utility functions such as read_file, write_file, ...
20 //! * fsio::directory - Directory specific utility functions.
21 //!
22 //! ### Examples
23 //!
24 //! ```rust
25 //! use fsio::{directory, file, path};
26 //! use std::fs::File;
27 //! use std::io::Write;
28 //! use std::path::Path;
29 //! use std::str;
30 //!
31 //! fn main() {
32 //! // file operations
33 //! let mut result = file::ensure_exists("./target/__test/doc/example/file_test/dir1/dir2/file.txt");
34 //! assert!(result.is_ok());
35 //!
36 //! // create/append and read text files
37 //! let mut file_path = "./target/__test/example/doc/file_test/append_text_file/file.txt";
38 //! result = file::write_text_file(file_path, "some content");
39 //! assert!(result.is_ok());
40 //! result = file::append_text_file(file_path, "\nmore content");
41 //! assert!(result.is_ok());
42 //! let mut text = file::read_text_file(file_path).unwrap();
43 //! assert_eq!(text, "some content\nmore content");
44 //!
45 //! // create/append and read binary files
46 //! file_path = "./target/__test/example/doc/file_test/append_and_read_file_test/file.txt";
47 //! result = file::write_file(file_path, "some content".as_bytes());
48 //! assert!(result.is_ok());
49 //! result = file::append_file(file_path, "\nmore content".as_bytes());
50 //! assert!(result.is_ok());
51 //! let data = file::read_file(file_path).unwrap();
52 //! assert_eq!(str::from_utf8(&data).unwrap(), "some content\nmore content");
53 //!
54 //! // custom writing
55 //! file_path = "./target/__test/example/doc/file_test/modify_file/file.txt";
56 //! result = file::modify_file(
57 //! file_path,
58 //! &move |file: &mut File| file.write_all("some content".as_bytes()),
59 //! false,
60 //! );
61 //! assert!(result.is_ok());
62 //! text = file::read_text_file(file_path).unwrap();
63 //! assert_eq!(text, "some content");
64 //!
65 //! // delete file
66 //! result = file::delete(file_path);
67 //! assert!(result.is_ok());
68 //!
69 //! // directory operations
70 //! result = directory::create("./target/__test/example/doc/directory_test/dir1/dir2");
71 //! assert!(result.is_ok());
72 //!
73 //! result = directory::create_parent("./target/__test/example/doc/directory_test/dir1/files/file.txt");
74 //! assert!(result.is_ok());
75 //!
76 //! // delete directory
77 //! result = directory::delete("./target/__test/example/doc/directory_test");
78 //! assert!(result.is_ok());
79 //!
80 //! // basename and parent directory examples
81 //! let basename = path::get_basename("./src/path/mod.rs");
82 //! assert_eq!(basename.unwrap(), "mod.rs");
83 //!
84 //! let dirname = path::get_parent_directory("./src/path/mod.rs");
85 //! assert_eq!(dirname.unwrap(), "./src/path");
86 //!
87 //! // canonicalize examples
88 //! let path_obj = Path::new("./src/path/mod.rs");
89 //!
90 //! let path1 = path::canonicalize_as_string(&path_obj);
91 //! let path2 = path::canonicalize_or("./src/path/mod.rs", "/src/path/mod.rs");
92 //!
93 //! assert_eq!(path1.unwrap(), path2);
94 //! }
95 //! ```
96 //!
97 //! # Installation
98 //! In order to use this library, just add it as a dependency:
99 //!
100 //! ```ini
101 //! [dependencies]
102 //! fsio = "*"
103 //! ```
104 //!
105 //! If you need access to temporary file paths, enable the **temp-path** feature as follows:
106 //!
107 //! ```ini
108 //! [dependencies]
109 //! fsio = { version = "*", features = ["temp-path"] }
110 //! ```
111 //!
112 //! # Contributing
113 //! See [contributing guide](https://github.com/sagiegurari/fsio/blob/master/.github/CONTRIBUTING.md)
114 //!
115 //! # License
116 //! Developed by Sagie Gur-Ari and licensed under the
117 //! [Apache 2](https://github.com/sagiegurari/fsio/blob/master/LICENSE) open source license.
118 //!
119
120 #[cfg(test)]
121 use doc_comment as _;
122
123 #[cfg(doctest)]
124 doc_comment::doctest!("../README.md");
125
126 pub mod directory;
127 pub mod error;
128 pub mod file;
129 pub mod path;
130 pub mod types;