Skip to content

Latest commit

 

History

History
159 lines (103 loc) · 3.17 KB

README.md

File metadata and controls

159 lines (103 loc) · 3.17 KB
Raw

Textus Coloris

Simple "library" for doing colourised console output.

API

enum tc_coloris_mode {
        TC_COLORIS_MODE_OFF,
        TC_COLORIS_MODE_ON,
        TC_COLORIS_MODE_AUTO,
};

There are five functions

void tc_set_colors(const struct tc_coloris *colors, enum tc_coloris_mode mode);

This is to set the colour map. mode can be one of enum tc_coloris_mode which produces the following behaviour

TC_COLORIS_MODE_OFF

Forces colour output off.

TC_COLORIS_MODE_ON

Forces colour output on, regardless of the NO_COLOR setting.

TC_COLORIS_MODE_AUTO

Obey the NO_COLOR environment variable.

int tc_print(FILE *fp, const char *fmt, ...);
int tc_printv(FILE *fp, const char *fmt, va_list args);

These print a colourised output to the given output stream. These are analogous to the fprintf(3) & vfprintf(3) function.

char *tc_cstring(const char *fmt, ...);
char *tc_cstringv(const char *fmt, va_list args);

These return a pointer to a colourised string. You should free(2) this pointer, NULL will be returned on error. These are sort of analogous to the asprintf(3) & vasprintf(3) functions.

Use

Seeing as this is really a bit too simple to make into an actual DSO, it is instead presented as a header-only library.

This is contained under header-only/.

There is a simple test program to show basic usage. Essentially just copy textus_coloris.h into your project and

#define TEXTUS_COLORIS_IMPL
#include "textus_coloris.h"

in one of your .c files. If you want to use these functions from any other source files then just do

#include "textus_coloris.h"

in them.

Define a colour map

static const struct tc_coloris colors[] = {
        { "RED",                "\e[38;5;160m" },
        { "GREEN",              "\e[38;5;40m"  },
        { "BLUE",               "\e[38;5;75m"  },

        { "BOLD",               "\e[1m"        },
        { "RST",                "\e[0m"        },

        {}
};

then set it with

tc_set_colors(colors, TC_COLORIS_MODE_AUTO);

Then you can do stuff like

tc_print(stdout, "Hello World! #BOLD##GREEN#%s#RST#\n", "Hello World!");

split-out

There is also a version with the core code split out into a .c file. You can just copy textus_coloris.[ch] into your project and build the .c file as you do the rest. Then it's like the above but you don't #define TEXTUS_COLORIS_IMPL

Otherwise the functionality is the same.

Examples

There are examples of usage under header-only/ & split-out/

Build

On Linux

$ make

in either of the header-only/ & split-out/ directories.

On FreeBSD

$ gmake

or if GCC isn't installed, it will build cleanly with clang

$ gmake CC=clang

NO_COLOR

This obeys the NO_COLOR environment variable when using TC_COLORIS_MODE_AUTO

Thread safety

This should be thread safe, the colour map pointer is stored in thread local storage so you should be able to set per thread colour maps.

License

This licensed under under the MIT license.

See LICENSE in the repository root for details.

Contributing

See CodingStyle.md & Contributing.md