[thirdparty/qemu.git] / scripts / qapi / common.py

#
# QAPI helper library
#
# Copyright IBM, Corp. 2011
# Copyright (c) 2013-2018 Red Hat Inc.
#
# Authors:
#  Anthony Liguori <aliguori@us.ibm.com>
#  Markus Armbruster <armbru@redhat.com>
#
# This work is licensed under the terms of the GNU GPL, version 2.
# See the COPYING file in the top-level directory.

import re
from typing import (
    Any,
    Dict,
    Match,
    Optional,
    Sequence,
    Union,
)


#: Magic string that gets removed along with all space to its right.
EATSPACE = '\033EATSPACE.'
POINTER_SUFFIX = ' *' + EATSPACE


def camel_to_upper(value: str) -> str:
    """
    Converts CamelCase to CAMEL_CASE.

    Examples::

        ENUMName -> ENUM_NAME
        EnumName1 -> ENUM_NAME1
        ENUM_NAME -> ENUM_NAME
        ENUM_NAME1 -> ENUM_NAME1
        ENUM_Name2 -> ENUM_NAME2
        ENUM24_Name -> ENUM24_NAME
    """
    ret = value[0]
    upc = value[0].isupper()

    # Copy remainder of ``value`` to ``ret`` with '_' inserted
    for ch in value[1:]:
        if ch.isupper() == upc:
            pass
        elif upc:
            # ``ret`` ends in upper case, next char isn't: insert '_'
            # before the last upper case char unless there is one
            # already, or it's at the beginning
            if len(ret) > 2 and ret[-2].isalnum():
                ret = ret[:-1] + '_' + ret[-1]
        else:
            # ``ret`` doesn't end in upper case, next char is: insert
            # '_' before it
            if ret[-1].isalnum():
                ret += '_'
        ret += ch
        upc = ch.isupper()

    return c_name(ret.upper()).lstrip('_')


def c_enum_const(type_name: str,
                 const_name: str,
                 prefix: Optional[str] = None) -> str:
    """
    Generate a C enumeration constant name.

    :param type_name: The name of the enumeration.
    :param const_name: The name of this constant.
    :param prefix: Optional, prefix that overrides the type_name.
    """
    if prefix is None:
        prefix = camel_to_upper(type_name)
    return prefix + '_' + c_name(const_name, False).upper()


def c_name(name: str, protect: bool = True) -> str:
    """
    Map ``name`` to a valid C identifier.

    Used for converting 'name' from a 'name':'type' qapi definition
    into a generated struct member, as well as converting type names
    into substrings of a generated C function name.

    '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
    protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'

    :param name: The name to map.
    :param protect: If true, avoid returning certain ticklish identifiers
                    (like C keywords) by prepending ``q_``.
    """
    # ANSI X3J11/88-090, 3.1.1
    c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
                     'default', 'do', 'double', 'else', 'enum', 'extern',
                     'float', 'for', 'goto', 'if', 'int', 'long', 'register',
                     'return', 'short', 'signed', 'sizeof', 'static',
                     'struct', 'switch', 'typedef', 'union', 'unsigned',
                     'void', 'volatile', 'while'])
    # ISO/IEC 9899:1999, 6.4.1
    c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
    # ISO/IEC 9899:2011, 6.4.1
    c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic',
                     '_Noreturn', '_Static_assert', '_Thread_local'])
    # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
    # excluding _.*
    gcc_words = set(['asm', 'typeof'])
    # C++ ISO/IEC 14882:2003 2.11
    cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete',
                     'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
                     'namespace', 'new', 'operator', 'private', 'protected',
                     'public', 'reinterpret_cast', 'static_cast', 'template',
                     'this', 'throw', 'true', 'try', 'typeid', 'typename',
                     'using', 'virtual', 'wchar_t',
                     # alternative representations
                     'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
                     'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
    # namespace pollution:
    polluted_words = set(['unix', 'errno', 'mips', 'sparc', 'i386', 'linux'])
    name = re.sub(r'[^A-Za-z0-9_]', '_', name)
    if protect and (name in (c89_words | c99_words | c11_words | gcc_words
                             | cpp_words | polluted_words)
                    or name[0].isdigit()):
        return 'q_' + name
    return name


class Indentation:
    """
    Indentation level management.

    :param initial: Initial number of spaces, default 0.
    """
    def __init__(self, initial: int = 0) -> None:
        self._level = initial

    def __repr__(self) -> str:
        return "{}({:d})".format(type(self).__name__, self._level)

    def __str__(self) -> str:
        """Return the current indentation as a string of spaces."""
        return ' ' * self._level

    def increase(self, amount: int = 4) -> None:
        """Increase the indentation level by ``amount``, default 4."""
        self._level += amount

    def decrease(self, amount: int = 4) -> None:
        """Decrease the indentation level by ``amount``, default 4."""
        assert amount <= self._level
        self._level -= amount


#: Global, current indent level for code generation.
indent = Indentation()


def cgen(code: str, **kwds: object) -> str:
    """
    Generate ``code`` with ``kwds`` interpolated.

    Obey `indent`, and strip `EATSPACE`.
    """
    raw = code % kwds
    pfx = str(indent)
    if pfx:
        raw = re.sub(r'^(?!(#|$))', pfx, raw, flags=re.MULTILINE)
    return re.sub(re.escape(EATSPACE) + r' *', '', raw)


def mcgen(code: str, **kwds: object) -> str:
    if code[0] == '\n':
        code = code[1:]
    return cgen(code, **kwds)


def c_fname(filename: str) -> str:
    return re.sub(r'[^A-Za-z0-9_]', '_', filename)


def guardstart(name: str) -> str:
    return mcgen('''
#ifndef %(name)s
#define %(name)s

''',
                 name=c_fname(name).upper())


def guardend(name: str) -> str:
    return mcgen('''

#endif /* %(name)s */
''',
                 name=c_fname(name).upper())


def gen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]],
               cond_fmt: str, not_fmt: str,
               all_operator: str, any_operator: str) -> str:

    def do_gen(ifcond: Union[str, Dict[str, Any]],
               need_parens: bool) -> str:
        if isinstance(ifcond, str):
            return cond_fmt % ifcond
        assert isinstance(ifcond, dict) and len(ifcond) == 1
        if 'not' in ifcond:
            return not_fmt % do_gen(ifcond['not'], True)
        if 'all' in ifcond:
            gen = gen_infix(all_operator, ifcond['all'])
        else:
            gen = gen_infix(any_operator, ifcond['any'])
        if need_parens:
            gen = '(' + gen + ')'
        return gen

    def gen_infix(operator: str, operands: Sequence[Any]) -> str:
        return operator.join([do_gen(o, True) for o in operands])

    if not ifcond:
        return ''
    return do_gen(ifcond, False)


def cgen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]]) -> str:
    return gen_ifcond(ifcond, 'defined(%s)', '!%s', ' && ', ' || ')


def docgen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]]) -> str:
    # TODO Doc generated for conditions needs polish
    return gen_ifcond(ifcond, '%s', 'not %s', ' and ', ' or ')


def gen_if(cond: str) -> str:
    if not cond:
        return ''
    return mcgen('''
#if %(cond)s
''', cond=cond)


def gen_endif(cond: str) -> str:
    if not cond:
        return ''
    return mcgen('''
#endif /* %(cond)s */
''', cond=cond)


def must_match(pattern: str, string: str) -> Match[str]:
    match = re.match(pattern, string)
    assert match is not None
    return match
Commit	Line	Data
	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 (
	16	Any,
	17	Dict,
	18	Match,
	19	Optional,
	20	Sequence,
	21	Union,
	22	)
	23
	24
	25	#: Magic string that gets removed along with all space to its right.
	26	EATSPACE = '\033EATSPACE.'
	27	POINTER_SUFFIX = ' *' + EATSPACE
	28
	29
	30	def camel_to_upper(value: str) -> str:
	31	"""
	32	Converts CamelCase to CAMEL_CASE.
	33
	34	Examples::
	35
	36	ENUMName -> ENUM_NAME
	37	EnumName1 -> ENUM_NAME1
	38	ENUM_NAME -> ENUM_NAME
	39	ENUM_NAME1 -> ENUM_NAME1
	40	ENUM_Name2 -> ENUM_NAME2
	41	ENUM24_Name -> ENUM24_NAME
	42	"""
	43	ret = value[0]
	44	upc = value[0].isupper()
	45
	46	# Copy remainder of ``value`` to ``ret`` with '_' inserted
	47	for ch in value[1:]:
	48	if ch.isupper() == upc:
	49	pass
	50	elif upc:
	51	# ``ret`` ends in upper case, next char isn't: insert '_'
	52	# before the last upper case char unless there is one
	53	# already, or it's at the beginning
	54	if len(ret) > 2 and ret[-2].isalnum():
	55	ret = ret[:-1] + '_' + ret[-1]
	56	else:
	57	# ``ret`` doesn't end in upper case, next char is: insert
	58	# '_' before it
	59	if ret[-1].isalnum():
	60	ret += '_'
	61	ret += ch
	62	upc = ch.isupper()
	63
	64	return c_name(ret.upper()).lstrip('_')
	65
	66
	67	def c_enum_const(type_name: str,
	68	const_name: str,
	69	prefix: Optional[str] = None) -> str:
	70	"""
	71	Generate a C enumeration constant name.
	72
	73	:param type_name: The name of the enumeration.
	74	:param const_name: The name of this constant.
	75	:param prefix: Optional, prefix that overrides the type_name.
	76	"""
	77	if prefix is None:
	78	prefix = camel_to_upper(type_name)
	79	return prefix + '_' + c_name(const_name, False).upper()
	80
	81
	82	def c_name(name: str, protect: bool = True) -> str:
	83	"""
	84	Map ``name`` to a valid C identifier.
	85
	86	Used for converting 'name' from a 'name':'type' qapi definition
	87	into a generated struct member, as well as converting type names
	88	into substrings of a generated C function name.
	89
	90	'__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
	91	protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
	92
	93	:param name: The name to map.
	94	:param protect: If true, avoid returning certain ticklish identifiers
	95	(like C keywords) by prepending ``q_``.
	96	"""
	97	# ANSI X3J11/88-090, 3.1.1
	98	c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
	99	'default', 'do', 'double', 'else', 'enum', 'extern',
	100	'float', 'for', 'goto', 'if', 'int', 'long', 'register',
	101	'return', 'short', 'signed', 'sizeof', 'static',
	102	'struct', 'switch', 'typedef', 'union', 'unsigned',
	103	'void', 'volatile', 'while'])
	104	# ISO/IEC 9899:1999, 6.4.1
	105	c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
	106	# ISO/IEC 9899:2011, 6.4.1
	107	c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic',
	108	'_Noreturn', '_Static_assert', '_Thread_local'])
	109	# GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
	110	# excluding _.*
	111	gcc_words = set(['asm', 'typeof'])
	112	# C++ ISO/IEC 14882:2003 2.11
	113	cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete',
	114	'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
	115	'namespace', 'new', 'operator', 'private', 'protected',
	116	'public', 'reinterpret_cast', 'static_cast', 'template',
	117	'this', 'throw', 'true', 'try', 'typeid', 'typename',
	118	'using', 'virtual', 'wchar_t',
	119	# alternative representations
	120	'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
	121	'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
	122	# namespace pollution:
	123	polluted_words = set(['unix', 'errno', 'mips', 'sparc', 'i386', 'linux'])
	124	name = re.sub(r'[^A-Za-z0-9_]', '_', name)
	125	if protect and (name in (c89_words \| c99_words \| c11_words \| gcc_words
	126	\| cpp_words \| polluted_words)
	127	or name[0].isdigit()):
	128	return 'q_' + name
	129	return name
	130
	131
	132	class Indentation:
	133	"""
	134	Indentation level management.
	135
	136	:param initial: Initial number of spaces, default 0.
	137	"""
	138	def __init__(self, initial: int = 0) -> None:
	139	self._level = initial
	140
	141	def __repr__(self) -> str:
	142	return "{}({:d})".format(type(self).__name__, self._level)
	143
	144	def __str__(self) -> str:
	145	"""Return the current indentation as a string of spaces."""
	146	return ' ' * self._level
	147
	148	def increase(self, amount: int = 4) -> None:
	149	"""Increase the indentation level by ``amount``, default 4."""
	150	self._level += amount
	151
	152	def decrease(self, amount: int = 4) -> None:
	153	"""Decrease the indentation level by ``amount``, default 4."""
	154	assert amount <= self._level
	155	self._level -= amount
	156
	157
	158	#: Global, current indent level for code generation.
	159	indent = Indentation()
	160
	161
	162	def cgen(code: str, **kwds: object) -> str:
	163	"""
	164	Generate ``code`` with ``kwds`` interpolated.
	165
	166	Obey `indent`, and strip `EATSPACE`.
	167	"""
	168	raw = code % kwds
	169	pfx = str(indent)
	170	if pfx:
	171	raw = re.sub(r'^(?!(#\|$))', pfx, raw, flags=re.MULTILINE)
	172	return re.sub(re.escape(EATSPACE) + r' *', '', raw)
	173
	174
	175	def mcgen(code: str, **kwds: object) -> str:
	176	if code[0] == '\n':
	177	code = code[1:]
	178	return cgen(code, **kwds)
	179
	180
	181	def c_fname(filename: str) -> str:
	182	return re.sub(r'[^A-Za-z0-9_]', '_', filename)
	183
	184
	185	def guardstart(name: str) -> str:
	186	return mcgen('''
	187	#ifndef %(name)s
	188	#define %(name)s
	189
	190	''',
	191	name=c_fname(name).upper())
	192
	193
	194	def guardend(name: str) -> str:
	195	return mcgen('''
	196
	197	#endif /* %(name)s */
	198	''',
	199	name=c_fname(name).upper())
	200
	201
	202	def gen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]],
	203	cond_fmt: str, not_fmt: str,
	204	all_operator: str, any_operator: str) -> str:
	205
	206	def do_gen(ifcond: Union[str, Dict[str, Any]],
	207	need_parens: bool) -> str:
	208	if isinstance(ifcond, str):
	209	return cond_fmt % ifcond
	210	assert isinstance(ifcond, dict) and len(ifcond) == 1
	211	if 'not' in ifcond:
	212	return not_fmt % do_gen(ifcond['not'], True)
	213	if 'all' in ifcond:
	214	gen = gen_infix(all_operator, ifcond['all'])
	215	else:
	216	gen = gen_infix(any_operator, ifcond['any'])
	217	if need_parens:
	218	gen = '(' + gen + ')'
	219	return gen
	220
	221	def gen_infix(operator: str, operands: Sequence[Any]) -> str:
	222	return operator.join([do_gen(o, True) for o in operands])
	223
	224	if not ifcond:
	225	return ''
	226	return do_gen(ifcond, False)
	227
	228
	229	def cgen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]]) -> str:
	230	return gen_ifcond(ifcond, 'defined(%s)', '!%s', ' && ', ' \|\| ')
	231
	232
	233	def docgen_ifcond(ifcond: Optional[Union[str, Dict[str, Any]]]) -> str:
	234	# TODO Doc generated for conditions needs polish
	235	return gen_ifcond(ifcond, '%s', 'not %s', ' and ', ' or ')
	236
	237
	238	def gen_if(cond: str) -> str:
	239	if not cond:
	240	return ''
	241	return mcgen('''
	242	#if %(cond)s
	243	''', cond=cond)
	244
	245
	246	def gen_endif(cond: str) -> str:
	247	if not cond:
	248	return ''
	249	return mcgen('''
	250	#endif /* %(cond)s */
	251	''', cond=cond)
	252
	253
	254	def must_match(pattern: str, string: str) -> Match[str]:
	255	match = re.match(pattern, string)
	256	assert match is not None
	257	return match