Colorful

A tiny Java library to build ANSI-colored strings for terminals. It provides:

• A fluent Builder API via the Colorful class for composing colored text segments
• Truecolor (24-bit) RGB helpers via RGB.foreground(...) and RGB.background(...)
• 256-color helpers via Colorful.fg256(n) and Colorful.BG256(n)
• Predefined text and background colors (normal and bright)
• Common text styles (bold, italic, underline, strikethrough, hidden, reset)
• Minecraft-style color code translation (e.g., "&aHello &lWorld") to and from ANSI

Works in terminals that support ANSI escape sequences.

Requirements

• Java 8 or newer

Getting started

You can use Colorful in several ways:

1. Build from source and use the JAR

• Clone this repository
• Build: ./gradlew build
• Add the generated JAR from build/libs/ to your project

2. Copy small utility classes

• The library is small and self-contained. You can copy the classes under src/main/java/io/github/undeffineddev/colorful/ into your project if you prefer.

Usage

Fluent builder for colored text Each segment you add ends with a RESET automatically to avoid color bleed. Chain multiple segments to compose complex output.

    import io.github.undeffineddev.colorful.Colorful;
    import io.github.undeffineddev.colorful.type.BackgroundColor;
    import io.github.undeffineddev.colorful.type.TextStyles;

    String s = Colorful.BLACK("CO", BackgroundColor.BG_YELLOW)
            .BLACK("LOM", BackgroundColor.BG_BLUE)
            .BLACK("BIA", BackgroundColor.BG_RED)
            .build();

    System.out.println(s);

Exact RGB foreground/background (24-bit truecolor)

    import io.github.undeffineddev.colorful.Colorful;
    import io.github.undeffineddev.colorful.RGB;
    import io.github.undeffineddev.colorful.type.TextStyles;

    String out = Colorful.GENERIC(10, 20, 30, "Hi", 1, 2, 3).build();
    // Equivalent manual form:
    String expected = RGB.foreground(10, 20, 30) + RGB.background(1, 2, 3) + "Hi" + TextStyles.RESET;

256-color helpers

    import io.github.undeffineddev.colorful.Colorful;

    String f = Colorful.fg256(123); // "\u001B[38;5;123m"
    String b = Colorful.BG256(200); // "\u001B[48;5;200m"

Predefined colors and styles

• Text colors: see io.github.undeffineddev.colorful.type.TextColor
• Background colors: see io.github.undeffineddev.colorful.type.BackgroundColor
• Styles (bold, italic, underline, strikethrough, hidden, reset): see io.github.undeffineddev.colorful.type.TextStyles

You can also use the fluent methods on Colorful to set standard and bright colors for text and backgrounds, e.g. Colorful.RED("text"), Colorful.BRIGHT_BLUE("text"), or their overloads with backgrounds.

Minecraft color codes Translate Minecraft-style codes to ANSI and back.

    import io.github.undeffineddev.colorful.Minecraft;
    import io.github.undeffineddev.colorful.type.TextStyles;
    import io.github.undeffineddev.colorful.RGB;

    String ansi = Minecraft.toColorCode("&aHello &lWorld");
    // Produces: RGB.foreground(85, 255, 85) + "Hello " + TextStyles.BOLD + "World" + TextStyles.RESET

    String custom = Minecraft.toColorCode("§9Blue §nUnderline", '§');

    String mc = Minecraft.fromColorCode(
            RGB.foreground(255, 85, 85) + "Error " + TextStyles.ITALIC + "msg" + TextStyles.RESET);
    // mc == "&cError &omsg&r"

API overview

• Colorful: entry points for the fluent builder and 256-color helpers

  • fg256(int n): String — 256-color foreground
  • BG256(int n): String — 256-color background
  • Color methods (BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE) and their BRIGHT_* variants
    • Overloads:
      • method(String text)
      • method(String text, String bg)
      • method(String text, int bgR, int bgG, int bgB)
      • method() — continue chaining with just color/style
  • GENERIC(int r, int g, int b, String text [, String bg or bgR,bgG,bgB]) — exact RGB

• RGB: low-level helpers for truecolor sequences

  • foreground(int r, int g, int b): String
  • background(int r, int g, int b): String

• type.TextColor / type.BackgroundColor: predefined ANSI constants

• type.TextStyles: style constants (BOLD, ITALIC, UNDERLINE, STRIKETHROUGH, HIDDEN, RESET)

• Minecraft: translate between Minecraft codes and ANSI

  • toColorCode(String input[, char sign])
  • fromColorCode(String input)

Notes

• Every built segment ends with RESET ("\u001B[0m") to prevent color bleeding into subsequent terminal output.
• ANSI support varies by terminal. Most modern terminals support 24-bit RGB; older ones may require 256-color or 16-color sequences.
• When combining raw ANSI with the builder output, remember that the builder appends a RESET at the end of each build() call and between chained segments.

Building

• Run tests: ./gradlew test
• Build artifacts: ./gradlew build

License