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>.