scripts/qapi/common.py

   1 #
   2 # QAPI helper library
   3 #
   4 # Copyright IBM, Corp. 2011
   5 # Copyright (c) 2013-2018 Red Hat Inc.
   6 #
   7 # Authors:
   8 #  Anthony Liguori <aliguori@us.ibm.com>
   9 #  Markus Armbruster <armbru@redhat.com>
  10 #
  11 # This work is licensed under the terms of the GNU GPL, version 2.
  12 # See the COPYING file in the top-level directory.
  13
  14 import re
  15 from typing import Optional, Sequence
  16
  17
  18 #: Magic string that gets removed along with all space to its right.
  19 EATSPACE = '\033EATSPACE.'
  20 POINTER_SUFFIX = ' *' + EATSPACE
  21 _C_NAME_TRANS = str.maketrans('.-', '__')
  22
  23
  24 def camel_to_upper(value: str) -> str:
  25     """
  26     Converts CamelCase to CAMEL_CASE.
  27
  28     Examples::
  29
  30         ENUMName -> ENUM_NAME
  31         EnumName1 -> ENUM_NAME1
  32         ENUM_NAME -> ENUM_NAME
  33         ENUM_NAME1 -> ENUM_NAME1
  34         ENUM_Name2 -> ENUM_NAME2
  35         ENUM24_Name -> ENUM24_NAME
  36     """
  37     c_fun_str = c_name(value, False)
  38     if value.isupper():
  39         return c_fun_str
  40
  41     new_name = ''
  42     length = len(c_fun_str)
  43     for i in range(length):
  44         char = c_fun_str[i]
  45         # When char is upper case and no '_' appears before, do more checks
  46         if char.isupper() and (i > 0) and c_fun_str[i - 1] != '_':
  47             if i < length - 1 and c_fun_str[i + 1].islower():
  48                 new_name += '_'
  49             elif c_fun_str[i - 1].isdigit():
  50                 new_name += '_'
  51         new_name += char
  52     return new_name.lstrip('_').upper()
  53
  54
  55 def c_enum_const(type_name: str,
  56                  const_name: str,
  57                  prefix: Optional[str] = None) -> str:
  58     """
  59     Generate a C enumeration constant name.
  60
  61     :param type_name: The name of the enumeration.
  62     :param const_name: The name of this constant.
  63     :param prefix: Optional, prefix that overrides the type_name.
  64     """
  65     if prefix is not None:
  66         type_name = prefix
  67     return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper()
  68
  69
  70 def c_name(name: str, protect: bool = True) -> str:
  71     """
  72     Map ``name`` to a valid C identifier.
  73
  74     Used for converting 'name' from a 'name':'type' qapi definition
  75     into a generated struct member, as well as converting type names
  76     into substrings of a generated C function name.
  77
  78     '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
  79     protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
  80
  81     :param name: The name to map.
  82     :param protect: If true, avoid returning certain ticklish identifiers
  83                     (like C keywords) by prepending ``q_``.
  84     """
  85     # ANSI X3J11/88-090, 3.1.1
  86     c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
  87                      'default', 'do', 'double', 'else', 'enum', 'extern',
  88                      'float', 'for', 'goto', 'if', 'int', 'long', 'register',
  89                      'return', 'short', 'signed', 'sizeof', 'static',
  90                      'struct', 'switch', 'typedef', 'union', 'unsigned',
  91                      'void', 'volatile', 'while'])
  92     # ISO/IEC 9899:1999, 6.4.1
  93     c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
  94     # ISO/IEC 9899:2011, 6.4.1
  95     c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic',
  96                      '_Noreturn', '_Static_assert', '_Thread_local'])
  97     # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
  98     # excluding _.*
  99     gcc_words = set(['asm', 'typeof'])
 100     # C++ ISO/IEC 14882:2003 2.11
 101     cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete',
 102                      'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
 103                      'namespace', 'new', 'operator', 'private', 'protected',
 104                      'public', 'reinterpret_cast', 'static_cast', 'template',
 105                      'this', 'throw', 'true', 'try', 'typeid', 'typename',
 106                      'using', 'virtual', 'wchar_t',
 107                      # alternative representations
 108                      'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
 109                      'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
 110     # namespace pollution:
 111     polluted_words = set(['unix', 'errno', 'mips', 'sparc', 'i386'])
 112     name = name.translate(_C_NAME_TRANS)
 113     if protect and (name in c89_words | c99_words | c11_words | gcc_words
 114                     | cpp_words | polluted_words):
 115         return 'q_' + name
 116     return name
 117
 118
 119 class Indentation:
 120     """
 121     Indentation level management.
 122
 123     :param initial: Initial number of spaces, default 0.
 124     """
 125     def __init__(self, initial: int = 0) -> None:
 126         self._level = initial
 127
 128     def __int__(self) -> int:
 129         return self._level
 130
 131     def __repr__(self) -> str:
 132         return "{}({:d})".format(type(self).__name__, self._level)
 133
 134     def __str__(self) -> str:
 135         """Return the current indentation as a string of spaces."""
 136         return ' ' * self._level
 137
 138     def __bool__(self) -> bool:
 139         """True when there is a non-zero indentation."""
 140         return bool(self._level)
 141
 142     def increase(self, amount: int = 4) -> None:
 143         """Increase the indentation level by ``amount``, default 4."""
 144         self._level += amount
 145
 146     def decrease(self, amount: int = 4) -> None:
 147         """Decrease the indentation level by ``amount``, default 4."""
 148         if self._level < amount:
 149             raise ArithmeticError(
 150                 f"Can't remove {amount:d} spaces from {self!r}")
 151         self._level -= amount
 152
 153
 154 #: Global, current indent level for code generation.
 155 indent = Indentation()
 156
 157
 158 def cgen(code: str, **kwds: object) -> str:
 159     """
 160     Generate ``code`` with ``kwds`` interpolated.
 161
 162     Obey `indent`, and strip `EATSPACE`.
 163     """
 164     raw = code % kwds
 165     if indent:
 166         raw = re.sub(r'^(?!(#|$))', str(indent), raw, flags=re.MULTILINE)
 167     return re.sub(re.escape(EATSPACE) + r' *', '', raw)
 168
 169
 170 def mcgen(code: str, **kwds: object) -> str:
 171     if code[0] == '\n':
 172         code = code[1:]
 173     return cgen(code, **kwds)
 174
 175
 176 def c_fname(filename: str) -> str:
 177     return re.sub(r'[^A-Za-z0-9_]', '_', filename)
 178
 179
 180 def guardstart(name: str) -> str:
 181     return mcgen('''
 182 #ifndef %(name)s
 183 #define %(name)s
 184
 185 ''',
 186                  name=c_fname(name).upper())
 187
 188
 189 def guardend(name: str) -> str:
 190     return mcgen('''
 191
 192 #endif /* %(name)s */
 193 ''',
 194                  name=c_fname(name).upper())
 195
 196
 197 def gen_if(ifcond: Sequence[str]) -> str:
 198     ret = ''
 199     for ifc in ifcond:
 200         ret += mcgen('''
 201 #if %(cond)s
 202 ''', cond=ifc)
 203     return ret
 204
 205
 206 def gen_endif(ifcond: Sequence[str]) -> str:
 207     ret = ''
 208     for ifc in reversed(ifcond):
 209         ret += mcgen('''
 210 #endif /* %(cond)s */
 211 ''', cond=ifc)
 212     return ret