Skip to content

Commit 4930b7a

Browse files
ac000ac000
committed
Initial commit
This is a simple "library" for doing colourised console output. Signed-off-by: Andrew Clayton <andrew@digital-domain.net>
0 parents  commit 4930b7a

16 files changed

Lines changed: 1232 additions & 0 deletions

‎.gitattributes‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*.c diff=cpp
2+
*.h diff=cpp

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.d/
2+
3+
*.swp
4+
*~
5+
6+
*.o
7+
example

‎CodingStyle.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Coding Style
2+
3+
We follow the Linux kernel [coding style](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst).
4+
5+
As a general rule :-
6+
7+
- all indentation is tabs (set to 8 char) with the exception of
8+
continuation lines that are aligned with tabs and then spaces
9+
10+
- all keywords followed by a '(' have a space in between
11+
12+
```C
13+
if (condition)
14+
15+
for (i = 0; i < 5; i++)
16+
```
17+
18+
- function calls do NOT have a space between their name and argument
19+
20+
```C
21+
i = some_function(argument);
22+
```
23+
24+
- usually there is no space on the inside of parenthesis (see examples
25+
above)
26+
27+
- function / method implementations have their opening curly braces in
28+
column 1
29+
30+
- all other opening curly braces follow at the end of the line, with a
31+
space separating them:
32+
33+
```C
34+
if (condition) {
35+
dosomething();
36+
dosomethingelse();
37+
}
38+
```
39+
40+
- both sides of an if / else clause either use or do not use curly braces:
41+
42+
```C
43+
if (condition)
44+
i = 4;
45+
else
46+
j = 6;
47+
48+
if (condition) {
49+
i = 6;
50+
} else {
51+
i = 4;
52+
j = 6;
53+
}
54+
```
55+
56+
- don't do assignments inside if () statements, always do it this way
57+
58+
```C
59+
res = something();
60+
if (!res)
61+
return NULL;
62+
```
63+
64+
- if you don't need the result you can do
65+
66+
```C
67+
if (!something())
68+
return NULL;
69+
```
70+
71+
- use space to make visual separation easier
72+
73+
```C
74+
a = b + 3 + e / 4;
75+
```
76+
77+
- continuation lines have the operator / comma at the end
78+
79+
```C
80+
if (very_long_conditiont_1 ||
81+
condition_2)
82+
83+
b = a + (c + d +
84+
f + z);
85+
```
86+
87+
- switch statements with blocks are a little bit special (to avoid indenting
88+
too far)
89+
90+
```C
91+
switch (foo) {
92+
case FIRST:
93+
whatever();
94+
break;
95+
case SECOND: {
96+
int i;
97+
for (i = 0; i < 5; i++)
98+
do_something(i);
99+
}
100+
}
101+
```
102+
103+
- comments should be C style not C++/C99
104+
105+
for single line comments
106+
107+
```C
108+
/* This is a single line comment */
109+
```
110+
111+
for multi-line comments
112+
113+
```C
114+
/*
115+
* This is a multi
116+
* line comment
117+
*/
118+
```
119+
120+
- variable declarations should be at the beginning of a code block, not
121+
interspersed in the middle
122+
123+
- variable and function naming should be all lower case with _ used for spaces

‎Contributing.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Contributing
2+
3+
When sending code, please either send signed-off patches or a pull request
4+
with signed-off commits. This means adding a line that says
5+
"Signed-off-by: Name \<Email\>" at the end of each commit. E.g
6+
7+
```
8+
Signed-off-by: Andrew Clayton <andrew@digital-domain.net>
9+
```
10+
11+
This signifies that you have read/understood/and agreed to the
12+
[Developer's Certificate of Origin](DCO). Essentially indicating that you
13+
wrote the code and/or have the right to contribute it to this project.
14+
15+
This is **not** a CLA.
16+
17+
Also, please write good git commit messages. A good commit message looks like
18+
this:
19+
20+
```
21+
Header line: explaining the commit in one line
22+
23+
Body of commit message is a few lines of text, explaining things in
24+
more detail, possibly giving some background about the issue being
25+
fixed, etc etc.
26+
27+
The body of the commit message can be several paragraphs, and please do
28+
proper word-wrap and keep columns less than or equal to 72 characters.
29+
That way "git log" will show things nicely even when it's indented.
30+
31+
Reported-by: whoever-reported-it
32+
Signed-off-by: Your Name <you@example.com>
33+
```
34+
35+
That header line really should be meaningful, and really should be just one
36+
line. The header line is what is shown by tools like gitk and shortlog, and
37+
should summarize the change in one readable line of text, independently of
38+
the longer explanation.
39+
40+
- If emailing patches, it is recommended to use git-send-email(1).
41+
- If emailing a pull request it is recommended to use git-request-pull(1).
42+
- Pull requests can be made via GitHub.
43+
44+
Email should be sent to the project maintainer;
45+
46+
```
47+
Andrew Clayton <andrew@digital-domain.net>
48+
```

‎DCO‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Developer Certificate of Origin
2+
Version 1.1
3+
4+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
5+
1 Letterman Drive
6+
Suite D4700
7+
San Francisco, CA, 94129
8+
9+
Everyone is permitted to copy and distribute verbatim copies of this
10+
license document, but changing it is not allowed.
11+
12+
13+
Developer's Certificate of Origin 1.1
14+
15+
By making a contribution to this project, I certify that:
16+
17+
(a) The contribution was created in whole or in part by me and I
18+
have the right to submit it under the open source license
19+
indicated in the file; or
20+
21+
(b) The contribution is based upon previous work that, to the best
22+
of my knowledge, is covered under an appropriate open source
23+
license and I have the right under that license to submit that
24+
work with modifications, whether created in whole or in part
25+
by me, under the same open source license (unless I am
26+
permitted to submit under a different license), as indicated
27+
in the file; or
28+
29+
(c) The contribution was provided directly to me by some other
30+
person who certified (a), (b) or (c) and I have not modified
31+
it.
32+
33+
(d) I understand and agree that this project and the contribution
34+
are public and that a record of the contribution (including all
35+
personal information I submit with it, including my sign-off) is
36+
maintained indefinitely and may be redistributed consistent with
37+
this project or the open source license(s) involved.

‎LICENSE‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Copyright (c) 2021 Andrew Clayton
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a
4+
copy of this software and associated documentation files (the "Software"),
5+
to deal in the Software without restriction, including without limitation
6+
the rights to use, copy, modify, merge, publish, distribute, sublicense,
7+
and/or sell copies of the Software, and to permit persons to whom the
8+
Software is furnished to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in
11+
all copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19+
THE SOFTWARE.

‎README.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Textus Coloris
2+
3+
Simple "library" for doing colourised console output.
4+
5+
# API
6+
7+
There are five functions
8+
9+
```C
10+
void tc_set_colors(const struct tc_coloris *colors);
11+
```
12+
13+
This is to set the colour map.
14+
15+
```C
16+
int tc_print(FILE *fp, const char *fmt, ...);
17+
int tc_printv(FILE *fp, const char *fmt, va_list args);
18+
```
19+
20+
These print a colourised output to the given output stream. These are
21+
analogous to the fprintf(3) & vfprintf(3) function.
22+
23+
```C
24+
char *tc_cstring(const char *fmt, ...);
25+
char *tc_cstringv(const char *fmt, va_list args);
26+
```
27+
28+
These return a pointer to a colourised string. You should free(2) this
29+
pointer, NULL will be returned on error. These are sort of analogous to the
30+
asprintf(3) & vasprintf(3) functions.
31+
32+
# Use
33+
34+
Seeing as this is really a bit too simple to make into an actual _DSO_, it is
35+
instead presented as a header-only library.
36+
37+
This is contained under _header-only/_.
38+
39+
There is a simple test program to show basic usage. Essentially just copy
40+
_textus\_coloris.h_ into your project and
41+
42+
```C
43+
#define TEXTUS_COLORIS_IMPL
44+
#include "textus_coloris.h"
45+
```
46+
47+
in **one** of your .c files. If you want to use these functions from any other
48+
source files then just do
49+
50+
```C
51+
#include "textus_coloris.h"
52+
```
53+
54+
in them.
55+
56+
Define a colour map
57+
58+
```C
59+
static const struct tc_coloris colors[] = {
60+
{ "RED", "\e[38;5;160m" },
61+
{ "GREEN", "\e[38;5;40m" },
62+
{ "BLUE", "\e[38;5;75m" },
63+
64+
{ "BOLD", "\e[1m" },
65+
{ "RST", "\e[0m" },
66+
67+
{}
68+
};
69+
```
70+
71+
then set it with
72+
73+
```C
74+
tc_set_colors(colors);
75+
```
76+
77+
Then you can do stuff like
78+
79+
```C
80+
tc_print(stdout, "Hello World! #BOLD##GREEN#%s#RST#\n", "Hello World!");
81+
```
82+
83+
## split-out
84+
85+
There is also a version with the core code split out into a _.c_ file. You
86+
can just copy _textus\_coloris.[ch]_ into your project and build the .c file
87+
as you do the rest. Then it's like the above but you don't
88+
_#define TEXTUS\_COLORIS\_IMPL_
89+
90+
Otherwise the functionality is the same.
91+
92+
## Examples
93+
94+
There are examples of usage under _header-only/_ & _split-out/_
95+
96+
# NO\_COLOR
97+
98+
This obeys the [NO\_COLOR](https://no-color.org/) environment variable.
99+
100+
# Thread safety
101+
102+
This should be thread safe, the colour map pointer is stored in thread local
103+
storage so you should be able to set per thread colour maps.
104+
105+
# License
106+
107+
This licensed under under the MIT license.
108+
109+
See *LICENSE* in the repository root for details.
110+
111+
# Contributing
112+
113+
See *CodingStyle.md* & *Contributing.md*

0 commit comments

Comments
 (0)