Initial commit

This is a simple "library" for doing colourised console output.

Signed-off-by: Andrew Clayton <[email protected]>

.gitattributes

@@ -0,0 +1,2 @@
+*.c	diff=cpp
+*.h	diff=cpp

.gitignore

@@ -0,0 +1,7 @@
+.d/
+
+*.swp
+*~
+
+*.o
+example

CodingStyle.md

@@ -0,0 +1,123 @@
+# Coding Style
+
+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).
+
+As a general rule :-
+
+- all indentation is tabs (set to 8 char) with the exception of
+  continuation lines that are aligned with tabs and then spaces
+
+- all keywords followed by a '(' have a space in between
+
+```C
+	if (condition)
+
+	for (i = 0; i < 5; i++)
+```
+
+- function calls do NOT have a space between their name and argument
+
+```C
+	i = some_function(argument);
+```
+
+- usually there is no space on the inside of parenthesis (see examples
+  above)
+
+- function / method implementations have their opening curly braces in
+  column 1
+
+- all other opening curly braces follow at the end of the line, with a
+  space separating them:
+
+```C
+	if (condition) {
+		dosomething();
+		dosomethingelse();
+	}
+```
+
+- both sides of an if / else clause either use or do not use curly braces:
+
+```C
+	if (condition)
+		i = 4;
+	else
+		j = 6;
+
+	if (condition) {
+		i = 6;
+	} else {
+		i = 4;
+		j = 6;
+	}
+```
+
+- don't do assignments inside if () statements, always do it this way
+
+```C
+	res = something();
+	if (!res)
+		return NULL;
+```
+
+- if you don't need the result you can do
+
+```C
+	if (!something())
+		return NULL;
+```
+
+- use space to make visual separation easier
+
+```C
+	a = b + 3 + e / 4;
+```
+
+- continuation lines have the operator / comma at the end
+
+```C
+       if (very_long_conditiont_1 ||
+           condition_2)
+
+        b = a + (c + d +
+                 f + z);
+```
+
+- switch statements with blocks are a little bit special (to avoid indenting
+  too far)
+
+```C
+	switch (foo) {
+	case FIRST:
+		whatever();
+		break;
+	case SECOND: {
+		int i;
+		for (i = 0; i < 5; i++)
+			do_something(i);
+	}
+	}
+```
+
+- comments should be C style not C++/C99
+
+  for single line comments
+
+```C
+	/* This is a single line comment */
+```
+
+  for multi-line comments
+
+```C
+	/*
+	 * This is a multi
+	 * line comment
+	 */
+```
+
+- variable declarations should be at the beginning of a code block, not
+  interspersed in the middle
+
+- variable and function naming should be all lower case with _ used for spaces

Contributing.md

@@ -0,0 +1,48 @@
+# Contributing
+
+When sending code, please either send signed-off patches or a pull request
+with signed-off commits. This means adding a line that says
+"Signed-off-by: Name \<Email\>" at the end of each commit. E.g
+
+```
+Signed-off-by: Andrew Clayton <[email protected]>
+```
+
+This signifies that you have read/understood/and agreed to the
+[Developer's Certificate of Origin](DCO). Essentially indicating that you
+wrote the code and/or have the right to contribute it to this project.
+
+This is **not** a CLA.
+
+Also, please write good git commit messages. A good commit message looks like
+this:
+
+```
+Header line: explaining the commit in one line
+
+Body of commit message is a few lines of text, explaining things in
+more detail, possibly giving some background about the issue being
+fixed, etc etc.
+
+The body of the commit message can be several paragraphs, and please do
+proper word-wrap and keep columns less than or equal to 72 characters.
+That way "git log" will show things nicely even when it's indented.
+
+Reported-by: whoever-reported-it
+Signed-off-by: Your Name <[email protected]>
+```
+
+That header line really should be meaningful, and really should be just one
+line. The header line is what is shown by tools like gitk and shortlog, and
+should summarize the change in one readable line of text, independently of
+the longer explanation.
+
+- If emailing patches, it is recommended to use git-send-email(1).
+- If emailing a pull request it is recommended to use git-request-pull(1).
+- Pull requests can be made via GitHub.
+
+Email should be sent to the project maintainer;
+
+```
+Andrew Clayton <[email protected]>
+```

DCO

@@ -0,0 +1,37 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

LICENSE

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

README.md

@@ -0,0 +1,113 @@
+# Textus Coloris
+
+Simple "library" for doing colourised console output.
+
+# API
+
+There are five functions
+
+```C
+void tc_set_colors(const struct tc_coloris *colors);
+```
+
+This is to set the colour map.
+
+```C
+int tc_print(FILE *fp, const char *fmt, ...);
+int tc_printv(FILE *fp, const char *fmt, va_list args);
+```
+
+These print a colourised output to the given output stream. These are
+analogous to the fprintf(3) & vfprintf(3) function.
+
+```C
+char *tc_cstring(const char *fmt, ...);
+char *tc_cstringv(const char *fmt, va_list args);
+```
+
+These return a pointer to a colourised string. You should free(2) this
+pointer, NULL will be returned on error. These are sort of analogous to the
+asprintf(3) & vasprintf(3) functions.
+
+# Use
+
+Seeing as this is really a bit too simple to make into an actual _DSO_, it is
+instead presented as a header-only library.
+
+This is contained under _header-only/_.
+
+There is a simple test program to show basic usage. Essentially just copy
+_textus\_coloris.h_ into your project and
+
+```C
+#define TEXTUS_COLORIS_IMPL
+#include "textus_coloris.h"
+```
+
+in **one** of your .c files. If you want to use these functions from any other
+source files then just do
+
+```C
+#include "textus_coloris.h"
+```
+
+in them.
+
+Define a colour map
+
+```C
+static const struct tc_coloris colors[] = {
+        { "RED",                "\e[38;5;160m" },
+        { "GREEN",              "\e[38;5;40m"  },
+        { "BLUE",               "\e[38;5;75m"  },
+
+        { "BOLD",               "\e[1m"        },
+        { "RST",                "\e[0m"        },
+
+        {}
+};
+```
+
+then set it with
+
+```C
+tc_set_colors(colors);
+```
+
+Then you can do stuff like
+
+```C
+tc_print(stdout, "Hello World! #BOLD##GREEN#%s#RST#\n", "Hello World!");
+```
+
+## split-out
+
+There is also a version with the core code split out into a _.c_ file. You
+can just copy _textus\_coloris.[ch]_ into your project and build the .c file
+as you do the rest. Then it's like the above but you don't
+_#define TEXTUS\_COLORIS\_IMPL_
+
+Otherwise the functionality is the same.
+
+## Examples
+
+There are examples of usage under _header-only/_ & _split-out/_
+
+# NO\_COLOR
+
+This obeys the [NO\_COLOR](https://no-color.org/) environment variable.
+
+# Thread safety
+
+This should be thread safe, the colour map pointer is stored in thread local
+storage so you should be able to set per thread colour maps.
+
+# License
+
+This licensed under under the MIT license.
+
+See *LICENSE* in the repository root for details.
+
+# Contributing
+
+See *CodingStyle.md* & *Contributing.md*