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
42 No checks are done for recursively-defined macros. If they
43 occur, the preprocessor will crash.
46 #ifndef VTK_PARSE_PREPROCESS_H
47 #define VTK_PARSE_PREPROCESS_H
50 * The preprocessor int type. Use the compiler's longest int type.
52 #if defined(_WIN32) && !defined(__MINGW32__) && !defined(__CYGWIN__)
53 typedef __int64 preproc_int_t;
54 typedef unsigned __int64 preproc_uint_t;
56 typedef long long preproc_int_t;
57 typedef unsigned long long preproc_uint_t;
61 * Struct to describe a preprocessor symbol.
63 typedef struct _MacroInfo
66 const char *Definition;
67 const char *Comment; /* unused */
68 int NumberOfArguments; /* only if IsFunction == 1 */
69 const char **Arguments; /* symbols for arguments */
70 int IsFunction; /* this macro takes arguments */
71 int IsExternal; /* this macro is from an included file */
75 * Contains all symbols defined thus far (including those defined
76 * in any included header files).
78 typedef struct _PreprocessInfo
80 const char *FileName; /* the file that is being parsed */
83 int NumberOfIncludeDirectories;
84 const char **IncludeDirectories;
85 int NumberOfIncludeFiles; /* all included files */
86 const char **IncludeFiles;
87 int IsExternal; /* label all macros as "external" */
88 int ConditionalDepth; /* internal state variable */
89 int ConditionalDone; /* internal state variable */
93 * Platforms. Always choose native unless crosscompiling.
95 enum _preproc_platform_t {
100 * Directive return values.
102 enum _preproc_return_t {
104 VTK_PARSE_SKIP = 1, /* skip next block */
105 VTK_PARSE_PREPROC_DOUBLE = 2, /* encountered a double */
106 VTK_PARSE_PREPROC_FLOAT = 3, /* encountered a float */
107 VTK_PARSE_PREPROC_STRING = 4, /* encountered a string */
108 VTK_PARSE_MACRO_UNDEFINED = 5, /* macro lookup failed */
109 VTK_PARSE_MACRO_REDEFINED = 6, /* attempt to redefine a macro */
110 VTK_PARSE_FILE_NOT_FOUND = 7, /* include file not found */
111 VTK_PARSE_FILE_OPEN_ERROR = 8, /* include file not readable */
112 VTK_PARSE_FILE_READ_ERROR = 9, /* error during read */
113 VTK_PARSE_MACRO_NUMARGS = 10, /* wrong number of args to func macro */
114 VTK_PARSE_SYNTAX_ERROR = 11 /* any and all syntax errors */
118 * Bitfield for fatal errors.
120 #define VTK_PARSE_FATAL_ERROR 0xF8
127 * Handle a preprocessor directive. Return value VTK_PARSE_OK
128 * means that no errors occurred, while VTK_PARSE_SKIP means that
129 * a conditional directive was encountered and the next code
130 * block should be skipped. The preprocessor has an internal state
131 * machine that keeps track of conditional if/else/endif directives.
132 * All other return values indicate errors, and it is up to the
133 * parser to decide which errors are fatal. The preprocessor
134 * only considers syntax errors and I/O errors to be fatal.
136 int vtkParsePreprocess_HandleDirective(
137 PreprocessInfo *info, const char *directive);
140 * Evaluate a preprocessor expression, providing an integer result
141 * in "val", and whether it is unsigned in "is_unsigned". A return
142 * value of VTK_PARSE_OK means that no errors occurred, while
143 * VTK_PREPROC_DOUBLE, VTK_PREPROC_FLOAT, and VTK_PREPROC_STRING
144 * indicate that the preprocessor encountered a non-integer value.
145 * Error return values are VTK_PARSE_MACRO_UNDEFINED and
146 * VTK_PARSE_SYNTAX_ERRORS. Undefined macros evaluate to zero.
148 int vtkParsePreprocess_EvaluateExpression(
149 PreprocessInfo *info, const char *text,
150 preproc_int_t *val, int *is_unsigned);
153 * Add all standard preprocessor symbols. Use VTK_PARSE_NATIVE
154 * as the platform. In the future, other platform specifiers
155 * might be added to allow crosscompiling.
157 void vtkParsePreprocess_AddStandardMacros(
158 PreprocessInfo *info, int platform);
161 * Add a preprocessor symbol, including a definition. Return
162 * values are VTK_PARSE_OK and VTK_PARSE_MACRO_REDEFINED.
164 int vtkParsePreprocess_AddMacro(
165 PreprocessInfo *info, const char *name, const char *definition);
168 * Remove a preprocessor symbol. Return values are VTK_PARSE_OK
169 * and VTK_PARSE_MACRO_UNDEFINED.
171 int vtkParsePreprocess_RemoveMacro(
172 PreprocessInfo *info, const char *name);
175 * Return a preprocessor symbol struct, or NULL if not found.
177 MacroInfo *vtkParsePreprocess_GetMacro(
178 PreprocessInfo *info, const char *name);
181 * Expand a function macro, given arguments in parentheses.
182 * Returns a new string that was allocated with malloc, or
183 * NULL if the wrong number of arguments were given.
185 const char *vtkParsePreprocess_ExpandMacro(
186 MacroInfo *macro, const char *argstring);
189 * Free an expanded macro.
191 void vtkParsePreprocess_FreeExpandedMacro(const char *emacro);
194 * Add an include directory. The directories that were added
195 * first will be searched first.
197 void vtkParsePreprocess_IncludeDirectory(
198 PreprocessInfo *info, const char *name);
201 * Find an include file in the path. If system_first is set, then
202 * the current directory is ignored unless it is explicitly in the
203 * path. A null return value indicates that the file was not found.
204 * If already_loaded is set, then the file was already loaded. This
205 * preprocessor never loads the same file twice.
207 const char *vtkParsePreprocess_FindIncludeFile(
208 PreprocessInfo *info, const char *filename, int system_first,
209 int *already_loaded);
212 * Initialize a preprocessor symbol struct.
214 void vtkParsePreprocess_InitMacro(MacroInfo *symbol);
217 * Initialize a preprocessor struct.
219 void vtkParsePreprocess_InitPreprocess(PreprocessInfo *info);