From ef24de24a82fe681581cc130f342363c47c0969a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 7 Jun 2024 07:48:48 +0200 Subject: Merging upstream version 1.75.0+dfsg1. Signed-off-by: Daniel Baumann --- vendor/color-print/src/lib.rs | 91 ++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 48 deletions(-) (limited to 'vendor/color-print/src/lib.rs') diff --git a/vendor/color-print/src/lib.rs b/vendor/color-print/src/lib.rs index 14535f5db..2a5c1d14a 100644 --- a/vendor/color-print/src/lib.rs +++ b/vendor/color-print/src/lib.rs @@ -1,4 +1,4 @@ -//! Colorize and stylize strings at compile-time, by using an HTML-like syntax. +//! Colorize and stylize strings for terminal at compile-time, by using an HTML-like syntax. //! //! This library provides the following macros: //! @@ -10,24 +10,23 @@ //! //! [`cformat!()`], [`cprint!()`], and [`cprintln!()`] have the same syntax as `format!()`, //! `print!()` and `println!()` respectively, but they accept an additional syntax inside the -//! format string: HTML-like tags which add terminal colors/styles at compile-time. -//! -//! *Note*: these tags are commonly named "*color tags*" in the documentation below. +//! format string: HTML-like tags which add ANSI colors/styles at compile-time. //! //! [`cstr!()`] only transforms the given string literal into another string literal, without //! formatting anything else than the colors tag. //! -//! [`untagged!()`] removes all the color tags found in the given string literal. +//! [`untagged!()`] removes all the tags found in the given string literal. //! //! ## What does it do ? //! -//! By default, the provided macros will replace the color tags found in the format string by ANSI +//! By default, the provided macros will replace the tags found in the format string by ANSI //! hexadecimal escape codes. E.g.: //! //! ``` //! # use color_print::cprintln; //! # fn main() { -//! cprintln!("HELLO WORLD") +//! cprintln!("HELLO WORLD"); +//! cprintln!("HELLO WORLD"); // Alternative, shorter syntax //! # } //! ``` //! @@ -48,7 +47,7 @@ //! //! ## Pros //! -//! * Styling is processed at compile-time, so the runtime payload is quite inexistant (unless the +//! * Styling is processed at compile-time, so the runtime payload is inexistant (unless the //! feature `terminfo` is activated); //! * Nested tags are well handled, e.g. `"........."`; //! * Some optimizations are performed to avoid redundant ANSI sequences, because these @@ -56,16 +55,12 @@ //! * Almost every tag has a short name, so colorizing can be done quickly: `"my blue word"`; //! * Each provided macro can be used exactly in the same way as the standard `format!`-like //! macros; e.g., positional arguments and named arguments can be used as usual; -//! * Fine-grained error handling. +//! * Supports 16, 256 and 16M colors; +//! * Fine-grained error handling (errors will be given at compile-time). //! //! ## Cons //! -//! * Many CLI programs detect on runtime if they are actually piped to another command or not, and -//! decide to colorize their output based on this information. As `color-print` formats strings at -//! compile-time, this is not possible to do that easily; -//! * Not compatible with non-ANSI Windows terminals (and not tested at all on Windows, feedbacks -//! are welcome); -//! * Not tested on Mac, feedbacks are welcome. +//! * Not compatible with non-ANSI terminals. //! //! # Introduction //! @@ -78,8 +73,9 @@ //! //! ## Closing a tag more simply: the `` tag //! -//! Basically, tags must be closed by giving exactly the same colors/styles of the matching open -//! tag (with a slash `/` at the beginning). But it can be tedious! +//! Basically, tags must be closed by giving *exactly* the same colors/styles as their matching +//! open tag (with a slash `/` at the beginning), e.g: `...`. But it can be +//! tedious! //! //! So, it is also possible to close the last open tag simply with ``: //! @@ -92,7 +88,7 @@ //! //! ## Combining colors and styles //! -//! Multiple styles and color(s) can be combined into a single tag by separating them with the `,` +//! Multiple styles and colors can be combined into a single tag by separating them with the `,` //! comma character: //! //! ``` @@ -104,13 +100,14 @@ //! # } //! ``` //! -//! Of course, combining multiple foreground colors or multiple background colors into the same tag -//! is useless (in such a case, only the last one is taken into account). -//! //! ## Nesting tags //! -//! Any tag can be nested with any other, as long as the closing tags match correctly (following -//! the basic rules of nesting for HTML tags): +//! Any tag can be nested with any other. +//! +//! *Note*: The closing tags must match correctly (following the basic rules of nesting for HTML +//! tags), but it can always be simplified by using the tag ``. +//! +//! Example of nested tags: //! //! ``` //! # use color_print::cprintln; @@ -140,7 +137,8 @@ //! //! ## How to display the chars `<` and `>` verbatim //! -//! As for `{` and `}`, the chars `<` and `>` have to be doubled in order to display them verbatim: +//! As for `{` and `}` in standard format strings, the chars `<` and `>` have to be doubled in +//! order to display them verbatim: //! //! ``` //! # use color_print::cprintln; @@ -152,15 +150,15 @@ //! # Optimization: no redundant ANSI codes //! //! The expanded format string will only contain the *needed* ANSI codes. This is done by making a -//! diff of the different style attributes, each time a color tag is encountered, instead of -//! mechanically adding the ANSI codes. +//! diff of the different style attributes, each time a tag is encountered, instead of mechanically +//! adding the ANSI codes. //! //! E.g., several nested `` tags will only produce one bold ANSI sequence: //! //! ``` //! # use color_print::cprintln; //! # fn main() { -//! cprintln!("A B C D E") +//! cprintln!(" A B C ") //! # } //! ``` //! @@ -169,10 +167,10 @@ //! ``` //! # use color_print::cprintln; //! # fn main() { -//! println!("\u{1b}[1mA \u{1b}[34mB C D\u{1b}[39m E\u{1b}[22m") -//! // ^-------^ ^--------^ ^--------^ ^--------^ -//! // bold blue color bold -//! // reset reset +//! println!("\u{1b}[1m A \u{1b}[34m B \u{1b}[39m C \u{1b}[22m") +//! // ^-------^ ^--------^ ^--------^ ^--------^ +//! // bold blue color bold +//! // reset reset //! # } //! ``` //! @@ -200,38 +198,37 @@ //! [`lazy_static`]: https://crates.io/crates/lazy_static //! [`terminfo`]: https://crates.io/crates/terminfo //! -//! # Naming rules of the color tags: +//! # Naming rules of the tags: //! -//! Each color/style tag has at least a long name, like `` or ``. +//! Each tag has at least a **long name**, like `` or ``. //! //! The tags directly relative to *colors* (like ``, ``, ``..., as //! opposed to *style* tags like ``, ``...) have some common naming rules: //! -//! * Each color tag has four variants: +//! * Each tag has four variants: //! - ``: the normal, foreground color; //! - `` or ``: the bright, foreground color; -//! - ``: the normal, background color; +//! - ``, ``: the normal, background color; //! - ``, ``, `` or ``: the bright, //! background color; -//! * Each color tag has a *shortcut*, with a base letter for each color (example with the `x` -//! letter): +//! * Each tag has a *shortcut*, with a base letter for each color; example with the `x` letter: //! - ``: the normal, foreground color; //! - ``: the bright, foreground color; -//! - `` or ``: the normal, background color; -//! - `` or ``: the bright, background color; -//! * Except for the color ``, each color's shortcut letter is simply the first letter of -//! its name, e.g. `` is the shortcut for ``; -//! * Each color's tag which is uppercase is a background color; -//! * Each tag which has a trailing exclamation point `!` is a bright color; +//! - ``, ``: the normal, background color; +//! - ``, ``: the bright, background color; +//! * Each color's shortcut letter is simply the **first letter of its name** (excepted for `` +//! which is the shortcut for ``), e.g. `` is the shortcut for ``; +//! * Each color's tag which is uppercase is a **background color**; +//! * Each tag which has a trailing exclamation point `!` is a **bright color**; //! -//! # List of accepted color/style tags: +//! # List of accepted tags: //! //! The two first columns show which styles are supported, respectively with the default crate //! features (ANSI column), and with the feature `terminfo` being activated. //! //! | ANSI | Terminfo | Shortcuts | Long names | Aliases | //! | ---- | -------- | --------- | ----------------------- | ----------------------------------------------- | -//! | X | X | `` | `` | `` `` | +//! | X | X | `` | `` | `` `` | //! | X | X | | `` | | //! | X | X | `` | `` | | //! | X | | | `` | | @@ -276,9 +273,7 @@ //! | X | | `<0>`...`<255>` | `` | `` `` | //! | X | | `` | `` | `` `` `` `` | -pub use color_print_proc_macro::{cformat, cprint, cprintln, untagged}; -#[cfg(not(feature = "terminfo"))] -pub use color_print_proc_macro::cstr; +pub use color_print_proc_macro::{cformat, cprint, cprintln, cstr, untagged}; #[cfg(feature = "terminfo")] mod terminfo; -- cgit v1.2.3