DOCSEARCHbyAlgolia
Submit Docs

paris

repository·master·Indexed 42 days ago

https://github.com/0x20f/paris

A simple Rust crate for outputting colorized, icon-enriched text in CLI applications. Version 1.5.15 provides a Logger API for chained logging, macro-based logging, and a formatter for direct string colorization using tags like <color>text</>. It supports foreground and background ANSI colors, text styles (bold, underline, etc.), and visual indicators via LogIcon.

Tokens
7.8K
Snippets
38
Records
42
Agent score
54%

What's inside paris

  1. Use the Formatter for direct string colorization

    master
    If you want to colorize strings without using the Logger struct, you can use the formatter module. This is useful if you want the formatting style (like <blue></>) but need a different logging mechanism. You can use the colorize_string function for direct usage.

  2. Reset text formatting with tags

    master

    To stop applying styles or colors, use the following reset tags:

    • </>: Resets everything to default (foreground and background).
    • <//>: Resets only the foreground color.
    • <///>: Resets only the background color.
    • </<tag_name>: Resets a specific style (e.g., </bold> to close a <bold> tag).

  3. Customize text with color tags

    master

    You can colorize text within your log strings using tags in the format <color>text</>.

    • Foreground colors: black, red, green, yellow, blue, cyan, magenta, white.
    • Bright colors: Add bright- prefix (e.g., <bright-red>).
    • Background colors: Add on- prefix (e.g., <on-red>).
    • Combined: You can combine tags (e.g., <blue><on-bright-red>).
    • Custom Styles: Use `log.add_style("name", vec!["color1", "color2"])" to create reusable style keys.
    log.info("I can write normal text or use tags to <red>color it</>");
log.add_style("lol", vec!["green", "bold", "on-bright-blue"]);
log.info("<lol>This is has all your new styles</>");
    log.info("I can write normal text or use tags to <red>color it</>");
log.warn("Every function can contain <on-green><black>tags</>");

log.info("If you don't write them <bleu>correctly</>, you just get an ugly looking tag");

// Custom styles
log.add_style("lol", vec!["green", "bold", "on-bright-blue"]);
log.info("<lol>This is has all your new styles</>");

  4. Install paris via Cargo

    master

    Add paris to your Cargo.toml dependencies. You can enable optional features like timestamps for log timestamps, macros for using macro-based logging, or no_logger if you only want to use macros without the Logger struct.

    # Basic installation
[dependencies]
paris = "1.5"

# Installation with timestamps and macros
[dependencies]
paris = { version = "1.5", features = ["timestamps", "macros"] }

# Installation using only macros (no Logger struct included)
[dependencies]
paris = { version = "1.5", features = ["no_logger"] }

  5. Chain Logger methods for complex layouts

    master

    All Logger methods return a reference to the logger, allowing you to chain commands to handle indentation, newlines, and multiple log levels in a single statement. This helps avoid manual string concatenation for tabs and newlines.

    #[cfg(not(feature = "no_logger"))] {
    use paris::Logger;
    let mut log = Logger::new();

    log.info("this is some info")
       .indent(4).warn("this is now indented by 4")
       .newline(5)
       .success("and this is 5 lines under all other messages");
}

  6. Use loading animations

    master

    You can display a continuous loading animation in the terminal using loading(message). This spawns a background thread that cycles through animation frames.

    To stop the animation and clear the line, call .done(). Note that most other logging methods (like success, info, or error) automatically call .done() for you, so you can transition directly from a loading state to a result state.

    Important: If you start a loading animation, ensure you eventually call .done() or another logging method to clean up the thread and clear the terminal line.

    use paris::Logger;

let mut logger = Logger::new();
logger.loading("Counting to 52!");

// ... perform work ...

// Transitioning directly to success calls .done() automatically
logger.success("Done counting!");

  7. Customize text color with tags

    master

    You can colorize text within your log strings using tags in the format <color>text</>.

    • Foreground colors: Use standard color names like red, blue, green, magenta, black, white, etc.
    • Background colors: Prefix a color with on- (e.g., <on-red>text</>).
    • Bright colors: Add bright to the tag (e.g., <blue><on-bright-red>text</>).
    • Resetting: Use </> to reset all styling to default. Use <///> to reset only the background, or <//> to reset only the foreground.
    #[cfg(not(feature = "no_logger"))] {
    use paris::Logger;
    let mut log = Logger::new();

    // Foreground and Background
    log.info("<on-red> This has red background </>");

    // Combined styles
    log.info("<blue><on-bright-red> This text is blue on a bright red background</> it's a pain");

    // Partial resets
    log.info("Reset background: <red>text<///> still red foreground");
    log.info("Reset foreground: <blue>text<//> still blue background");
}

  8. Initialize the Logger

    master

    To use the high-level logging output in paris, initialize a new Logger instance using Logger::new(). The logger supports method chaining and provides various levels of output with built-in styling and animations.

    use paris::Logger;

let mut logger = Logger::new();

  9. Use the Logger to output styled text

    master

    To use paris for basic logging, instantiate a Logger and call its level-specific methods like info, warn, error, or success. By default, these methods prepend an icon (e.g., ℹ for info, ✖ for error) to your message.

    Note: The Logger struct is only available if the no_logger feature is not enabled.

    #[cfg(not(feature = "no_logger"))] {
    use paris::Logger;

    let mut log = Logger::new();
    log.info("It's that simple!");
}

  10. Use Paris macros for quick logging

    master

    If the macros feature is enabled, you can use info! and error! macros.

    Advantages:

    • No need to instantiate Logger::new().
    • Supports standard print! style parameter formatting.

    Disadvantages:

    • Cannot chain calls.
    • Requires manual \n and \t for newlines and tabs.
    • Does not support loading animations.
    #[cfg(feature = "macros")] {
    use paris::{ info, error };

    info!("Will add ℹ at the start");
    error!("Will add ✖ at the start");
}

  11. Chain Logger methods

    master

    All Logger methods return a type that allows for chaining. This enables you to build complex log structures with indentation and newlines in a single statement, avoiding manual string concatenation.

    log.info("this is some info")
   .indent(4).warn("this is now indented by 4")
   .newline(5)
   .success("and this is 5 lines under all other messages");

  12. Directly colorize strings with `colorize_string`

    master
    For ease of use without initializing a Logger, use the colorize_string function from the formatter module to directly colorize strings. Note that drawbacks and caveats may apply depending on your environment.