NAME¶
ccze - A robust log colorizer, plugin infrastructure
SYNOPSIS¶
#include <ccze.h>
/* Plugin support */
typedef void (*ccze_plugin_startup_t) (void);
typedef void (*ccze_plugin_shutdown_t) (void);
typedef int (*ccze_plugin_handle_t) (const char
*str, size_t length, char
**rest);
CCZE_DEFINE_PLUGIN (name, type,
desc);
CCZE_DEFINE_PLUGINS (plugins...);
/* Display */
void ccze_addstr (ccze_color_t col, const char
*str);
void ccze_newline (void);
void ccze_space (void);
void ccze_wordcolor_process_one (char *word, int
slookup);
/* Helpers */
ccze_color_t ccze_http_action (const char *method);
void ccze_print_date (const char *date);
/* Command line */
char **ccze_plugin_argv_get (const char *name);
const char *ccze_plugin_name_get (void);
DESCRIPTION¶
This manual page attempts to outline the internals of CCZE plugins: how they
work, how they are implemented, and how to add new ones.
There are four required entry points in a plugin: a
startup, a
shutdown and a
handler routine (more on these later), and an
informational structure.
The
startup function must be of type
ccze_plugin_startup_t. This
is called right after the module is loaded. Its purpose is to initialise all
kinds of module-specific global variables, such as the regular expressions.
The
shutdown function is its counterpart: this is used to deallocate any
memory reserved by the
startup code.
The core part of a plugin is the
handler, of type
ccze_plugin_handle_t. This does the actual coloring. The string to
process is passed in the
str argument, its length in
length. The
third argument,
rest is a pointer to a string. Unlike the first two,
this argument is used only for output.
When a handler processed a string, it must return a non-zero value, in case it
could not process it, the handler must return with zero. If the string could
be processed only partially, the part which was deemed unknown by the handler
must be passed back in the
rest variable.
The fourth part, although the smallest part, is the most important. Without
this, the module is useless, it cannot be loaded. This part tells CCZE what
the
startup,
shutdown and
handler functions are called.
To encourage good style, the little details of this structure will not be
disclosed in this manual page. Instead, the helper macro,
CCZE_DEFINE_PLUGIN will be explained.
CCZE_DEFINE_PLUGIN is the macro to use if one wants to make the plugin
loadable. Its first argument is an unquoted string: the name of the plugin.
The second part is the type of the plugin, it can be
FULL,
PARTIAL or
ANY. The last argument is a short description of the
plugin.
It is assumed that the three functions mentioned earlier are called
ccze_name_setup,
ccze_name_shutdown
and
ccze_name_handle, respectively.
A
FULL plugin is one that accepts raw input, untouched by any other
plugin before, and processes it. On the other hand, a
PARTIAL plugin
relies on previous ones preprocessing the input. For example,
syslog is
a full plugin, on which
ulogd, a partial plugin relies. The
syslog plugin processes the raw input from the logfile, adds colour to
most of it, save the actual message sent by a process, that is left to
subsequent plugins, like
ulogd. An
ANY plugin is one can act as
both other types.
With
CCZE_DEFINE_PLUGINS one can place more than one plugin into one
shared object.
There are two other helper functions,
ccze_plugin_argv_get and
ccze_plugin_name_get. One can pass arguments to CCZE plugins, and these
is the function to retrieve them. While
ccze_plugin_name_get returns
the name of the current plugin,
ccze_plugin_argv_get returns a
NULL-terminated array, with each entry containing an argument.
DISPLAY METHODS¶
The so-called
display methods are the
only supported interface to
emit something to the display. These handle both the normal, ncurses-based,
and the HTML output. This is a kind of abstraction so plugins will not have to
worry about the differences between the output formats.
The most important one is
ccze_addstr, which takes a color (see
ccze.h for a list of supported color tags) and a string, and displays
it appropriately. The
ccze_space and
ccze_newline functions emit
a space and a newline, respectively.
Our last function,
ccze_wordcolor_process_one passes
word to the
word colourising engine. If the second argument,
slookup is non-zero,
the engine will perform service lookups (like
getent and friends).
HELPER METHODS¶
We only have two helper methods:
ccze_print_date, which simply prints out
the date in the appropriate colour, and
ccze_http_action, which given a
HTTP
method, returns the associated colour, in a format suitable for
ccze_addstr.
EXAMPLE¶
#include <ccze.h>
#include <stddef.h>
#include <string.h>
static char **ccze_foo_argv;
static int
ccze_foo_handle (const char *str, size_t length, char **rest)
{
int i = 1;
if (strstr (str, "foo"))
{
ccze_addstr (CCZE_COLOR_GOODWORD, str);
return 1;
}
while (ccze_foo_argv[i])
{
if (strstr (str, ccze_foo_argv[i]))
{
ccze_addstr (CCZE_COLOR_GOODWORD, str);
return 1;
}
i++;
}
return 0;
}
static void
ccze_foo_startup (void)
{
ccze_foo_argv = ccze_plugin_argv_get (ccze_plugin_name_get ());
}
static void
ccze_foo_shutdown (void)
{
}
CCZE_DEFINE_PLUGIN (foo, PARTIAL, "Partial FOO coloriser.");
SEE ALSO¶
ccze(1)
AUTHOR¶
ccze was written by Gergely Nagy <algernon@bonehunter.rulez.org>, based on
colorize by Istvan Karaszi <colorize@spam.raszi.hu>.