generic/utilities/error.h

#ifndef ASC_ERROR_H
#define ASC_ERROR_H
/**
    This file provides error reporting to a callback function via
    ASCEND's FPRINTF(ASCERR,...) syntax. It is anticipated that
    this would gradually be expanded to including richer reporting
    of errors with severity and source file name and line numbers.

    Usage:
        error_reporter_start(<error-severity>,<filepath>,<linenumber>);
        FPRINTF(ASCERR,"half of ");
        FPRINTF(ASCERR,"your message");
        error_reporter_end_flush();

    or:
        error_reporter_start(<error-severity>,<filepath>,<linenumber>
                ,"format string %s %d etc",<printf-args>,...");

    The first form allows you to use multiple FPRINTF statements to
    generate your error message. The second form assumes that your
    entire message will be contained in a single statement.

    Error severities are
        ASC_(USER|PROG)_(NOTE|WARNING|ERROR)
    and ASC_USER_SUCCESS
*/

#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>

/**
    ascConfig defines ASC_FPRINTF etc, the routines to provide
    default 'real' printf behaviour on this platform. (As
    opposed to the sneaky stuff that FPRINTF does in this header)
*/
#include <utilities/ascConfig.h>
#include <utilities/ascPrint.h>

/**
    FPRINTF(ASCERR,...) messages will by default be treated
    by the error_reporter as ASC_PROG_NOTE messages. These will
    gradually need to be replaced with error_severity_t values
    that accurately reflect the nature of the error.
*/
#define FPRINTF fprintf_error_reporter
#define FPUTC fputc_error_reporter
#define PUTC fputc_error_reporter
#define FFLUSH fflush_error_reporter

/*
    By default, don't use coloured output on any terminals. We will reintroduce
    this later, hopefully. It should be done using CURSES, instead of directly
    using xterm codes. But that brings its own problems on MinGW and Windows...
*/

#ifdef USE_XTERM_COLOR_CODES
/** XTERM colour codes used to distinguish between errors of different types.

    @TODO some runtime testing to determine if these should be used or not
    depending on TERM env var.
*/
#  define ERR_RED "\033[31;1m"
#  define ERR_GRN "\033[32;2m"
#  define ERR_BLU "\033[34;1m"
#  define ERR_BRN "\033[33;1m"
#  define ERR_NORM "\033[0m"
#  define ERR_BOLD "\033[1m"
#else
#  define ERR_RED ""
#  define ERR_GRN ""
#  define ERR_BLU ""
#  define ERR_BRN ""
#  define ERR_NORM ""
#  define ERR_BOLD ""
#endif

/**
    Error severity codes. This will be used to visually
    the seriousness of errors. ASC_PROG_ERRORs for example
    might be red, or be highlighted with a (!) icon, etc.
*/
typedef enum error_severity_enum{
    ASC_USER_SUCCESS=0
   ,ASC_USER_NOTE=1    /**< a note to the user */
   ,ASC_USER_WARNING   /**< the user has done something bad but tolerable */
   ,ASC_USER_ERROR     /**< the user has done something wrong */
   ,ASC_PROG_NOTE      /**< a note for the programmer */
   ,ASC_PROG_WARNING   /**< the program encounters an unexpected state */
   ,ASC_PROG_ERROR     /**< the program has failed but can ignore and continue (maybe) */
   ,ASC_PROG_FATAL     /**< fatal error, program will exit */
} error_severity_t;


/**
    Variadic macros to allow nice succint logging and error reporting
    calls from C dialects that support them (GCC, C99 and others)

    If you don't support variadic macros, you will still get the messages
    but without the file/function/line number.
*/
#if defined(__GNUC__) && !defined(__STRICT_ANSI__)
# define ERROR_REPORTER_DEBUG(args...) error_reporter(ASC_PROG_NOTE, __FILE__, __LINE__, __func__, ##args)
# define ERROR_REPORTER_HERE(SEV,args...) error_reporter(SEV,__FILE__, __LINE__, __func__, ##args)
# define ERROR_REPORTER_NOLINE(SEV,args...) error_reporter(SEV, NULL, 0, NULL, ##args)
# define CONSOLE_DEBUG(args...) (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
                                 fprintf(stderr, ##args) + \
                                 fprintf(stderr, ERR_NORM "\n"))

# define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,__func__);

#elif defined(HAVE_C99)
# define ERROR_REPORTER_DEBUG(...) error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,__func__,## __VA_ARGS__)
# define ERROR_REPORTER_HERE(SEV,...) error_reporter(SEV,__FILE__,__LINE__,__func__, ## __VA_ARGS__)
# define ERROR_REPORTER_NOLINE(SEV,...) error_reporter(SEV,NULL,0,NULL, ## __VA_ARGS__)
# define CONSOLE_DEBUG(...) (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
                             fprintf(stderr, ##__VA_ARGS__) + \
                             fprintf(stderr, ERR_NORM "\n"))

#elif defined(_MSC_VER) && _MSC_VER >= 1310 /* Microsoft Visual C++ 2003 or newer */
#  define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,__FUNCTION__);
#  define ERROR_REPORTER_DEBUG(...)     error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,__FUNCTION__,## __VA_ARGS__)
#  define ERROR_REPORTER_HERE(SEV,...)  error_reporter(SEV,__FILE__,__LINE__,__FUNCTION__, ## __VA_ARGS__)
#  define ERROR_REPORTER_NOLINE(SEV,...) error_reporter(SEV,NULL,0,NULL, ## __VA_ARGS__)
#  define CONSOLE_DEBUG(...)   (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__FUNCTION__) + \
                                fprintf(stderr, ##__VA_ARGS__) + \
                                fprintf(stderr, ERR_NORM "\n"))

#else /* workaround for compilers without variadic macros: last resort */
# define NO_VARIADIC_MACROS
# define ERROR_REPORTER_DEBUG error_reporter_note_no_line
# define ERROR_REPORTER_HERE error_reporter_here
# define ERROR_REPORTER_NOLINE error_reporter_noline
# define CONSOLE_DEBUG console_debug
# define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,"[function?]");
int error_reporter_note_no_line(const char *fmt,...);
int error_reporter_here(const error_severity_t sev, const char *fmt,...);
int error_reporter_noline(const error_severity_t sev, const char *fmt,...);
int console_debug(const char *fmt,...);
#endif

#define ERROR_REPORTER_START_NOLINE(SEV) error_reporter_start(SEV,NULL,0,NULL);

#define ERROR_REPORTER_STAT(sev,stat,msg) \
    error_reporter(sev,Asc_ModuleFileName(stat->mod),stat->linenum,NULL,msg)

/** An alias for ASC_PROG_ERROR */
#define ASC_PROG_ERR ASC_PROG_ERROR

#define ERROR_REPORTER_MAX_MSG 4096 /* no particular reason */

typedef struct{
    unsigned char iscaching; /** set to true for fprintf_error_reporter to do its work */
    error_severity_t sev;
    const char *filename;
    int line;
    const char *func;
    char msg[ERROR_REPORTER_MAX_MSG];
} error_reporter_meta_t;

/**
    This is the drop-in replacement for Asc_FPrintf. Anythin you attempt
    to print to stderr will be captured and passed to the error_reporter_callback
    function for handling.
*/
int fprintf_error_reporter(FILE *file, const char *fmt, ...);

/**
    If file!=stderr, this will do the usual thing. If file==stderr, it will output
    the character via fprintf_error_reporter.
*/
int fputc_error_reporter(int c, FILE *file); /* just calls fprintf_error_reporter */

/**
    This replaces the standard 'fflush' of Asc_FFlush. If file!=stderr, it will
    call the standard fflush. If file==stderr, it will call error_reporter_end_flush.
*/
int fflush_error_reporter(FILE *file);

/**
    Start a cached error report. This means that multiple frprintf_error_reporter calls will
    be stored in a global string until an error_reporter_end_flush is encountered.
*/
int error_reporter_start(const error_severity_t sev, const char *filename, const int line, const char *func);

/**
    Output the contents of the checked global string as an error report
*/
int error_reporter_end_flush();

/**
    This #define saves you typing the list of arguments in your
    callback function declarations.
*/
#define ERROR_REPORTER_CALLBACK_ARGS \
    const error_severity_t sev \
  , const char *filename \
  , const int line \
  , const char *funcname \
  , const char *fmt \
  , const va_list args

/*
    In you have functions which pass-through callback parameters,
    this #define ensures that if their ordering/naming changes,
    you won't have to go hunting and change stuff.
*/
#define ERROR_REPORTER_CALLBACK_VARS \
    sev, filename, line, funcname, fmt, args

/*
    Define the type of the function pointer to be used for all
    error reporting functions. The final argument is a va_list.
    You should use 'vsnprintf' of 'vfprintf' to output your
    message to the desired file or string, see <stdio.h> for these.
*/
typedef int (*error_reporter_callback_t)(
    ERROR_REPORTER_CALLBACK_ARGS
);

typedef int (*ErrorReporter_fptr_t)(
      const error_severity_t sev
    , const char *errfile
    , const int errline
    , const char *errfunc
    , const char *fmt
    , ...
);

/**
    Use this function directly for 'richer' reporting of
    of error messages.

    @return follows the style of fprintf
*/
DLEXPORT int error_reporter(
      const error_severity_t sev
    , const char *errfile
    , const int errline
    , const char *errfunc
    , const char *fmt
    , ...
);

/**
    This format of the error reporter is useful if you must call it
    from another variable-argument-list function.
*/
int va_error_reporter(ERROR_REPORTER_CALLBACK_ARGS);

/**
    Set error reporting callback function using this
    function. If left unset, errors will be printed
    to standard error, which is effectively what the
    hitherto FPRINTF has done.
*/
void error_reporter_set_callback(
        const error_reporter_callback_t new_callback
);

#endif /* ASC_ERROR_H */
1	johnpye	62	#ifndef ASC_ERROR_H
2			#define ASC_ERROR_H
3			/**
4			This file provides error reporting to a callback function via
5			ASCEND's FPRINTF(ASCERR,...) syntax. It is anticipated that
6	johnpye	190	this would gradually be expanded to including richer reporting
7	johnpye	62	of errors with severity and source file name and line numbers.
8
9			Usage:
10			error_reporter_start(<error-severity>,<filepath>,<linenumber>);
11			FPRINTF(ASCERR,"half of ");
12			FPRINTF(ASCERR,"your message");
13			error_reporter_end_flush();
14
15			or:
16			error_reporter_start(<error-severity>,<filepath>,<linenumber>
17			,"format string %s %d etc",<printf-args>,...");
18
19	johnpye	190	The first form allows you to use multiple FPRINTF statements to
20	johnpye	62	generate your error message. The second form assumes that your
21			entire message will be contained in a single statement.
22
23			Error severities are
24			ASC_(USER\|PROG)_(NOTE\|WARNING\|ERROR)
25			and ASC_USER_SUCCESS
26			*/
27
28			#include <stdio.h>
29			#include <stdlib.h>
30			#include <stdarg.h>
31
32			/**
33			ascConfig defines ASC_FPRINTF etc, the routines to provide
34			default 'real' printf behaviour on this platform. (As
35			opposed to the sneaky stuff that FPRINTF does in this header)
36			*/
37	johnpye	399	#include <utilities/ascConfig.h>
38			#include <utilities/ascPrint.h>
39	johnpye	62
40			/**
41			FPRINTF(ASCERR,...) messages will by default be treated
42			by the error_reporter as ASC_PROG_NOTE messages. These will
43			gradually need to be replaced with error_severity_t values
44			that accurately reflect the nature of the error.
45			*/
46			#define FPRINTF fprintf_error_reporter
47			#define FPUTC fputc_error_reporter
48			#define PUTC fputc_error_reporter
49			#define FFLUSH fflush_error_reporter
50
51	johnpye	377	/*
52			By default, don't use coloured output on any terminals. We will reintroduce
53			this later, hopefully. It should be done using CURSES, instead of directly
54			using xterm codes. But that brings its own problems on MinGW and Windows...
55			*/
56
57			#ifdef USE_XTERM_COLOR_CODES
58			/** XTERM colour codes used to distinguish between errors of different types.
59
60			@TODO some runtime testing to determine if these should be used or not
61			depending on TERM env var.
62			*/
63			# define ERR_RED "\033[31;1m"
64			# define ERR_GRN "\033[32;2m"
65			# define ERR_BLU "\033[34;1m"
66			# define ERR_BRN "\033[33;1m"
67			# define ERR_NORM "\033[0m"
68			# define ERR_BOLD "\033[1m"
69			#else
70			# define ERR_RED ""
71			# define ERR_GRN ""
72			# define ERR_BLU ""
73			# define ERR_BRN ""
74			# define ERR_NORM ""
75			# define ERR_BOLD ""
76			#endif
77	johnpye	414
78	johnpye	62	/**
79	johnpye	414	Error severity codes. This will be used to visually
80			the seriousness of errors. ASC_PROG_ERRORs for example
81			might be red, or be highlighted with a (!) icon, etc.
82			*/
83			typedef enum error_severity_enum{
84			ASC_USER_SUCCESS=0
85			,ASC_USER_NOTE=1 /*< a note to the user /
86			,ASC_USER_WARNING /*< the user has done something bad but tolerable /
87			,ASC_USER_ERROR /*< the user has done something wrong /
88			,ASC_PROG_NOTE /*< a note for the programmer /
89			,ASC_PROG_WARNING /*< the program encounters an unexpected state /
90			,ASC_PROG_ERROR /*< the program has failed but can ignore and continue (maybe) /
91			,ASC_PROG_FATAL /*< fatal error, program will exit /
92			} error_severity_t;
93
94
95			/**
96	johnpye	195	Variadic macros to allow nice succint logging and error reporting
97			calls from C dialects that support them (GCC, C99 and others)
98
99			If you don't support variadic macros, you will still get the messages
100			but without the file/function/line number.
101	johnpye	62	*/
102	johnpye	153	#if defined(__GNUC__) && !defined(__STRICT_ANSI__)
103	johnpye	222	# define ERROR_REPORTER_DEBUG(args...) error_reporter(ASC_PROG_NOTE, __FILE__, __LINE__, __func__, ##args)
104			# define ERROR_REPORTER_HERE(SEV,args...) error_reporter(SEV,__FILE__, __LINE__, __func__, ##args)
105			# define ERROR_REPORTER_NOLINE(SEV,args...) error_reporter(SEV, NULL, 0, NULL, ##args)
106	johnpye	377	# define CONSOLE_DEBUG(args...) (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
107	johnpye	222	fprintf(stderr, ##args) + \
108	johnpye	377	fprintf(stderr, ERR_NORM "\n"))
109	johnpye	190
110	johnpye	414	# define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,__func__);
111
112	johnpye	124	#elif defined(HAVE_C99)
113	johnpye	222	# define ERROR_REPORTER_DEBUG(...) error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,__func__,## __VA_ARGS__)
114			# define ERROR_REPORTER_HERE(SEV,...) error_reporter(SEV,__FILE__,__LINE__,__func__, ## __VA_ARGS__)
115			# define ERROR_REPORTER_NOLINE(SEV,...) error_reporter(SEV,NULL,0,NULL, ## __VA_ARGS__)
116	johnpye	377	# define CONSOLE_DEBUG(...) (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
117	johnpye	222	fprintf(stderr, ##__VA_ARGS__) + \
118	johnpye	377	fprintf(stderr, ERR_NORM "\n"))
119	johnpye	190
120	johnpye	427	#elif defined(_MSC_VER) && _MSC_VER >= 1310 /* Microsoft Visual C++ 2003 or newer */
121	wangym	456	# define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,__FUNCTION__);
122			# define ERROR_REPORTER_DEBUG(...) error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,__FUNCTION__,## __VA_ARGS__)
123			# define ERROR_REPORTER_HERE(SEV,...) error_reporter(SEV,__FILE__,__LINE__,__FUNCTION__, ## __VA_ARGS__)
124			# define ERROR_REPORTER_NOLINE(SEV,...) error_reporter(SEV,NULL,0,NULL, ## __VA_ARGS__)
125			# define CONSOLE_DEBUG(...) (fprintf(stderr, ERR_BOLD "%s:%d (%s): ", __FILE__,__LINE__,__FUNCTION__) + \
126			fprintf(stderr, ##__VA_ARGS__) + \
127			fprintf(stderr, ERR_NORM "\n"))
128	johnpye	427
129			#else /* workaround for compilers without variadic macros: last resort */
130			# define NO_VARIADIC_MACROS
131	johnpye	62	# define ERROR_REPORTER_DEBUG error_reporter_note_no_line
132	johnpye	188	# define ERROR_REPORTER_HERE error_reporter_here
133	johnpye	190	# define ERROR_REPORTER_NOLINE error_reporter_noline
134	johnpye	86	# define CONSOLE_DEBUG console_debug
135	johnpye	427	# define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,"[function?]");
136	johnpye	62	int error_reporter_note_no_line(const char *fmt,...);
137	johnpye	188	int error_reporter_here(const error_severity_t sev, const char *fmt,...);
138	johnpye	190	int error_reporter_noline(const error_severity_t sev, const char *fmt,...);
139	johnpye	85	int console_debug(const char *fmt,...);
140	johnpye	62	#endif
141
142	johnpye	222	#define ERROR_REPORTER_START_NOLINE(SEV) error_reporter_start(SEV,NULL,0,NULL);
143
144	johnpye	124	#define ERROR_REPORTER_STAT(sev,stat,msg) \
145	johnpye	222	error_reporter(sev,Asc_ModuleFileName(stat->mod),stat->linenum,NULL,msg)
146	johnpye	124
147	johnpye	82	/** An alias for ASC_PROG_ERROR */
148	johnpye	76	#define ASC_PROG_ERR ASC_PROG_ERROR
149
150	johnpye	62	#define ERROR_REPORTER_MAX_MSG 4096 /* no particular reason */
151
152			typedef struct{
153			unsigned char iscaching; /** set to true for fprintf_error_reporter to do its work */
154			error_severity_t sev;
155			const char *filename;
156			int line;
157	johnpye	222	const char *func;
158	johnpye	62	char msg[ERROR_REPORTER_MAX_MSG];
159			} error_reporter_meta_t;
160
161			/**
162			This is the drop-in replacement for Asc_FPrintf. Anythin you attempt
163			to print to stderr will be captured and passed to the error_reporter_callback
164			function for handling.
165			*/
166			int fprintf_error_reporter(FILE file, const char fmt, ...);
167
168			/**
169			If file!=stderr, this will do the usual thing. If file==stderr, it will output
170			the character via fprintf_error_reporter.
171			*/
172			int fputc_error_reporter(int c, FILE file); / just calls fprintf_error_reporter */
173
174			/**
175			This replaces the standard 'fflush' of Asc_FFlush. If file!=stderr, it will
176			call the standard fflush. If file==stderr, it will call error_reporter_end_flush.
177			*/
178			int fflush_error_reporter(FILE *file);
179
180			/**
181			Start a cached error report. This means that multiple frprintf_error_reporter calls will
182			be stored in a global string until an error_reporter_end_flush is encountered.
183			*/
184	johnpye	222	int error_reporter_start(const error_severity_t sev, const char filename, const int line, const char func);
185	johnpye	62
186			/**
187			Output the contents of the checked global string as an error report
188			*/
189			int error_reporter_end_flush();
190
191			/**
192			This #define saves you typing the list of arguments in your
193			callback function declarations.
194			*/
195			#define ERROR_REPORTER_CALLBACK_ARGS \
196	johnpye	222	const error_severity_t sev \
197			, const char *filename \
198			, const int line \
199			, const char *funcname \
200			, const char *fmt \
201			, const va_list args
202	johnpye	62
203			/*
204			In you have functions which pass-through callback parameters,
205			this #define ensures that if their ordering/naming changes,
206			you won't have to go hunting and change stuff.
207			*/
208			#define ERROR_REPORTER_CALLBACK_VARS \
209	johnpye	224	sev, filename, line, funcname, fmt, args
210	johnpye	62
211			/*
212	johnpye	190	Define the type of the function pointer to be used for all
213	johnpye	62	error reporting functions. The final argument is a va_list.
214			You should use 'vsnprintf' of 'vfprintf' to output your
215			message to the desired file or string, see <stdio.h> for these.
216			*/
217			typedef int (*error_reporter_callback_t)(
218			ERROR_REPORTER_CALLBACK_ARGS
219			);
220
221	johnpye	380	typedef int (*ErrorReporter_fptr_t)(
222			const error_severity_t sev
223			, const char *errfile
224			, const int errline
225			, const char *errfunc
226			, const char *fmt
227			, ...
228			);
229
230	johnpye	62	/**
231	johnpye	190	Use this function directly for 'richer' reporting of
232	johnpye	62	of error messages.
233
234			@return follows the style of fprintf
235			*/
236	johnpye	369	DLEXPORT int error_reporter(
237	johnpye	222	const error_severity_t sev
238			, const char *errfile
239			, const int errline
240			, const char *errfunc
241			, const char *fmt
242			, ...
243	johnpye	62	);
244
245			/**
246			This format of the error reporter is useful if you must call it
247			from another variable-argument-list function.
248			*/
249			int va_error_reporter(ERROR_REPORTER_CALLBACK_ARGS);
250
251			/**
252			Set error reporting callback function using this
253			function. If left unset, errors will be printed
254			to standard error, which is effectively what the
255			hitherto FPRINTF has done.
256			*/
257			void error_reporter_set_callback(
258			const error_reporter_callback_t new_callback
259			);
260
261			#endif /* ASC_ERROR_H */