pistonite_cu/
lib.rs

1//! Batteries-included common utils
2//!
3//! (If you are viewing this on docs.rs, please use the [self-hosted
4//! version](https://cu.pistonite.dev) instead)
5//!
6//! # Install
7//! Since crates.io does not have namespaces, this crate has a prefix.
8//! You should manually rename it to `cu`, as that's what the proc-macros
9//! expect.
10//! ```toml
11//! # Cargo.toml
12//! # ...
13//! [dependencies.cu]
14//! package = "pistonite-cu"
15//! version = "..." # check by running `cargo info pistonite-cu`
16//! features = [ "full" ] # see docs
17//!
18//! # ...
19//! [dependencies]
20//! ```
21//!
22//! # General Principal
23//! `cu` tries to be as short as possible with imports. Common and misc
24//! utilities are exported directly by the crate and should be used
25//! as `cu::xxx` directly. Sub-functionalities are bundled when makes
26//! sense, and should be called from submodules directly, like `cu::fs::xxx`
27//! or `cu::co::xxx`. The submodules are usually 2-4 characters.
28//!
29//! The only time to use `use` to import from `cu`, is with the prelude module
30//! `pre`:
31//! ```rust
32//! # use pistonite_cu as cu;
33//! use cu::pre::*;
34//! ```
35//! This imports traits like [`Context`] and [`PathExtension`] into scope.
36//!
37//! # Feature Reference:
38//! - `cli`, `print`, `prompt`:
39//!   See [`cli`](module@cli). Note that logging is still available without any feature flag.
40//! - `coroutine` and `coroutine-heavy`:
41//!   Enables `async` and integration with `tokio`. See [`cu::co`](module@co).
42//! - `fs`: Enables file system utils. See [`cu::fs`](module@fs) and [`cu::bin`](module@bin).
43//! - `process`: Enables utils spawning child process. See [`Command`].
44//! - `parse`, `json`, `yaml`, `toml`:
45//!   Enable parsing utilities, and additional support for common formats. See
46//!   [`Parse`](trait@Parse).
47
48#![cfg_attr(any(docsrs, feature = "nightly"), feature(doc_cfg))]
49
50#[cfg(feature = "process")]
51mod process;
52#[cfg(feature = "process")]
53pub use process::{Child, Command, CommandBuilder, Spawn, color_flag, color_flag_eq, pio};
54#[cfg(all(feature = "process", feature = "print"))]
55pub use process::{width_flag, width_flag_eq};
56
57#[cfg(feature = "fs")]
58pub mod bin;
59#[cfg(feature = "fs")]
60#[doc(inline)]
61pub use bin::which;
62
63/// File System utils (WIP)
64#[cfg(feature = "fs")]
65pub mod fs;
66
67/// Path utils
68#[cfg(feature = "fs")]
69mod path;
70#[cfg(feature = "fs")]
71pub use path::{PathExtension, PathExtensionOwned};
72
73#[cfg(feature = "cli")]
74pub mod cli;
75#[cfg(feature = "cli")]
76pub use pistonite_cu_proc_macros::cli;
77
78#[cfg(feature = "coroutine")]
79mod async_;
80/// Alias for a boxed future
81pub type BoxedFuture<T> = std::pin::Pin<Box<dyn Future<Output = T> + Send + 'static>>;
82#[cfg(feature = "coroutine")]
83pub mod co;
84
85/// Low level printing utils and integration with log and clap
86#[cfg(feature = "print")]
87mod print;
88#[cfg(feature = "print")]
89pub use print::{
90    ProgressBar, init_print_options, log_init, progress_bar, progress_bar_lowp, progress_unbounded,
91    progress_unbounded_lowp, set_thread_print_name, term_width, term_width_height,
92    term_width_or_max,
93};
94
95/// Printing level values
96pub mod lv;
97#[doc(inline)]
98pub use lv::{color_enabled, disable_print_time, disable_trace_hint, log_enabled};
99
100/// Parsing utilities
101#[cfg(feature = "parse")]
102mod parse;
103#[cfg(feature = "parse")]
104pub use parse::*;
105#[cfg(feature = "parse")]
106pub use pistonite_cu_proc_macros::Parse;
107
108// Atomic helpers
109mod atomic;
110pub use atomic::*;
111
112// other stuff that doesn't have a place
113mod misc;
114pub use misc::*;
115
116// re-exports from libraries
117pub use anyhow::{Context, Error, Ok, Result, anyhow as fmterr, bail, ensure};
118pub use log::{debug, error, info, trace, warn};
119#[cfg(feature = "coroutine")]
120pub use tokio::{join, try_join};
121
122#[doc(hidden)]
123pub mod __priv {
124    #[cfg(feature = "print")]
125    pub use crate::print::{__print_with_level, __prompt, __prompt_yesno};
126    #[cfg(feature = "process")]
127    pub use crate::process::__ConfigFn;
128}
129
130/// Lib re-exports
131pub mod lib {
132    #[cfg(feature = "cli")]
133    pub use clap;
134    #[cfg(feature = "derive")]
135    pub use derive_more;
136}
137
138/// Prelude imports
139pub mod pre {
140    pub use crate::Context as _;
141    #[cfg(feature = "parse")]
142    pub use crate::ParseTo as _;
143    #[cfg(feature = "fs")]
144    pub use crate::PathExtension as _;
145    #[cfg(feature = "fs")]
146    pub use crate::PathExtensionOwned as _;
147    #[cfg(feature = "process")]
148    pub use crate::Spawn as _;
149    #[cfg(feature = "json")]
150    pub use crate::json;
151    #[cfg(feature = "cli")]
152    pub use crate::lib::clap;
153    #[cfg(feature = "toml")]
154    pub use crate::toml;
155    #[cfg(feature = "yaml")]
156    pub use crate::yaml;
157    #[cfg(feature = "serde")]
158    pub use ::serde::{Deserialize, Serialize};
159
160    #[cfg(feature = "derive")]
161    pub use crate::lib::derive_more;
162    #[cfg(feature = "derive")]
163    pub use crate::lib::derive_more::{
164        AsMut, AsRef, Binary as DisplayBinary, Constructor, Debug as DebugCustom, Deref, DerefMut,
165        Display, From, Index, IndexMut, Into, IntoIterator, IsVariant, LowerExp as DisplayLowerExp,
166        LowerHex as DisplayLowerHex, Octal as DisplayOctal, Pointer as DisplayPointer,
167        UpperExp as DisplayUpperExp, UpperHex as DisplayUpperHex,
168    };
169
170    #[cfg(feature = "coroutine")]
171    pub use tokio::io::{AsyncBufReadExt as _, AsyncReadExt as _};
172}
pistonite_cu/lib.rs

pistonite_cu/
lib.rs
