src/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   No checks are done for recursively-defined macros.  If they
  43   occur, the preprocessor will crash.
  44 */
  45
  46 #ifndef VTK_PARSE_PREPROCESS_H
  47 #define VTK_PARSE_PREPROCESS_H
  48
  49 /**
  50  * The preprocessor int type.  Use the compiler's longest int type.
  51  */
  52 #if defined(_WIN32) && !defined(__MINGW32__) && !defined(__CYGWIN__)
  53 typedef __int64 preproc_int_t;
  54 typedef unsigned __int64 preproc_uint_t;
  55 #else
  56 typedef long long preproc_int_t;
  57 typedef unsigned long long preproc_uint_t;
  58 #endif
  59
  60 /**
  61  * Struct to describe a preprocessor symbol.
  62  */
  63 typedef struct _MacroInfo
  64 {
  65   const char    *Name;
  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 */
  72 } MacroInfo;
  73
  74 /**
  75  * Contains all symbols defined thus far (including those defined
  76  * in any included header files).
  77  */
  78 typedef struct _PreprocessInfo
  79 {
  80   const char    *FileName;         /* the file that is being parsed */
  81   int            NumberOfMacros;
  82   MacroInfo    **Macros;
  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 */
  90 } PreprocessInfo;
  91
  92 /**
  93  * Platforms.  Always choose native unless crosscompiling.
  94  */
  95 enum _preproc_platform_t {
  96   VTK_PARSE_NATIVE = 0,
  97 };
  98
  99 /**
 100  * Directive return values.
 101  */
 102 enum _preproc_return_t {
 103   VTK_PARSE_OK = 0,
 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 */
 115 };
 116
 117 /**
 118  * Bitfield for fatal errors.
 119  */
 120 #define VTK_PARSE_FATAL_ERROR 0xF8
 121
 122 #ifdef __cplusplus
 123 extern "C" {
 124 #endif
 125
 126 /**
 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.
 135  */
 136 int vtkParsePreprocess_HandleDirective(
 137   PreprocessInfo *info, const char *directive);
 138
 139 /**
 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.
 147  */
 148 int vtkParsePreprocess_EvaluateExpression(
 149   PreprocessInfo *info, const char *text,
 150   preproc_int_t *val, int *is_unsigned);
 151
 152 /**
 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.
 156  */
 157 void vtkParsePreprocess_AddStandardMacros(
 158   PreprocessInfo *info, int platform);
 159
 160 /**
 161  * Add a preprocessor symbol, including a definition.  Return
 162  * values are VTK_PARSE_OK and VTK_PARSE_MACRO_REDEFINED.
 163  */
 164 int vtkParsePreprocess_AddMacro(
 165   PreprocessInfo *info, const char *name, const char *definition);
 166
 167 /**
 168  * Remove a preprocessor symbol.  Return values are VTK_PARSE_OK
 169  * and VTK_PARSE_MACRO_UNDEFINED.
 170  */
 171 int vtkParsePreprocess_RemoveMacro(
 172   PreprocessInfo *info, const char *name);
 173
 174 /**
 175  * Return a preprocessor symbol struct, or NULL if not found.
 176  */
 177 MacroInfo *vtkParsePreprocess_GetMacro(
 178   PreprocessInfo *info, const char *name);
 179
 180 /**
 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.
 184  */
 185 const char *vtkParsePreprocess_ExpandMacro(
 186   MacroInfo *macro, const char *argstring);
 187
 188 /**
 189  * Free an expanded macro.
 190  */
 191 void vtkParsePreprocess_FreeExpandedMacro(const char *emacro);
 192
 193 /**
 194  * Add an include directory.  The directories that were added
 195  * first will be searched first.
 196  */
 197 void vtkParsePreprocess_IncludeDirectory(
 198   PreprocessInfo *info, const char *name);
 199
 200 /**
 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.
 206  */
 207 const char *vtkParsePreprocess_FindIncludeFile(
 208   PreprocessInfo *info, const char *filename, int system_first,
 209   int *already_loaded);
 210
 211 /**
 212  * Initialize a preprocessor symbol struct.
 213  */
 214 void vtkParsePreprocess_InitMacro(MacroInfo *symbol);
 215
 216 /**
 217  * Initialize a preprocessor struct.
 218  */
 219 void vtkParsePreprocess_InitPreprocess(PreprocessInfo *info);
 220
 221 #ifdef __cplusplus
 222 } /* extern "C" */
 223 #endif
 224
 225 #endif