Declarations for ColrC functions, enums, structs, etc. More...
#include <assert.h>
#include <ctype.h>
#include <math.h>
#include <limits.h>
#include <locale.h>
#include <printf.h>
#include <regex.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <unistd.h>
#include <wchar.h>
Go to the source code of this file.
Data Structures | |
struct | BasicInfo |
Holds a known color name and it's BasicValue . More... | |
struct | ColorArg |
Holds an ArgType, and a ColorValue. More... | |
struct | ColorJustify |
Holds a string justification method, width, and padding character for ColorTexts. More... | |
struct | ColorNameData |
Holds info about a known color name, like it's ExtendedValue and it's RGB value. More... | |
struct | ColorResult |
Holds a string (char* ) that was definitely allocated by Colr. More... | |
union | ColorStructMarker |
Breaks down Colr struct markers, such as COLORARG_MARKER, into individual bytes. More... | |
struct | ColorStructMarker.bytes |
Individual bytes that make up the marker. More... | |
struct | ColorText |
Holds a string of text, and optional fore, back, and style ColorArgs. More... | |
struct | ColorValue |
Holds a color type and it's value. More... | |
struct | ExtendedInfo |
Holds a known color name and it's ExtendedValue . More... | |
struct | RGB |
Container for RGB values. More... | |
struct | StyleInfo |
Holds a known style name and it's StyleValue . More... | |
struct | TermSize |
Holds a terminal size, usually retrieved with colr_term_size(). More... | |
Macros | |
#define | alloc_basic() calloc(CODE_LEN, sizeof(char)) |
Allocate enough for a basic code. More... | |
#define | alloc_extended() calloc(CODEX_LEN, sizeof(char)) |
Allocate enough for an extended code. More... | |
#define | alloc_rgb() calloc(CODE_RGB_LEN, sizeof(char)) |
Allocate enough for an rgb code. More... | |
#define | alloc_style() calloc(STYLE_LEN, sizeof(char)) |
Allocate enough for a style code. More... | |
#define | asprintf_or_return(retval, ...) if_not_asprintf(__VA_ARGS__) return retval |
Convenience macro for bailing out of a function when asprintf fails. More... | |
#define | back(x) ColorArg_to_ptr(back_arg(x)) |
Create a back color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros. More... | |
#define | back_arg(x) |
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument. More... | |
#define | back_str(x) ColorArg_to_esc(back_arg(x)) |
Return just the escape code string for a back color. More... | |
#define | back_str_static(x) |
Creates a stack-allocated escape code string (char* ) for a back color. More... | |
#define | basic(x) ((BasicValue)(x)) |
Casts to BasicValue. More... | |
#define | bool_colr_enum(x) (x < 0 ? false: true) |
Returns the "truthiness" of the enums used in ColrC (BasicValue, ExtendedValue function-returns, StyleValue, ColorType, ArgType). More... | |
#define | CODE_ANY_LEN 46 |
Maximum length in chars for any possible escape code mixture for one complete style (one of each: fore, back, and style). More... | |
#define | CODE_LEN 14 |
Maximum length for a basic fore/back escape code, including `'\0'`. More... | |
#define | CODE_LEN_MIN 5 |
Minimum length for the shortest basic fore/back escape code, including `'\0'`. More... | |
#define | CODE_RESET_ALL "\x1b[0m" |
Convenience definition, because this is used a lot. | |
#define | CODE_RESET_BACK "\x1b[49m" |
Convenience definition for resetting the back color. | |
#define | CODE_RESET_FORE "\x1b[39m" |
Convenience definition for resetting the fore color. | |
#define | CODE_RESET_LEN 5 |
Length of CODE_RESET_ALL, including `'\0'`. | |
#define | CODE_RGB_LEN 20 |
Maximum length in chars for an RGB fore/back escape code, including `'\0'`. | |
#define | CODE_RGB_LEN_MIN 14 |
Minimum length for the shortest RGB fore/back escape code, including `'\0'`. More... | |
#define | CODEX_LEN 12 |
Maximum length for an extended fore/back escape code, including `'\0'`. | |
#define | CODEX_LEN_MIN 10 |
Minimum length for the shortest extended fore/back escape code, including `'\0'`. More... | |
#define | color_arg(type, x) |
Builds a correct ColorArg struct according to the type of it's second argument. More... | |
#define | COLOR_INVALID (-2) |
Possible error return value for BasicValue_from_str(), ExtendedValue_from_str(), and colorname_to_rgb(). | |
#define | COLOR_INVALID_RANGE (-3) |
Possible error return value for RGB_from_str(). | |
#define | COLOR_LEN 30 |
Maximum length in chars for any combination of basic/extended escape codes for one complete style (one of each: fore, back, style). More... | |
#define | color_name_is_invalid(x) ColorType_is_invalid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is invalid. More... | |
#define | color_name_is_valid(x) ColorType_is_valid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is valid. More... | |
#define | COLOR_RGB_LEN 26 |
Maximum length in chars added to a rgb colorized string. More... | |
#define | color_val(x) |
Builds a correct ColorValue struct according to the type of it's first argument. More... | |
#define | COLORARG_MARKER UINT32_MAX |
Marker for the ColorArg struct, for identifying a void pointer as a ColorArg. More... | |
#define | COLORJUSTIFY_MARKER (UINT32_MAX - 30) |
Marker for the ColorJustify struct, for identifying a void pointer as a ColorJustify. | |
#define | COLORLASTARG_MARKER (UINT32_MAX - 20) |
Marker for the _ColrLastArg_s struct, for identifying a void pointer as a _ColrLastArg_s. | |
#define | COLORRESULT_MARKER (UINT32_MAX - 40) |
Marker for the ColorResult struct, for identifying a void pointer as a ColorResult. | |
#define | ColorText_center(text, justwidth, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | ColorText_center_char(text, justwidth, c, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | ColorText_ljust(text, justwidth, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | ColorText_ljust_char(text, justwidth, c, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | COLORTEXT_MARKER (UINT32_MAX - 50) |
Marker for the ColorText struct, for identifying a void pointer as a ColorText. | |
#define | ColorText_rjust(text, justwidth, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | ColorText_rjust_char(text, justwidth, c, ...) |
Sets the JustifyMethod for a ColorText while allocating it. More... | |
#define | ColorValue_has(cval, val) |
Call the current ColorValue_has_<type> function for the given value. More... | |
#define | Colr(text, ...) ColorText_to_ptr(ColorText_from_values(text, __VA_ARGS__, _ColrLastArg)) |
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros. More... | |
#define | colr(text, ...) colr_cat(Colr(text, __VA_ARGS__)) |
Create an allocated string directly from Colr() arguments. More... | |
#define | colr_alloc_len(x) |
Return the number of bytes needed to allocate an escape code string based on the color type. More... | |
#define | colr_asprintf(...) colr_printf_macro(asprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call asprintf . More... | |
#define | Colr_cat(...) ColorResult_to_ptr(ColorResult_new(colr_cat(__VA_ARGS__))) |
Like colr_cat(), but returns an allocated ColorResult that the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free() . More... | |
#define | colr_cat(...) _colr_join("", __VA_ARGS__, _ColrLastArg) |
Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string. More... | |
#define | Colr_center(x, width) |
Like Colr_center_char, it center-justifies ColrC objects and strings (char* ), except it uses `' '` (space) as the pad character. More... | |
#define | colr_center(x, width) colr_center_char(x, width, ' ') |
Like Colr_center it center-justifies ColrC objects and strings (char* ) using `' '(space) as the pad character, except it returns an allocated string ( char*`). More... | |
#define | colr_center_char(x, width, padchar) |
Like Colr_center_char it left-justifies ColrC objects and strings (char* ), except it returns an allocated string (char* ). More... | |
#define | colr_eq(a, b) |
Calls the <type>_eq functions for the supported types. More... | |
#define | colr_example(x) |
Calls the <type>_example functions for the supported types. More... | |
#define | COLR_FMT "R" |
Format character string suitable for use in the printf-family of functions. More... | |
#define | Colr_fmt(fmt, value, ...) |
Format and colorize a value like the printf -family. More... | |
#define | COLR_FMT_CHAR COLR_FMT[0] |
Character used in printf format strings for Colr objects. | |
#define | COLR_FMT_MOD_ESC "/" |
Modifier for Colr printf character to produce escaped output. | |
#define | COLR_FMT_MOD_ESC_CHAR COLR_FMT_MOD_ESC[0] |
Modifier for Colr printf character to produce escaped output, in char form. | |
#define | colr_fprint(file, ...) |
Create a string from a colr_cat() call, print it to file (without a newline), and free it. More... | |
#define | colr_fprintf(...) colr_printf_macro(fprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call fprintf . More... | |
#define | colr_free(x) |
Calls the <type>_free functions for the supported types. More... | |
#define | COLR_GNU |
Defined when __GNUC__ is available, to enable statement-expressions and register_printf_specifier . More... | |
#define | COLR_HASH_SEED 5381 |
Seed value for colr_str_hash(). | |
#define | colr_is_empty(x) |
Calls the <type>is_empty functions for the supported types. More... | |
#define | colr_is_invalid(x) |
Calls the <type>is_invalid functions for the supported types. More... | |
#define | colr_is_valid(x) |
Calls the <type>is_valid functions for the supported types. More... | |
#define | colr_is_valid_mblen(x) ((x) && ((x) != (size_t)-1) && ((x) != (size_t)-2)) |
Checks return values from mbrlen() and colr_mb_len(). More... | |
#define | colr_istr_either(s1, s2, s3) |
Convenience macro for !strcasecmp(s1, s2) || !strcasecmp(s1, s3) . More... | |
#define | colr_istr_eq(s1, s2) |
Convenience macro for !strcasecmp(s1, s2) . More... | |
#define | Colr_join(joiner, ...) ColrResult(colr_join(joiner, __VA_ARGS__)) |
Joins Colr objects and strings, exactly like colr_join(), but returns an allocated ColorResult that the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free() for you. More... | |
#define | colr_join(joiner, ...) _colr_join(joiner, __VA_ARGS__, _ColrLastArg) |
Join ColorArg pointers, ColorText pointers, and strings by another ColorArg pointer, ColorText pointer, or string. More... | |
#define | colr_length(x) |
Calls the <type>_length functions for the supported types. More... | |
#define | Colr_ljust(x, width) |
Like Colr_ljust_char, it left-justifies ColrC objects and strings (char* ), except it uses `' '` (space) as the pad character. More... | |
#define | colr_ljust(x, width) colr_ljust_char(x, width, ' ') |
Like Colr_ljust it left-justifies ColrC objects and strings (char* ) using `' '(space) as the pad character, except it returns an allocated string ( char*`). More... | |
#define | colr_ljust_char(x, width, padchar) |
Like Colr_ljust_char it left-justifies ColrC objects and strings (char* ), except it returns an allocated string (char* ). More... | |
#define | colr_max(a, b) (a > b ? a : b) |
Macro for (a > b ? a : b) . More... | |
#define | colr_print(...) |
Create a string from a colr_cat() call, print it to stdout (without a newline), and free it. More... | |
#define | colr_printf(...) colr_printf_macro(printf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call printf . More... | |
#define | colr_printf_macro(func, ...) |
Calls one of the printf-family functions, with format warnings disabled for the call, and returns the result. More... | |
#define | colr_puts(...) |
Create a string from a colr_cat() call, print it (with a newline), and free it. More... | |
#define | colr_replace(s, target, repl) |
Replace a substring in s with another string, ColorArg string, ColorResult string, or ColorText string. More... | |
#define | colr_replace_all(s, target, repl) |
Replace all substrings in s with another string, ColorArg string, ColorResult string, or ColorText string. More... | |
#define | colr_replace_re(s, target, repl, flags) |
Replace a regex pattern string (char* ) in s with another string, ColorArg string, ColorResult string, or ColorText string. More... | |
#define | colr_replace_re_all(s, target, repl, flags) |
Replace all matches to a regex pattern string (char* ) in s with another string, ColorArg string, ColorResult string, or ColorText string. More... | |
#define | colr_repr(x) |
Transforms several ColrC objects into their string representations. More... | |
#define | Colr_rjust(x, width) |
Like Colr_rjust_char, it right-justifies ColrC objects and strings (char* ), except it uses `' '` (space) as the pad character. More... | |
#define | colr_rjust(x, width) colr_rjust_char(x, width, ' ') |
Like Colr_rjust it right-justifies ColrC objects and strings (char* ) using `' '(space) as the pad character, except it returns an allocated string ( char*`). More... | |
#define | colr_rjust_char(x, width, padchar) |
Like Colr_rjust_char it right-justifies ColrC objects and strings (char* ), except it returns an allocated string (char* ). More... | |
#define | colr_snprintf(...) colr_printf_macro(snprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call snprintf . More... | |
#define | colr_sprintf(...) colr_printf_macro(sprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call sprintf . More... | |
#define | colr_str_either(s1, s2, s3) (colr_str_eq(s1, s2) || colr_str_eq(s1, s3)) |
Convenience macro for !strcmp(s1, s2) || !strcmp(s1, s3) . More... | |
#define | colr_str_eq(s1, s2) |
Convenience macro for !strcmp(s1, s2) . More... | |
#define | colr_to_str(x) |
Calls the <type>_to_str functions for the supported types. More... | |
#define | COLR_VERSION "0.4.0" |
Current version for ColrC. | |
#define | Colra(text, ...) ColorText_from_values(text, __VA_ARGS__, _ColrLastArg) |
Returns an initialized stack-allocated ColorText. More... | |
#define | ColrColorResult(cres, ...) ColorResult_Colr(cres, __VA_ARGS__, _ColrLastArg) |
Like Colr(), but it operates on a ColorResult to generate a new colorized ColorResult. More... | |
#define | ColrResult(s) ColorResult_to_ptr(ColorResult_new(s)) |
Wraps an allocated string in a ColorResult, which marks it as "freeable" in the colr macros. More... | |
#define | ext(x) ((ExtendedValue)x) |
Casts to ExtendedValue (unsigned char ). More... | |
#define | ext_hex(s) ext_hex_or(s, ext(0)) |
Like hex(), but force a conversion to the closest ExtendedValue (256-colors). More... | |
#define | ext_hex_or(s, default_value) ExtendedValue_from_hex_default(s, default_value) |
Like hex_or(), but force a conversion to the closest ExtendedValue (256-colors). More... | |
#define | EXT_INVALID COLOR_INVALID |
Alias for COLOR_INVALID. More... | |
#define | EXT_INVALID_RANGE COLOR_INVALID_RANGE |
Possible error return value for ExtendedValue_from_str() or ExtendedValue_from_esc(). More... | |
#define | ext_rgb(r, g, b) ExtendedValue_from_RGB((RGB){.red=r, .green=g, .blue=b}) |
Creates the closest matching ExtendedValue from separate red, green, and blue values. More... | |
#define | ext_RGB(rgbval) ExtendedValue_from_RGB(rgbval) |
Creates the closest matching ExtendedValue from an RGB value. More... | |
#define | fore(x) ColorArg_to_ptr(fore_arg(x)) |
Create a fore color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros. More... | |
#define | fore_arg(x) |
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument. More... | |
#define | fore_str(x) ColorArg_to_esc(fore_arg(x)) |
Return just the escape code string for a fore color. More... | |
#define | fore_str_static(x) |
Creates a stack-allocated escape code string (char* ) for a fore color. More... | |
#define | hex(s) hex_or(s, rgb(0, 0, 0)) |
Use RGB_from_hex_default() to create an RGB value. More... | |
#define | hex_or(s, default_rgb) RGB_from_hex_default(s, default_rgb) |
Use RGB_from_hex_default() to create an RGB value. More... | |
#define | if_not_asprintf(...) if (asprintf(__VA_ARGS__) < 1) |
Convenience macro for checking asprintf's return value. More... | |
#define | NC CODE_RESET_ALL |
Short-hand for CODE_RESET_ALL, stands for "No Color". | |
#define | NCNL CODE_RESET_ALL "\n" |
Short-hand for CODE_RESET_ALL "\n" , stands for "No Color, New Line". | |
#define | rgb(r, g, b) ((RGB){.red=r, .green=g, .blue=b}) |
Creates an anonymous RGB struct for use in function calls. More... | |
#define | style(x) ColorArg_to_ptr(style_arg(x)) |
Create a style suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros. More... | |
#define | style_arg(x) |
Uses ColorArg_from_StyleValue to build a ColorArg with the appropriate color type/value. More... | |
#define | STYLE_LEN 6 |
Maximum length for a style escape code, including `'\0'`. | |
#define | STYLE_LEN_MIN 5 |
Minimum length for the shortest style escape code, including `'\0'`. More... | |
#define | STYLE_MAX_VALUE ((StyleValue)OVERLINE) |
Maximum value allowed for a StyleValue. | |
#define | STYLE_MIN_VALUE ((StyleValue)STYLE_INVALID_RANGE) |
Minimum value allowed for a StyleValue. | |
#define | style_str(x) ColorArg_to_esc(style_arg(x)) |
Return just the escape code string for a style. More... | |
#define | style_str_static(x) |
A less-flexible style_str() that returns a static escape code string for a style. More... | |
#define | WCODE_RESET_ALL L"\x1b[0m" |
Convenience definition for wide chars. | |
#define | WCODE_RESET_BACK L"\x1b[49m" |
Convenience definition for resetting the back color. | |
#define | WCODE_RESET_FORE L"\x1b[39m" |
Convenience definition for resetting the fore color. | |
#define | while_colr_va_arg(ap, vartype, x) while (x = va_arg(ap, vartype), !_colr_is_last_arg(x)) |
Construct a while-loop over a va_list , where the last argument is expected to be _ColrLastArg, or a pointer to a _ColrLastArg_s with the same values as _ColrLastArg. More... | |
#define | WNC WCODE_RESET_ALL |
Short-hand for WCODE_RESET_ALL, stands for "Wide No Color". | |
#define | WNCNL WCODE_RESET_ALL L"\n" |
Short-hand for WCODE_RESET_ALL "\n" , stands for "Wide No Color, New Line". | |
Typedefs | |
typedef unsigned char | ExtendedValue |
Convenience typedef for clarity when dealing with extended (256) colors. | |
typedef char *(* | rainbow_creator) (const char *s, double freq, size_t offset, size_t spread) |
A function type that knows how to create rainbowized text. | |
typedef void(* | RGB_fmter) (char *out, RGB rgb) |
A function type that knows how to fill a string with an rgb escape code. More... | |
Enumerations | |
enum | ArgType { ARGTYPE_NONE = -1, FORE = 0, BACK = 1, STYLE = 2 } |
Argument types (fore, back, style). | |
enum | BasicValue { BASIC_INVALID_RANGE = COLOR_INVALID_RANGE, BASIC_INVALID = COLOR_INVALID, BASIC_NONE = -1, BLACK = 0, RED = 1, GREEN = 2, YELLOW = 3, BLUE = 4, MAGENTA = 5, CYAN = 6, WHITE = 7, UNUSED = 8, RESET = 9, LIGHTBLACK = 10, LIGHTRED = 11, LIGHTGREEN = 12, LIGHTYELLOW = 13, LIGHTBLUE = 14, LIGHTMAGENTA = 15, LIGHTCYAN = 16, LIGHTWHITE = 17 } |
Basic color values, with a few convenience values for extended colors. More... | |
enum | ColorJustifyMethod { JUST_NONE = -1, JUST_LEFT = 0, JUST_RIGHT = 1, JUST_CENTER = 2 } |
Justification style for ColorTexts. | |
enum | ColorType { TYPE_NONE = -6, TYPE_INVALID_STYLE = -5, TYPE_INVALID_RGB_RANGE = -4, TYPE_INVALID_EXT_RANGE = COLOR_INVALID_RANGE, TYPE_INVALID = COLOR_INVALID, TYPE_BASIC = 0, TYPE_EXTENDED = 1, TYPE_RGB = 2, TYPE_STYLE = 3 } |
Color/Style code types. Used with ColorType_from_str() and ColorValue. | |
enum | StyleValue { STYLE_INVALID_RANGE = COLOR_INVALID_RANGE, STYLE_INVALID = COLOR_INVALID, STYLE_NONE = -1, RESET_ALL = 0, BRIGHT = 1, DIM = 2, ITALIC = 3, UNDERLINE = 4, FLASH = 5, HIGHLIGHT = 7, STRIKETHRU = 9, NORMAL = 22, FRAME = 51, ENCIRCLE = 52, OVERLINE = 53 } |
Style values. | |
Functions | |
void | _colr_free (void *p) |
Calls Colr *_free() functions for Colr objects, otherwise just calls free() . More... | |
bool | _colr_is_last_arg (void *p) |
Determines if a void pointer is _ColrLastArg (the last-arg-marker). More... | |
char * | _colr_join (void *joinerp,...) |
Joins ColorArgs, ColorTexts, and strings (char* ) into one long string separated by it's first argument. More... | |
size_t | _colr_join_array_length (void *ps) |
Determine the length of a NULL -terminated array of strings (char* ), ColorArg s, ColorResult s, or ColorText s. More... | |
size_t | _colr_join_arrayn_size (void *joinerp, void *ps, size_t count) |
Get the size in bytes needed to join an array of strings (char* ), ColorArg s, ColorResult s, or ColorText s by another string (char* ), ColorArg, ColorResult, or ColorText. More... | |
size_t | _colr_join_size (void *joinerp, va_list args) |
Parse arguments, just as in _colr_join(), but only return the size needed to allocate the resulting string. More... | |
size_t | _colr_ptr_length (void *p) |
Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char* ) into a string. More... | |
char * | _colr_ptr_repr (void *p) |
Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obtain an allocated string representation. More... | |
char * | _colr_ptr_to_str (void *p) |
Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to obtain an allocated string. More... | |
char * | _rainbow (RGB_fmter fmter, const char *s, double freq, size_t offset, size_t spread) |
Handles multibyte character string (char* ) conversion and character iteration for all of the rainbow_ functions. More... | |
bool | ArgType_eq (ArgType a, ArgType b) |
Compares two ArgTypes. More... | |
char * | ArgType_repr (ArgType type) |
Creates a string (char* ) representation of a ArgType. More... | |
char * | ArgType_to_str (ArgType type) |
Creates a human-friendly string (char* ) from an ArgType. More... | |
bool | BasicValue_eq (BasicValue a, BasicValue b) |
Compares two BasicValues. More... | |
BasicValue | BasicValue_from_esc (const char *s) |
Convert an escape-code string (char* ) to an actual BasicValue enum value. More... | |
BasicValue | BasicValue_from_str (const char *arg) |
Convert named argument to an actual BasicValue enum value. More... | |
bool | BasicValue_is_invalid (BasicValue bval) |
Determines whether a BasicValue is invalid. More... | |
bool | BasicValue_is_valid (BasicValue bval) |
Determines whether a BasicValue is valid. More... | |
char * | BasicValue_repr (BasicValue bval) |
Creates a string (char* ) representation of a BasicValue. More... | |
int | BasicValue_to_ansi (ArgType type, BasicValue bval) |
Converts a fore/back BasicValue to the actual ansi code number. More... | |
char * | BasicValue_to_str (BasicValue bval) |
Create a human-friendly string (char* ) representation for a BasicValue. More... | |
ColorArg | ColorArg_empty (void) |
Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE. More... | |
bool | ColorArg_eq (ColorArg a, ColorArg b) |
Compares two ColorArg structs. More... | |
char * | ColorArg_example (ColorArg carg, bool colorized) |
Create a string (char* ) representation of a ColorArg with a stylized type/name using escape codes built from the ColorArg's values. More... | |
void | ColorArg_free (ColorArg *p) |
Free allocated memory for a ColorArg. More... | |
ColorArg | ColorArg_from_BasicValue (ArgType type, BasicValue value) |
Explicit version of ColorArg_from_value that only handles BasicValues. More... | |
ColorArg | ColorArg_from_esc (const char *s) |
Parse an escape-code string (char* ) into a ColorArg. More... | |
ColorArg | ColorArg_from_ExtendedValue (ArgType type, ExtendedValue value) |
Explicit version of ColorArg_from_value that only handles ExtendedValues. More... | |
ColorArg | ColorArg_from_RGB (ArgType type, RGB value) |
Explicit version of ColorArg_from_value that only handles RGB structs. More... | |
ColorArg | ColorArg_from_str (ArgType type, const char *colorname) |
Build a ColorArg (fore, back, or style value) from a known color name/style. More... | |
ColorArg | ColorArg_from_StyleValue (ArgType type, StyleValue value) |
Explicit version of ColorArg_from_value that only handles StyleValues. More... | |
ColorArg | ColorArg_from_value (ArgType type, ColorType colrtype, void *p) |
Used with the color_arg macro to dynamically create a ColorArg based on it's argument type. More... | |
bool | ColorArg_is_empty (ColorArg carg) |
Checks to see if a ColorArg is an empty placeholder. More... | |
bool | ColorArg_is_invalid (ColorArg carg) |
Checks to see if a ColorArg holds an invalid value. More... | |
bool | ColorArg_is_ptr (void *p) |
Checks a void pointer to see if it contains a ColorArg struct. More... | |
bool | ColorArg_is_valid (ColorArg carg) |
Checks to see if a ColorArg holds a valid value. More... | |
size_t | ColorArg_length (ColorArg carg) |
Returns the length in bytes needed to allocate a string (char* ) built with ColorArg_to_esc(). More... | |
char * | ColorArg_repr (ColorArg carg) |
Creates a string (char* ) representation for a ColorArg. More... | |
char * | ColorArg_to_esc (ColorArg carg) |
Converts a ColorArg into an escape code string (char* ). More... | |
bool | ColorArg_to_esc_s (char *dest, ColorArg carg) |
Converts a ColorArg into an escape code string (char* ) and fills the destination string. More... | |
ColorArg * | ColorArg_to_ptr (ColorArg carg) |
Copies a ColorArg into memory and returns the pointer. More... | |
void | ColorArgs_array_free (ColorArg **ps) |
Free an allocated array of ColorArgs, including the array itself. More... | |
char * | ColorArgs_array_repr (ColorArg **lst) |
Creates a string representation for an array of ColorArg pointers. More... | |
ColorArg ** | ColorArgs_from_str (const char *s, bool unique) |
Create an array of ColorArgs from escape-codes found in a string (char* ). More... | |
ColorJustify | ColorJustify_empty (void) |
Creates an "empty" ColorJustify, with JUST_NONE set. More... | |
bool | ColorJustify_eq (ColorJustify a, ColorJustify b) |
Compares two ColorJustify structs. More... | |
bool | ColorJustify_is_empty (ColorJustify cjust) |
Checks to see if a ColorJustify is "empty". More... | |
ColorJustify | ColorJustify_new (ColorJustifyMethod method, int width, char padchar) |
Creates a ColorJustify. More... | |
char * | ColorJustify_repr (ColorJustify cjust) |
Creates a string (char* ) representation for a ColorJustify. More... | |
char * | ColorJustifyMethod_repr (ColorJustifyMethod meth) |
Creates a string (char* ) representation for a ColorJustifyMethod. More... | |
ColorResult * | ColorResult_center (ColorResult *cres, int width, char padchar) |
Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
ColorResult * | ColorResult_Colr (ColorResult *cres,...) |
Colorize a ColorResult, and return a new allocated ColorResult. More... | |
ColorResult | ColorResult_empty (void) |
Creates a ColorResult with .result=NULL and .length=-1 , with the appropriate struct marker. More... | |
bool | ColorResult_eq (ColorResult a, ColorResult b) |
Compares two ColorResults. More... | |
void | ColorResult_free (ColorResult *p) |
Free allocated memory for a ColorResult and it's .result member. More... | |
ColorResult | ColorResult_from_str (const char *s) |
Allocates a copy of a string, and creates a ColorResult from it. More... | |
ColorResult * | ColorResult_from_stra (const char *s) |
Allocates a copy of a string, and creates an allocated ColorResult from it. More... | |
bool | ColorResult_is_empty (ColorResult cres) |
Checks to see if a ColorResult is "empty" (NULL or empty string). More... | |
bool | ColorResult_is_ptr (void *p) |
Checks a void pointer to see if it contains a ColorResult struct. More... | |
size_t | ColorResult_length (ColorResult cres) |
Return the length in bytes (including the null-terminator), that is needed to store the return from ColorResult_to_str() (.result ). More... | |
ColorResult * | ColorResult_ljust (ColorResult *cres, int width, char padchar) |
Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
ColorResult | ColorResult_new (char *s) |
Initialize a new ColorResult with an allocated string (char* ). More... | |
char * | ColorResult_repr (ColorResult cres) |
Create a string representation for a ColorResult. More... | |
char * | ColorResult_rip_str (ColorResult *cres) |
Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char* )). More... | |
ColorResult * | ColorResult_rjust (ColorResult *cres, int width, char padchar) |
Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
ColorResult * | ColorResult_to_ptr (ColorResult cres) |
Allocate memory for a ColorResult, fill it, and return it. More... | |
char * | ColorResult_to_str (ColorResult cres) |
Convert a ColorResult into a string (char* ). More... | |
ColorText | ColorText_empty (void) |
Creates an "empty" ColorText with pointers set to NULL . More... | |
void | ColorText_free (ColorText *p) |
Frees a ColorText and it's ColorArgs. More... | |
void | ColorText_free_args (ColorText *p) |
Frees the ColorArg members of a ColorText. More... | |
ColorText | ColorText_from_values (char *text,...) |
Builds a ColorText from 1 mandatory string (char* ), and optional fore, back, and style args (pointers to ColorArgs). More... | |
ColorText | ColorText_from_valuesv (char *text, va_list args) |
Builds a ColorText from 1 mandatory string (char* ), and a va_list with optional fore, back, and style args (pointers to ColorArgs). More... | |
bool | ColorText_has_arg (ColorText ctext, ColorArg carg) |
Checks to see if a ColorText has a certain ColorArg value set. More... | |
bool | ColorText_has_args (ColorText ctext) |
Checks to see if a ColorText has any argument values set. More... | |
bool | ColorText_is_empty (ColorText ctext) |
Checks to see if a ColorText has no usable values. More... | |
bool | ColorText_is_ptr (void *p) |
Checks a void pointer to see if it contains a ColorText struct. More... | |
size_t | ColorText_length (ColorText ctext) |
Returns the length in bytes needed to allocate a string (char* ) built with ColorText_to_str() with the current text , fore , back , and style members. More... | |
char * | ColorText_repr (ColorText ctext) |
Allocate a string (char* ) representation for a ColorText. More... | |
ColorText * | ColorText_set_center (ColorText *ctext, int width, char padchar) |
Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string. More... | |
ColorText * | ColorText_set_just (ColorText *ctext, ColorJustify cjust) |
Set the ColorJustify method for a ColorText, and return the ColorText. More... | |
ColorText * | ColorText_set_ljust (ColorText *ctext, int width, char padchar) |
Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string. More... | |
ColorText * | ColorText_set_rjust (ColorText *ctext, int width, char padchar) |
Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string. More... | |
void | ColorText_set_values (ColorText *ctext, char *text,...) |
Initializes an existing ColorText from 1 mandatory string (char* ), and optional fore, back, and style args (pointers to ColorArgs). More... | |
ColorText * | ColorText_to_ptr (ColorText ctext) |
Copies a ColorText into allocated memory and returns the pointer. More... | |
char * | ColorText_to_str (ColorText ctext) |
Stringifies a ColorText struct, creating a mix of escape codes and text. More... | |
bool | ColorType_eq (ColorType a, ColorType b) |
Compares two ColorTypes. More... | |
ColorType | ColorType_from_str (const char *arg) |
Determine which type of color value is desired by name. More... | |
bool | ColorType_is_invalid (ColorType type) |
Check to see if a ColorType value is considered invalid. More... | |
bool | ColorType_is_valid (ColorType type) |
Check to see if a ColorType value is considered valid. More... | |
char * | ColorType_repr (ColorType type) |
Creates a string (char* ) representation of a ColorType. More... | |
char * | ColorType_to_str (ColorType type) |
Create a human-friendly string (char* ) representation for a ColorType. More... | |
ColorValue | ColorValue_empty (void) |
Create an "empty" ColorValue. More... | |
bool | ColorValue_eq (ColorValue a, ColorValue b) |
Compares two ColorValue structs. More... | |
char * | ColorValue_example (ColorValue cval) |
Create a string (char* ) representation of a ColorValue with a human-friendly type/name. More... | |
ColorValue | ColorValue_from_esc (const char *s) |
Convert an escape-code string (char* ) into a ColorValue. More... | |
ColorValue | ColorValue_from_str (const char *s) |
Create a ColorValue from a known color name, or RGB string (char* ). More... | |
ColorValue | ColorValue_from_value (ColorType type, void *p) |
Used with the color_val macro to dynamically create a ColorValue based on it's argument type. More... | |
bool | ColorValue_has_BasicValue (ColorValue cval, BasicValue bval) |
Checks to see if a ColorValue has a BasicValue set. More... | |
bool | ColorValue_has_ExtendedValue (ColorValue cval, ExtendedValue eval) |
Checks to see if a ColorValue has a ExtendedValue set. More... | |
bool | ColorValue_has_RGB (ColorValue cval, RGB rgb) |
Checks to see if a ColorValue has a RGB value set. More... | |
bool | ColorValue_has_StyleValue (ColorValue cval, StyleValue sval) |
Checks to see if a ColorValue has a StyleValue set. More... | |
bool | ColorValue_is_empty (ColorValue cval) |
Checks to see if a ColorValue is an empty placeholder. More... | |
bool | ColorValue_is_invalid (ColorValue cval) |
Checks to see if a ColorValue holds an invalid value. More... | |
bool | ColorValue_is_valid (ColorValue cval) |
Checks to see if a ColorValue holds a valid value. More... | |
size_t | ColorValue_length (ArgType type, ColorValue cval) |
Returns the length in bytes needed to allocate a string (char* ) built with ColorValue_to_esc() with the specified ArgType and ColorValue. More... | |
char * | ColorValue_repr (ColorValue cval) |
Creates a string (char* ) representation of a ColorValue. More... | |
char * | ColorValue_to_esc (ArgType type, ColorValue cval) |
Converts a ColorValue into an escape code string (char* ). More... | |
bool | ColorValue_to_esc_s (char *dest, ArgType type, ColorValue cval) |
Converts a ColorValue into an escape code string (char* ) and fills the destination string. More... | |
regmatch_t * | colr_alloc_regmatch (regmatch_t match) |
Allocates space for a regmatch_t, initializes it, and returns a pointer to it. More... | |
void | colr_append_reset (char *s) |
Appends CODE_RESET_ALL to a string (char* ), but makes sure to do it before any newlines. More... | |
ColorResult * | Colr_center_char (void *x, int width, char padchar) |
Returns a center-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char* ), along with the desired width and pad character. More... | |
char | colr_char_escape_char (const char c) |
Returns the char needed to represent an escape sequence in C. More... | |
bool | colr_char_in_str (const char *s, const char c) |
Determines if a character exists in the given string (char* ). More... | |
bool | colr_char_is_code_end (const char c) |
Determines if a character is suitable for an escape code ending. More... | |
char * | colr_char_repr (char c) |
Creates a string (char* ) representation for a char. More... | |
bool | colr_char_should_escape (const char c) |
Determines if an ascii character has an escape sequence in C. More... | |
bool | colr_check_marker (uint32_t marker, void *p) |
Checks an unsigned int against the individual bytes behind a pointer's value. More... | |
char * | colr_empty_str (void) |
Allocates an empty string (char* ). More... | |
ColorResult * | Colr_fmt_str (const char *fmt,...) |
Allocate and format a string like asprintf , but wrap it in an allocated ColorResult. More... | |
void | colr_free_argsv (va_list args) |
Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list . More... | |
void | colr_free_re_matches (regmatch_t **matches) |
Free an array of allocated regmatch_t , like the return from colr_re_matches(). More... | |
bool | colr_is_colr_ptr (void *p) |
Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer. More... | |
char * | colr_join_array (void *joinerp, void *ps) |
Join an array of strings (char* ), ColorArg s, or ColorText s by another string (char* ), ColorArg, or ColorText. More... | |
char * | colr_join_arrayn (void *joinerp, void *ps, size_t count) |
Join an array of strings (char* ), ColorArg s, or ColorText s by another string (char* ), ColorArg, or ColorText. More... | |
ColorResult * | Colr_ljust_char (void *x, int width, char padchar) |
Returns a left-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char* ), along with the desired width and pad character. More... | |
size_t | colr_mb_len (const char *s, size_t length) |
Like mbrlen , except it will return the length of the next N (length ) multibyte characters in bytes. More... | |
int | colr_printf_handler (FILE *fp, const struct printf_info *info, const void *const *args) |
Handles printing with printf for Colr objects. More... | |
int | colr_printf_info (const struct printf_info *info, size_t n, int *argtypes, int *sz) |
Handles the arg count/size for the Colr printf handler. More... | |
void | colr_printf_register (void) |
Registers COLR_FMT_CHAR to handle Colr objects in the printf-family functions. More... | |
regmatch_t ** | colr_re_matches (const char *s, regex_t *repattern) |
Returns all regmatch_t matches for regex pattern in a string (char* ). More... | |
ColorResult * | Colr_rjust_char (void *x, int width, char padchar) |
Returns a right-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char* ), along with the desired width and pad character. More... | |
bool | colr_set_locale (void) |
Sets the locale to (LC_ALL, "") if it hasn't already been set. More... | |
bool | colr_str_array_contains (char **lst, const char *s) |
Determine if a string (char* ) is in an array of strings (char** , where the last element is NULL ). More... | |
void | colr_str_array_free (char **ps) |
Free an allocated array of strings, including the array itself. More... | |
char * | colr_str_center (const char *s, int width, const char padchar) |
Center-justifies a string (char* ), ignoring escape codes when measuring the width. More... | |
size_t | colr_str_char_count (const char *s, const char c) |
Counts the number of characters (c ) that are found in a string (char* ) (s ). More... | |
size_t | colr_str_char_lcount (const char *s, const char c) |
Counts the number of characters (c ) that are found at the beginning of a string (char* ) (s ). More... | |
size_t | colr_str_chars_lcount (const char *restrict s, const char *restrict chars) |
Counts the number of characters that are found at the beginning of a string (char* ) (s ), where the character can be any of chars . More... | |
size_t | colr_str_code_count (const char *s) |
Return the number of escape-codes in a string (char* ). More... | |
size_t | colr_str_code_len (const char *s) |
Return the number of bytes that make up all the escape-codes in a string (char* ). More... | |
char * | colr_str_copy (char *restrict dest, const char *restrict src, size_t length) |
Copies a string (char* ) like strncpy, but ensures null-termination. More... | |
bool | colr_str_ends_with (const char *restrict s, const char *restrict suffix) |
Determine if one string (char* ) ends with another. More... | |
char ** | colr_str_get_codes (const char *s, bool unique) |
Get an array of escape-codes from a string (char* ). More... | |
bool | colr_str_has_codes (const char *s) |
Determines if a string (char* ) has ANSI escape codes in it. More... | |
bool | colr_str_has_ColorArg (const char *s, ColorArg *carg) |
Determines whether a string contains a specific color code. More... | |
ColrHash | colr_str_hash (const char *s) |
Hash a string using djb2. More... | |
bool | colr_str_is_all (const char *s, const char c) |
Determines whether a string (char* ) consists of only one character, possibly repeated. More... | |
bool | colr_str_is_codes (const char *s) |
Determines if a string (char* ) is composed entirely of escape codes. More... | |
bool | colr_str_is_digits (const char *s) |
Determines whether all characters in a string (char* ) are digits. More... | |
bool | colr_str_is_empty (const char *s) |
Checks to see if a string empty. More... | |
char * | colr_str_ljust (const char *s, int width, const char padchar) |
Left-justifies a string (char* ), ignoring escape codes when measuring the width. More... | |
void | colr_str_lower (char *s) |
Converts a string (char* ) into lower case in place. More... | |
size_t | colr_str_lstrip (char *restrict dest, const char *restrict s, size_t length, const char c) |
Strip a leading character from a string (char* ), filling another string (char* ) with the result. More... | |
char * | colr_str_lstrip_char (const char *s, const char c) |
Strips a leading character from a string (char* ), and allocates a new string with the result. More... | |
char * | colr_str_lstrip_chars (const char *restrict s, const char *restrict chars) |
Removes certain characters from the start of a string (char* ) and allocates a new string with the result. More... | |
size_t | colr_str_mb_len (const char *s) |
Returns the number of characters in a string (char* ), taking into account possibly multibyte characters. More... | |
size_t | colr_str_noncode_len (const char *s) |
Returns the length of string (char* ), ignoring escape codes and the the null-terminator. More... | |
char * | colr_str_replace (const char *restrict s, const char *restrict target, const char *restrict repl) |
Replaces the first substring found in a string (char* ). More... | |
char * | colr_str_replace_all (const char *restrict s, const char *restrict target, const char *restrict repl) |
Replaces the first substring found in a string (char* ). More... | |
char * | colr_str_replace_all_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl) |
Replace all substrings in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_all_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl) |
Replace all substrings in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_all_ColorText (const char *restrict s, const char *restrict target, ColorText *repl) |
Replace all substrings in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_cnt (const char *restrict s, const char *restrict target, const char *restrict repl, int count) |
Replaces one or more substrings in a string (char* ). More... | |
char * | colr_str_replace_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl) |
Replace a substring in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl) |
Replace a substring in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_ColorText (const char *restrict s, const char *restrict target, ColorText *repl) |
Replace a substring in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags) |
Replaces a substring from a regex pattern string (char* ) in a string (char* ). More... | |
char * | colr_str_replace_re_all (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags) |
Replaces all substrings from a regex pattern string (char* ) in a string (char* ). More... | |
char * | colr_str_replace_re_all_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags) |
Replace all substrings from a regex pattern string (char* ) in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_all_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags) |
Replace all substrings from a regex pattern string (char* ) in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_all_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags) |
Replace all substrings from a regex pattern string (char* ) in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags) |
Replace substrings from a regex pattern string (char* ) in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags) |
Replace substrings from a regex pattern string (char* ) in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags) |
Replace substrings from a regex pattern string (char* ) in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re_match (const char *restrict s, regmatch_t *match, const char *restrict repl) |
Replaces substrings from a single regex match (regmatch_t* ) in a string (char* ). More... | |
char * | colr_str_replace_re_match_ColorArg (const char *restrict s, regmatch_t *match, ColorArg *repl) |
Replace substrings from a regex match (regmatch_t* ) in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_match_ColorResult (const char *restrict s, regmatch_t *match, ColorResult *repl) |
Replace substrings from a regex match (regmatch_t* ) in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_match_ColorText (const char *restrict s, regmatch_t *match, ColorText *repl) |
Replace substrings from a regex match (regmatch_t* ) in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re_match_i (const char *restrict ref, char *target, regmatch_t *match, const char *restrict repl) |
Replaces substrings from a regex match (regmatch_t* ) in a string (char* ). More... | |
char * | colr_str_replace_re_matches (const char *restrict s, regmatch_t **matches, const char *restrict repl) |
Replaces substrings from an array of regex match (regmatch_t* ) in a string (char* ). More... | |
char * | colr_str_replace_re_matches_ColorArg (const char *restrict s, regmatch_t **matches, ColorArg *repl) |
Replace substrings from an array of regex matches (regmatch_t** ) in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_matches_ColorResult (const char *restrict s, regmatch_t **matches, ColorResult *repl) |
Replace substrings from an array of regex matches (regmatch_t** ) in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_matches_ColorText (const char *restrict s, regmatch_t **matches, ColorText *repl) |
Replace substrings from an array of regex matches (regmatch_t** ) in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re_pat (const char *restrict s, regex_t *repattern, const char *restrict repl) |
Replaces regex patterns in a string (char* ). More... | |
char * | colr_str_replace_re_pat_all (const char *restrict s, regex_t *repattern, const char *restrict repl) |
Replaces all matches to a regex pattern in a string (char* ). More... | |
char * | colr_str_replace_re_pat_all_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl) |
Replace all matches to a regex pattern in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_pat_all_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl) |
Replace all matches to a regex pattern in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_pat_all_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl) |
Replace all matches to a regex pattern in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_replace_re_pat_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl) |
Replace regex patterns in a string (char* ) with a ColorArg's string result. More... | |
char * | colr_str_replace_re_pat_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl) |
Replace regex patterns in a string (char* ) with a ColorResult's string result. More... | |
char * | colr_str_replace_re_pat_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl) |
Replace regex patterns in a string (char* ) with a ColorText's string result. More... | |
char * | colr_str_repr (const char *s) |
Convert a string (char* ) into a representation of a string, by wrapping it in quotes and escaping characters that need escaping. More... | |
char * | colr_str_rjust (const char *s, int width, const char padchar) |
Right-justifies a string (char* ), ignoring escape codes when measuring the width. More... | |
bool | colr_str_starts_with (const char *restrict s, const char *restrict prefix) |
Checks a string (char* ) for a certain prefix substring. More... | |
char * | colr_str_strip_codes (const char *s) |
Strips escape codes from a string (char* ), resulting in a new allocated string. More... | |
char * | colr_str_to_lower (const char *s) |
Allocate a new lowercase version of a string (char* ). More... | |
bool | colr_supports_rgb (void) |
Determine whether the current environment support RGB (True Colors). More... | |
bool | colr_supports_rgb_static (void) |
Same as colr_supports_rgb(), but the environment is only checked on the first call. More... | |
TermSize | colr_term_size (void) |
Attempts to retrieve the row/column size of the terminal and returns a TermSize. More... | |
struct winsize | colr_win_size (void) |
Attempts to retrieve a winsize struct from an ioctl call. More... | |
struct winsize | colr_win_size_env (void) |
Get window/terminal size using the environment variables LINES , COLUMNS , or COLS . More... | |
bool | ExtendedValue_eq (ExtendedValue a, ExtendedValue b) |
Compares two ExtendedValues. More... | |
int | ExtendedValue_from_BasicValue (BasicValue bval) |
Convert a BasicValue into an ExtendedValue. More... | |
int | ExtendedValue_from_esc (const char *s) |
Convert an escape-code string (char* ) to an ExtendedValue. More... | |
int | ExtendedValue_from_hex (const char *hexstr) |
Create an ExtendedValue from a hex string (char* ). More... | |
ExtendedValue | ExtendedValue_from_hex_default (const char *hexstr, ExtendedValue default_value) |
Create an ExtendedValue from a hex string (char* ), but return a default value if the hex string is invalid. More... | |
ExtendedValue | ExtendedValue_from_RGB (RGB rgb) |
Convert an RGB value into the closest matching ExtendedValue. More... | |
int | ExtendedValue_from_str (const char *arg) |
Converts a known name, integer string (0-255), or a hex string (char* ), into an ExtendedValue suitable for the extended-value-based functions. More... | |
bool | ExtendedValue_is_invalid (int eval) |
Determines whether an integer is an invalid ExtendedValue. More... | |
bool | ExtendedValue_is_valid (int eval) |
Determines whether an integer is a valid ExtendedValue. More... | |
char * | ExtendedValue_repr (int eval) |
Creates a string (char* ) representation of a ExtendedValue. More... | |
char * | ExtendedValue_to_str (ExtendedValue eval) |
Creates a human-friendly string (char* ) from an ExtendedValue's actual value, suitable for use with ExtendedValue_from_str(). More... | |
void | format_bg (char *out, BasicValue value) |
Create an escape code for a background color. More... | |
void | format_bg_RGB (char *out, RGB rgb) |
Create an escape code for a true color (rgb) background color using values from an RGB struct. More... | |
void | format_bg_RGB_term (char *out, RGB rgb) |
Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More... | |
void | format_bgx (char *out, unsigned char num) |
Create an escape code for an extended background color. More... | |
void | format_fg (char *out, BasicValue value) |
Create an escape code for a fore color. More... | |
void | format_fg_RGB (char *out, RGB rgb) |
Create an escape code for a true color (rgb) fore color using an RGB struct's values. More... | |
void | format_fg_RGB_term (char *out, RGB rgb) |
Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More... | |
void | format_fgx (char *out, unsigned char num) |
Create an escape code for an extended fore color. More... | |
void | format_style (char *out, StyleValue style) |
Create an escape code for a style. More... | |
char * | rainbow_bg (const char *s, double freq, size_t offset, size_t spread) |
Rainbow-ize some text using rgb back colors, lolcat style. More... | |
char * | rainbow_bg_term (const char *s, double freq, size_t offset, size_t spread) |
This is exactly like rainbow_bg(), except it uses colors that are closer to the standard 256-color values. More... | |
char * | rainbow_fg (const char *s, double freq, size_t offset, size_t spread) |
Rainbow-ize some text using rgb fore colors, lolcat style. More... | |
char * | rainbow_fg_term (const char *s, double freq, size_t offset, size_t spread) |
This is exactly like rainbow_fg(), except it uses colors that are closer to the standard 256-color values. More... | |
RGB | rainbow_step (double freq, size_t offset) |
A single step in rainbow-izing produces the next color in the "rainbow" as an RGB value. More... | |
unsigned char | RGB_average (RGB rgb) |
Return the average for an RGB value. More... | |
bool | RGB_eq (RGB a, RGB b) |
Compare two RGB structs. More... | |
RGB | RGB_from_BasicValue (BasicValue bval) |
Return an RGB value from a known BasicValue. More... | |
int | RGB_from_esc (const char *s, RGB *rgb) |
Convert an escape-code string (char* ) to an actual RGB value. More... | |
RGB | RGB_from_ExtendedValue (ExtendedValue eval) |
Return an RGB value from a known ExtendedValue. More... | |
int | RGB_from_hex (const char *hexstr, RGB *rgb) |
Convert a hex color into an RGB value. More... | |
RGB | RGB_from_hex_default (const char *hexstr, RGB default_value) |
Convert a hex color into an RGB value, but use a default value when errors occur. More... | |
int | RGB_from_str (const char *arg, RGB *rgb) |
Convert an RGB string (char* ) into an RGB value. More... | |
RGB | RGB_grayscale (RGB rgb) |
Return a grayscale version of an RGB value. More... | |
RGB | RGB_inverted (RGB rgb) |
Make a copy of an RGB value, with the colors "inverted" (like highlighting text in the terminal). More... | |
RGB | RGB_monochrome (RGB rgb) |
Convert an RGB value into either black or white, depending on it's average grayscale value. More... | |
char * | RGB_repr (RGB rgb) |
Creates a string (char* ) representation for an RGB value. More... | |
char * | RGB_to_hex (RGB rgb) |
Converts an RGB value into a hex string (char* ). More... | |
char * | RGB_to_str (RGB rgb) |
Convert an RGB value into a human-friendly RGB string (char* ) suitable for input to RGB_from_str(). More... | |
RGB | RGB_to_term_RGB (RGB rgb) |
Convert an RGB value into it's nearest terminal-friendly RGB value. More... | |
bool | StyleValue_eq (StyleValue a, StyleValue b) |
Compares two StyleValues. More... | |
StyleValue | StyleValue_from_esc (const char *s) |
Convert an escape-code string (char* ) to an actual StyleValue enum value. More... | |
StyleValue | StyleValue_from_str (const char *arg) |
Convert a named argument to actual StyleValue enum value. More... | |
bool | StyleValue_is_invalid (StyleValue sval) |
Determines whether a StyleValue is invalid. More... | |
bool | StyleValue_is_valid (StyleValue sval) |
Determines whether a StyleValue is valid. More... | |
char * | StyleValue_repr (StyleValue sval) |
Creates a string (char* ) representation of a StyleValue. More... | |
char * | StyleValue_to_str (StyleValue sval) |
Create a human-friendly string (char* ) representation for a StyleValue. More... | |
char * | TermSize_repr (TermSize ts) |
Create a string (char* ) representation for a TermSize. More... | |
Variables | |
int | colr_printf_esc_mod |
Integer to test for the presence of the "escaped output modifier" in colr_printf_handler. More... | |
Declarations for ColrC functions, enums, structs, etc.
Common macros and definitions are found here in colr.h, however the functions are documented in colr.c.
struct BasicInfo |
Holds a known color name and it's BasicValue
.
This is used for the basic_names
array in colr.c.
Data Fields | ||
---|---|---|
char * | name | |
BasicValue | value |
struct ColorArg |
Holds an ArgType, and a ColorValue.
Data Fields | ||
---|---|---|
uint32_t | marker | A marker used to inspect void pointers and determine if they are ColorArgs. |
ArgType | type | Fore, back, style, invalid. |
ColorValue | value | Color type and value. |
struct ColorJustify |
Holds a string justification method, width, and padding character for ColorTexts.
Data Fields | ||
---|---|---|
uint32_t | marker | A marker used to inspect void pointers and determine if they are ColorJustifys. |
ColorJustifyMethod | method | The justification method, can be JUST_NONE. |
char | padchar |
The desired padding character, or 0 to use the default (`' '`). |
int | width |
The desired width for the final string, or 0 to use colr_term_size(). |
struct ColorNameData |
Holds info about a known color name, like it's ExtendedValue and it's RGB value.
Some of the names have the same ExtendedValue, and not all ExtendedValues have names.
This is used in the colr_name_data array.
Data Fields | ||
---|---|---|
ExtendedValue | ext | ExtendedValue (256-colors) for the color. |
char * | name | The known name of the color. |
RGB | rgb | RGB (TrueColor) for the color. |
struct ColorResult |
Holds a string (char*
) that was definitely allocated by Colr.
Data Fields | ||
---|---|---|
size_t | length |
A length in bytes for the string result. Set when the ColorResult is initialized with a string (ColorResult_new()). Initially set to |
uint32_t | marker | A marker used to inspect void pointers and determine if they are ColorResults. |
char * | result |
A string (char* ) result from one of the colr functions. |
union ColorStructMarker |
Breaks down Colr struct markers, such as COLORARG_MARKER, into individual bytes.
Data Fields | ||
---|---|---|
struct ColorStructMarker | bytes | Individual bytes that make up the marker. |
uint32_t | marker | The actual uint32_t marker value. |
struct ColorStructMarker.bytes |
struct ColorText |
Holds a string of text, and optional fore, back, and style ColorArgs.
Data Fields | ||
---|---|---|
ColorArg * | back |
ColorArg for back color. Can be NULL . |
ColorArg * | fore |
ColorArg for fore color. Can be NULL . |
ColorJustify | just | ColorJustify info, set to JUST_NONE by default. |
uint32_t | marker | A marker used to inspect void pointers and determine if they are ColorTexts. |
ColorArg * | style |
ColorArg for style value. Can be NULL . |
char * | text | Text to colorize. |
struct ColorValue |
Holds a color type and it's value.
The .type
member must always match the type of color value it is holding.
This is internal. It's used to make the final interface easier to use. You probably shouldn't be using it.
Data Fields | ||
---|---|---|
BasicValue | basic | |
ExtendedValue | ext | |
RGB | rgb | |
StyleValue | style | |
ColorType | type |
struct ExtendedInfo |
Holds a known color name and it's ExtendedValue
.
This is used for the basic_names
array in colr.c.
Data Fields | ||
---|---|---|
char * | name | |
ExtendedValue | value |
struct RGB |
Container for RGB values.
Data Fields | ||
---|---|---|
unsigned char | blue | Blue value for a color. |
unsigned char | green | Green value for a color. |
unsigned char | red | Red value for a color. |
struct StyleInfo |
Holds a known style name and it's StyleValue
.
This is used for the style_names
array in colr.c.
Data Fields | ||
---|---|---|
char * | name | |
StyleValue | value |
struct TermSize |
Holds a terminal size, usually retrieved with colr_term_size().
Data Fields | ||
---|---|---|
unsigned short | columns | |
unsigned short | rows |
#define alloc_basic | ( | ) | calloc(CODE_LEN, sizeof(char)) |
Allocate enough for a basic code.
Pointer to the allocated string, or NULL on error.
You must free()
the memory allocated by this function.
#define alloc_extended | ( | ) | calloc(CODEX_LEN, sizeof(char)) |
Allocate enough for an extended code.
Pointer to the allocated string, or NULL on error.
You must free()
the memory allocated by this function.
#define alloc_rgb | ( | ) | calloc(CODE_RGB_LEN, sizeof(char)) |
Allocate enough for an rgb code.
Pointer to the allocated string, or NULL on error.
You must free()
the memory allocated by this function.
#define alloc_style | ( | ) | calloc(STYLE_LEN, sizeof(char)) |
Allocate enough for a style code.
Pointer to the allocated string, or NULL on error.
You must free()
the memory allocated by this function.
#define asprintf_or_return | ( | retval, | |
... | |||
) | if_not_asprintf(__VA_ARGS__) return retval |
Convenience macro for bailing out of a function when asprintf fails.
[in] | retval | Value to return if the asprintf fails. |
[in] | ... | Arguments for asprintf. |
Referenced by BasicValue_to_str(), ColorArg_repr(), ColorArgs_array_repr(), ColorJustify_repr(), ColorText_repr(), colr_char_repr(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_scroll_down(), Colr_scroll_up(), colr_str_center(), colr_str_ljust(), colr_str_replace_re_match(), colr_str_repr(), colr_str_rjust(), ExtendedValue_repr(), ExtendedValue_to_str(), RGB_repr(), RGB_to_hex(), RGB_to_str(), StyleValue_to_str(), and TermSize_repr().
#define back | ( | x | ) | ColorArg_to_ptr(back_arg(x)) |
Create a back color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
Technically, this macro accepts BasicValues, ExtendedValues, or RGB structs. However, for some of these you should be using the macros that create those things.
BasicValues can be used by their names (RED, YELLOW, etc.).
ExtendedValues can be created on the fly with ext().
RGB structs can be easily created with rgb().
Color names (char*
) can be passed to generate the appropriate color value.
[in] | x | A BasicValue, ExtendedValue, or RGB struct to use for the color value. |
free()
the result. Otherwise, you are responsible for calling free()
. #define back_arg | ( | x | ) |
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument.
Uses _Generic
(C11 standard) to dynamically create a ColorArg. This is used by the back() macro.
[in] | x | BasicValue , Extended (unsigned char ), RGB struct, or string (color name) for back color. |
.value.type
set for the appropriate color type/value..value.type
may be set to TYPE_INVALID.free()
the memory allocated by this function. #define back_str | ( | x | ) | ColorArg_to_esc(back_arg(x)) |
#define back_str_static | ( | x | ) |
Creates a stack-allocated escape code string (char*
) for a back color.
These are not constant strings, but they are stored on the stack. A Statement Expression is used to build a string of the correct length and content using ColorArg_to_esc_s().
alloca
to reserve space on the stack inside of a Statement Expression. A Variable Length Array will not work inside of a statement expression. If the call causes a stack overflow, program behavior is undefined. See previous links, and here.You can also create stack-allocated escape code strings using format_bg(), format_bgx(), format_bg_RGB(), and format_bg_RGB_term().
[in] | x | A BasicValue, ExtendedValue, or RGB value. |
#define basic | ( | x | ) | ((BasicValue)(x)) |
#define bool_colr_enum | ( | x | ) | (x < 0 ? false: true) |
Returns the "truthiness" of the enums used in ColrC (BasicValue, ExtendedValue function-returns, StyleValue, ColorType, ArgType).
Any value less than 0
is considered false.
[in] | x | An enum to convert to boolean. |
true | if the value is considered valid, or non-empty. |
false | if the value is considered invalid, or empty. |
Referenced by ColorArg_is_invalid(), ColorArg_is_valid(), ColorType_is_invalid(), ColorType_is_valid(), ColorValue_is_invalid(), and ColorValue_is_valid().
#define CODE_ANY_LEN 46 |
Maximum length in chars for any possible escape code mixture for one complete style (one of each: fore, back, and style).
(basically (CODE_RGB_LEN * 2) + STYLE_LEN
since rgb codes are the longest).
Referenced by colr_str_has_ColorArg().
#define CODE_LEN 14 |
Maximum length for a basic fore/back escape code, including `'\0'`.
Keep in mind that BasicValue actually has some "light" colors (104).
Referenced by format_bg(), and format_fg().
#define CODE_LEN_MIN 5 |
Minimum length for the shortest basic fore/back escape code, including `'\0'`.
Use CODE_LEN for allocation.
#define CODE_RGB_LEN_MIN 14 |
Minimum length for the shortest RGB fore/back escape code, including `'\0'`.
Use CODE_RGB_LEN for allocation.
#define CODEX_LEN_MIN 10 |
Minimum length for the shortest extended fore/back escape code, including `'\0'`.
Use CODEX_LEN for allocation.
#define color_arg | ( | type, | |
x | |||
) |
Builds a correct ColorArg struct according to the type of it's second argument.
Uses _Generic
(C11 standard) to dynamically create a ColorArg.
[in] | type | ArgType (FORE , BACK , STYLE ) to build the ColorArg. |
[in] | x | BasicValue , Extended (unsigned char ). or RGB value. |
#define COLOR_LEN 30 |
Maximum length in chars for any combination of basic/extended escape codes for one complete style (one of each: fore, back, style).
Should be (CODEX_LEN * 2) + STYLE_LEN
. Allocating for a string that will be colorized must account for this.
#define color_name_is_invalid | ( | x | ) | ColorType_is_invalid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is invalid.
[in] | x | string (char* ) to check (a name, hex-string, rgb-string, or integer-string). |
true
if the name is an invalid color name, otherwise false
.#define color_name_is_valid | ( | x | ) | ColorType_is_valid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is valid.
[in] | x | string (char* ) to check (a name, hex-string, rgb-string, or integer-string). |
true
if the name is a valid color name, otherwise false
.#define COLOR_RGB_LEN 26 |
Maximum length in chars added to a rgb colorized string.
Should be CODE_RGB_LEN + STYLE_LEN
Allocating for a string that will be colorized with rgb values must account for this.
#define color_val | ( | x | ) |
Builds a correct ColorValue struct according to the type of it's first argument.
Uses _Generic
(C11 standard) to dynamically create a ColorValue.
[in] | x | BasicValue , Extended (unsigned char ). or RGB value. |
#define COLORARG_MARKER UINT32_MAX |
Marker for the ColorArg struct, for identifying a void pointer as a ColorArg.
Referenced by ColorArg_empty(), ColorArg_from_BasicValue(), ColorArg_from_esc(), ColorArg_from_ExtendedValue(), ColorArg_from_RGB(), ColorArg_from_StyleValue(), ColorArg_from_value(), ColorArg_is_ptr(), and ColorArg_to_ptr().
#define ColorText_center | ( | text, | |
justwidth, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_center_char(), except is uses space as the default character.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorText_center_char | ( | text, | |
justwidth, | |||
c, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | c | The character to pad with. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorText_ljust | ( | text, | |
justwidth, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_ljust_char(), except is uses space as the default character.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorText_ljust_char | ( | text, | |
justwidth, | |||
c, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | c | The character to pad with. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorText_rjust | ( | text, | |
justwidth, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_rjust_char(), except is uses space as the default character.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorText_rjust_char | ( | text, | |
justwidth, | |||
c, | |||
... | |||
) |
Sets the JustifyMethod for a ColorText while allocating it.
[in] | text | Text to colorize. |
[in] | justwidth | Width for justification. |
[in] | c | The character to pad with. |
[in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColorValue_has | ( | cval, | |
val | |||
) |
Call the current ColorValue_has_<type> function for the given value.
Given the correct type of value, this will check to see if a ColorValue has the correct .type
set for the value, and the values match.
[in] | cval | The ColorValue to check. |
[in] | val | A BasicValue, ExtendedValue, StyleValue, or RGB value. |
true
if the ColorValue has the correct .type
and it's value matches val
, otherwise false
.#define Colr | ( | text, | |
... | |||
) | ColorText_to_ptr(ColorText_from_values(text, __VA_ARGS__, _ColrLastArg)) |
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
You must free()
the resulting ColorText struct using ColorText_free(), unless you pass it to colr_cat(), which will free()
it for you.
[in] | text | String to colorize/style. |
[in] | ... | One to three ColorArg pointers for fore, back, and style in any order. |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Create an allocated string directly from Colr() arguments.
This is a wrapper around colr_cat(Colr(text, ...))
, which will automatically free()
the ColorText, and return a string that you are responsible for.
[in] | text | String to colorize/style. |
[in] | ... | No more than 3 ColorArg pointers for fore, back, and style in any order. colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define colr_alloc_len | ( | x | ) |
Return the number of bytes needed to allocate an escape code string based on the color type.
[in] | x | A BasicValue, ExtendedValue, RGB value, or StyleValue. |
#define colr_asprintf | ( | ... | ) | colr_printf_macro(asprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call asprintf
.
Will call free()
on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.
[in] | ... | Arguments for `asprintf colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
asprintf
. #define Colr_cat | ( | ... | ) | ColorResult_to_ptr(ColorResult_new(colr_cat(__VA_ARGS__))) |
Like colr_cat(), but returns an allocated ColorResult that the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free()
.
[in] | ... | Arguments for colr_cat(), to concatenate. colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated ColorResult with all arguments joined together.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Referenced by Colr_erase_display().
#define colr_cat | ( | ... | ) | _colr_join("", __VA_ARGS__, _ColrLastArg) |
Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string.
To build the ColorArg pointers, it is better to use the fore(), back(), and style() macros. The ColorArgs are heap allocated, but colr_cat() will free() them for you.
To build the ColorText pointers, it is better to use the Colr() macro, along with the fore(), back(), and style() macros. The ColorTexts are heap allocated, but colr_cat() will free() them for you.
You can use ColrResult() to wrap any allocated string and colr_cat() will free it for you. Do not wrap static/stack-allocated strings. It will result in an "invalid free". The result of Colr_join() is an allocated ColorResult, like ColrResult() returns.
If you do not want the colr macros to free your Colr-based structs/strings for you, then you will have to call colr_to_str() on the structs and build or join the resulting strings yourself.
[in] | ... | One or more ColorArg pointers, ColorResult pointers, ColorText pointers, or strings to join. colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
free()
the memory allocated by this function. #define Colr_center | ( | x, | |
width | |||
) |
Like Colr_center_char, it center-justifies ColrC objects and strings (char*
), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
#define colr_center | ( | x, | |
width | |||
) | colr_center_char(x, width, ' ') |
Like Colr_center it center-justifies ColrC objects and strings (char*
) using `' '(space) as the pad character, except it returns an allocated string (
char*`).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_center_char | ( | x, | |
width, | |||
padchar | |||
) |
Like Colr_center_char it left-justifies ColrC objects and strings (char*
), except it returns an allocated string (char*
).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
[in] | padchar | Pad character to use. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_eq | ( | a, | |
b | |||
) |
Calls the <type>_eq functions for the supported types.
The types for a
and b
must be the same.
[in] | a | First supported type to compare. |
[in] | b | Second supported type to compare. |
true
if the values are equal, otherwise false
. #define colr_example | ( | x | ) |
Calls the <type>_example functions for the supported types.
This is used to create a human-friendly representation for ColorArgs or ColorValues.
[in] | x | A supported type to get an example string for. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define COLR_FMT "R" |
Format character string suitable for use in the printf-family of functions.
This can be defined to any single-char string before including colr.h if you don't want to use the default value.
#define Colr_fmt | ( | fmt, | |
value, | |||
... | |||
) |
Format and colorize a value like the printf
-family.
Unlike printf
, this only accepts a single value to format. The other arguments are for coloring/styling the value.
[in] | fmt | The format string. |
[in] | value | The value to format. |
[in] | ... | At least one of fore(), back(), or style() arguments in any order. |
An allocated ColorResult.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define colr_fprint | ( | file, | |
... | |||
) |
Create a string from a colr_cat() call, print it to file
(without a newline), and free it.
[in] | file | FILE stream for output. |
[in] | ... | Arguments for colr_cat(). |
#define colr_fprintf | ( | ... | ) | colr_printf_macro(fprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call fprintf
.
Will call free()
on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.
[in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
fprintf
. #define colr_free | ( | x | ) |
Calls the <type>_free functions for the supported types.
If the type is not supported, a plain free(x)
is used.
Colr objects that have a <type>_free function will be properly released, even through a void
pointer (as long as the .marker
member is set, which it will be if it was created by the Colr functions/macros).
[in] | x | A pointer to a supported type to free. |
Referenced by colr_free_argsv().
#define COLR_GNU |
Defined when __GNUC__
is available, to enable statement-expressions and register_printf_specifier .
There isn't a lot of information available for register_printf_specifier
right now. There are a couple of tutorials out there. No man pages though. It looks like it was introduced in glibc-2.27
.
#define colr_is_empty | ( | x | ) |
Calls the <type>is_empty functions for the supported types.
[in] | x | A supported type to build a string from. |
#define colr_is_invalid | ( | x | ) |
Calls the <type>is_invalid functions for the supported types.
[in] | x | A supported type to build a string from. |
#define colr_is_valid | ( | x | ) |
Calls the <type>is_valid functions for the supported types.
[in] | x | A supported type to build a string from. |
#define colr_is_valid_mblen | ( | x | ) | ((x) && ((x) != (size_t)-1) && ((x) != (size_t)-2)) |
Checks return values from mbrlen()
and colr_mb_len().
[in] | x | A size_t return value to check, from mbrlen() or colr_mb_len(). |
true
if at least one valid multibyte character length was detected, otherwise false
. Invalid/incomplete multibyte sequences, or empty/ NULL
strings will cause this macro to return false
. Referenced by _rainbow(), and colr_mb_len().
#define colr_istr_either | ( | s1, | |
s2, | |||
s3 | |||
) |
Convenience macro for !strcasecmp(s1, s2) || !strcasecmp(s1, s3)
.
[in] | s1 | The string to compare against the other two strings. |
[in] | s2 | The first string to compare with. |
[in] | s3 | The second string to compare with. |
1
if s1
is equal to s2
or s3
, otherwise 0
. Referenced by colr_supports_rgb().
#define colr_istr_eq | ( | s1, | |
s2 | |||
) |
Convenience macro for !strcasecmp(s1, s2)
.
[in] | s1 | The first string to compare. |
[in] | s2 | The second string to compare. |
1
if s1
and s2
are equal, otherwise 0
. #define Colr_join | ( | joiner, | |
... | |||
) | ColrResult(colr_join(joiner, __VA_ARGS__)) |
Joins Colr objects and strings, exactly like colr_join(), but returns an allocated ColorResult that the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free()
for you.
[in] | joiner | What to put between the other arguments. ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char* ). |
[in] | ... | Other arguments to join, with colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated ColorResult.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define colr_join | ( | joiner, | |
... | |||
) | _colr_join(joiner, __VA_ARGS__, _ColrLastArg) |
Join ColorArg pointers, ColorText pointers, and strings by another ColorArg pointer, ColorText pointer, or string.
To build the ColorArg pointers, it is better to use the fore(), back(), and style() macros. The ColorArgs are heap allocated, but colr_join() will free() them for you.
To build the ColorText pointers, it is better to use the Colr() macro, along with the fore(), back(), and style() macros. The ColorTexts are heap allocated, but colr_join() will free() them for you.
[in] | joiner | What to put between the other arguments. ColorArg pointer, ColorText pointer, or string. |
[in] | ... | Other arguments to join, with joiner between them. ColorArg pointers, ColorText pointers, or strings, in any order. |
An allocated string.
You must free()
the memory allocated by this function.
#define colr_length | ( | x | ) |
Calls the <type>_length functions for the supported types.
If a void
pointer is given, _colr_ptr_length() is called on it to determine the length.
[in] | x | A supported type to build a string from. |
#define Colr_ljust | ( | x, | |
width | |||
) |
Like Colr_ljust_char, it left-justifies ColrC objects and strings (char*
), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
#define colr_ljust | ( | x, | |
width | |||
) | colr_ljust_char(x, width, ' ') |
Like Colr_ljust it left-justifies ColrC objects and strings (char*
) using `' '(space) as the pad character, except it returns an allocated string (
char*`).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_ljust_char | ( | x, | |
width, | |||
padchar | |||
) |
Like Colr_ljust_char it left-justifies ColrC objects and strings (char*
), except it returns an allocated string (char*
).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
[in] | padchar | Pad character to use. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_max | ( | a, | |
b | |||
) | (a > b ? a : b) |
Macro for (a > b ? a : b)
.
[in] | a | First value to compare. |
[in] | b | Second value to compare. |
a
if a > b
, otherwise b
. Referenced by ColorText_length().
#define colr_print | ( | ... | ) |
Create a string from a colr_cat() call, print it to stdout (without a newline), and free it.
[in] | ... | Arguments for colr_cat(). |
#define colr_printf | ( | ... | ) | colr_printf_macro(printf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call printf
.
Will call free()
on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.
[in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
printf
. #define colr_printf_macro | ( | func, | |
... | |||
) |
Calls one of the printf-family functions, with format warnings disabled for the call, and returns the result.
This function also ensures that colr_printf_register() is called, which ensures that register_printf_specifier() is called one time.
[in] | func | The standard printf function to call, with a return type of int . |
[in] | ... | Arguments for the printf function. |
func(...)
. #define colr_puts | ( | ... | ) |
Create a string from a colr_cat() call, print it (with a newline), and free it.
[in] | ... | Arguments for colr_cat(). |
#define colr_replace | ( | s, | |
target, | |||
repl | |||
) |
Replace a substring in s
with another string, ColorArg string, ColorResult string, or ColorText string.
If a string (char*
) is used as target
and repl
, this is just a wrapper around colr_str_replace().
If target
is a string (char*
), this is a plain string-replace.
If target
is a regex pattern (regex_t
), it's regex match (regmatch_t
) will be used to find a target string to replace in s
.
If target
is a regex match (regmatch_t
), it's offsets will be used to find a target string in s
.
If target
is a NULL
-terminated array of regex matches (regmatch_t**
), each match will be replaced in the target string, s
.
There is no difference between colr_replace() and colr_replace_all() when a NULL
-terminated array of regex matches (regmatch_t**
) is used.
If a ColorArg, ColorResult, or ColorText is used as repl
, the appropriate colr_str_replace_<types> function is called. The function will create a string of escape-codes/text to be used as a replacement.
If repl
is NULL
, then an empty string (""
) is used as the replacement, which causes the target
string to be removed.
If you would like to replace all occurrences of the substring, use colr_replace_all().
[in] | s | The string to operate on. Must be |
[in] | target | A target string, regex pattern (regex_t ), or regex match (regmatch_t ) to replace in s . If a string is given, it must be null-terminated. |
[in] | repl | A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define colr_replace_all | ( | s, | |
target, | |||
repl | |||
) |
Replace all substrings in s
with another string, ColorArg string, ColorResult string, or ColorText string.
If a string (char*
) is used as target
and repl
, this is just a wrapper around colr_str_replace().
If target
is a string (char*
), this is a plain string-replace.
If target
is a regex pattern (regex_t
), it's regex match (regmatch_t
) will be used to find a target string to replace in s
.
If target
is a NULL
-terminated array of regex matches (regmatch_t**
), each match will be replaced in the target string, s
.
There is no difference between colr_replace() and colr_replace_all() when a NULL
-terminated array of regex matches (regmatch_t**
) is used.
If a ColorArg, ColorResult, or ColorText is used as repl
, the appropriate colr_str_replace_<types> function is called. The function will create a string of escape-codes/text to be used as a replacement.
If repl
is NULL
, then an empty string (""
) is used as the replacement, which causes the target
string to be removed.
If you would like to replace only the first occurrence of the substring, use colr_replace().
[in] | s | The string to operate on. Must be |
[in] | target | A target string, or regex pattern (regex_t ) to replace in s . If a string is given, it must be null-terminated. |
[in] | repl | A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define colr_replace_re | ( | s, | |
target, | |||
repl, | |||
flags | |||
) |
Replace a regex pattern string (char*
) in s
with another string, ColorArg string, ColorResult string, or ColorText string.
If a string (char*
) is used as repl
, this is just a wrapper around colr_str_replace_re().
If a ColorArg, ColorResult, or ColorText is used as repl
, the appropriate colr_str_replace_re_<type> function is called. The function will create a string of escape-codes/text to be used as a replacement.
If repl
is NULL
, then an empty string (""
) is used as the replacement, which causes the target
string to be removed.
If you would like to replace all occurrences of the substring, use colr_replace_re_all().
[in] | s | The string to operate on. Must be |
[in] | target | A regex pattern string (char* ), regex pattern (regex_t ), or regex match (regmatch_t ) to replace in s . If a string is given, it must be null-terminated. |
[in] | repl | A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
[in] | flags | Flags for regcomp() . REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define colr_replace_re_all | ( | s, | |
target, | |||
repl, | |||
flags | |||
) |
Replace all matches to a regex pattern string (char*
) in s
with another string, ColorArg string, ColorResult string, or ColorText string.
If a string (char*
) is used as repl
, this is just a wrapper around colr_str_replace_re_all().
If a ColorArg, ColorResult, or ColorText is used as repl
, the appropriate colr_str_replace_re_<type> function is called. The function will create a string of escape-codes/text to be used as a replacement.
If repl
is NULL
, then an empty string (""
) is used as the replacement, which causes the target
string to be removed.
If you would like to replace only the first occurrence of the substring, use colr_replace_re().
[in] | s | The string to operate on. Must be |
[in] | target | A regex pattern string (char* ), regex pattern (regex_t ), or regex match (regmatch_t ) to replace in s . If a string is given, it must be null-terminated. |
[in] | repl | A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
[in] | flags | Flags for regcomp() . REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define colr_repr | ( | x | ) |
Transforms several ColrC objects into their string representations.
Uses _Generic (C11 standard) to dynamically dispatch to the proper *_repr
functions.
If a regular string is passed in, it will be escaped and you must still free()
the result.
Supported Types:
[in] | x | A value with one of the supported types to transform into a string. |
Stringified representation of what was passed in.
You must free()
the memory allocated by this function.
Referenced by ColorArgs_array_repr(), colr_printf_handler(), and colr_str_mb_len().
#define Colr_rjust | ( | x, | |
width | |||
) |
Like Colr_rjust_char, it right-justifies ColrC objects and strings (char*
), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
#define colr_rjust | ( | x, | |
width | |||
) | colr_rjust_char(x, width, ' ') |
Like Colr_rjust it right-justifies ColrC objects and strings (char*
) using `' '(space) as the pad character, except it returns an allocated string (
char*`).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_rjust_char | ( | x, | |
width, | |||
padchar | |||
) |
Like Colr_rjust_char it right-justifies ColrC objects and strings (char*
), except it returns an allocated string (char*
).
This macro uses a _Generic() match to help with type safety.
[in] | x | ColorText pointer, ColorResult pointer, or string (char* ) to justify. |
[in] | width | Maximum width for justification. |
[in] | padchar | Pad character to use. |
An allocated string (char*
) with the justification result.
You must free()
the memory allocated by this function. maybenullalloc
#define colr_snprintf | ( | ... | ) | colr_printf_macro(snprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call snprintf
.
Will call free()
on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.
[in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
snprintf
. #define colr_sprintf | ( | ... | ) | colr_printf_macro(sprintf, __VA_ARGS__) |
Ensure colr_printf_register() has been called, and then call sprintf
.
Will call free()
on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.
[in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
sprintf
. #define colr_str_either | ( | s1, | |
s2, | |||
s3 | |||
) | (colr_str_eq(s1, s2) || colr_str_eq(s1, s3)) |
Convenience macro for !strcmp(s1, s2) || !strcmp(s1, s3)
.
[in] | s1 | The string to compare against the other two strings. |
[in] | s2 | The first string to compare with. |
[in] | s3 | The second string to compare with. |
1
if s1
is equal to s2
or s3
, otherwise 0
. #define colr_str_eq | ( | s1, | |
s2 | |||
) |
Convenience macro for !strcmp(s1, s2)
.
[in] | s1 | The first string to compare. |
[in] | s2 | The second string to compare. |
1
if s1
and s2
are equal, otherwise 0
. Referenced by ColorResult_eq(), and RGB_from_str().
#define colr_to_str | ( | x | ) |
Calls the <type>_to_str functions for the supported types.
If a string is given, it is duplicated like strdup()
.
[in] | x | A supported type to build a string from. |
An allocated string from the type's *_to_str()
function.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
#define Colra | ( | text, | |
... | |||
) | ColorText_from_values(text, __VA_ARGS__, _ColrLastArg) |
Returns an initialized stack-allocated ColorText.
If this ColorText is manually stored on the heap, and then sent through the colr macros, it's ColorArgs will be free'd. You cannot use the same ColorText twice inside the colr macros/functions.
free()
on it.[in] | text | String to colorize/style. |
[in] | ... | No more than 3 ColorArg pointers for fore, back, and style in any order. |
#define ColrColorResult | ( | cres, | |
... | |||
) | ColorResult_Colr(cres, __VA_ARGS__, _ColrLastArg) |
Like Colr(), but it operates on a ColorResult to generate a new colorized ColorResult.
[in] | cres | An allocated ColorResult to colorize. This will be free() 'd to create the new ColorResult. |
[in] | ... | One to three fore(), back(), or style() arguments (ColorArg s). The ColorArg s will be free() 'd to generate the new ColorResult. |
An allocated ColorResult.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ColrResult | ( | s | ) | ColorResult_to_ptr(ColorResult_new(s)) |
Wraps an allocated string in a ColorResult, which marks it as "freeable" in the colr macros.
[in] | s | An allocated string. |
An allocated ColorResult.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define ext | ( | x | ) | ((ExtendedValue)x) |
Casts to ExtendedValue (unsigned char
).
[in] | x | Value to cast to unsigned char /ExtendedValue . |
Referenced by ExtendedValue_from_BasicValue(), and ExtendedValue_from_RGB().
#define ext_hex | ( | s | ) | ext_hex_or(s, ext(0)) |
Like hex(), but force a conversion to the closest ExtendedValue (256-colors).
[in] | s | A hex string to convert. |
#define ext_hex_or | ( | s, | |
default_value | |||
) | ExtendedValue_from_hex_default(s, default_value) |
Like hex_or(), but force a conversion to the closest ExtendedValue (256-colors).
This is a convenience macro for ExtendedValue_from_hex_default().
[in] | s | A hex string to convert. |
[in] | default_value | ExtendedValue to use if the hex string is not valid. |
default_value
for bad hex strings.#define EXT_INVALID COLOR_INVALID |
Alias for COLOR_INVALID.
All color values share an _INVALID member with the same value, so:
Referenced by ExtendedValue_from_BasicValue(), ExtendedValue_from_esc(), and ExtendedValue_from_str().
#define EXT_INVALID_RANGE COLOR_INVALID_RANGE |
Possible error return value for ExtendedValue_from_str() or ExtendedValue_from_esc().
This is just an alias for COLOR_INVALID_RANGE.
Referenced by ExtendedValue_from_esc(), and ExtendedValue_from_str().
#define ext_rgb | ( | r, | |
g, | |||
b | |||
) | ExtendedValue_from_RGB((RGB){.red=r, .green=g, .blue=b}) |
Creates the closest matching ExtendedValue from separate red, green, and blue values.
This is short-hand for ExtendedValue_from_RGB((RGB){r, g, b})
.
[in] | r | The red value. |
[in] | g | The green value. |
[in] | b | The blue value. |
#define ext_RGB | ( | rgbval | ) | ExtendedValue_from_RGB(rgbval) |
#define fore | ( | x | ) | ColorArg_to_ptr(fore_arg(x)) |
Create a fore color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
Technically, this macro accepts BasicValues, ExtendedValues, or RGB structs. However, for some of these you should be using the macros that create those things.
BasicValues can be used by their names (RED, YELLOW, etc.).
ExtendedValues can be created on the fly with ext().
RGB structs can be easily created with rgb().
Color names (char*
) can be passed to generate the appropriate color value.
[in] | x | A BasicValue, ExtendedValue, or RGB struct to use for the color value. |
A pointer to a heap-allocated ColorArg struct.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define fore_arg | ( | x | ) |
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument.
Uses _Generic
(C11 standard) to dynamically create a ColorArg. This is used by the fore() macro.
[in] | x | BasicValue , Extended (unsigned char ), RGB struct, or string (color name) for fore color. |
.value.type
set for the appropriate color type/value. For invalid values the .value.type
may be set to TYPE_INVALID.#define fore_str | ( | x | ) | ColorArg_to_esc(fore_arg(x)) |
#define fore_str_static | ( | x | ) |
Creates a stack-allocated escape code string (char*
) for a fore color.
These are not constant strings, but they are stored on the stack. A Statement Expression is used to build a string of the correct length and content using ColorArg_to_esc_s().
alloca
to reserve space on the stack inside of a Statement Expression. A Variable Length Array will not work inside of a statement expression. If the call causes a stack overflow, program behavior is undefined. See previous links, and here.You can also create stack-allocated escape code strings using format_fg(), format_fgx(), format_fg_RGB(), and format_fg_RGB_term().
[in] | x | A BasicValue, ExtendedValue, or RGB value. |
Use RGB_from_hex_default() to create an RGB value.
[in] | s | A hex string to convert. |
rgb(0, 0, 0)
for bad hex strings.#define hex_or | ( | s, | |
default_rgb | |||
) | RGB_from_hex_default(s, default_rgb) |
Use RGB_from_hex_default() to create an RGB value.
[in] | s | A hex string to convert. |
[in] | default_rgb | Default RGB value to use if the hex string is not valid. |
default_rgb
for bad hex strings.#define if_not_asprintf | ( | ... | ) | if (asprintf(__VA_ARGS__) < 1) |
Convenience macro for checking asprintf's return value.
Should be followed by a block of code.
Note: asprintf returns -1
for errors, but 0
is a valid return (0
bytes written to the string). The string will be untouched (may be NULL
if it was initialized as NULL
)
[in] | ... | Arguments for asprintf. |
#define rgb | ( | r, | |
g, | |||
b | |||
) | ((RGB){.red=r, .green=g, .blue=b}) |
Creates an anonymous RGB struct for use in function calls.
[in] | r | unsigned char Red value. |
[in] | g | unsigned char Blue value. |
[in] | b | unsigned char Green value. |
Referenced by ExtendedValue_from_hex(), rainbow_step(), RGB_from_hex_default(), RGB_grayscale(), RGB_inverted(), and RGB_monochrome().
#define style | ( | x | ) | ColorArg_to_ptr(style_arg(x)) |
Create a style suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
This macro accepts strings (style names) and StyleValues.
Style names (char*
) can be passed to generate the appropriate style value.
[in] | x | A StyleValue. |
A pointer to a heap-allocated ColorArg struct.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
#define style_arg | ( | x | ) |
Uses ColorArg_from_StyleValue to build a ColorArg with the appropriate color type/value.
[in] | x | StyleValue for the style. |
.value.type
set for the appropriate color type/value. For invalid values the .value.type
may be set to TYPE_INVALID.#define STYLE_LEN_MIN 5 |
Minimum length for the shortest style escape code, including `'\0'`.
Use STYLE_LEN for allocation.
#define style_str | ( | x | ) | ColorArg_to_esc(style_arg(x)) |
#define style_str_static | ( | x | ) |
A less-flexible style_str() that returns a static escape code string for a style.
This macro function does not accept style names. Only StyleValue
and literal int
values are accepted.
The resulting expression will be optimized into a constant static string (https://gcc.godbolt.org/z/TkoWtc).
[in] | x | A StyleValue to use. |
#define while_colr_va_arg | ( | ap, | |
vartype, | |||
x | |||
) | while (x = va_arg(ap, vartype), !_colr_is_last_arg(x)) |
Construct a while-loop over a va_list
, where the last argument is expected to be _ColrLastArg, or a pointer to a _ColrLastArg_s with the same values as _ColrLastArg.
[in] | ap | The va_list to use. |
[in] | vartype | Expected type of the argument. |
[in] | x | The variable to assign to (usually arg ). |
Referenced by _colr_join(), _colr_join_size(), ColorText_from_valuesv(), ColorText_set_values(), and colr_free_argsv().
A function type that knows how to fill a string with an rgb escape code.
enum BasicValue |
Basic color values, with a few convenience values for extended colors.
void _colr_free | ( | void * | p | ) |
Calls Colr *_free()
functions for Colr objects, otherwise just calls free()
.
You should use the colr_free() macro instead.
[in] | p | Pointer to a heap-allocated object. |
bool _colr_is_last_arg | ( | void * | p | ) |
Determines if a void pointer is _ColrLastArg (the last-arg-marker).
[in] | p | The pointer to check. |
true
if the pointer is _ColrLastArg, otherwise false
. char* _colr_join | ( | void * | joinerp, |
... | |||
) |
Joins ColorArgs, ColorTexts, and strings (char*
) into one long string separated by it's first argument.
This will free() any ColorArg
s, ColorResult
s, or ColorText
s that are passed in. It is backing the colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros, and enables easy throw-away color values.
Any plain strings that are passed in are left alone. It is up to the caller to free those. ColrC only manages the temporary Colr-based objects needed to build up these strings.
You should use colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros instead.
[in] | joinerp | The joiner (any ColorArg, ColorResult, ColorText, or string). |
[in] | ... | Zero or more ColorArgs, ColorResults, ColorTexts, or strings to join by the joiner. |
An allocated string with mixed escape codes/strings. CODE_RESET_ALL is appended to all ColorText arguments. This allows easy part-colored messages.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned. Also, NULL
will be returned if joinerp
is NULL
.
size_t _colr_join_array_length | ( | void * | ps | ) |
Determine the length of a NULL
-terminated array of strings (char*
), ColorArg
s, ColorResult
s, or ColorText
s.
[in] | ps | A NULL -terminated array of ColorArg s, ColorResult s, ColorText s, or strings (char* ). |
NULL
) in the array. Referenced by colr_join_array().
size_t _colr_join_arrayn_size | ( | void * | joinerp, |
void * | ps, | ||
size_t | count | ||
) |
Get the size in bytes needed to join an array of strings (char*
), ColorArg
s, ColorResult
s, or ColorText
s by another string (char*
), ColorArg, ColorResult, or ColorText.
This is used to allocate memory in the colr_join_array() function.
[in] | joinerp | The joiner (any ColorArg, ColorResult, ColorText, or string). |
[in] | ps | An array of pointers to ColorArg s, ColorResult s, ColorText s, or strings. The array must have NULL as the last item if count is greater than the total number of items. |
[in] | count | Total number of items in the array. |
0
.Referenced by colr_join_arrayn().
size_t _colr_join_size | ( | void * | joinerp, |
va_list | args | ||
) |
Parse arguments, just as in _colr_join(), but only return the size needed to allocate the resulting string.
This allows _colr_join() to allocate once, instead of reallocating for each argument that is passed.
[in] | joinerp | The joiner (any ColorArg, ColorText, or string (char* )). |
[in] | args | A va_list with zero or more ColorArg s, ColorText s, or strings (char* ) to join. |
0
if joinerp
is NULL
/empty). Except for 0
, it will never return anything less than CODE_RESET_LEN
. Referenced by _colr_join().
size_t _colr_ptr_length | ( | void * | p | ) |
Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char*
) into a string.
This is used in the variadic _colr* functions.
[in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char* ). |
strlen() + 1
for strings). Referenced by _colr_join_arrayn_size(), and _colr_join_size().
char* _colr_ptr_repr | ( | void * | p | ) |
Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obtain an allocated string representation.
You should use colr_repr() instead.
[in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
char* _colr_ptr_to_str | ( | void * | p | ) |
Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to obtain an allocated string.
[in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
char* _rainbow | ( | RGB_fmter | fmter, |
const char * | s, | ||
double | freq, | ||
size_t | offset, | ||
size_t | spread | ||
) |
Handles multibyte character string (char*
) conversion and character iteration for all of the rainbow_ functions.
[in] | fmter | A formatter function (RGB_fmter) that can create escape codes from RGB values. |
[in] | s | The string to "rainbowize". Input must be |
[in] | freq | The "tightness" for colors. |
[in] | offset | The starting offset into the rainbow. |
[in] | spread | Number of characters per color. |
An allocated string (char*
) with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by rainbow_bg(), rainbow_bg_term(), rainbow_fg(), and rainbow_fg_term().
Compares two ArgTypes.
This is used to implement colr_eq().
[in] | a | The first ArgType to compare. |
[in] | b | The second ArgType to compare. |
true
if they are equal, otherwise false
. char* ArgType_repr | ( | ArgType | type | ) |
Creates a string (char*
) representation of a ArgType.
[in] | type | An ArgType to get the type from. |
A pointer to an allocated string.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by ColorArg_repr().
char* ArgType_to_str | ( | ArgType | type | ) |
Creates a human-friendly string (char*
) from an ArgType.
[in] | type | An ArgType to get the type from. |
A pointer to an allocated string.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by ColorArg_example().
bool BasicValue_eq | ( | BasicValue | a, |
BasicValue | b | ||
) |
Compares two BasicValues.
This is used to implement colr_eq().
[in] | a | The first BasicValue to compare. |
[in] | b | The second BasicValue to compare. |
true
if they are equal, otherwise false
.BasicValue BasicValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*
) to an actual BasicValue enum value.
[in] | s | Escape-code string. Must be |
BasicValue | value on success. |
BASIC_INVALID | on error (or if s is NULL ). |
BASIC_INVALID_RANGE | if the code number was outside of the range 0-255 . |
BasicValue BasicValue_from_str | ( | const char * | arg | ) |
Convert named argument to an actual BasicValue enum value.
[in] | arg | Color name to find the BasicValue for. |
bool BasicValue_is_invalid | ( | BasicValue | bval | ) |
Determines whether a BasicValue is invalid.
[in] | bval | A BasicValue to check. |
true
if the value is considered invalid, otherwise false
.Referenced by ExtendedValue_from_BasicValue().
bool BasicValue_is_valid | ( | BasicValue | bval | ) |
Determines whether a BasicValue is valid.
[in] | bval | A BasicValue to check. |
true
if the value is considered valid, otherwise false
.char* BasicValue_repr | ( | BasicValue | bval | ) |
Creates a string (char*
) representation of a BasicValue.
[in] | bval | A BasicValue to get the value from. |
A pointer to an allocated string.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
int BasicValue_to_ansi | ( | ArgType | type, |
BasicValue | bval | ||
) |
Converts a fore/back BasicValue to the actual ansi code number.
[in] | type | ArgType (FORE/BACK). |
[in] | bval | BasicValue to convert. |
Referenced by format_bg(), and format_fg().
char* BasicValue_to_str | ( | BasicValue | bval | ) |
Create a human-friendly string (char*
) representation for a BasicValue.
[in] | bval | BasicValue to get the name for. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
ColorArg ColorArg_empty | ( | void | ) |
Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE.
This is used to pass "empty" fore/back/style args to the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, where NULL
may have a different meaning for users of the ColorArg.
(ColorArg){.type=ARGTYPE_NONE, .value.type=TYPE_NONE}
Compares two ColorArg structs.
They are considered "equal" if their .type
and .value
match.
true
if they are equal, otherwise false
.Referenced by ColorText_has_arg().
char* ColorArg_example | ( | ColorArg | carg, |
bool | colorized | ||
) |
Create a string (char*
) representation of a ColorArg with a stylized type/name using escape codes built from the ColorArg's values.
[in] | carg | A ColorArg to get an example string for. |
[in] | colorized | Whether to include a colorized example. If set to false , there will be no escape-codes in the string. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
void ColorArg_free | ( | ColorArg * | p | ) |
Free allocated memory for a ColorArg.
This has no advantage over free(colorarg)
right now, it is used in debugging, and may be extended in the future. It's better just to use it (or the colr_free() macro).
[in] | p | ColorArg to free. |
Referenced by _colr_free(), _colr_join(), ColorText_free_args(), colr_printf_handler(), colr_str_replace_all_ColorArg(), colr_str_replace_ColorArg(), colr_str_replace_re_all_ColorArg(), colr_str_replace_re_ColorArg(), colr_str_replace_re_match_ColorArg(), colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_pat_all_ColorArg(), and colr_str_replace_re_pat_ColorArg().
ColorArg ColorArg_from_BasicValue | ( | ArgType | type, |
BasicValue | value | ||
) |
Explicit version of ColorArg_from_value that only handles BasicValues.
This is used in some macros to aid in dynamic escape code creation.
[in] | type | ArgType (FORE, BACK, STYLE). |
[in] | value | BasicValue to use. |
.value.type
member possibly set to TYPE_INVALID
.ColorArg ColorArg_from_esc | ( | const char * | s | ) |
Parse an escape-code string (char*
) into a ColorArg.
For malformed escape-codes the .type
member will be ARGTYPE_NONE
, and the .value.type
member will be set to TYPE_INVALID
. This means that ColorArg_is_invalid(carg) == true
.
[in] | s | The escape code to parse. It must not have extra characters. |
Referenced by ColorArgs_from_str().
ColorArg ColorArg_from_ExtendedValue | ( | ArgType | type, |
ExtendedValue | value | ||
) |
Explicit version of ColorArg_from_value that only handles ExtendedValues.
This is used in some macros to aid in dynamic escape code creation.
[in] | type | ArgType (FORE, BACK, STYLE). |
[in] | value | ExtendedValue to use. |
.value.type
member possibly set to TYPE_INVALID
.Explicit version of ColorArg_from_value that only handles RGB structs.
This is used in some macros to aid in dynamic escape code creation.
[in] | type | ArgType (FORE, BACK, STYLE). |
[in] | value | RGB struct to use. |
.value.type
member possibly set to TYPE_INVALID
.Build a ColorArg (fore, back, or style value) from a known color name/style.
The .value.type
attribute can be checked for an invalid type, or you can call ColorArg_is_invalid(x).
[in] | type | ArgType (FORE, BACK, STYLE). |
[in] | colorname | A known color name/style. |
ColorArg ColorArg_from_StyleValue | ( | ArgType | type, |
StyleValue | value | ||
) |
Explicit version of ColorArg_from_value that only handles StyleValues.
This is used in some macros to aid in dynamic escape code creation.
[in] | type | ArgType (FORE, BACK, STYLE). |
[in] | value | StyleValue to use. |
.value.type
member possibly set to TYPE_INVALID
.Used with the color_arg macro to dynamically create a ColorArg based on it's argument type.
[in] | type | ArgType value, to mark the type of ColorArg. |
[in] | colrtype | ColorType value, to mark the type of ColorValue. |
[in] | p | A pointer to either a BasicValue, ExtendedValue, or a RGB. |
.value.type
member set for the value that was passed. For invalid types the .value.type
member may be set to one of:bool ColorArg_is_empty | ( | ColorArg | carg | ) |
Checks to see if a ColorArg is an empty placeholder.
A ColorArg is empty if it's .type
is set to ARGTYPE_NONE
.
[in] | carg | A ColorArg to check. |
true
if the ColorArg is considered "empty", otherwise false
. Referenced by ColorArg_length(), ColorArg_to_esc(), ColorArg_to_esc_s(), ColorText_has_args(), and ColorText_to_str().
bool ColorArg_is_invalid | ( | ColorArg | carg | ) |
bool ColorArg_is_ptr | ( | void * | p | ) |
Checks a void pointer to see if it contains a ColorArg struct.
The first member of a ColorArg is a marker.
[in] | p | A void pointer to check. |
true
if the pointer is a ColorArg, otherwise false
.Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), ColorText_from_valuesv(), ColorText_set_values(), colr_is_colr_ptr(), colr_join_arrayn(), and colr_printf_handler().
bool ColorArg_is_valid | ( | ColorArg | carg | ) |
size_t ColorArg_length | ( | ColorArg | carg | ) |
Returns the length in bytes needed to allocate a string (char*
) built with ColorArg_to_esc().
[in] | carg | ColorArg to use. |
size_t
) needed to allocate a ColorArg's string, or 1
(size of an empty string) for invalid/empty arg types/values.Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_length().
char* ColorArg_repr | ( | ColorArg | carg | ) |
Creates a string (char*
) representation for a ColorArg.
Allocates memory for the string representation.
[in] | carg | ColorArg struct to get the representation for. |
Allocated string for the representation.
You must free()
the memory allocated by this function.
Referenced by _colr_ptr_repr(), and ColorText_repr().
char* ColorArg_to_esc | ( | ColorArg | carg | ) |
Converts a ColorArg into an escape code string (char*
).
Allocates memory for the string.
If the ColorArg is empty (ARGTYPE_NONE
), an empty string is returned.
If the ColorValue is invalid, an empty string is returned. You must still free the empty string.
[in] | carg | ColorArg to get the ArgType and ColorValue from. |
Allocated string for the escape code.
You must free()
the memory allocated by this function. If the ColorArg is considered "empty", or the ColorValue is invalid, then NULL
is returned.
Referenced by _colr_join(), _colr_ptr_to_str(), ColorText_to_str(), colr_join_arrayn(), colr_printf_handler(), colr_str_replace_all_ColorArg(), colr_str_replace_ColorArg(), colr_str_replace_re_all_ColorArg(), colr_str_replace_re_ColorArg(), colr_str_replace_re_match_ColorArg(), colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_pat_all_ColorArg(), and colr_str_replace_re_pat_ColorArg().
bool ColorArg_to_esc_s | ( | char * | dest, |
ColorArg | carg | ||
) |
Converts a ColorArg into an escape code string (char*
) and fills the destination string.
If the ColorArg is empty (ARGTYPE_NONE
), dest[0]
is set to `'\0'`.
If the ColorValue is invalid, dest[0]
is set to `'\0'`.
[in] | dest | Destination for the escape code string. Must have room for the code type being used. See ColorArg_length() for determining the size needed. |
[in] | carg | ColorArg to get the ArgType and ColorValue from. |
true
if the ColorArg was valid, otherwise false
.Referenced by colr_str_has_ColorArg().
Copies a ColorArg into memory and returns the pointer.
You must free() the memory if you call this directly.
[in] | carg | ColorArg to copy/allocate for. |
Pointer to a heap-allocated ColorArg.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by ColorArgs_from_str().
void ColorArgs_array_free | ( | ColorArg ** | ps | ) |
Free an allocated array of ColorArgs, including the array itself.
Each individual ColorArg will be released, and finally the allocated memory for the array of pointers will be released.
[in] | ps | A pointer to an array of ColorArgs, where NULL is the last item. |
char* ColorArgs_array_repr | ( | ColorArg ** | lst | ) |
Creates a string representation for an array of ColorArg pointers.
[in] | lst | The ColorArg array to create the representation for (ColorArg** ). |
NULL
if lst
is NULL
, or the allocation fails.ColorArg** ColorArgs_from_str | ( | const char * | s, |
bool | unique | ||
) |
Create an array of ColorArgs from escape-codes found in a string (char*
).
This uses ColorArg_from_esc() and colr_str_get_codes() to build a heap-allocated array of heap-allocated ColorArgs.
[in] | s | A string to get the escape-codes from. Must be |
[in] | unique | Whether to only include unique ColorArgs. |
An allocated array of ColorArg pointers, where the last element is NULL
.
You must free()
the memory allocated by this function.
If | s is NULL , or empty, or there are otherwise no escape-codes found in the string, then NULL is returned. |
On | success, there will be at least two pointers behind the return value. The last pointer is always NULL . |
ColorJustify ColorJustify_empty | ( | void | ) |
Creates an "empty" ColorJustify, with JUST_NONE set.
Referenced by ColorText_empty().
bool ColorJustify_eq | ( | ColorJustify | a, |
ColorJustify | b | ||
) |
Compares two ColorJustify structs.
They are considered "equal" if their member values match.
[in] | a | First ColorJustify to compare. |
[in] | b | Second ColorJustify to compare. |
true
if they are equal, otherwise false
.bool ColorJustify_is_empty | ( | ColorJustify | cjust | ) |
Checks to see if a ColorJustify is "empty".
A ColorJustify is considered "empty" if the .method
member is set to JUST_NONE
.
[in] | cjust | The ColorJustify to check. |
true
if the ColorJustify is empty, otherwise false
.Referenced by ColorText_is_empty(), and ColorText_length().
ColorJustify ColorJustify_new | ( | ColorJustifyMethod | method, |
int | width, | ||
char | padchar | ||
) |
Creates a ColorJustify.
This is used to ensure every ColorJustify has it's .marker
member set correctly.
[in] | method | ColorJustifyMethod to use. |
[in] | width | Width for justification. If 0 is given, ColorText will use the width from colr_term_size(). |
[in] | padchar | Padding character to use. If 0 is given, the default, space (`' '`), is used. |
Referenced by ColorText_set_center(), ColorText_set_ljust(), and ColorText_set_rjust().
char* ColorJustify_repr | ( | ColorJustify | cjust | ) |
Creates a string (char*
) representation for a ColorJustify.
Allocates memory for the string representation.
[in] | cjust | ColorJustify struct to get the representation for. |
Allocated string for the representation.
You must free()
the memory allocated by this function.
Referenced by ColorText_repr().
char* ColorJustifyMethod_repr | ( | ColorJustifyMethod | meth | ) |
Creates a string (char*
) representation for a ColorJustifyMethod.
Allocates memory for the string representation.
[in] | meth | ColorJustifyMethod to get the representation for. |
Allocated string for the representation.
You must free()
the memory allocated by this function.
Referenced by ColorJustify_repr().
ColorResult* ColorResult_center | ( | ColorResult * | cres, |
int | width, | ||
char | padchar | ||
) |
Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
[in] | cres | A ColorResult pointer to center. It will be free 'd after this. |
[in] | width | Maximum width in characters, or 0 for current terminal width. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL
if cres
is NULL
. If cres
is empty, it is simply returned.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Referenced by Colr_center_char().
ColorResult* ColorResult_Colr | ( | ColorResult * | cres, |
... | |||
) |
Colorize a ColorResult, and return a new allocated ColorResult.
This is like ColorText_from_value(), except it accepts an allocated ColorResult as the first argument.
[in] | cres | An allocated ColorResult to colorize. This will be released to create the new ColorResult. |
[in] | ... | One or more fore(), back(), or style() arguments (ColorArgs). The last argument must be _ColrLastArg. The allocated ColorArgs will be free() 'd. |
An allocated ColorResult, or NULL
if cres
is NULL
.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
ColorResult ColorResult_empty | ( | void | ) |
Creates a ColorResult with .result=NULL
and .length=-1
, with the appropriate struct marker.
Referenced by ColorResult_from_stra(), and ColorResult_new().
bool ColorResult_eq | ( | ColorResult | a, |
ColorResult | b | ||
) |
Compares two ColorResults.
They are equal if all of their members are equal, excluding the memory address for the .result
member.
[in] | a | First ColorResult to compare. |
[in] | b | Second ColorResult to compare. |
true
if they are equal, otherwise false
.void ColorResult_free | ( | ColorResult * | p | ) |
Free allocated memory for a ColorResult and it's .result
member.
[in] | p | A ColorResult with a NULL or heap-allocated .result member. |
Referenced by _colr_free(), _colr_join(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rip_str(), ColorResult_rjust(), colr_printf_handler(), colr_str_replace_all_ColorResult(), colr_str_replace_ColorResult(), colr_str_replace_re_all_ColorResult(), colr_str_replace_re_ColorResult(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_ColorResult().
ColorResult ColorResult_from_str | ( | const char * | s | ) |
Allocates a copy of a string, and creates a ColorResult from it.
[in] | s | The string to copy. |
s
is NULL
. ColorResult* ColorResult_from_stra | ( | const char * | s | ) |
Allocates a copy of a string, and creates an allocated ColorResult from it.
[in] | s | The string to copy. |
An allocated ColorResult. The ColorResult may be "empty" if s
is NULL
.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Referenced by Colr_cursor_hide(), Colr_cursor_show(), Colr_erase_display(), Colr_erase_line(), Colr_move_return(), Colr_pos_restore(), and Colr_pos_save().
bool ColorResult_is_empty | ( | ColorResult | cres | ) |
Checks to see if a ColorResult is "empty" (NULL or empty string).
[in] | cres | ColorResult to check. |
true
if the ColorResult is "empty", otherwise false
. Referenced by ColorResult_center(), ColorResult_ljust(), and ColorResult_rjust().
bool ColorResult_is_ptr | ( | void * | p | ) |
Checks a void pointer to see if it contains a ColorResult struct.
The first member of a ColorResult is a marker.
[in] | p | A void pointer to check. |
true
if the pointer is a ColorResult, otherwise false
.Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().
size_t ColorResult_length | ( | ColorResult | cres | ) |
Return the length in bytes (including the null-terminator), that is needed to store the return from ColorResult_to_str() (.result
).
[in] | cres | A ColorResult to calculate the length for. |
0
if .result
is NULL
.Referenced by _colr_join_arrayn_size(), and _colr_ptr_length().
ColorResult* ColorResult_ljust | ( | ColorResult * | cres, |
int | width, | ||
char | padchar | ||
) |
Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
[in] | cres | A ColorResult pointer to center. It will be free 'd after this. |
[in] | width | Maximum width in characters, or 0 for current terminal width. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL
if cres
is NULL
. If cres
is empty, it is simply returned.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Referenced by Colr_ljust_char().
ColorResult ColorResult_new | ( | char * | s | ) |
Initialize a new ColorResult with an allocated string (char*
).
[in] | s | An allocated string to use for the .result member. |
s
is NULL
Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_str(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().
char* ColorResult_repr | ( | ColorResult | cres | ) |
Create a string representation for a ColorResult.
This happens to be the same as colr_str_repr(cres.result)
right now.
[in] | cres | A ColorResult to create the representation string for. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by _colr_ptr_repr().
char* ColorResult_rip_str | ( | ColorResult * | cres | ) |
Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char*
)).
[in] | cres | ColorResult to get the string from and free() . |
The string (char*
) from the result
member.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
ColorResult* ColorResult_rjust | ( | ColorResult * | cres, |
int | width, | ||
char | padchar | ||
) |
Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
[in] | cres | A ColorResult pointer to center. It will be free 'd after this. |
[in] | width | Maximum width in characters, or 0 for current terminal width. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL
if cres
is NULL
. If cres
is empty, it is simply returned.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
Referenced by Colr_rjust_char().
ColorResult* ColorResult_to_ptr | ( | ColorResult | cres | ) |
Allocate memory for a ColorResult, fill it, and return it.
This ensure the appropriate struct marker is set, for use with Colr.
[in] | cres | A ColorResult to use. |
An allocated ColorResult.
You must free()
the memory allocated by this function.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
If allocation fails, NULL
is returned.
Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_stra(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().
char* ColorResult_to_str | ( | ColorResult | cres | ) |
Convert a ColorResult into a string (char*
).
This simply returns the .result
member right now. It is used for compatibility with the colr_to_str() macro.
[in] | cres | A ColorResult to use. |
.result
member. If you free the result of this function, the original string used to create the ColorResult will be lost. Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rjust(), colr_join_arrayn(), colr_printf_handler(), colr_str_replace_all_ColorResult(), colr_str_replace_ColorResult(), colr_str_replace_re_all_ColorResult(), colr_str_replace_re_ColorResult(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_ColorResult().
ColorText ColorText_empty | ( | void | ) |
Creates an "empty" ColorText with pointers set to NULL
.
Referenced by ColorText_from_valuesv(), and ColorText_set_values().
void ColorText_free | ( | ColorText * | p | ) |
Frees a ColorText and it's ColorArgs.
The text member is left alone, because it wasn't created by ColrC.
[in] | p | Pointer to ColorText to free, along with it's Colr-based members. |
Referenced by _colr_free(), _colr_join(), Colr_center_char(), Colr_ljust_char(), colr_printf_handler(), Colr_rjust_char(), colr_str_replace_all_ColorText(), colr_str_replace_ColorText(), colr_str_replace_re_all_ColorText(), colr_str_replace_re_ColorText(), colr_str_replace_re_match_ColorText(), colr_str_replace_re_matches_ColorText(), colr_str_replace_re_pat_all_ColorText(), and colr_str_replace_re_pat_ColorText().
void ColorText_free_args | ( | ColorText * | p | ) |
Frees the ColorArg members of a ColorText.
The ColorText itself is not free'd.
This is safe to use on a stack-allocated ColorText with heap-allocated ColorArgs.
[in] | p | Pointer to a ColorText. |
Referenced by ColorResult_Colr(), and ColorText_free().
ColorText ColorText_from_values | ( | char * | text, |
... | |||
) |
Builds a ColorText from 1 mandatory string (char*
), and optional fore, back, and style args (pointers to ColorArgs).
[in] | text | Text to colorize (a regular string). |
[in] | ... | ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you. |
ColorText ColorText_from_valuesv | ( | char * | text, |
va_list | args | ||
) |
Builds a ColorText from 1 mandatory string (char*
), and a va_list
with optional fore, back, and style args (pointers to ColorArgs).
[in] | text | Text to colorize (a regular string). |
[in] | args | va_list with ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you, and should be used for basic text colorization. |
Referenced by ColorResult_Colr(), and ColorText_from_values().
Checks to see if a ColorText has a certain ColorArg value set.
Uses ColorArg_eq() to inspect the fore
, back
, and style
members.
true
if the fore
, back
, or style
arg matches carg
, otherwise false
.bool ColorText_has_args | ( | ColorText | ctext | ) |
bool ColorText_is_empty | ( | ColorText | ctext | ) |
Checks to see if a ColorText has no usable values.
A ColorText is considered "empty" if the .text
, .fore
, .back
, and .style
pointers are NULL
, and the .just
member is set to an "empty" ColorJustify.
[in] | ctext | The ColorText to check. |
true
if the ColorText is empty, otherwise false
.bool ColorText_is_ptr | ( | void * | p | ) |
Checks a void pointer to see if it contains a ColorText struct.
The first member of a ColorText is a marker.
[in] | p | A void pointer to check. |
true
if the pointer is a ColorText, otherwise false
.Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().
size_t ColorText_length | ( | ColorText | ctext | ) |
Returns the length in bytes needed to allocate a string (char*
) built with ColorText_to_str() with the current text
, fore
, back
, and style
members.
[in] | ctext | ColorText to use. |
size_t
) needed to allocate a ColorText's string, or 1
(size of an empty string) for invalid/empty arg types/values.Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_to_str().
char* ColorText_repr | ( | ColorText | ctext | ) |
Allocate a string (char*
) representation for a ColorText.
[in] | ctext | ColorText to get the string representation for. |
Referenced by _colr_ptr_repr().
Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_center and friends.
[out] | ctext | The ColorText to set the justification method for. |
[in] | width | Maximum width for the justification. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext
. Referenced by Colr_center_char().
ColorText* ColorText_set_just | ( | ColorText * | ctext, |
ColorJustify | cjust | ||
) |
Set the ColorJustify method for a ColorText, and return the ColorText.
This is to facilitate the justification macros. If you already have a pointer to a ColorText, you can just do ctext->just = just;
. The purpose of this is to allow ColorText_set_just(ColorText_to_ptr(...), ...)
to work.
[out] | ctext | The ColorText to set the justification method for. |
[in] | cjust | The ColorJustify struct to use. |
ctext
.Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_ljust and friends.
[out] | ctext | The ColorText to set the justification method for. |
[in] | width | Maximum width for the justification. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext
. Referenced by Colr_ljust_char().
Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_rjust and friends.
[out] | ctext | The ColorText to set the justification method for. |
[in] | width | Maximum width for the justification. |
[in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext
. Referenced by Colr_rjust_char().
void ColorText_set_values | ( | ColorText * | ctext, |
char * | text, | ||
... | |||
) |
Initializes an existing ColorText from 1 mandatory string (char*
), and optional fore, back, and style args (pointers to ColorArgs).
[out] | ctext | A ColorText to initialize with values. |
[in] | text | Text to colorize (a regular string). |
[in] | ... | A va_list with ColorArgs pointers for fore, back, and style, in any order. |
Copies a ColorText into allocated memory and returns the pointer.
You must free() the memory if you call this directly.
[in] | ctext | ColorText to copy/allocate for. |
Pointer to a heap-allocated ColorText.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free()
the result. Otherwise, you are responsible for calling free()
.
char* ColorText_to_str | ( | ColorText | ctext | ) |
Stringifies a ColorText struct, creating a mix of escape codes and text.
[in] | ctext | ColorText to stringify. |
An allocated string with text/escape-codes.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned. If the ColorText has a NULL
.text
member, NULL
is returned.
Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_Colr(), Colr_center_char(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), Colr_rjust_char(), colr_str_replace_all_ColorText(), colr_str_replace_ColorText(), colr_str_replace_re_all_ColorText(), colr_str_replace_re_ColorText(), colr_str_replace_re_match_ColorText(), colr_str_replace_re_matches_ColorText(), colr_str_replace_re_pat_all_ColorText(), and colr_str_replace_re_pat_ColorText().
ColorType ColorType_from_str | ( | const char * | arg | ) |
Determine which type of color value is desired by name.
Example:
[in] | arg | Color name to get the ColorType for. |
ColorType | value on success. |
TYPE_INVALID | for invalid color names/strings. |
TYPE_INVALID_EXT_RANGE | for ExtendedValues outside of 0-255. |
TYPE_INVALID_RGB_RANGE | for rgb values outside of 0-255. |
bool ColorType_is_invalid | ( | ColorType | type | ) |
Check to see if a ColorType value is considered invalid.
[in] | type | ColorType value to check. |
true
if the value is considered invalid, otherwise false
.bool ColorType_is_valid | ( | ColorType | type | ) |
Check to see if a ColorType value is considered valid.
[in] | type | ColorType value to check. |
true
if the value is considered valid, otherwise false
.char* ColorType_repr | ( | ColorType | type | ) |
Creates a string (char*
) representation of a ColorType.
[in] | type | A ColorType to get the type from. |
A pointer to an allocated string.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
char* ColorType_to_str | ( | ColorType | type | ) |
Create a human-friendly string (char*
) representation for a ColorType.
[in] | type | A ColorType to get the name for. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by ColorValue_example().
ColorValue ColorValue_empty | ( | void | ) |
Create an "empty" ColorValue.
This is used with ColorArg_empty() to build ColorArgs that don't do anything, where using NULL
has a different meaning inside the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
(ColorValue){.type=TYPE_NONE, .basic=0, .ext=0, .rgb=(RGB){0, 0, 0}}
bool ColorValue_eq | ( | ColorValue | a, |
ColorValue | b | ||
) |
Compares two ColorValue structs.
They are considered "equal" if all of their members match.
[in] | a | First ColorValue to compare. |
[in] | b | Second ColorValue to compare. |
true
if they are equal, otherwise false
.Referenced by ColorArg_eq().
char* ColorValue_example | ( | ColorValue | cval | ) |
Create a string (char*
) representation of a ColorValue with a human-friendly type/name.
[in] | cval | A ColorValue to get an example string for. |
An allocated string with the result.
You must free()
the memory allocated by this function.
If allocation fails, NULL
is returned.
Referenced by ColorArg_example().
ColorValue ColorValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*
) into a ColorValue.
[in] | s | An escape-code string to parse. Must be |
For | invalid strings, the .type member can be one of:
|
Referenced by ColorArg_from_esc().
ColorValue ColorValue_from_str | ( | const char * | s | ) |
Create a ColorValue from a known color name, or RGB string (char*
).
[in] | s | A string to parse the color name from (can be an RGB string). |
For | invalid strings, the .type member can be one of:
|
Referenced by ColorArg_from_str().
ColorValue ColorValue_from_value | ( | ColorType | type, |
void * | p | ||
) |
Used with the color_val macro to dynamically create a ColorValue based on it's argument type.
[in] | type | A ColorType value, to mark the type of ColorValue. |
[in] | p | A pointer to either a BasicValue, ExtendedValue, or a RGB. |
.type
member set for the value that was passed. For invalid types the .type
member may be set to one of:Referenced by ColorArg_from_BasicValue(), ColorArg_from_ExtendedValue(), ColorArg_from_RGB(), ColorArg_from_StyleValue(), ColorValue_from_esc(), and ColorValue_from_str().
bool ColorValue_has_BasicValue | ( | ColorValue | cval, |
BasicValue | bval | ||
) |
Checks to see if a ColorValue has a BasicValue set.
[in] | cval | ColorValue to check. |
[in] | bval | BasicValue to look for. |
true
if the ColorValue has the exact BasicValue set.bool ColorValue_has_ExtendedValue | ( | ColorValue | cval, |
ExtendedValue | eval | ||
) |
Checks to see if a ColorValue has a ExtendedValue set.