Tutorial part 8: message buffers

In previous examples, we finished a diagnostic with a call to diagnostic_finish(), which takes a format string and arguments to determine the text message of the diagnostic.

Sometimes this approach is inconvenient, such as where you might want to build up a message programatically from a series of components. Additionally, you might have existing code that uses fprintf, whereas diagnostic_finish() has its own formatting conventions which are not the same as printf.

For this reason libgdiagnostics (from LIBGDIAGNOSTICS_ABI_3 onwards) supports diagnostic_message_buffer, which can be used to accumulate a message before using it.

You create a diagnostic_message_buffer using diagnostic_message_buffer_new().

There are various API entrypoints for accumulating text into the buffer.

For example:

Running this will produce this text output:

.. code-block:: console

$ ./test-message-buffer.c.exe ./test-message-buffer.c.exe: error: this is a string; foo; int: 42 str: mostly harmless; this is a link ‘this is quoted’ highlight A highlight B (1).

where in a suitably-capable terminal if a text sink is directly connected to a tty:

• the this is a link will be a clickable hyperlink (and the URL will be captured in SARIF output).

• the quoted text will be in bold

• the highlight A and highlight B text will be colorized

• the event ID will be colorized (and will be a URL in SARIF output if used within a diagnostic_execution_path).

Moving on

That’s the end of the tutorial. For more information on libgdiagnostics, see the topic guide.