Skip to main content

couleur_rs/
lib.rs

1#![allow(unused)]
2//! couleur-rs: parse, apply contrast algorithms to ANSI RGB colors and print text powered by a simple template language
3//!
4//! ## Parsing Colors
5//!
6//! ```rust
7//! let dark_pink = "#C32454".parse::<Color>()?;
8//! let darkest_pink = "#831C5D".parse::<Color>()?;
9//! let light_pink = "#FCA790".parse::<Color>()?;
10//! let lightest_pink = "#FDCBB0".parse::<Color>()?;
11//! ```
12//!
13//! ## Applying Contrast
14//! ```rust
15//! let dark_pink = "#C32454".parse::<Color>()?;
16//! let darkest_pink = "#831C5D".parse::<Color>()?;
17//! let light_pink = "#FCA790".parse::<Color>()?;
18//! let lightest_pink = "#FDCBB0".parse::<Color>()?;
19//!
20//! assert_eq!(
21//!     dark_pink.to_triple(),
22//!     (Value::from_u8(0xC3)?, Value::from_u8(0x24)?, Value::from_u8(0x54)?)
23//! );
24//!
25//! assert_eq!(lightest_pink.get_adobe_complementary().to_hex_string(), "#B0E2FD");
26//! assert_eq!(lightest_pink.get_accessible_contrast().to_hex_string(), "#000000");
27//! assert_eq!(lightest_pink.get_binary_contrast().to_hex_string(), "#000000");
28//! assert_eq!(lightest_pink.get_msb_invert_contrast().to_hex_string(), "#7D4B30");
29//!
30//! assert_eq!(darkest_pink.get_adobe_complementary().to_hex_string(), "#1C8342");
31//! assert_eq!(darkest_pink.get_accessible_contrast().to_hex_string(), "#000000");
32//! assert_eq!(darkest_pink.get_binary_contrast().to_hex_string(), "#FFFFFF");
33//! assert_eq!(darkest_pink.get_msb_invert_contrast().to_hex_string(), "#039CDD");
34//! ```
35//!
36//! ## Template Language
37//! ```rust
38//! parse::<&str, ContextError>(
39//!     "{color:#1EBC73}Hello{color:#1EBC73%contrast:web} World",
40//! );
41//! Ok(Node::Array(vec![
42//!     Node::Color("#1EBC73".parse::<couleur_rs::Color>().unwrap()),
43//!     Node::Text("Hello".to_string()),
44//!     Node::RenderableColor(
45//!         RenderableColor::new("#1EBC73".parse::<couleur_rs::Color>().unwrap())
46//!             .with_contrast(Contrast::Web),
47//!     ),
48//!     Node::Text(" World".to_string()),
49//! ]))
50//! ```
51//!
52//!
53//! <div class="important">
54//! <h1>IMPORTANT</h1>
55//!
56//! This library is currently a work-in-progress and
57//! provides the feature flags `logging` and `tracing` as debugging
58//! tools. All the tracing and logging annotations and calls will be
59//! removed before `couleur-rs` reaches version 1.0.0
60//!
61//! Until then, the API likely to undergo changes in design and
62//! usability.
63//!
64//! </div>
65use std::sync::LazyLock;
66
67use lazy_mut::LazyMut;
68
69#[doc(hidden)] pub mod cli;
70#[doc(hidden)] pub use cli::RenderingOptions;
71#[doc(hidden)] pub mod cmp;
72#[doc(hidden)] pub use cmp::{max_rgb, min_rgb};
73#[doc(hidden)] pub mod color;
74#[doc(inline)] pub use color::{BLACK, Color, RGBParseError, RgbTriple, U8Triple, WHITE};
75#[doc(hidden)] pub mod contrast;
76#[doc(inline)] pub use contrast::Contrast;
77#[doc(hidden)] pub mod dispatch;
78#[doc(hidden)]
79pub use dispatch::{ArgsDispatcher, ParserDispatcher, SubcommandDispatcher};
80#[doc(hidden)] pub mod errors;
81#[doc(hidden)] pub use errors::Exit;
82#[doc(inline)]
83pub use errors::{ConversionToF32Error, ConversionToU8Error, Error, ParseError, Result};
84#[doc(hidden)] pub mod float;
85#[doc(inline)] pub use float::FloatMetadata;
86#[doc(hidden)] pub use float::{leading_zeros_exp, leading_zeros_fractional};
87#[doc(hidden)] pub mod layer;
88#[doc(inline)] pub use layer::Layer;
89#[doc(hidden)] pub mod macros;
90#[doc(hidden)] pub mod prefix;
91#[doc(inline)] pub use prefix::{Prefix, PrefixContainer};
92
93#[doc(hidden)] pub mod reset;
94#[doc(inline)] pub use reset::Reset;
95#[doc(hidden)] pub mod terminal;
96#[doc(inline)] pub use terminal::{Terminal, TerminalInfo, TerminalInfoError};
97#[doc(hidden)] pub mod state;
98#[doc(inline)] pub use state::{ColorPalette, Context};
99#[doc(hidden)] pub mod value;
100#[doc(inline)] pub use value::Value;
101#[doc(hidden)] pub mod wrap;
102#[doc(inline)] pub use wrap::Wrap;
103#[doc(hidden)] pub mod renderable_color;
104#[doc(inline)] pub use renderable_color::RenderableColor;
105#[doc(hidden)] pub mod traits;
106#[doc(inline)] pub use traits::{AnsiRenderable, ToAnsiEscSuffix};
107#[doc(hidden)] pub mod templating;
108
109#[doc(hidden)]
110pub use templating::{
111    Node,
112    Result as ParsingResult,
113    Stream,
114    color,
115    fold_nodes,
116    nodes,
117    parse,
118    parse_color,
119    parse_contrast,
120    parse_layer,
121    parse_node,
122    parse_rgb_hex,
123    parse_rgb_triple,
124    parse_triple,
125    parse_u8,
126    render_nodes,
127    renderable_color,
128    reset,
129    text,
130    ws,
131};
132
133#[doc(hidden)] pub mod util;
134#[doc(hidden)]
135pub use util::{
136    HEX_RGB_REGEX,
137    SINGLE_BAND_DECIMAL_RGB_REGEX,
138    SINGLE_BAND_HEX_RGB_REGEX,
139    TRIPLE_RGB_REGEX,
140    deserialize_string_to_str,
141    serialize_static_str_to_string,
142};
143
144// #[cfg(any(feature = "tracing", feature = "logging"))]
145#[doc(hidden)] pub mod logging;
146#[doc(inline)]
147pub use logging::{get_log_path, local_data_dir, setup_logging, setup_tracing};
148
149#[doc(hidden)] pub mod testing;
150#[doc(hidden)] pub use testing::global_setup;
151pub static TERMINAL: LazyLock<TerminalInfo> = LazyLock::new(|| Terminal::info());
152pub static PREFIX: LazyMut<PrefixContainer> = LazyMut::new(|| PrefixContainer::default());
153
154pub fn set_runtime_prefix<T: Into<Prefix>>(prefix: T) {
155    let mut current = PREFIX.get_mut();
156    current.set(prefix.into());
157}
158pub fn get_runtime_prefix() -> Prefix {
159    crate::PREFIX.get_mut().get()
160}