src/engine/SCons/cpp.py

   1 #
   2 # __COPYRIGHT__
   3 #
   4 # Permission is hereby granted, free of charge, to any person obtaining
   5 # a copy of this software and associated documentation files (the
   6 # "Software"), to deal in the Software without restriction, including
   7 # without limitation the rights to use, copy, modify, merge, publish,
   8 # distribute, sublicense, and/or sell copies of the Software, and to
   9 # permit persons to whom the Software is furnished to do so, subject to
  10 # the following conditions:
  11 #
  12 # The above copyright notice and this permission notice shall be included
  13 # in all copies or substantial portions of the Software.
  14 #
  15 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  16 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  17 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  19 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  20 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  21 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22 #
  23
  24 __revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
  25
  26 __doc__ = """
  27 SCons C Pre-Processor module
  28 """
  29
  30 # TODO(1.5):  remove this import
  31 # This module doesn't use anything from SCons by name, but we import SCons
  32 # here to pull in zip() from the SCons.compat layer for early Pythons.
  33 import SCons
  34
  35 import os
  36 import re
  37
  38 #
  39 # First "subsystem" of regular expressions that we set up:
  40 #
  41 # Stuff to turn the C preprocessor directives in a file's contents into
  42 # a list of tuples that we can process easily.
  43 #
  44
  45 # A table of regular expressions that fetch the arguments from the rest of
  46 # a C preprocessor line.  Different directives have different arguments
  47 # that we want to fetch, using the regular expressions to which the lists
  48 # of preprocessor directives map.
  49 cpp_lines_dict = {
  50     # Fetch the rest of a #if/#elif/#ifdef/#ifndef as one argument,
  51     # separated from the keyword by white space.
  52     ('if', 'elif', 'ifdef', 'ifndef',)
  53                         : '\s+(.+)',
  54
  55     # Fetch the rest of a #import/#include/#include_next line as one
  56     # argument, with white space optional.
  57     ('import', 'include', 'include_next',)
  58                         : '\s*(.+)',
  59
  60     # We don't care what comes after a #else or #endif line.
  61     ('else', 'endif',)  : '',
  62
  63     # Fetch three arguments from a #define line:
  64     #   1) The #defined keyword.
  65     #   2) The optional parentheses and arguments (if it's a function-like
  66     #      macro, '' if it's not).
  67     #   3) The expansion value.
  68     ('define',)         : '\s+([_A-Za-z][_A-Za-z0-9_]*)(\([^)]*\))?\s*(.*)',
  69
  70     # Fetch the #undefed keyword from a #undef line.
  71     ('undef',)          : '\s+([_A-Za-z][A-Za-z0-9_]*)',
  72 }
  73
  74 # Create a table that maps each individual C preprocessor directive to
  75 # the corresponding compiled regular expression that fetches the arguments
  76 # we care about.
  77 Table = {}
  78 for op_list, expr in cpp_lines_dict.items():
  79     e = re.compile(expr)
  80     for op in op_list:
  81         Table[op] = e
  82 del e
  83 del op
  84 del op_list
  85
  86 # Create a list of the expressions we'll use to match all of the
  87 # preprocessor directives.  These are the same as the directives
  88 # themselves *except* that we must use a negative lookahead assertion
  89 # when matching "if" so it doesn't match the "if" in "ifdef."
  90 override = {
  91     'if'                        : 'if(?!def)',
  92 }
  93 l = [override.get(x, x) for x in Table.keys()]
  94
  95
  96 # Turn the list of expressions into one big honkin' regular expression
  97 # that will match all the preprocessor lines at once.  This will return
  98 # a list of tuples, one for each preprocessor line.  The preprocessor
  99 # directive will be the first element in each tuple, and the rest of
 100 # the line will be the second element.
 101 e = '^\s*#\s*(' + '|'.join(l) + ')(.*)$'
 102
 103 # And last but not least, compile the expression.
 104 CPP_Expression = re.compile(e, re.M)
 105
 106
 107
 108
 109 #
 110 # Second "subsystem" of regular expressions that we set up:
 111 #
 112 # Stuff to translate a C preprocessor expression (as found on a #if or
 113 # #elif line) into an equivalent Python expression that we can eval().
 114 #
 115
 116 # A dictionary that maps the C representation of Boolean operators
 117 # to their Python equivalents.
 118 CPP_to_Python_Ops_Dict = {
 119     '!'         : ' not ',
 120     '!='        : ' != ',
 121     '&&'        : ' and ',
 122     '||'        : ' or ',
 123     '?'         : ' and ',
 124     ':'         : ' or ',
 125     '\r'        : '',
 126 }
 127
 128 CPP_to_Python_Ops_Sub = lambda m: CPP_to_Python_Ops_Dict[m.group(0)]
 129
 130 # We have to sort the keys by length so that longer expressions
 131 # come *before* shorter expressions--in particular, "!=" must
 132 # come before "!" in the alternation.  Without this, the Python
 133 # re module, as late as version 2.2.2, empirically matches the
 134 # "!" in "!=" first, instead of finding the longest match.
 135 # What's up with that?
 136 l = sorted(CPP_to_Python_Ops_Dict.keys(), cmp=lambda a, b: cmp(len(b), len(a)))
 137
 138 # Turn the list of keys into one regular expression that will allow us
 139 # to substitute all of the operators at once.
 140 expr = '|'.join(map(re.escape, l))
 141
 142 # ...and compile the expression.
 143 CPP_to_Python_Ops_Expression = re.compile(expr)
 144
 145 # A separate list of expressions to be evaluated and substituted
 146 # sequentially, not all at once.
 147 CPP_to_Python_Eval_List = [
 148     ['defined\s+(\w+)',         '"\\1" in __dict__'],
 149     ['defined\s*\((\w+)\)',     '"\\1" in __dict__'],
 150     ['/\*.*\*/',                ''],
 151     ['/\*.*',                   ''],
 152     ['//.*',                    ''],
 153     ['(0x[0-9A-Fa-f]*)[UL]+',   '\\1'],
 154 ]
 155
 156 # Replace the string representations of the regular expressions in the
 157 # list with compiled versions.
 158 for l in CPP_to_Python_Eval_List:
 159     l[0] = re.compile(l[0])
 160
 161 # Wrap up all of the above into a handy function.
 162 def CPP_to_Python(s):
 163     """
 164     Converts a C pre-processor expression into an equivalent
 165     Python expression that can be evaluated.
 166     """
 167     s = CPP_to_Python_Ops_Expression.sub(CPP_to_Python_Ops_Sub, s)
 168     for expr, repl in CPP_to_Python_Eval_List:
 169         s = expr.sub(repl, s)
 170     return s
 171
 172
 173
 174 del expr
 175 del l
 176 del override
 177
 178
 179
 180 class FunctionEvaluator:
 181     """
 182     Handles delayed evaluation of a #define function call.
 183     """
 184     def __init__(self, name, args, expansion):
 185         """
 186         Squirrels away the arguments and expansion value of a #define
 187         macro function for later evaluation when we must actually expand
 188         a value that uses it.
 189         """
 190         self.name = name
 191         self.args = function_arg_separator.split(args)
 192         try:
 193             expansion = expansion.split('##')
 194         except (AttributeError, TypeError):
 195             # Python 1.5 throws TypeError if "expansion" isn't a string,
 196             # later versions throw AttributeError.
 197             pass
 198         self.expansion = expansion
 199     def __call__(self, *values):
 200         """
 201         Evaluates the expansion of a #define macro function called
 202         with the specified values.
 203         """
 204         if len(self.args) != len(values):
 205             raise ValueError, "Incorrect number of arguments to `%s'" % self.name
 206         # Create a dictionary that maps the macro arguments to the
 207         # corresponding values in this "call."  We'll use this when we
 208         # eval() the expansion so that arguments will get expanded to
 209         # the right values.
 210         locals = {}
 211         for k, v in zip(self.args, values):
 212             locals[k] = v
 213
 214         parts = []
 215         for s in self.expansion:
 216             if not s in self.args:
 217                 s = repr(s)
 218             parts.append(s)
 219         statement = ' + '.join(parts)
 220
 221         return eval(statement, globals(), locals)
 222
 223
 224
 225 # Find line continuations.
 226 line_continuations = re.compile('\\\\\r?\n')
 227
 228 # Search for a "function call" macro on an expansion.  Returns the
 229 # two-tuple of the "function" name itself, and a string containing the
 230 # arguments within the call parentheses.
 231 function_name = re.compile('(\S+)\(([^)]*)\)')
 232
 233 # Split a string containing comma-separated function call arguments into
 234 # the separate arguments.
 235 function_arg_separator = re.compile(',\s*')
 236
 237
 238
 239 class PreProcessor:
 240     """
 241     The main workhorse class for handling C pre-processing.
 242     """
 243     def __init__(self, current=os.curdir, cpppath=(), dict={}, all=0):
 244         global Table
 245
 246         cpppath = tuple(cpppath)
 247
 248         self.searchpath = {
 249             '"' :       (current,) + cpppath,
 250             '<' :       cpppath + (current,),
 251         }
 252
 253         # Initialize our C preprocessor namespace for tracking the
 254         # values of #defined keywords.  We use this namespace to look
 255         # for keywords on #ifdef/#ifndef lines, and to eval() the
 256         # expressions on #if/#elif lines (after massaging them from C to
 257         # Python).
 258         self.cpp_namespace = dict.copy()
 259         self.cpp_namespace['__dict__'] = self.cpp_namespace
 260
 261         if all:
 262            self.do_include = self.all_include
 263
 264         # For efficiency, a dispatch table maps each C preprocessor
 265         # directive (#if, #define, etc.) to the method that should be
 266         # called when we see it.  We accomodate state changes (#if,
 267         # #ifdef, #ifndef) by pushing the current dispatch table on a
 268         # stack and changing what method gets called for each relevant
 269         # directive we might see next at this level (#else, #elif).
 270         # #endif will simply pop the stack.
 271         d = {
 272             'scons_current_file'    : self.scons_current_file
 273         }
 274         for op in Table.keys():
 275             d[op] = getattr(self, 'do_' + op)
 276         self.default_table = d
 277
 278     # Controlling methods.
 279
 280     def tupleize(self, contents):
 281         """
 282         Turns the contents of a file into a list of easily-processed
 283         tuples describing the CPP lines in the file.
 284
 285         The first element of each tuple is the line's preprocessor
 286         directive (#if, #include, #define, etc., minus the initial '#').
 287         The remaining elements are specific to the type of directive, as
 288         pulled apart by the regular expression.
 289         """
 290         global CPP_Expression, Table
 291         contents = line_continuations.sub('', contents)
 292         cpp_tuples = CPP_Expression.findall(contents)
 293         return  [(m[0],) + Table[m[0]].match(m[1]).groups() for m in cpp_tuples]
 294
 295     def __call__(self, file):
 296         """
 297         Pre-processes a file.
 298
 299         This is the main public entry point.
 300         """
 301         self.current_file = file
 302         return self.process_contents(self.read_file(file), file)
 303
 304     def process_contents(self, contents, fname=None):
 305         """
 306         Pre-processes a file contents.
 307
 308         This is the main internal entry point.
 309         """
 310         self.stack = []
 311         self.dispatch_table = self.default_table.copy()
 312         self.current_file = fname
 313         self.tuples = self.tupleize(contents)
 314
 315         self.initialize_result(fname)
 316         while self.tuples:
 317             t = self.tuples.pop(0)
 318             # Uncomment to see the list of tuples being processed (e.g.,
 319             # to validate the CPP lines are being translated correctly).
 320             #print t
 321             self.dispatch_table[t[0]](t)
 322         return self.finalize_result(fname)
 323
 324     # Dispatch table stack manipulation methods.
 325
 326     def save(self):
 327         """
 328         Pushes the current dispatch table on the stack and re-initializes
 329         the current dispatch table to the default.
 330         """
 331         self.stack.append(self.dispatch_table)
 332         self.dispatch_table = self.default_table.copy()
 333
 334     def restore(self):
 335         """
 336         Pops the previous dispatch table off the stack and makes it the
 337         current one.
 338         """
 339         try: self.dispatch_table = self.stack.pop()
 340         except IndexError: pass
 341
 342     # Utility methods.
 343
 344     def do_nothing(self, t):
 345         """
 346         Null method for when we explicitly want the action for a
 347         specific preprocessor directive to do nothing.
 348         """
 349         pass
 350
 351     def scons_current_file(self, t):
 352         self.current_file = t[1]
 353
 354     def eval_expression(self, t):
 355         """
 356         Evaluates a C preprocessor expression.
 357
 358         This is done by converting it to a Python equivalent and
 359         eval()ing it in the C preprocessor namespace we use to
 360         track #define values.
 361         """
 362         t = CPP_to_Python(' '.join(t[1:]))
 363         try: return eval(t, self.cpp_namespace)
 364         except (NameError, TypeError): return 0
 365
 366     def initialize_result(self, fname):
 367         self.result = [fname]
 368
 369     def finalize_result(self, fname):
 370         return self.result[1:]
 371
 372     def find_include_file(self, t):
 373         """
 374         Finds the #include file for a given preprocessor tuple.
 375         """
 376         fname = t[2]
 377         for d in self.searchpath[t[1]]:
 378             if d == os.curdir:
 379                 f = fname
 380             else:
 381                 f = os.path.join(d, fname)
 382             if os.path.isfile(f):
 383                 return f
 384         return None
 385
 386     def read_file(self, file):
 387         return open(file).read()
 388
 389     # Start and stop processing include lines.
 390
 391     def start_handling_includes(self, t=None):
 392         """
 393         Causes the PreProcessor object to start processing #import,
 394         #include and #include_next lines.
 395
 396         This method will be called when a #if, #ifdef, #ifndef or #elif
 397         evaluates True, or when we reach the #else in a #if, #ifdef,
 398         #ifndef or #elif block where a condition already evaluated
 399         False.
 400
 401         """
 402         d = self.dispatch_table
 403         d['import'] = self.do_import
 404         d['include'] =  self.do_include
 405         d['include_next'] =  self.do_include
 406
 407     def stop_handling_includes(self, t=None):
 408         """
 409         Causes the PreProcessor object to stop processing #import,
 410         #include and #include_next lines.
 411
 412         This method will be called when a #if, #ifdef, #ifndef or #elif
 413         evaluates False, or when we reach the #else in a #if, #ifdef,
 414         #ifndef or #elif block where a condition already evaluated True.
 415         """
 416         d = self.dispatch_table
 417         d['import'] = self.do_nothing
 418         d['include'] =  self.do_nothing
 419         d['include_next'] =  self.do_nothing
 420
 421     # Default methods for handling all of the preprocessor directives.
 422     # (Note that what actually gets called for a given directive at any
 423     # point in time is really controlled by the dispatch_table.)
 424
 425     def _do_if_else_condition(self, condition):
 426         """
 427         Common logic for evaluating the conditions on #if, #ifdef and
 428         #ifndef lines.
 429         """
 430         self.save()
 431         d = self.dispatch_table
 432         if condition:
 433             self.start_handling_includes()
 434             d['elif'] = self.stop_handling_includes
 435             d['else'] = self.stop_handling_includes
 436         else:
 437             self.stop_handling_includes()
 438             d['elif'] = self.do_elif
 439             d['else'] = self.start_handling_includes
 440
 441     def do_ifdef(self, t):
 442         """
 443         Default handling of a #ifdef line.
 444         """
 445         self._do_if_else_condition(t[1] in self.cpp_namespace)
 446
 447     def do_ifndef(self, t):
 448         """
 449         Default handling of a #ifndef line.
 450         """
 451         self._do_if_else_condition(t[1] not in self.cpp_namespace)
 452
 453     def do_if(self, t):
 454         """
 455         Default handling of a #if line.
 456         """
 457         self._do_if_else_condition(self.eval_expression(t))
 458
 459     def do_elif(self, t):
 460         """
 461         Default handling of a #elif line.
 462         """
 463         d = self.dispatch_table
 464         if self.eval_expression(t):
 465             self.start_handling_includes()
 466             d['elif'] = self.stop_handling_includes
 467             d['else'] = self.stop_handling_includes
 468
 469     def do_else(self, t):
 470         """
 471         Default handling of a #else line.
 472         """
 473         pass
 474
 475     def do_endif(self, t):
 476         """
 477         Default handling of a #endif line.
 478         """
 479         self.restore()
 480
 481     def do_define(self, t):
 482         """
 483         Default handling of a #define line.
 484         """
 485         _, name, args, expansion = t
 486         try:
 487             expansion = int(expansion)
 488         except (TypeError, ValueError):
 489             pass
 490         if args:
 491             evaluator = FunctionEvaluator(name, args[1:-1], expansion)
 492             self.cpp_namespace[name] = evaluator
 493         else:
 494             self.cpp_namespace[name] = expansion
 495
 496     def do_undef(self, t):
 497         """
 498         Default handling of a #undef line.
 499         """
 500         try: del self.cpp_namespace[t[1]]
 501         except KeyError: pass
 502
 503     def do_import(self, t):
 504         """
 505         Default handling of a #import line.
 506         """
 507         # XXX finish this -- maybe borrow/share logic from do_include()...?
 508         pass
 509
 510     def do_include(self, t):
 511         """
 512         Default handling of a #include line.
 513         """
 514         t = self.resolve_include(t)
 515         include_file = self.find_include_file(t)
 516         if include_file:
 517             #print "include_file =", include_file
 518             self.result.append(include_file)
 519             contents = self.read_file(include_file)
 520             new_tuples = [('scons_current_file', include_file)] + \
 521                          self.tupleize(contents) + \
 522                          [('scons_current_file', self.current_file)]
 523             self.tuples[:] = new_tuples + self.tuples
 524
 525     # Date: Tue, 22 Nov 2005 20:26:09 -0500
 526     # From: Stefan Seefeld <seefeld@sympatico.ca>
 527     #
 528     # By the way, #include_next is not the same as #include. The difference
 529     # being that #include_next starts its search in the path following the
 530     # path that let to the including file. In other words, if your system
 531     # include paths are ['/foo', '/bar'], and you are looking at a header
 532     # '/foo/baz.h', it might issue an '#include_next <baz.h>' which would
 533     # correctly resolve to '/bar/baz.h' (if that exists), but *not* see
 534     # '/foo/baz.h' again. See http://www.delorie.com/gnu/docs/gcc/cpp_11.html
 535     # for more reasoning.
 536     #
 537     # I have no idea in what context 'import' might be used.
 538
 539     # XXX is #include_next really the same as #include ?
 540     do_include_next = do_include
 541
 542     # Utility methods for handling resolution of include files.
 543
 544     def resolve_include(self, t):
 545         """Resolve a tuple-ized #include line.
 546
 547         This handles recursive expansion of values without "" or <>
 548         surrounding the name until an initial " or < is found, to handle
 549                 #include FILE
 550         where FILE is a #define somewhere else.
 551         """
 552         s = t[1]
 553         while not s[0] in '<"':
 554             #print "s =", s
 555             try:
 556                 s = self.cpp_namespace[s]
 557             except KeyError:
 558                 m = function_name.search(s)
 559                 s = self.cpp_namespace[m.group(1)]
 560                 if callable(s):
 561                     args = function_arg_separator.split(m.group(2))
 562                     s = s(*args)
 563             if not s:
 564                 return None
 565         return (t[0], s[0], s[1:-1])
 566
 567     def all_include(self, t):
 568         """
 569         """
 570         self.result.append(self.resolve_include(t))
 571
 572 class DumbPreProcessor(PreProcessor):
 573     """A preprocessor that ignores all #if/#elif/#else/#endif directives
 574     and just reports back *all* of the #include files (like the classic
 575     SCons scanner did).
 576
 577     This is functionally equivalent to using a regular expression to
 578     find all of the #include lines, only slower.  It exists mainly as
 579     an example of how the main PreProcessor class can be sub-classed
 580     to tailor its behavior.
 581     """
 582     def __init__(self, *args, **kw):
 583         PreProcessor.__init__(self, *args, **kw)
 584         d = self.default_table
 585         for func in ['if', 'elif', 'else', 'endif', 'ifdef', 'ifndef']:
 586             d[func] = d[func] = self.do_nothing
 587
 588 del __revision__
 589
 590 # Local Variables:
 591 # tab-width:4
 592 # indent-tabs-mode:nil
 593 # End:
 594 # vim: set expandtab tabstop=4 shiftwidth=4: