add support for colored terminal output

[goatshriek]

A convenient feature in any logging library is colored output when logging to a console so that messages of different severity levels stand out from one another. This could be implemented in stumpless as a new set of attributes for stream loggers, which is off by default but is set when getting the stdout our stderr targets using stumpless_open_stdout_target or stumpless_open_stderr_target (respectively).

Bonus points if you can also implement build-time configuration options to set the default severity colors! However, if you aren't feeling up to this part then it can be split out into a separate issue for someone else to try their hand at - just make a note of this when you announce that you're going to work on this.

Check out the Contributing Guidelines and the development guide for the basics on working with the stumpless code base and submitting changes.

General Approach

There are a few details left out of the following approach, for you to fill in as you encounter them. If you find you need help, please ask here and someone can help you get past the stumbling block.

If you aren't familiar with printing colors in terminals, first do some research on the topic. This article has a good walkthrough of the concepts for beginners.

include/stumpless/target/stream.h declares the public functions that are specific to stream targets. This is where you will need to add a new function to set the color for a severity code. Name the function something like stumpless_set_severity_color and will take a target, a severity code, and an escape code as arguments. Put the definition for this into the src/target/stream.c file.

Make sure that your implementation is thread safe! The simplest way to do this is to lock the target whenever it is being modified or read for the values, using the lock_target and unlock_target functions.

You'll need somewhere to store the configured colors. They should be added to the struct that stores details for stream targets, defined in include/private/target/stream.h. Exactly how the codes are stored is up to you, for example it could be an array of pointers to strings. Your new function for setting the color will update this field with the desired value. You should add code to stumpless_open_stream_target in src/target/stream.c to initialize these fields with something that means off (NULL pointers, perhaps)?

To set these up for stdout and stderr targets by default, just add some calls to your new set color functions to stumpless_open_stderr_target and stumpless_open_stdout_target (in src/target/stream.c) with some default colors that make sense. For example STUMPLESS_SEVERITY_EMERG should probably be something alarming like red!

Next take a look at the sendto_stream_target function in src/target/stream.c. This function is responsible for writing messages to a stream target. This is the function where you will add calls to print the escape codes before and after the message to color it. Before the message you will print the configured color escape code, and afterwards you will print the escape code to clear the colors back to what they were before.

Finally, remember to add new tests for your code in test/function/target/stream.cpp. You can use the other tests that are already there as starting points.

[northernSage]

This one seems fun, I'll give it a go

[goatshriek]

@northernSage Absolutely no pressure, but just want to check in to see if you're still planning to work this? No worries if not, I will return it to the pool of issues available for newcomers to try out.

[northernSage]

Hey @goatshriek, thanks for the ping. Things have been a bit unruly lately, so I have slowed down all open source activity (not only stumpless). I fully intend to finish this PR and keep contributing, though 👍🏻

[goatshriek]

No worries, completely understand! Good luck getting things back in line!

[abhakta-47]

This looks interesting. Can I work on it ?

[northernSage]

Yes, go ahead. I'm a bit caught up in other stuff at the moment :/

[abhakta-47]

In sendto_stream_target how to get the severity of the msg, to choose which escapecode to write depending on the severity.

[goatshriek]

The previous comment was deleted as irrelevant spam.

@abhakta-47 that's a great question, the current implementation doesn't support this. You'll need to modify the signature of the function to also receive the entry in addition to the buffer, similar to what config_sendto_wel_target already does. Eventually the signatures of the sendto_ functions will be standardized, but for now they differ as needed for tasks like this.

[abhakta-47]

What would be the fastest way to this test color functionality, other than installing and writing code ?
Also, How to use example-basics example-streams etc. ?

[abhakta-47]

I want to keep terminal_colors code in a different header/source file. I have created a header file and put related definitions in there. But, functions in the source_file are not picked up by the compiler (already added the src file in STUMPLESS_SOURCES list in cmakelist). What should I do ?

[goatshriek]

For testing, look at the test suites in the test/function/target/stream.cpp file, which is where you would add your test code. To test it visually you can modify some of the example code to just have a quick look.

I'm not sure what the problem could be based on your description. You can create a pull request in draft mode if you still need this reviewed.

[BlockMagiX97]

I will give it a go

[goatshriek]

Good luck! There are some previous attempts in the conversation above that may give you a good starting point.

[BlockMagiX97]

should i make the colors global or on target basis

[goatshriek]

These should be set on a per-target basis. That means that you can use new fields in the stream_target structure, instead of trying to manage global values.

[BlockMagiX97]

How do I figure out what test is number 57. It seqfaults and i don't know what edge cases I need to handle.

[goatshriek]

In the case of a segfault, I recommend using a debugger like gdb to run the test and get a backtrace at the point of the segfault.

[BlockMagiX97]

where should i put helper functions?

[goatshriek]

This depends heavily on the purpose of the helper, so it's hard to answer without more context. Since the coloration is specific to stream targets, I would expect most helpers for this to end up in the stream targets source files.

[BlockMagiX97]

How do i make stumpless_set_severity_color visible code i have is in colored-terminal branch. thread safety and not memory leaking in process.

[goatshriek]

You can open a pull request whenever you'd like, though it is preferred to leave it in draft status until you are ready for review. When you believe it's ready to merge, you can request my review on it and I will take a look.

[MorganDoyle]

is this issue still open? id like to work on it!

[goatshriek]

It is still open, please feel free to give it a shot!

[Celestial071]

I assume this is still open? Can I give it a shot too?

[goatshriek]

Yes, go for it!

[TomGitman]

Sorry, but which struct should I add a color array? stumpless_target or stream_target?
I am just checking around and see if I can contribute.

[goatshriek]

Hello @TomGitman, it would make the most sense to me to add the current color settings to the stream_target struct, as these are only expected to be valid for terminal targets, which the stream targets handle.

As a side note, see #290 for an implementation attempt that was pretty far along, and took this approach. Feel free to deviate from what was done there, but it may speed things up for you to see how another person tackled the problem.