tools -- error handling and filename tools

General messages -- function message() is meant to format and print normal messages, for example to trace the program's normal processing. A message also specifies a level and the message is only printed, if its level is equal or lower than the current message verbosity level as set with setmsglevel(). Messages are printed to the stream as set with setmsgfile(), default it is stdout.

Debug messages -- function debug() is meant to format and print debug messages, for example to trace the program's data handling. A debug message also specifies a level and the message is only printed, if its level is equal or lower than the current debug message verbosity level as set with setdbglevel(). Messages are printed to the stream as set with setdbgfile(), default it is stdout.

Filenames -- parts of a filename path can be obtained with basename(), dirname() and extname(). Function exist() tells if the specified filename exists.

User interaction -- funtion prompt() lets you request a user to supply a non-empty string. With pick() you ask a user to accept or reject its argument. ttyin() reads a single character from the terminal.

Module tools is written by Martin J. Moene, Leiden University. It was inspired by the books:

The Unix Programming Environment
Brian W. Kernighan and Rob Pike.
Prentice Hall, Inc., 1984.
ISBN 0-13-937681-X (paperback), 0-13-937699-2 (hardback).

The Practice of Programming.
Brian W. Kernighan and Rob Pike.
Addison-Wesley, Reading, Massachusetts, 1999.
ISBN 0-201-61586-X.

Module tools is released into the public domain. You are free to use it in any way you like.

This software is provided "as is" with no expressed or implied warranty. I accept no liability for any damage or loss of business that this software may cause.


Defines
#define	SLASH '\\'
	filename separation slash
Enumerations
enum	{ E_OK, E_OPT, E_PS, E_INT, E_ITL }
	application return codes. More...
enum	{ MSG_L0, MSG_L1, MSG_L2 }
	application message level codes. More...
enum	{ DBG_L0, DBG_L1, DBG_L2 }
	application debug level codes. More...
Functions
const char *	getprogname ()
	return the program's name as set with setprogname().
void	setprogname (const char *name)
	set the program's name as used with error() etc.
int	getmsglevel ()
	get the current message verbosity level.
void	setmsglevel (int level)
	set the message verbosity level.
FILE *	getmsgfile ()
	get the current file messages will be written to.
void	setmsgfile (FILE *file)
	set the file to write messages to.
int	getdbglevel ()
	get the current debug message verbosity level.
void	setdbglevel (int level)
	set the debug message verbosity level.
FILE *	getdbgfile ()
	get the current file debug messages are written to.
void	setdbgfile (FILE *file)
	set the file to write the debug messages to.
int	error (int status, const char *format...)
	format and print error message, return status.
int	debug (int level, const char *format...)
	format and print debug message, if level permits.
int	message (int level, const char *format...)
	format and print message, if level permits.
const char *	dirname (const char *pathname)
	return directory part of pathname.
const char *	basename (const char *pathname)
	return filename without directory part and extension.
const char *	extname (const char *pathname)
	return extension of filename.
int	exist (const char *filename)
	tell if specified filename exists.
string	prompt (const char *ps)
	prompt for non-empty string input.
int	pick (int isInteractive, const char arg, const char set)
	select or skip argument.
int	ttyin ()
	read a character from the terminal.
Variables
char *	progname = NULL
	program name (default not set)
int	dbglevel = 0
	current debug message level
int	msglevel = 0
	current message level
FILE *	dbgfile = stdout
	file to write debug messages to
FILE *	msgfile = stdout
	file to write messages to

Enumeration Type Documentation

anonymous enum

Enumeration values:

E_OK	fine
E_OPT	commandline option/argument error
E_PS	processing error
E_INT	user interrupted program
E_ITL	internal/unrecognized error

anonymous enum

Enumeration values:

MSG_L0	level 0, defult on
MSG_L1	level 1
MSG_L2	level 2

anonymous enum

Enumeration values:

DBG_L0	level 0, default on
DBG_L1	level 1
DBG_L2	level 2

Function Documentation

const char* basename

(

const char *

pathname

)

basename() returns the filename part of the given path without the extension. The returned string does not contain a trailing slash.

If you specify a pathname of NULL, the program's path is used as set with setprogname().

Note:: basename() returns a static buffer, so you must use its contents before the next call to basename().

Parameters:

pathname

path or NULL

Returns:: string with basename

See also:: dirname(), extname()

Examples:: main-simple.cpp.

int debug	(	int	level,
		const char *	format...
	)

debug() formats and prints the message if the specified level is equal or less than the current debug level. format is a printf format string, optionally followed by arguments.

The message has the following format:

[progname: ]message[: system-message]\n

progname is included when a colon starts the format and it has been set via setprogname(); system-message is included when the format string ends with a colon (:).

debug() returns the specified level.

Parameters:

level	this message's level
format	a printf format string, optionally followed by arguments

Returns:: level

See also:: setprogname(), getdbglevel(), setdbglevel(), getdbgfile(), setdbgfile()

const char* dirname

(

const char *

pathname

)

dirname() returns the directory part of the given path. The returned string does not contain a trailing slash.

If you specify a pathname of NULL, the program's path is used as set with setprogname().

Note:: dirname() returns a static buffer, so you must use its contents before the next call to dirname().

Parameters:

pathname

path or NULL

Returns:: string with directory part

See also:: basename(), extname()

int error	(	int	status,
		const char *	format...
	)

error() formats and prints and error message. format is a printf format string, optionally followed by arguments.

The error message has the following format:

[progname: ]message[: system-message]\n

progname is included when it has been set via setprogname(); system-message is included when the format string ends with a colon (:).

error() returns the specified status.

Parameters:

status	the error status to return, see E_OK
format	a printf format string, optionally followed by arguments

Returns:: application exit status

See also:: setprogname()

Examples:: main-simple.cpp.

int exist

(

const char *

filename

)

exist() returns true if the specified filename is "-" (stdin) or exists as diskfile, exist() returns false otherwise.

Parameters:

filename

name of file to check for

Returns:: 1, 0 (exists, not exists)

See also:: prompt()

const char* extname

(

const char *

pathname

)

extname() returns the extension part of the given path without a dot.

If you specify a pathname of NULL, the program's path is used as set with setprogname().

Note:: extname() returns a static buffer, so you must use its contents before the next call to extname().

Parameters:

pathname

path or NULL

Returns:: string with extension

See also:: dirname(), basename()

FILE* getdbgfile

(

)

getdbgfile() returns the current file to write the debug messages to. Default it is stdout.

Returns:: current file to write debug messages to

See also:: getdbglevel(), setdbglevel(), getdbgfile(), debug()

int message	(	int	level,
		const char *	format...
	)

message() formats and print the specified message if its level is equal or less than the current verbosity level as set with setmsglevel(). format is a printf format string, optionally followed by arguments.

The message has the following format:

[progname: ]message[: system-message]\n

progname is included when a colon starts the format and it has been set via setprogname(); system-message is included when the format string ends with a colon (:).

message() returns the specified level.

Parameters:

level	this message's level
format	a printf format string, optionally followed by arguments

Returns:: level

See also:: setprogname(), getmsglevel(), setmsglevel(), getmsgfile(), setmsgfile()

int pick	(	int	isInteractive,
		const char *	arg,
		const char *	set
	)

If isInteractive is true, pick() writes its argument arg followed by a question mark to stderr and waits for a one-key response. If the response is a member of the supplied or default set, pick returns 1, for all other values, it returns 0.

If isInteractive is false, pick() returns true immediately, without prompting.

Parameters:

isInteractive	select interactively
arg	argument to use or skip
set	string with response characters to accept argument [yY]

Returns:: 0, 1 (skip, use)

See also:: prompt()

string prompt

(

const char *

)

prompt() issues the prompt ps and returns the user's response. prompt() skips leading whitespace and includes all input to the end of the line.

prompt() keeps prompting until a non-empty resonse is provided.

Parameters:

ps	prompt string

Returns:: response string

See also:: pick()

void setdbgfile

(

FILE *

file

)

setdbgfile() sets the file to write the debug messages to. Default it is stdout.

Parameters:

file

file to write debug messages to [stdout]

See also:: getdbglevel(), setdbglevel(), getdbgfile(), debug()

void setdbglevel

(

int

level

)

setdbglevel() sets the level for debug messages to be printed. Debug messages with a level equal or less than the current verbosity level as set with setdbglevel() will be printed. The debug level is default 0.

Parameters:

level

debug verbosity level to set [0]

See also:: getdbglevel(), getdbgfile(), setdbgfile(), debug()

void setmsgfile

(

FILE *

file

)

setmsgfile() sets the file to write the messages to. Default it is stdout.

Parameters:

file

file to write messages to [stdout]

See also:: setmsglevel(), getmsgfile(), getmsgfile(), message()

void setmsglevel

(

int

level

)

setmsglevel() sets the level for messages to be printed. Messages with a level equal or less than the current verbosity level as set with setmsglevel() will be printed. The message level is default 0.

Parameters:

level

verbosity level to set [0]

See also:: getmsglevel(), getmsgfile(), setmsgfile(), message()

int ttyin

(

)

ttyin() reads a single character from the terminal, echoes and returns it.

Returns:: character read

See also:: pick()

tools -- error handling and filename tools

Detailed Description

Defines

Enumerations

Functions

Variables

Enumeration Type Documentation

Function Documentation