== Terminal Rich-Text C-Library ==

A string-builder for generating rich-textual-output for terminals, supporting
Select Graphic Rendition ANSI-escape-sequences (see
https://en.wikipedia.org/wiki/ANSI_escape_code#Select_Graphic_Rendition_parameters
); implemented as a single-header C-library.

-- IMPORTANT NOTICE --

CURRENTLY NOT WELL TESTED! FOR NOW, ONLY USE THIS LIBRARY IF YOU'RE WILLING TO
UNDERSTANDING THE CODE AND FIXING BUGS YOURSELF!

-- Including the Library in your code --

1. Copy the file terminal_rich_text.h into your code-base.

2. Include the library in code:

    #include terminal_rich_text.h

    // Tell the C-compiler to generate instructions-code for the library
    // implementation, while processing the header.
    #define TRT_IMPLEMENTATION
    //
    //  Only add the above line in ONE single file in your code-base!
    //  (Or once for each entry-point; in which case you probably know what
    //   you're doing anyway.)
    //  In contrast, the include directive `#include trt.h` can be used
    //  in multiple source-code files.
    //
    //  See https://github.com/nothings/stb/blob/master/docs/stb_howto.txt
    //  for more information on the single-header-file-library concept.
    //
    #include terminal_rich_text.h

-- Example Usage --

#include <stdint.h>
#include <stdlib.h>
#include <unistd.h>
#define TRT_IMPLEMENTATION
#include "terminal_rich_text.h"

int main(void) {
    char str[4096];
    char* str_ptr  = str;
    char* str_stop = str + sizeof(str)/sizeof(char);

    uint64_t rich_text_state = 0;

    uint64_t colors_instruction[] = {
        TRT_COLOR_4BIT_TEXT(TRT_BLACK),
        TRT_COLOR_4BIT_TEXT(TRT_WHITE),
        TRT_COLOR_4BIT_TEXT(TRT_RED),

        TRT_COLOR_4BIT_TEXT(TRT_BRIGHT|TRT_BLUE),
        TRT_COLOR_4BIT_BACKGROUND(TRT_CYAN),
        TRT_RESET,

        TRT_COLOR_8BIT_TEXT(42),
        TRT_COLOR_RGB_TEXT(42, 111, 222),

        TRT_COLOR_RGB_TEXT(1, 2, 3)|TRT_COLOR_4BIT_BACKGROUND(TRT_BRIGHT|TRT_WHITE)
    };
    for (int i = 0; i < sizeof(colors_instruction)/sizeof(uint64_t); ++i) {
        if (trt_rich(&str_ptr, str_stop, &rich_text_state, colors_instruction[i]))
            return EXIT_FAILURE;

        if (   trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_BOLD, "Bold ")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_FAINT, "Faint ")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_ITALIC, "Italic ")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_UNDERLINE, "Underline ")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_STRIKETHROUGH, "Strikethrough ")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_INVERT_COLORS, "Inverted Colors")
            || trt_rich_text(&str_ptr, str_stop, &rich_text_state,
                             TRT_BOLD|TRT_UNDERLINE, "Bold Underline\n")
        )   return EXIT_FAILURE;
    }

    if (write(1, str, str_ptr - str) == -1)
        return EXIT_FAILURE;

    return EXIT_SUCCESS;
}

-- API Documentation --

See header definitions.


-- License (MIT) --

Copyright (c) 2025 Oscar Butler-Aldridge

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.