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

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