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 = "prompt-password")]
89pub use print::check_password_legality;
90#[cfg(feature = "print")]
91pub use print::{
92    ProgressBar, ZeroWhenDropString, init_print_options, log_init, progress_bar, progress_bar_lowp,
93    progress_unbounded, progress_unbounded_lowp, set_thread_print_name, term_width,
94    term_width_height, term_width_or_max,
95};
96
97/// Printing level values
98pub mod lv;
99#[doc(inline)]
100pub use lv::{color_enabled, disable_print_time, disable_trace_hint, log_enabled};
101
102/// Parsing utilities
103#[cfg(feature = "parse")]
104mod parse;
105#[cfg(feature = "parse")]
106pub use parse::*;
107#[cfg(feature = "parse")]
108pub use pistonite_cu_proc_macros::Parse;
109mod env_var;
110pub use env_var::*;
111
112// Atomic helpers
113mod atomic;
114pub use atomic::*;
115
116// other stuff that doesn't have a place
117mod misc;
118pub use misc::*;
119
120// re-exports from libraries
121pub use anyhow::{Context, Error, Ok, Result, anyhow as fmterr, bail, ensure};
122pub use log::{debug, error, info, trace, warn};
123pub use pistonite_cu_proc_macros::error_ctx;
124#[cfg(feature = "coroutine")]
125pub use tokio::{join, try_join};
126
127#[doc(hidden)]
128pub mod __priv {
129    #[cfg(feature = "print")]
130    pub use crate::print::{__print_with_level, __prompt, __prompt_yesno};
131    #[cfg(feature = "process")]
132    pub use crate::process::__ConfigFn;
133}
134
135/// Lib re-exports
136pub mod lib {
137    #[cfg(feature = "cli")]
138    pub use clap;
139    #[cfg(feature = "derive")]
140    pub use derive_more;
141}
142
143/// Prelude imports
144pub mod pre {
145    pub use crate::Context as _;
146    #[cfg(feature = "parse")]
147    pub use crate::ParseTo as _;
148    #[cfg(feature = "fs")]
149    pub use crate::PathExtension as _;
150    #[cfg(feature = "fs")]
151    pub use crate::PathExtensionOwned as _;
152    #[cfg(feature = "process")]
153    pub use crate::Spawn as _;
154    #[cfg(feature = "json")]
155    pub use crate::json;
156    #[cfg(feature = "cli")]
157    pub use crate::lib::clap;
158    #[cfg(feature = "toml")]
159    pub use crate::toml;
160    #[cfg(feature = "yaml")]
161    pub use crate::yaml;
162    #[cfg(feature = "serde")]
163    pub use ::serde::{Deserialize, Serialize};
164
165    #[cfg(feature = "derive")]
166    pub use crate::lib::derive_more;
167    #[cfg(feature = "derive")]
168    pub use crate::lib::derive_more::{
169        AsMut, AsRef, Binary as DisplayBinary, Constructor, Debug as DebugCustom, Deref, DerefMut,
170        Display, From, Index, IndexMut, Into, IntoIterator, IsVariant, LowerExp as DisplayLowerExp,
171        LowerHex as DisplayLowerHex, Octal as DisplayOctal, Pointer as DisplayPointer,
172        UpperExp as DisplayUpperExp, UpperHex as DisplayUpperHex,
173    };
174
175    #[cfg(feature = "coroutine")]
176    pub use tokio::io::{AsyncBufReadExt as _, AsyncReadExt as _};
177}
pistonite_cu/lib.rs

pistonite_cu/
lib.rs
