faux/lub/dump.h

/*
 * dump.h
 */
/**
\ingroup lub
\defgroup lub_dump dump
@{

\brief This utility provides a simple hierachical debugging mechanism.

By indenting and undenting the output, printing nested debug messages is made
easy.
*/
#ifndef _lub_dump_h
#define _lub_dump_h

#include <stdarg.h>
/*=====================================
 * DUMP INTERFACE
 *===================================== */
/**
 * This operation behaves identically to the standard printf() function
 * with the exception that the offset at the begining of the line is 
 * determined by the current indent settings.
 * \pre 
 * - none
 *
 * \return
 * The number of characters sent to stdout.
 *
 * \post
 * - The formatted message will be sent to stdout.
 */
 /*lint -esym(534,lub_dump_printf) Ignoring return value of function */
int lub_dump_printf(
	    /**
             * printf-like format string
             */
			   const char *fmt, ...
    );
/**
 * This operation indicates that the offset for messages should be increased by
 * one level.
 *
 * \pre 
 * - none
 *
 * \post
 * - An indentation divider will be sent to stdout to emphasise the change
 *   in offset.
 * - Subsequent calls to lub_dump_printf() will output at this new offset.
 * - Client may call lub_undent() to restore offset.
 */
void lub_dump_indent(void);
/**
 * This operation indicates that the offset for messages should be decreased by
 * one level.
 *
 * \pre 
 * - lub_dump_indent() should have been called at least one more time than
 *   this function.
 *
 * \post
 * - An indentation divider will be sent to stdout to emphasise the change
 *   in offset.
 * - Subsequent calls to lub_dump_printf() will output at this new offset.
 */
void lub_dump_undent(void);

#endif				/* _lub_dump_h */
/** @} lub_dump */