fsio/
lib.rs

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)]
121use doc_comment as _;
122
123#[cfg(doctest)]
124doc_comment::doctest!("../README.md");
125
126pub mod directory;
127pub mod error;
128pub mod file;
129pub mod path;
130pub mod types;
fsio/lib.rs

fsio/
lib.rs
