/[ascend]/trunk/base/generic/utilities/error.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/error.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 222 - (show annotations) (download) (as text)
Fri Jan 27 04:23:20 2006 UTC (14 years, 10 months ago) by johnpye
File MIME type: text/x-chdr
File size: 7458 byte(s)
Updating for Jerry's new error_reporter syntax, bug #179
1 #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 this would gradually be expanded to including richer reporting
7 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 The first form allows you to use multiple FPRINTF statements to
20 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 #include "utilities/ascConfig.h"
38 #include "utilities/ascPrint.h"
39
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 /**
52 Variadic macros to allow nice succint logging and error reporting
53 calls from C dialects that support them (GCC, C99 and others)
54
55 If you don't support variadic macros, you will still get the messages
56 but without the file/function/line number.
57 */
58 #if defined(__GNUC__) && !defined(__STRICT_ANSI__)
59 # define ERROR_REPORTER_DEBUG(args...) error_reporter(ASC_PROG_NOTE, __FILE__, __LINE__, __func__, ##args)
60 # define ERROR_REPORTER_HERE(SEV,args...) error_reporter(SEV,__FILE__, __LINE__, __func__, ##args)
61 # define ERROR_REPORTER_NOLINE(SEV,args...) error_reporter(SEV, NULL, 0, NULL, ##args)
62 # define CONSOLE_DEBUG(args...) (fprintf(stderr,"\33[1m%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
63 fprintf(stderr, ##args) + \
64 fprintf(stderr, "\33[0m\n"))
65
66 #elif defined(HAVE_C99)
67 # define ERROR_REPORTER_DEBUG(...) error_reporter(ASC_PROG_NOTE,__FILE__,__LINE__,__func__,## __VA_ARGS__)
68 # define ERROR_REPORTER_HERE(SEV,...) error_reporter(SEV,__FILE__,__LINE__,__func__, ## __VA_ARGS__)
69 # define ERROR_REPORTER_NOLINE(SEV,...) error_reporter(SEV,NULL,0,NULL, ## __VA_ARGS__)
70 # define CONSOLE_DEBUG(...) (fprintf(stderr,"\33[1m%s:%d (%s): ", __FILE__,__LINE__,__func__) + \
71 fprintf(stderr, ##__VA_ARGS__) + \
72 fprintf(stderr, "\33[0m\n"))
73
74 #else
75 # define ERROR_REPORTER_DEBUG error_reporter_note_no_line
76 # define ERROR_REPORTER_HERE error_reporter_here
77 # define ERROR_REPORTER_NOLINE error_reporter_noline
78 # define CONSOLE_DEBUG console_debug
79 int error_reporter_note_no_line(const char *fmt,...);
80 int error_reporter_here(const error_severity_t sev, const char *fmt,...);
81 int error_reporter_noline(const error_severity_t sev, const char *fmt,...);
82 int console_debug(const char *fmt,...);
83 #endif
84
85 #define ERROR_REPORTER_START_NOLINE(SEV) error_reporter_start(SEV,NULL,0,NULL);
86 #define ERROR_REPORTER_START_HERE(SEV) error_reporter_start(SEV,__FILE__,__LINE__,__func__);
87
88 #define ERROR_REPORTER_STAT(sev,stat,msg) \
89 error_reporter(sev,Asc_ModuleFileName(stat->mod),stat->linenum,NULL,msg)
90
91 /**
92 Error severity codes. This will be used to visually
93 the seriousness of errors. ASC_PROG_ERRORs for example
94 might be red, or be highlighted with a (!) icon, etc.
95 */
96 typedef enum error_severity_enum{
97 ASC_USER_SUCCESS=0
98 ,ASC_USER_NOTE=1 /**< a note to the user */
99 ,ASC_USER_WARNING /**< the user has done something bad but tolerable */
100 ,ASC_USER_ERROR /**< the user has done something wrong */
101 ,ASC_PROG_NOTE /**< a note for the programmer */
102 ,ASC_PROG_WARNING /**< the program encounters an unexpected state */
103 ,ASC_PROG_ERROR /**< the program has failed but can ignore and continue (maybe) */
104 ,ASC_PROG_FATAL /**< fatal error, program will exit */
105 } error_severity_t;
106
107 /** An alias for ASC_PROG_ERROR */
108 #define ASC_PROG_ERR ASC_PROG_ERROR
109
110 #define ERROR_REPORTER_MAX_MSG 4096 /* no particular reason */
111
112 typedef struct{
113 unsigned char iscaching; /** set to true for fprintf_error_reporter to do its work */
114 error_severity_t sev;
115 const char *filename;
116 int line;
117 const char *func;
118 char msg[ERROR_REPORTER_MAX_MSG];
119 } error_reporter_meta_t;
120
121 /**
122 This is the drop-in replacement for Asc_FPrintf. Anythin you attempt
123 to print to stderr will be captured and passed to the error_reporter_callback
124 function for handling.
125 */
126 int fprintf_error_reporter(FILE *file, const char *fmt, ...);
127
128 /**
129 If file!=stderr, this will do the usual thing. If file==stderr, it will output
130 the character via fprintf_error_reporter.
131 */
132 int fputc_error_reporter(int c, FILE *file); /* just calls fprintf_error_reporter */
133
134 /**
135 This replaces the standard 'fflush' of Asc_FFlush. If file!=stderr, it will
136 call the standard fflush. If file==stderr, it will call error_reporter_end_flush.
137 */
138 int fflush_error_reporter(FILE *file);
139
140 /**
141 Start a cached error report. This means that multiple frprintf_error_reporter calls will
142 be stored in a global string until an error_reporter_end_flush is encountered.
143 */
144 int error_reporter_start(const error_severity_t sev, const char *filename, const int line, const char *func);
145
146 /**
147 Output the contents of the checked global string as an error report
148 */
149 int error_reporter_end_flush();
150
151 /**
152 This #define saves you typing the list of arguments in your
153 callback function declarations.
154 */
155 #define ERROR_REPORTER_CALLBACK_ARGS \
156 const error_severity_t sev \
157 , const char *filename \
158 , const int line \
159 , const char *funcname \
160 , const char *fmt \
161 , const va_list args
162
163 /*
164 In you have functions which pass-through callback parameters,
165 this #define ensures that if their ordering/naming changes,
166 you won't have to go hunting and change stuff.
167 */
168 #define ERROR_REPORTER_CALLBACK_VARS \
169 sev, filename, line, func, fmt, args
170
171 /*
172 Define the type of the function pointer to be used for all
173 error reporting functions. The final argument is a va_list.
174 You should use 'vsnprintf' of 'vfprintf' to output your
175 message to the desired file or string, see <stdio.h> for these.
176 */
177 typedef int (*error_reporter_callback_t)(
178 ERROR_REPORTER_CALLBACK_ARGS
179 );
180
181 /**
182 Use this function directly for 'richer' reporting of
183 of error messages.
184
185 @return follows the style of fprintf
186 */
187 int error_reporter(
188 const error_severity_t sev
189 , const char *errfile
190 , const int errline
191 , const char *errfunc
192 , const char *fmt
193 , ...
194 );
195
196 /**
197 This format of the error reporter is useful if you must call it
198 from another variable-argument-list function.
199 */
200 int va_error_reporter(ERROR_REPORTER_CALLBACK_ARGS);
201
202 /**
203 Set error reporting callback function using this
204 function. If left unset, errors will be printed
205 to standard error, which is effectively what the
206 hitherto FPRINTF has done.
207 */
208 void error_reporter_set_callback(
209 const error_reporter_callback_t new_callback
210 );
211
212 #endif /* ASC_ERROR_H */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22