Skip to main content

Crate pistonite_cu

Crate pistonite_cu 

Source
Expand description

§Cu = Copper

Batteries-included common utils

(If you are viewing this on docs.rs, please use the self-hosted version instead)

§Quick start

When installing, rename the crate to cu in Cargo.toml:

# Cargo.toml
# ...
[dependencies.cu]
package = "pistonite-cu"
version = "..." # check by running `cargo info pistonite-cu`
features = [ "full" ] # see docs

[dependencies]
# ...

The goal with using cu is use only one use statement:

use cu::pre::*;

This brings into scope a few things:

  • Traits that are expected to be used, such as anyhow::Context
  • Re-exports of modules, such as json if the json feature is enabled

If a function or type is not included with pre::*, that means the canonical style for using it is with the full path, for example, you would write:

use cu::pre::*;

fn read_file() -> cu::Result<()> {
    cu::fs::read_string("foo/bar.txt")?;
    cu::info!("successfully read file");
    Ok(())
}

instead of the below:

use cu::pre::*;
use cu::{Result, fs, info};
// ^ don't include extra uses!
//   the biggest disadvantage of this is
//   it's easy to confuse with types in the standard library

fn read_file() -> Result<()> {
    fs::read_string("foo/bar.txt")?;
    info!("successfully read file");
    Ok(())
}

§Quick Reference

Re-exports§

pub use str::Regex;regex
pub use str::ByteFormat;
pub use str::ZString;
pub use cli::CtrlcSignal;print
pub use cli::ProgressBar;print
pub use cli::progress;print
pub use cli::prompt;prompt
pub use cli::yesno;prompt
pub use fs::bin;fs
pub use fs::bin::which;fs

Modules§

cliprint
Printting and Command Line Interface
cocoroutine
Coroutines (Async)
fsfs
File System Operations
jsonjson and parse
serde JSON integration via the serde_json crate
lv
Logging
pioprocess
Utility to configure IO with child process.
str
Working with bytes
tomlparse and toml
serde TOML integration via the toml crate
yamlparse and yaml
serde YAML integration via the serde_yaml_ng crate

Macros§

argsprocess
Create a config to add multiple args of different types when building a subprocess.
bail
Return early with an error.
check
Error Handling
custom_printprint
Print message with a custom log format and level.
debug
Logs a message at the debug level.
ensure
Check if an expression is true, as an assertion
envsprocess
Create a config to add multiple environments of different types when building a subprocess.
error
Logs a message at the error level.
fmtand
Format and invoke a print macro
fmterr
Construct an ad-hoc error from a string or existing non-anyhow error value.
hintprint
Logs a hint message
info
Logs a message at the info level.
joincoroutine
Waits on multiple concurrent branches, returning when all branches complete.
jsonjson
Construct a serde_json::Value from a JSON literal.
panicand
Invoke a print macro, then panic with the same message
path
Efficient Path-join macro
printprint
Print something
progressprint
Update a progress bar
promptcoroutine and print and prompt
Show prompt to the user. See Prompting
rethrow
Rethrow an Err, optionally with additional context
selectcoroutine
Waits on multiple concurrent branches, returning when the first branch completes, cancelling the remaining branches.
some
Check if an expression is Some
tomltoml
Construct a Table from TOML syntax.
trace
Logs a message at the trace level.
try_joincoroutine
Waits on multiple concurrent branches, returning when all branches complete with Ok(_) or on the first Err(_).
unimplemented
Like unimplemented! in std library, but log a message and return an error instead of panicking
unreachable
Like unreachable! in std library, but log a message and return an error instead of panicking reached. This might be less performant in release builds
warn
Logs a message at the warn level.
yesnocoroutine and print and prompt
Show a Yes/No prompt. See Prompting

Structs§

Atomic
An atomic wrapper with an underlying atomic storage and conversion to a type T.
Childprocess
A child process spawned with Command
Commandprocess
Builder for spawning a child process.
Error
The Error type, a wrapper around a dynamic error type.

Traits§

AtomicType
Marker type to associate primitive with their atomic versions
Context
Provides the context method for Result.
Parseparse
The parsing utilities in cu provides wrapper to the std library for parsing common data, such as different radix for numbers, and support for common formats like json, yaml and toml.
ParseToparse
the .parse_to function.
Spawnprocess
This trait allows implementing different return types for Command::spawn based on the configured IO.

Functions§

Ok
Equivalent to Ok::<_, anyhow::Error>(value).
best_effort_panic_info
Try to get info from a panic payload
co_copycoroutine
Copy an async reader to an async writer.
co_readcoroutine and parse
Parse a value from a tokio::io::AsyncRead.
color_flagprocess
Create a --color always|never flag that can be added to a command, based on if color is enabled for the current process using this crate’s cli flags
color_flag_eqprocess
Create a --color=always|never flag that can be added to a command, based on if color is enabled for the current process using this crate’s cli flags
copy
Copy a reader to a writer.
env_var
Like std::env::var, but treat not-set as empty string. Tracing and reporting is built-in.
parseparse
Parse a value from a &str.
parse_ownedparse
Parse a value from a String.
readparse
Parse a value from a std::io::Read.
width_flagprint and process
Create a --width WIDTH flag that can be added to a command, based on the current width of the terminal
width_flag_eqprint and process
Create a --width=WIDTH flag that can be added to a command, based on the current width of the terminal

Type Aliases§

BoxedFuture
Alias for a boxed future
CommandBuilderprocess
A Command to be built
Result
Result<T, Error>

Attribute Macros§

clicli
For the Command Line Interface feature set, please refer to the cu::cli module.
context
Attribute macro for wrapping a function with an error context

Derive Macros§

Parseparse
Derive the cu::Parse trait