src/VTKWrapping/ParaView/vtkParsePreprocess.h

   1 /*=========================================================================
   2
   3   Program:   Visualization Toolkit
   4   Module:    vtkParsePreprocess.h
   5
   6   Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
   7   All rights reserved.
   8   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
   9
  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.
  13
  14 =========================================================================*/
  15 /*-------------------------------------------------------------------------
  16   Copyright (c) 2010 David Gobbi.
  17
  18   Contributed to the VisualizationToolkit by the author in June 2010
  19   under the terms of the Visualization Toolkit 2008 copyright.
  20 -------------------------------------------------------------------------*/
  21
  22 /**
  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.
  26
  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.
  32
  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
  40   of code be skipped.
  41 */
  42
  43 #ifndef VTK_PARSE_PREPROCESS_H
  44 #define VTK_PARSE_PREPROCESS_H
  45
  46 #include "vtkParseString.h"
  47
  48 /**
  49  * The preprocessor int type.  Use the compiler's longest int type.
  50  */
  51 #if defined(_WIN32) && !defined(__MINGW32__) && !defined(__CYGWIN__)
  52 typedef __int64 preproc_int_t;
  53 typedef unsigned __int64 preproc_uint_t;
  54 #else
  55 typedef long long preproc_int_t;
  56 typedef unsigned long long preproc_uint_t;
  57 #endif
  58
  59 /**
  60  * Struct to describe a preprocessor symbol.
  61  */
  62 typedef struct _MacroInfo
  63 {
  64   const char    *Name;
  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 */
  73 } MacroInfo;
  74
  75 /**
  76  * Contains all symbols defined thus far (including those defined
  77  * in any included header files).
  78  */
  79 typedef struct _PreprocessInfo
  80 {
  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 */
  91 } PreprocessInfo;
  92
  93 /**
  94  * Platforms.  Always choose native unless crosscompiling.
  95  */
  96 enum _preproc_platform_t {
  97   VTK_PARSE_NATIVE = 0
  98 };
  99
 100 /**
 101  * Directive return values.
 102  */
 103 enum _preproc_return_t {
 104   VTK_PARSE_OK = 0,
 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 */
 116 };
 117
 118 /**
 119  * Bitfield for fatal errors.
 120  */
 121 #define VTK_PARSE_FATAL_ERROR 0xF8
 122
 123 #ifdef __cplusplus
 124 extern "C" {
 125 #endif
 126
 127 /**
 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.
 136  */
 137 int vtkParsePreprocess_HandleDirective(
 138   PreprocessInfo *info, const char *directive);
 139
 140 /**
 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.
 148  */
 149 int vtkParsePreprocess_EvaluateExpression(
 150   PreprocessInfo *info, const char *text,
 151   preproc_int_t *val, int *is_unsigned);
 152
 153 /**
 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.
 157  */
 158 void vtkParsePreprocess_AddStandardMacros(
 159   PreprocessInfo *info, int platform);
 160
 161 /**
 162  * Add a preprocessor symbol, including a definition.  Return
 163  * values are VTK_PARSE_OK and VTK_PARSE_MACRO_REDEFINED.
 164  */
 165 int vtkParsePreprocess_AddMacro(
 166   PreprocessInfo *info, const char *name, const char *definition);
 167
 168 /**
 169  * Remove a preprocessor symbol.  Return values are VTK_PARSE_OK
 170  * and VTK_PARSE_MACRO_UNDEFINED.
 171  */
 172 int vtkParsePreprocess_RemoveMacro(
 173   PreprocessInfo *info, const char *name);
 174
 175 /**
 176  * Return a preprocessor symbol struct, or NULL if not found.
 177  */
 178 MacroInfo *vtkParsePreprocess_GetMacro(
 179   PreprocessInfo *info, const char *name);
 180
 181 /**
 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.
 185  */
 186 const char *vtkParsePreprocess_ExpandMacro(
 187   PreprocessInfo *info, MacroInfo *macro, const char *argstring);
 188
 189 /**
 190  * Free an expanded macro
 191  */
 192 void vtkParsePreprocess_FreeMacroExpansion(
 193   PreprocessInfo *info, MacroInfo *macro, const char *text);
 194
 195 /**
 196  * Fully process a string with the preprocessor, and
 197  * return a new string or NULL if a fatal error occurred.
 198  */
 199 const char *vtkParsePreprocess_ProcessString(
 200   PreprocessInfo *info, const char *text);
 201
 202 /**
 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.
 207  */
 208 void vtkParsePreprocess_FreeProcessedString(
 209   PreprocessInfo *info, const char *text);
 210
 211 /**
 212  * Add an include directory.  The directories that were added
 213  * first will be searched first.
 214  */
 215 void vtkParsePreprocess_IncludeDirectory(
 216   PreprocessInfo *info, const char *name);
 217
 218 /**
 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.
 224  */
 225 const char *vtkParsePreprocess_FindIncludeFile(
 226   PreprocessInfo *info, const char *filename, int system_first,
 227   int *already_loaded);
 228
 229 /**
 230  * Initialize a preprocessor symbol struct.
 231  */
 232 void vtkParsePreprocess_InitMacro(MacroInfo *symbol);
 233
 234 /**
 235  * Free a preprocessor macro struct
 236  */
 237 void vtkParsePreprocess_FreeMacro(MacroInfo *macro);
 238
 239 /**
 240  * Initialize a preprocessor struct.
 241  */
 242 void vtkParsePreprocess_Init(
 243   PreprocessInfo *info, const char *filename);
 244
 245 /**
 246  * Free a preprocessor struct and its contents;
 247  */
 248 void vtkParsePreprocess_Free(PreprocessInfo *info);
 249
 250 #ifdef __cplusplus
 251 } /* extern "C" */
 252 #endif
 253
 254 #endif