1 /*=========================================================================
3 Program: Visualization Toolkit
4 Module: vtkParsePreprocess.h
6 Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
8 See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
10 This software is distributed WITHOUT ANY WARRANTY; without even
11 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12 PURPOSE. See the above copyright notice for more information.
14 =========================================================================*/
15 /*-------------------------------------------------------------------------
16 Copyright (c) 2010 David Gobbi.
18 Contributed to the VisualizationToolkit by the author in June 2010
19 under the terms of the Visualization Toolkit 2008 copyright.
20 -------------------------------------------------------------------------*/
23 This file provides subroutines to assist in preprocessing
24 C/C++ header files. It evaluates preprocessor directives
25 and stores a list of all preprocessor macros.
27 The preprocessing is done in-line while the file is being
28 parsed. Macros that are defined in the file are stored but
29 are not automatically expanded. The parser can query the
30 macro definitions, expand them into plain text, or ask the
31 preprocessor to evaluate them and return an integer result.
33 The typical usage of this preprocessor is that the main
34 parser will pass any lines that begin with '#' to the
35 vtkParsePreprocess_HandleDirective() function, which will
36 evaluate the line and provide a return code. The return
37 code will tell the main parser if a syntax error or macro
38 lookup error occurred, and will also let the parser know
39 if an #if or #else directive requires that the next block
43 #ifndef VTK_PARSE_PREPROCESS_H
44 #define VTK_PARSE_PREPROCESS_H
46 #include "vtkParseString.h"
49 * The preprocessor int type. Use the compiler's longest int type.
51 #if defined(_WIN32) && !defined(__MINGW32__) && !defined(__CYGWIN__)
52 typedef __int64 preproc_int_t;
53 typedef unsigned __int64 preproc_uint_t;
55 typedef long long preproc_int_t;
56 typedef unsigned long long preproc_uint_t;
60 * Struct to describe a preprocessor symbol.
62 typedef struct _MacroInfo
65 const char *Definition;
66 const char *Comment; /* unused */
67 int NumberOfParameters; /* only if IsFunction == 1 */
68 const char **Parameters; /* symbols for parameters */
69 int IsFunction; /* this macro requires arguments */
70 int IsVariadic; /* this macro can take unlimited arguments */
71 int IsExternal; /* this macro is from an included file */
72 int IsExcluded; /* do not expand this macro */
76 * Contains all symbols defined thus far (including those defined
77 * in any included header files).
79 typedef struct _PreprocessInfo
81 const char *FileName; /* the file that is being parsed */
82 MacroInfo ***MacroHashTable; /* hash table for macro lookup */
83 int NumberOfIncludeDirectories;
84 const char **IncludeDirectories;
85 int NumberOfIncludeFiles; /* all included files */
86 const char **IncludeFiles;
87 StringCache *Strings; /* to aid string allocation */
88 int IsExternal; /* label all macros as "external" */
89 int ConditionalDepth; /* internal state variable */
90 int ConditionalDone; /* internal state variable */
94 * Platforms. Always choose native unless crosscompiling.
96 enum _preproc_platform_t {
101 * Directive return values.
103 enum _preproc_return_t {
105 VTK_PARSE_SKIP = 1, /* skip next block */
106 VTK_PARSE_PREPROC_DOUBLE = 2, /* encountered a double */
107 VTK_PARSE_PREPROC_FLOAT = 3, /* encountered a float */
108 VTK_PARSE_PREPROC_STRING = 4, /* encountered a string */
109 VTK_PARSE_MACRO_UNDEFINED = 5, /* macro lookup failed */
110 VTK_PARSE_MACRO_REDEFINED = 6, /* attempt to redefine a macro */
111 VTK_PARSE_FILE_NOT_FOUND = 7, /* include file not found */
112 VTK_PARSE_FILE_OPEN_ERROR = 8, /* include file not readable */
113 VTK_PARSE_FILE_READ_ERROR = 9, /* error during read */
114 VTK_PARSE_MACRO_NUMARGS = 10, /* wrong number of args to func macro */
115 VTK_PARSE_SYNTAX_ERROR = 11 /* any and all syntax errors */
119 * Bitfield for fatal errors.
121 #define VTK_PARSE_FATAL_ERROR 0xF8
128 * Handle a preprocessor directive. Return value VTK_PARSE_OK
129 * means that no errors occurred, while VTK_PARSE_SKIP means that
130 * a conditional directive was encountered and the next code
131 * block should be skipped. The preprocessor has an internal state
132 * machine that keeps track of conditional if/else/endif directives.
133 * All other return values indicate errors, and it is up to the
134 * parser to decide which errors are fatal. The preprocessor
135 * only considers syntax errors and I/O errors to be fatal.
137 int vtkParsePreprocess_HandleDirective(
138 PreprocessInfo *info, const char *directive);
141 * Evaluate a preprocessor expression, providing an integer result
142 * in "val", and whether it is unsigned in "is_unsigned". A return
143 * value of VTK_PARSE_OK means that no errors occurred, while
144 * VTK_PREPROC_DOUBLE, VTK_PREPROC_FLOAT, and VTK_PREPROC_STRING
145 * indicate that the preprocessor encountered a non-integer value.
146 * Error return values are VTK_PARSE_MACRO_UNDEFINED and
147 * VTK_PARSE_SYNTAX_ERRORS. Undefined macros evaluate to zero.
149 int vtkParsePreprocess_EvaluateExpression(
150 PreprocessInfo *info, const char *text,
151 preproc_int_t *val, int *is_unsigned);
154 * Add all standard preprocessor symbols. Use VTK_PARSE_NATIVE
155 * as the platform. In the future, other platform specifiers
156 * might be added to allow crosscompiling.
158 void vtkParsePreprocess_AddStandardMacros(
159 PreprocessInfo *info, int platform);
162 * Add a preprocessor symbol, including a definition. Return
163 * values are VTK_PARSE_OK and VTK_PARSE_MACRO_REDEFINED.
165 int vtkParsePreprocess_AddMacro(
166 PreprocessInfo *info, const char *name, const char *definition);
169 * Remove a preprocessor symbol. Return values are VTK_PARSE_OK
170 * and VTK_PARSE_MACRO_UNDEFINED.
172 int vtkParsePreprocess_RemoveMacro(
173 PreprocessInfo *info, const char *name);
176 * Return a preprocessor symbol struct, or NULL if not found.
178 MacroInfo *vtkParsePreprocess_GetMacro(
179 PreprocessInfo *info, const char *name);
182 * Expand a macro. A function macro must be given an argstring
183 * with args in parentheses, otherwise the argstring can be NULL.
184 * returns NULL if the wrong number of arguments were given.
186 const char *vtkParsePreprocess_ExpandMacro(
187 PreprocessInfo *info, MacroInfo *macro, const char *argstring);
190 * Free an expanded macro
192 void vtkParsePreprocess_FreeMacroExpansion(
193 PreprocessInfo *info, MacroInfo *macro, const char *text);
196 * Fully process a string with the preprocessor, and
197 * return a new string or NULL if a fatal error occurred.
199 const char *vtkParsePreprocess_ProcessString(
200 PreprocessInfo *info, const char *text);
203 * Free a processed string. Only call this method if
204 * the string returned by ProcessString is different from
205 * the original string, because ProcessString will just
206 * return the original string if no processing was needed.
208 void vtkParsePreprocess_FreeProcessedString(
209 PreprocessInfo *info, const char *text);
212 * Add an include directory. The directories that were added
213 * first will be searched first.
215 void vtkParsePreprocess_IncludeDirectory(
216 PreprocessInfo *info, const char *name);
219 * Find an include file in the path. If system_first is set, then
220 * the current directory is ignored unless it is explicitly in the
221 * path. A null return value indicates that the file was not found.
222 * If already_loaded is set, then the file was already loaded. This
223 * preprocessor never loads the same file twice.
225 const char *vtkParsePreprocess_FindIncludeFile(
226 PreprocessInfo *info, const char *filename, int system_first,
227 int *already_loaded);
230 * Initialize a preprocessor symbol struct.
232 void vtkParsePreprocess_InitMacro(MacroInfo *symbol);
235 * Free a preprocessor macro struct
237 void vtkParsePreprocess_FreeMacro(MacroInfo *macro);
240 * Initialize a preprocessor struct.
242 void vtkParsePreprocess_Init(
243 PreprocessInfo *info, const char *filename);
246 * Free a preprocessor struct and its contents;
248 void vtkParsePreprocess_Free(PreprocessInfo *info);