# ccze-plugin - A robust log colorizer, plugin infrastructure - man(7) - [phpMan]

[_CCZE-PLUGIN_(7)](https://www.chedong.com/phpMan.php/man/CCZE-PLUGIN/7/markdown)                                  CCZE                                  [_CCZE-PLUGIN_(7)](https://www.chedong.com/phpMan.php/man/CCZE-PLUGIN/7/markdown)

## 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 vari‐
       ables, 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  par‐
       tially,  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  plu‐
       gin.

       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_ plu‐
       gin 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_plu‐_
       _gin_name_get_ returns the name of the current plugin, _ccze_plugin_argv_get_ returns a NULL-ter‐
       minated array, with each entry containing an argument.

## DISPLAY METHODS
       The so-called _display_ _methods_ are the **only **supported interface to emit something to the  dis‐
       play. These handle both the normal, ncurses-based, and the HTML output. This is a kind of ab‐
       straction 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 sup‐
       ported color tags) and a string, and displays it appropriately. The _ccze_space_ and  _ccze_new‐_
       _line_ 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 ap‐
       propriate  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)](https://www.chedong.com/phpMan.php/man/ccze/1/markdown)

## AUTHOR
       ccze was written by Gergely Nagy <<algernon@bonehunter.rulez.org>>, based on colorize by Istvan
       Karaszi <<colorize@spam.raszi.hu>>.

CCZE 0.2.1                                   2003-03-29                               [_CCZE-PLUGIN_(7)](https://www.chedong.com/phpMan.php/man/CCZE-PLUGIN/7/markdown)
