gwion-util
utilities for the Gwion project
Loading...
Searching...
No Matches
termcolor.h
Go to the documentation of this file.
1// libtermcolor: termcolor.h
2// Copyright (C) 2021 Jérémie Astor
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <https://www.gnu.org/licenses/>.
16/*
17 This is the header file for libtermcolor. It contains the documentation for
18 using the various functions in the exposed API. The doc folder contains
19 other information. Both places are vital for proper API usage, so reading
20 both places will facilitate adeptitude with libtermcolor.
21*/
22
23#ifndef _LIBTERMCOLOR_TERMCOLOR_H
24#define _LIBTERMCOLOR_TERMCOLOR_H
25
26#include <stdbool.h>
27#include <stdio.h>
28//#include "termcolor_export.h"
29
30#if (defined(WIN32) || defined(_WIN32) || defined(__WIN32__) || defined(__NT__) || defined(__WIN32) && !defined(__CYGWIN__)) && defined (ENABLE_VIRTUAL_TERMINAL_PROCESSING)
31 #define TERMCOLOR_OS_WIN
32 #include <windows.h>
33#endif
34
35/* A type describing an termcolor error. These are the only values returned by
36 the `tcol_fprintf` and `tcol_printf` functions. You may assume any nonzero
37 value is an error and use `tcol_errorstr` to display a diagnostic. */
46
47/* Decodes the given termcolor representation of a color
48
49 Parameters:
50 - `dst`: The buffer to write the resulting ANSI escape code to
51 - `dstn`: The length of the destination buffer
52 - `len`: A pointer to a value which is initialized to the number of bytes
53 written to `dst`
54 - `rep`: The attributes applied to the text
55 - `foreground`: A foreground color, if any
56 - `background`: A background color, if any
57
58 Return Value:
59 - int: One of the values `enum term_color_error_t`
60
61 NOTE: This is private API exposed for developers. Those interested can read
62 the source (found in src/termcolor.c). The relevant parts are the enum
63 `_termcolor_internal_color` and the function `_termcolor_internal_lookup`.
64*/
65int _tcol_color_generate(char *dst, size_t dstn, size_t *len, int rep,
66 int foreground, int background);
67
68/* Returns a human-readable string describing the given libtermcolor error. */
69const char *tcol_errorstr(const enum term_color_error_t err);
70
71/* Parses a termcolor color string without the brackets.
72
73 Parameters:
74 - `dst`: The buffer to write the resulting ANSI escape code to
75 - `dstn`: The length of the destination buffer
76 - `color`: The buffer that the color is given in
77 - `k`: The length of the given color in the buffer
78 - `len`: A pointer to a value which is initialized to the number of bytes
79 written to `dst`
80
81 Return Value:
82 - `int`: One of the values `enum term_color_error_t`
83
84 NOTE: color is not null-terminated as its length is given by k which shall be
85 between 1 and 16.*/
86int tcol_color_parse(char *dst, size_t dstn, char color[16],
87 size_t k, size_t *len);
88
89/* By default libtermcolor will use color. However this behavior can be manually
90 overridden using this function.
91
92 Parameters
93 - `enable_color`: Whether to enable "colorization" of the format string */
94void tcol_override_color_checks(bool enable_color);
95
96/* Return the current state of colorization. */
97bool tcol_has_color(void);
98
99/* Printfs the colorized format string to the specified stream.
100
101 Parameters:
102 - `fmt`: The termcolor format string
103 - `...`: The variable argumentsto replace the format specifiers with
104
105 Return Value:
106 - `int`: One of the values `enum term_color_error_t` */
107int tcol_fprintf(FILE *stream, const char *fmt, ...);
108
109/* Printfs the colorized format string to the standard output.
110
111 Parameters:
112 - `stream`: The `FILE*` stream to printf to
113 - `fmt`: The termcolor format string
114 - `...`: The variable argumentsto replace the format specifiers with
115
116 Return Value:
117 - `int`: One of the values `enum term_color_error_t` */
118int tcol_printf(const char *fmt, ...);
119
120/* Snprintfs the colorized format string to the specified string stream.
121
122 Parameters:
123 - `buffer`: The `char*` stream to printf to
124 - `N`: The total size of `buffer`, including the null terminatr
125 - `fmt`: The termcolor format string
126 - `...`: The variable argumentsto replace the format specifiers with
127
128 Return Value:
129 - `int`: One of the values `enum term_color_error_t`*/
130int tcol_snprintf(char *buffer, size_t N, const char *fmt, ...);
131
132#endif /* _LIBTERMCOLOR_TERMCOLOR_H */
char const char * fmt
Definition gwion_print.h:2
const char * tcol_errorstr(const enum term_color_error_t err)
Definition termcolor.c:32
int tcol_snprintf(char *buffer, size_t N, const char *fmt,...)
Definition termcolor.c:382
int tcol_fprintf(FILE *stream, const char *fmt,...)
Definition termcolor.c:365
int tcol_printf(const char *fmt,...)
Definition termcolor.c:373
int _tcol_color_generate(char *dst, size_t dstn, size_t *len, int rep, int foreground, int background)
Definition termcolor.c:76
void tcol_override_color_checks(bool enable_color)
Definition termcolor.c:40
int tcol_color_parse(char *dst, size_t dstn, char color[16], size_t k, size_t *len)
Definition termcolor.c:142
bool tcol_has_color(void)
Definition termcolor.c:36
term_color_error_t
Definition termcolor.h:38
@ TermColorErrorInvalidColor
Definition termcolor.h:42
@ TermColorErrorUnterminatedColor
Definition termcolor.h:43
@ TERM_COLOR_ERROR_COUNT
Definition termcolor.h:44
@ TermColorErrorAllocationFailed
Definition termcolor.h:40
@ TermColorErrorNone
Definition termcolor.h:39
@ TermColorErrorPrintingFailed
Definition termcolor.h:41