BaseTools/Source/Python/Common/Expression.py

   1 ## @file
   2 # This file is used to parse and evaluate expression in directive or PCD value.
   3 #
   4 # Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5 # This program and the accompanying materials
   6 # are licensed and made available under the terms and conditions of the BSD License
   7 # which accompanies this distribution.    The full text of the license may be found at
   8 # http://opensource.org/licenses/bsd-license.php
   9 #
  10 # THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 ## Import Modules
  14 #
  15 from Common.GlobalData import *
  16 from CommonDataClass.Exceptions import BadExpression
  17 from CommonDataClass.Exceptions import SymbolNotFound
  18 from CommonDataClass.Exceptions import WrnExpression
  19 from Misc import GuidStringToGuidStructureString
  20
  21 ERR_STRING_EXPR         = 'This operator cannot be used in string expression: [%s].'
  22 ERR_SNYTAX              = 'Syntax error, the rest of expression cannot be evaluated: [%s].'
  23 ERR_MATCH               = 'No matching right parenthesis.'
  24 ERR_STRING_TOKEN        = 'Bad string token: [%s].'
  25 ERR_MACRO_TOKEN         = 'Bad macro token: [%s].'
  26 ERR_EMPTY_TOKEN         = 'Empty token is not allowed.'
  27 ERR_PCD_RESOLVE         = 'PCD token cannot be resolved: [%s].'
  28 ERR_VALID_TOKEN         = 'No more valid token found from rest of string: [%s].'
  29 ERR_EXPR_TYPE           = 'Different types found in expression.'
  30 ERR_OPERATOR_UNSUPPORT  = 'Unsupported operator: [%s]'
  31 ERR_REL_NOT_IN          = 'Expect "IN" after "not" operator.'
  32 WRN_BOOL_EXPR           = 'Operand of boolean type cannot be used in arithmetic expression.'
  33 WRN_EQCMP_STR_OTHERS    = '== Comparison between Operand of string type and Boolean/Number Type always return False.'
  34 WRN_NECMP_STR_OTHERS    = '!= Comparison between Operand of string type and Boolean/Number Type always return True.'
  35 ERR_RELCMP_STR_OTHERS   = 'Operator taking Operand of string type and Boolean/Number Type is not allowed: [%s].'
  36 ERR_STRING_CMP          = 'Unicode string and general string cannot be compared: [%s %s %s]'
  37 ERR_ARRAY_TOKEN         = 'Bad C array or C format GUID token: [%s].'
  38 ERR_ARRAY_ELE           = 'This must be HEX value for NList or Array: [%s].'
  39
  40 ## SplitString
  41 #  Split string to list according double quote
  42 #  For example: abc"de\"f"ghi"jkl"mn will be: ['abc', '"de\"f"', 'ghi', '"jkl"', 'mn']
  43 #
  44 def SplitString(String):
  45     # There might be escaped quote: "abc\"def\\\"ghi"
  46     Str = String.replace('\\\\', '//').replace('\\\"', '\\\'')
  47     RetList = []
  48     InQuote = False
  49     Item = ''
  50     for i, ch in enumerate(Str):
  51         if ch == '"':
  52             InQuote = not InQuote
  53             if not InQuote:
  54                 Item += String[i]
  55                 RetList.append(Item)
  56                 Item = ''
  57                 continue
  58             if Item:
  59                 RetList.append(Item)
  60                 Item = ''
  61         Item += String[i]
  62     if InQuote:
  63         raise BadExpression(ERR_STRING_TOKEN % Item)
  64     if Item:
  65         RetList.append(Item)
  66     return RetList
  67
  68 ## ReplaceExprMacro
  69 #
  70 def ReplaceExprMacro(String, Macros, ExceptionList = None):
  71     StrList = SplitString(String)
  72     for i, String in enumerate(StrList):
  73         InQuote = False
  74         if String.startswith('"'):
  75             InQuote = True
  76         MacroStartPos = String.find('$(')
  77         if MacroStartPos < 0:
  78             continue
  79         RetStr = ''
  80         while MacroStartPos >= 0:
  81             RetStr = String[0:MacroStartPos]
  82             MacroEndPos = String.find(')', MacroStartPos)
  83             if MacroEndPos < 0:
  84                 raise BadExpression(ERR_MACRO_TOKEN % String[MacroStartPos:])
  85             Macro = String[MacroStartPos+2:MacroEndPos]
  86             if Macro not in Macros:
  87                 # From C reference manual:
  88                 # If an undefined macro name appears in the constant-expression of
  89                 # !if or !elif, it is replaced by the integer constant 0.
  90                 RetStr += '0'
  91             elif not InQuote and ExceptionList and Macro in ExceptionList:
  92                 # Make sure the macro in exception list is encapsulated by double quote
  93                 # For example: DEFINE ARCH = IA32 X64
  94                 # $(ARCH) is replaced with "IA32 X64"
  95                 RetStr += '"' + Macros[Macro] + '"'
  96             else:
  97                 if Macros[Macro].strip() != "":
  98                     RetStr += Macros[Macro]
  99                 else:
 100                     RetStr += '""'
 101             RetStr += String[MacroEndPos+1:]
 102             String = RetStr
 103             MacroStartPos = String.find('$(')
 104         StrList[i] = RetStr
 105     return ''.join(StrList)
 106
 107 class ValueExpression(object):
 108     # Logical operator mapping
 109     LogicalOperators = {
 110         '&&' : 'and', '||' : 'or',
 111         '!'  : 'not', 'AND': 'and',
 112         'OR' : 'or' , 'NOT': 'not',
 113         'XOR': '^'  , 'xor': '^',
 114         'EQ' : '==' , 'NE' : '!=',
 115         'GT' : '>'  , 'LT' : '<',
 116         'GE' : '>=' , 'LE' : '<=',
 117         'IN' : 'in'
 118     }
 119
 120     NonLetterOpLst = ['+', '-', '&', '|', '^', '!', '=', '>', '<']
 121
 122     PcdPattern = re.compile(r'[_a-zA-Z][0-9A-Za-z_]*\.[_a-zA-Z][0-9A-Za-z_]*$')
 123     HexPattern = re.compile(r'0[xX][0-9a-fA-F]+$')
 124     RegGuidPattern = re.compile(r'[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}')
 125
 126     SymbolPattern = re.compile("("
 127                                  "\$\([A-Z][A-Z0-9_]*\)|\$\(\w+\.\w+\)|\w+\.\w+|"
 128                                  "&&|\|\||!(?!=)|"
 129                                  "(?<=\W)AND(?=\W)|(?<=\W)OR(?=\W)|(?<=\W)NOT(?=\W)|(?<=\W)XOR(?=\W)|"
 130                                  "(?<=\W)EQ(?=\W)|(?<=\W)NE(?=\W)|(?<=\W)GT(?=\W)|(?<=\W)LT(?=\W)|(?<=\W)GE(?=\W)|(?<=\W)LE(?=\W)"
 131                                ")")
 132
 133     @staticmethod
 134     def Eval(Operator, Oprand1, Oprand2 = None):
 135         WrnExp = None
 136
 137         if Operator not in ["==", "!=", ">=", "<=", ">", "<", "in", "not in"] and \
 138             (type(Oprand1) == type('') or type(Oprand2) == type('')):
 139             raise BadExpression(ERR_STRING_EXPR % Operator)
 140
 141         TypeDict = {
 142             type(0)  : 0,
 143             type(0L) : 0,
 144             type('') : 1,
 145             type(True) : 2
 146         }
 147
 148         EvalStr = ''
 149         if Operator in ["!", "NOT", "not"]:
 150             if type(Oprand1) == type(''):
 151                 raise BadExpression(ERR_STRING_EXPR % Operator)
 152             EvalStr = 'not Oprand1'
 153         else:
 154             if Operator in ["+", "-"] and (type(True) in [type(Oprand1), type(Oprand2)]):
 155                 # Boolean in '+'/'-' will be evaluated but raise warning
 156                 WrnExp = WrnExpression(WRN_BOOL_EXPR)
 157             elif type('') in [type(Oprand1), type(Oprand2)] and type(Oprand1)!= type(Oprand2):
 158                 # == between string and number/boolean will always return False, != return True
 159                 if Operator == "==":
 160                     WrnExp = WrnExpression(WRN_EQCMP_STR_OTHERS)
 161                     WrnExp.result = False
 162                     raise WrnExp
 163                 elif Operator == "!=":
 164                     WrnExp = WrnExpression(WRN_NECMP_STR_OTHERS)
 165                     WrnExp.result = True
 166                     raise WrnExp
 167                 else:
 168                     raise BadExpression(ERR_RELCMP_STR_OTHERS % Operator)
 169             elif TypeDict[type(Oprand1)] != TypeDict[type(Oprand2)]:
 170                 if Operator in ["==", "!=", ">=", "<=", ">", "<"] and set((TypeDict[type(Oprand1)], TypeDict[type(Oprand2)])) == set((TypeDict[type(True)], TypeDict[type(0)])):
 171                     # comparison between number and boolean is allowed
 172                     pass
 173                 elif Operator in ['&', '|', '^', "&&", "||"] and set((TypeDict[type(Oprand1)], TypeDict[type(Oprand2)])) == set((TypeDict[type(True)], TypeDict[type(0)])):
 174                     # bitwise and logical operation between number and boolean is allowed
 175                     pass
 176                 else:
 177                     raise BadExpression(ERR_EXPR_TYPE)
 178             if type(Oprand1) == type('') and type(Oprand2) == type(''):
 179                 if (Oprand1.startswith('L"') and not Oprand2.startswith('L"')) or \
 180                     (not Oprand1.startswith('L"') and Oprand2.startswith('L"')):
 181                     raise BadExpression(ERR_STRING_CMP % (Oprand1, Operator, Oprand2))
 182             if 'in' in Operator and type(Oprand2) == type(''):
 183                 Oprand2 = Oprand2.split()
 184             EvalStr = 'Oprand1 ' + Operator + ' Oprand2'
 185
 186         # Local symbols used by built in eval function
 187         Dict = {
 188             'Oprand1' : Oprand1,
 189             'Oprand2' : Oprand2
 190         }
 191         try:
 192             Val = eval(EvalStr, {}, Dict)
 193         except Exception, Excpt:
 194             raise BadExpression(str(Excpt))
 195
 196         if Operator in ['and', 'or']:
 197             if Val:
 198                 Val = True
 199             else:
 200                 Val = False
 201
 202         if WrnExp:
 203             WrnExp.result = Val
 204             raise WrnExp
 205         return Val
 206
 207     def __init__(self, Expression, SymbolTable={}):
 208         self._NoProcess = False
 209         if type(Expression) != type(''):
 210             self._Expr = Expression
 211             self._NoProcess = True
 212             return
 213
 214         self._Expr = ReplaceExprMacro(Expression.strip(),
 215                                   SymbolTable,
 216                                   ['TARGET', 'TOOL_CHAIN_TAG', 'ARCH'])
 217
 218         if not self._Expr.strip():
 219             self._NoProcess = True
 220             return
 221
 222         #
 223         # The symbol table including PCD and macro mapping
 224         #
 225         self._Symb = SymbolTable
 226         self._Symb.update(self.LogicalOperators)
 227         self._Idx = 0
 228         self._Len = len(self._Expr)
 229         self._Token = ''
 230
 231         # Literal token without any conversion
 232         self._LiteralToken = ''
 233
 234     # Public entry for this class
 235     def __call__(self):
 236         if self._NoProcess:
 237             return self._Expr
 238
 239         Val = self._OrExpr()
 240         if type(Val) == type('') and Val == 'L""':
 241             Val = ''
 242
 243         # The expression has been parsed, but the end of expression is not reached
 244         # It means the rest does not comply EBNF of <Expression>
 245         if self._Idx != self._Len:
 246             raise BadExpression(ERR_SNYTAX % self._Expr[self._Idx:])
 247
 248         return Val
 249
 250     # Template function to parse binary operators which have same precedence
 251     # Expr [Operator Expr]*
 252     def _ExprFuncTemplate(self, EvalFunc, OpLst):
 253         Val = EvalFunc()
 254         while self._IsOperator(OpLst):
 255             Op = self._Token
 256             Val = self.Eval(Op, Val, EvalFunc())
 257         return Val
 258
 259     # A [|| B]*
 260     def _OrExpr(self):
 261         return self._ExprFuncTemplate(self._AndExpr, ["OR", "or", "||"])
 262
 263     # A [&& B]*
 264     def _AndExpr(self):
 265         return self._ExprFuncTemplate(self._BitOr, ["AND", "and", "&&"])
 266
 267     # A [ | B]*
 268     def _BitOr(self):
 269         return self._ExprFuncTemplate(self._BitXor, ["|"])
 270
 271     # A [ ^ B]*
 272     def _BitXor(self):
 273         return self._ExprFuncTemplate(self._BitAnd, ["XOR", "xor", "^"])
 274
 275     # A [ & B]*
 276     def _BitAnd(self):
 277         return self._ExprFuncTemplate(self._EqExpr, ["&"])
 278
 279     # A [ == B]*
 280     def _EqExpr(self):
 281         Val = self._RelExpr()
 282         while self._IsOperator(["==", "!=", "EQ", "NE", "IN", "in", "!", "NOT", "not"]):
 283             Op = self._Token
 284             if Op in ["!", "NOT", "not"]:
 285                 if not self._IsOperator(["IN", "in"]):
 286                     raise BadExpression(ERR_REL_NOT_IN)
 287                 Op += ' ' + self._Token
 288             Val = self.Eval(Op, Val, self._RelExpr())
 289         return Val
 290
 291     # A [ > B]*
 292     def _RelExpr(self):
 293         return self._ExprFuncTemplate(self._AddExpr, ["<=", ">=", "<", ">", "LE", "GE", "LT", "GT"])
 294
 295     # A [ + B]*
 296     def _AddExpr(self):
 297         return self._ExprFuncTemplate(self._UnaryExpr, ["+", "-"])
 298
 299     # [!]*A
 300     def _UnaryExpr(self):
 301         if self._IsOperator(["!", "NOT", "not"]):
 302             Val = self._UnaryExpr()
 303             return self.Eval('not', Val)
 304         return self._IdenExpr()
 305
 306     # Parse identifier or encapsulated expression
 307     def _IdenExpr(self):
 308         Tk = self._GetToken()
 309         if Tk == '(':
 310             Val = self._OrExpr()
 311             try:
 312                 # _GetToken may also raise BadExpression
 313                 if self._GetToken() != ')':
 314                     raise BadExpression(ERR_MATCH)
 315             except BadExpression:
 316                 raise BadExpression(ERR_MATCH)
 317             return Val
 318         return Tk
 319
 320     # Skip whitespace or tab
 321     def __SkipWS(self):
 322         for Char in self._Expr[self._Idx:]:
 323             if Char not in ' \t':
 324                 break
 325             self._Idx += 1
 326
 327     # Try to convert string to number
 328     def __IsNumberToken(self):
 329         Radix = 10
 330         if self._Token.lower()[0:2] == '0x' and len(self._Token) > 2:
 331             Radix = 16
 332         try:
 333             self._Token = int(self._Token, Radix)
 334             return True
 335         except ValueError:
 336             return False
 337         except TypeError:
 338             return False
 339
 340     # Parse array: {...}
 341     def __GetArray(self):
 342         Token = '{'
 343         self._Idx += 1
 344         self.__GetNList(True)
 345         Token += self._LiteralToken
 346         if self._Idx >= self._Len or self._Expr[self._Idx] != '}':
 347             raise BadExpression(ERR_ARRAY_TOKEN % Token)
 348         Token += '}'
 349
 350         # All whitespace and tabs in array are already stripped.
 351         IsArray = IsGuid = False
 352         if len(Token.split(',')) == 11 and len(Token.split(',{')) == 2 \
 353             and len(Token.split('},')) == 1:
 354             HexLen = [11,6,6,5,4,4,4,4,4,4,6]
 355             HexList= Token.split(',')
 356             if HexList[3].startswith('{') and \
 357                 not [Index for Index, Hex in enumerate(HexList) if len(Hex) > HexLen[Index]]:
 358                 IsGuid = True
 359         if Token.lstrip('{').rstrip('}').find('{') == -1:
 360             if not [Hex for Hex in Token.lstrip('{').rstrip('}').split(',') if len(Hex) > 4]:
 361                 IsArray = True
 362         if not IsArray and not IsGuid:
 363             raise BadExpression(ERR_ARRAY_TOKEN % Token)
 364         self._Idx += 1
 365         self._Token = self._LiteralToken = Token
 366         return self._Token
 367
 368     # Parse string, the format must be: "..."
 369     def __GetString(self):
 370         Idx = self._Idx
 371
 372         # Skip left quote
 373         self._Idx += 1
 374
 375         # Replace escape \\\", \"
 376         Expr = self._Expr[self._Idx:].replace('\\\\', '//').replace('\\\"', '\\\'')
 377         for Ch in Expr:
 378             self._Idx += 1
 379             if Ch == '"':
 380                 break
 381         self._Token = self._LiteralToken = self._Expr[Idx:self._Idx]
 382         if not self._Token.endswith('"'):
 383             raise BadExpression(ERR_STRING_TOKEN % self._Token)
 384         self._Token = self._Token[1:-1]
 385         return self._Token
 386
 387     # Get token that is comprised by alphanumeric, underscore or dot(used by PCD)
 388     # @param IsAlphaOp: Indicate if parsing general token or script operator(EQ, NE...)
 389     def __GetIdToken(self, IsAlphaOp = False):
 390         IdToken = ''
 391         for Ch in self._Expr[self._Idx:]:
 392             if not self.__IsIdChar(Ch):
 393                 break
 394             self._Idx += 1
 395             IdToken += Ch
 396
 397         self._Token = self._LiteralToken = IdToken
 398         if not IsAlphaOp:
 399             self.__ResolveToken()
 400         return self._Token
 401
 402     # Try to resolve token
 403     def __ResolveToken(self):
 404         if not self._Token:
 405             raise BadExpression(ERR_EMPTY_TOKEN)
 406
 407         # PCD token
 408         if self.PcdPattern.match(self._Token):
 409             if self._Token not in self._Symb:
 410                 raise SymbolNotFound(ERR_PCD_RESOLVE % self._Token)
 411             self._Token = ValueExpression(self._Symb[self._Token], self._Symb)()
 412             if type(self._Token) != type(''):
 413                 self._LiteralToken = hex(self._Token)
 414                 return
 415
 416         if self._Token.startswith('"'):
 417             self._Token = self._Token[1:-1]
 418         elif self._Token in ["FALSE", "false", "False"]:
 419             self._Token = False
 420         elif self._Token in ["TRUE", "true", "True"]:
 421             self._Token = True
 422         else:
 423             self.__IsNumberToken()
 424
 425     def __GetNList(self, InArray=False):
 426         self._GetSingleToken()
 427         if not self.__IsHexLiteral():
 428             if InArray:
 429                 raise BadExpression(ERR_ARRAY_ELE % self._Token)
 430             return self._Token
 431
 432         self.__SkipWS()
 433         Expr = self._Expr[self._Idx:]
 434         if not Expr.startswith(','):
 435             return self._Token
 436
 437         NList = self._LiteralToken
 438         while Expr.startswith(','):
 439             NList += ','
 440             self._Idx += 1
 441             self.__SkipWS()
 442             self._GetSingleToken()
 443             if not self.__IsHexLiteral():
 444                 raise BadExpression(ERR_ARRAY_ELE % self._Token)
 445             NList += self._LiteralToken
 446             self.__SkipWS()
 447             Expr = self._Expr[self._Idx:]
 448         self._Token = self._LiteralToken = NList
 449         return self._Token
 450
 451     def __IsHexLiteral(self):
 452         if self._LiteralToken.startswith('{') and \
 453             self._LiteralToken.endswith('}'):
 454             return True
 455
 456         if self.HexPattern.match(self._LiteralToken):
 457             Token = self._LiteralToken[2:]
 458             Token = Token.lstrip('0')
 459             if not Token:
 460                 self._LiteralToken = '0x0'
 461             else:
 462                 self._LiteralToken = '0x' + Token
 463             return True
 464         return False
 465
 466     def _GetToken(self):
 467         return self.__GetNList()
 468
 469     @staticmethod
 470     def __IsIdChar(Ch):
 471         return Ch in '._/:' or Ch.isalnum()
 472
 473     # Parse operand
 474     def _GetSingleToken(self):
 475         self.__SkipWS()
 476         Expr = self._Expr[self._Idx:]
 477         if Expr.startswith('L"'):
 478             # Skip L
 479             self._Idx += 1
 480             UStr = self.__GetString()
 481             self._Token = 'L"' + UStr + '"'
 482             return self._Token
 483
 484         self._Token = ''
 485         if Expr:
 486             Ch = Expr[0]
 487             Match = self.RegGuidPattern.match(Expr)
 488             if Match and not Expr[Match.end():Match.end()+1].isalnum() \
 489                 and Expr[Match.end():Match.end()+1] != '_':
 490                 self._Idx += Match.end()
 491                 self._Token = ValueExpression(GuidStringToGuidStructureString(Expr[0:Match.end()]))()
 492                 return self._Token
 493             elif self.__IsIdChar(Ch):
 494                 return self.__GetIdToken()
 495             elif Ch == '"':
 496                 return self.__GetString()
 497             elif Ch == '{':
 498                 return self.__GetArray()
 499             elif Ch == '(' or Ch == ')':
 500                 self._Idx += 1
 501                 self._Token = Ch
 502                 return self._Token
 503
 504         raise BadExpression(ERR_VALID_TOKEN % Expr)
 505
 506     # Parse operator
 507     def _GetOperator(self):
 508         self.__SkipWS()
 509         LegalOpLst = ['&&', '||', '!=', '==', '>=', '<='] + self.NonLetterOpLst
 510
 511         self._Token = ''
 512         Expr = self._Expr[self._Idx:]
 513
 514         # Reach end of expression
 515         if not Expr:
 516             return ''
 517
 518         # Script operator: LT, GT, LE, GE, EQ, NE, and, or, xor, not
 519         if Expr[0].isalpha():
 520             return self.__GetIdToken(True)
 521
 522         # Start to get regular operator: +, -, <, > ...
 523         if Expr[0] not in self.NonLetterOpLst:
 524             return ''
 525
 526         OpToken = ''
 527         for Ch in Expr:
 528             if Ch in self.NonLetterOpLst:
 529                 if '!' == Ch and OpToken in ['!=', '!']:
 530                     break
 531                 self._Idx += 1
 532                 OpToken += Ch
 533             else:
 534                 break
 535
 536         if OpToken not in LegalOpLst:
 537             raise BadExpression(ERR_OPERATOR_UNSUPPORT % OpToken)
 538         self._Token = OpToken
 539         return OpToken
 540
 541     # Check if current token matches the operators given from OpList
 542     def _IsOperator(self, OpList):
 543         Idx = self._Idx
 544         self._GetOperator()
 545         if self._Token in OpList:
 546             if self._Token in self.LogicalOperators:
 547                 self._Token = self.LogicalOperators[self._Token]
 548             return True
 549         self._Idx = Idx
 550         return False
 551
 552 if __name__ == '__main__':
 553     pass
 554
 555