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

Contents of /trunk/base/generic/utilities/ascPrint.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: 8174 byte(s)
Working on improving handling of paths.
1 #ifndef ASC_ASCPRINT_H
2 #define ASC_ASCPRINT_H
3 /*
4 * ASCEND Printf stdout/stderr Substitutes Dispatcher
5 * by Benjamin Allan
6 * Created: 4.March.2005
7 * Version: $Revision: 1.6 $
8 * Version control file: $RCSfile: ascPrint.h,v $
9 * Date last modified: $Date: 1997/10/29 13:08:50 $
10 * Last modified by: $Author: mthomas $
11 *
12 * This file is part of the ASCEND utilities.
13 *
14 * Copyright 2005, Benjamin Andrew Allan
15 *
16 * The ASCEND utilities is free software; you can redistribute
17 * it and/or modify it under the terms of the GNU General Public License as
18 * published by the Free Software Foundation; either version 2 of the
19 * License, or (at your option) any later version.
20 *
21 * The ASCEND utilities is distributed in hope that it will be
22 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24 * General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with the program; if not, write to the Free Software Foundation,
28 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
29 * COPYING. COPYING is found in ../compiler.
30 */
31
32 /** @file
33 * ASCEND Printf stdout/stderr substitutes dispatcher.
34 * These routines redirect output to stdout and stdin to other
35 * functions defined by the user. This is not required when you
36 * desire to send output to an available console, which is normally
37 * the case on Linux/unix. However, in cases where a console is
38 * not available (e.g. Win32 gui) or you prefer to redirect output
39 * for other reasons, these routines make it possible.<br><br>
40 */
41
42 #include <stdio.h>
43 #include <stdarg.h>
44
45 #include <utilities/ascConfig.h>
46
47 /**
48 * Output functions interceptor vtable. This should be constructed
49 * and the functions fully operational before it is
50 * pushed on the stack of output tables.
51 *
52 * This should be constructed and the functions fully operational
53 * before it is pushed on the stack of output tables.<br><br>
54 */
55 struct Asc_PrintVTable {
56 CONST char *name; /**< Vtable name. */
57 int (*print)(FILE *fp, CONST char *format, va_list args); /**< Print function. */
58 int (*fflush)(FILE *); /**< Flush function. */
59 struct Asc_PrintVTable *next; /**< Next vtable in linked list. */
60 };
61
62
63 extern int Asc_PrintPushVTable(struct Asc_PrintVTable *vtable);
64 /**<
65 * Adds a vtable to the ASCEND output interceptor list.
66 * Each registered vtable defines print and flush functions that are
67 * called by the internal ASCEND print functions to do the actual output.
68 * This function should be called after the user interface io channels
69 * have been initialized. Any calls to Asc_Printf() made prior to calling
70 * Asc_PrintAddVTable() will use ordinary printf().<br><br>
71 *
72 * More than one vtable can be pushed, in which case output will go to all
73 * the outputs setup in the reverse order in which tables were pushed.
74 * The vtable will be rejected if it or any field in it is null,
75 * other than next which must be null. It is advisable to use distinct
76 * names for all registered vtables so they may be uniquely identified in
77 * calls to Asc_PrintRemoveVTable(). This in not, however, enforced.<br><br>
78 *
79 * He who pushes a vtable should eventually remove it and destroy it.
80 *
81 * @param vtable The new vtable to add to the output interceptor list.
82 * @return Returns 1 if an error occurs, 0 otherwise.
83 */
84
85 extern struct Asc_PrintVTable *Asc_PrintRemoveVTable(CONST char *name);
86 /**<
87 * Removes a vtable from the printing list and returns it.
88 * The first vtable found with the specified name is the one removed.
89 * If name is NULL or not found in the list, NULL is returned.
90 *
91 * @param name The name of the vtable to remove from the printing list.
92 * @return Returns a pointer to the removed vtable if found, NULL otherwise.
93 */
94
95 extern int Asc_PrintHasVTable(CONST char *name);
96 /**<
97 * Queries whether a vtable is registered.
98 *
99 * @param name Pointer to a string containing the name of the vtable to find.
100 * @return Returns TRUE if a vtable with the specified name is registered,
101 * FALSE otherwise.
102 */
103
104 extern int Asc_Printf(CONST char *format, ...);
105 /**<
106 * Prints the specified variables to stdout using all registered print
107 * vtables. Using the sprintf-style format string `format', this
108 * function prints the `variable_number_args' to stdout using the print
109 * functions defined in the registered vtables. The same output is
110 * printed using all registered vtables. If no vtables are registered,
111 * nothing will be output. Returns the number of bytes printed from
112 * the final vtable that is called.<br><br>
113 *
114 * This is needed under Windows to redirect stdout to the TkConsole
115 * instead of into the bit bucket.
116 *
117 * @param format The sprintf-style format string to use to format the output.
118 * @param ... Variable number of arguments to print using the specified format.
119 * @return Returns the number of bytes printed from the final vtable called.
120 */
121
122 ASC_DLLSPEC(int) Asc_FPrintf(FILE *fileptr, CONST char *format, ...);
123 /**<
124 * Prints the specified variables to fileptr using all registered print
125 * vtables. Using the sprintf-style format string `format', this
126 * function prints the `variable_number_args' to the file handle
127 * 'fileptr' using the print functions defined in the registered vtables.
128 * The same output is printed using all registered vtables. If no vtables
129 * are registered, nothing will be output. Returns the number of bytes
130 * printed from the final vtable that is called.<br><br>
131 *
132 * This is needed under Windows to redirect stdout to the TkConsole
133 * instead of into the bit bucket.
134 *
135 * @param fileptr The file handle to receive the output.
136 * @param format The sprintf-style format string to use to format the output.
137 * @param ... Variable number of arguments to print using the specified format.
138 * @return Returns the number of bytes printed from the final vtable called.
139 */
140
141 extern int Asc_VFPrintf(FILE *fileptr, CONST char *format, va_list args);
142 /**<
143 Var-arg output function, required for calls passed through by error.h
144
145 Follows calling convention of vfprintf from <stdarg.h>, see K&R2, p 245.
146 */
147
148 extern int Asc_FFlush(FILE *fileptr);
149 /**<
150 * Flushes output to fileptr.
151 * This function loops over all registered print vtables, flushing
152 * output to the file pointed to by `fileptr'. If no vtables are
153 * registered, no streams will be flushed. Returns 0 for success
154 * and EOF for failure.<br><br>
155 *
156 * This is needed for consistency with Asc_FPrintf() and Asc_Printf().
157 *
158 * @param fileptr The file handle to flush output to.
159 * @return Returns 0 for success, EOF otherwise.
160 */
161
162 extern int Asc_FPutc(int c, FILE *fileptr);
163 /**<
164 * Prints c to the file stream pointed to by fileptr.
165 * If fileptr is 'stdout' or 'stderr', this function loops over
166 * all registered print vtables. For other file streams, the standard
167 * fputc() function is used. Returns non-zero for success and EOF for
168 * failure.<br><br>
169 *
170 * This is needed under Windows to redirect stdout and stderr to the
171 * TkConsole instead of into the bit bucket.
172 *
173 * @param c The character to print.
174 * @param fileptr The file handle to print c to.
175 * @return Returns non-zero for success, EOF otherwise.
176 */
177
178 extern int Asc_Putchar(int c);
179 /**<
180 * Prints c to stdout.
181 * This function loops over all registered print vtables.
182 * Returns 1 for success and EOF for failure.<br><br>
183 *
184 * This is needed under Windows to redirect stdout and stderr to the
185 * TkConsole instead of into the bit bucket.
186 *
187 * @param c The character to print.
188 * @return Returns 1 for success, EOF otherwise.
189 */
190
191 ASC_DLLSPEC(int) color_on(FILE *f, const char *colorcode);
192 ASC_DLLSPEC(int) color_off(FILE *f);
193
194 #endif /* _ASCPRINT_H */
195
196

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