1 # -*- coding: utf-8 -*-
3 # Check (context-free) QAPI schema expression structure
5 # Copyright IBM, Corp. 2011
6 # Copyright (c) 2013-2019 Red Hat Inc.
9 # Anthony Liguori <aliguori@us.ibm.com>
10 # Markus Armbruster <armbru@redhat.com>
11 # Eric Blake <eblake@redhat.com>
12 # Marc-André Lureau <marcandre.lureau@redhat.com>
14 # This work is licensed under the terms of the GNU GPL, version 2.
15 # See the COPYING file in the top-level directory.
17 from collections
import OrderedDict
20 from .common
import c_name
21 from .error
import QAPISemError
24 # Names must be letters, numbers, -, and _. They must start with letter,
25 # except for downstream extensions which must start with __RFQDN_.
26 # Dots are only valid in the downstream extension prefix.
27 valid_name
= re
.compile(r
'^(__[a-zA-Z0-9.-]+_)?'
28 '[a-zA-Z][a-zA-Z0-9_-]*$')
31 def check_name_is_str(name
, info
, source
):
32 if not isinstance(name
, str):
33 raise QAPISemError(info
, "%s requires a string name" % source
)
36 def check_name_str(name
, info
, source
,
37 allow_optional
=False, enum_member
=False,
41 if allow_optional
and name
.startswith('*'):
43 # Enum members can start with a digit, because the generated C
44 # code always prefixes it with the enum name
45 if enum_member
and membername
[0].isdigit():
46 membername
= 'D' + membername
47 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
48 # and 'q_obj_*' implicit type names.
49 if not valid_name
.match(membername
) or \
50 c_name(membername
, False).startswith('q_'):
51 raise QAPISemError(info
, "%s has an invalid name" % source
)
52 if not permit_upper
and name
.lower() != name
:
54 info
, "%s uses uppercase in name" % source
)
55 assert not membername
.startswith('*')
58 def check_defn_name_str(name
, info
, meta
):
59 check_name_str(name
, info
, meta
, permit_upper
=True)
60 if name
.endswith('Kind') or name
.endswith('List'):
62 info
, "%s name should not end in '%s'" % (meta
, name
[-4:]))
65 def check_keys(value
, info
, source
, required
, optional
):
68 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
70 missing
= set(required
) - set(value
)
75 % (source
, 's' if len(missing
) > 1 else '',
77 allowed
= set(required
+ optional
)
78 unknown
= set(value
) - allowed
82 "%s has unknown key%s %s\nValid keys are %s."
83 % (source
, 's' if len(unknown
) > 1 else '',
84 pprint(unknown
), pprint(allowed
)))
87 def check_flags(expr
, info
):
88 for key
in ['gen', 'success-response']:
89 if key
in expr
and expr
[key
] is not False:
91 info
, "flag '%s' may only use false value" % key
)
92 for key
in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']:
93 if key
in expr
and expr
[key
] is not True:
95 info
, "flag '%s' may only use true value" % key
)
96 if 'allow-oob' in expr
and 'coroutine' in expr
:
97 # This is not necessarily a fundamental incompatibility, but
98 # we don't have a use case and the desired semantics isn't
99 # obvious. The simplest solution is to forbid it until we get
101 raise QAPISemError(info
, "flags 'allow-oob' and 'coroutine' "
105 def check_if(expr
, info
, source
):
107 def check_if_str(ifcond
, info
):
108 if not isinstance(ifcond
, str):
111 "'if' condition of %s must be a string or a list of strings"
113 if ifcond
.strip() == '':
116 "'if' condition '%s' of %s makes no sense"
119 ifcond
= expr
.get('if')
122 if isinstance(ifcond
, list):
125 info
, "'if' condition [] of %s is useless" % source
)
127 check_if_str(elt
, info
)
129 check_if_str(ifcond
, info
)
130 expr
['if'] = [ifcond
]
133 def normalize_members(members
):
134 if isinstance(members
, OrderedDict
):
135 for key
, arg
in members
.items():
136 if isinstance(arg
, dict):
138 members
[key
] = {'type': arg
}
141 def check_type(value
, info
, source
,
142 allow_array
=False, allow_dict
=False):
147 if isinstance(value
, list):
149 raise QAPISemError(info
, "%s cannot be an array" % source
)
150 if len(value
) != 1 or not isinstance(value
[0], str):
151 raise QAPISemError(info
,
152 "%s: array type must contain single type name" %
157 if isinstance(value
, str):
163 raise QAPISemError(info
, "%s should be a type name" % source
)
165 if not isinstance(value
, OrderedDict
):
166 raise QAPISemError(info
,
167 "%s should be an object or type name" % source
)
169 permit_upper
= allow_dict
in info
.pragma
.name_case_whitelist
171 # value is a dictionary, check that each member is okay
172 for (key
, arg
) in value
.items():
173 key_source
= "%s member '%s'" % (source
, key
)
174 check_name_str(key
, info
, key_source
,
175 allow_optional
=True, permit_upper
=permit_upper
)
176 if c_name(key
, False) == 'u' or c_name(key
, False).startswith('has_'):
177 raise QAPISemError(info
, "%s uses reserved name" % key_source
)
178 check_keys(arg
, info
, key_source
, ['type'], ['if', 'features'])
179 check_if(arg
, info
, key_source
)
180 check_features(arg
.get('features'), info
)
181 check_type(arg
['type'], info
, key_source
, allow_array
=True)
184 def check_features(features
, info
):
187 if not isinstance(features
, list):
188 raise QAPISemError(info
, "'features' must be an array")
189 features
[:] = [f
if isinstance(f
, dict) else {'name': f
}
192 source
= "'features' member"
193 assert isinstance(f
, dict)
194 check_keys(f
, info
, source
, ['name'], ['if'])
195 check_name_is_str(f
['name'], info
, source
)
196 source
= "%s '%s'" % (source
, f
['name'])
197 check_name_str(f
['name'], info
, source
)
198 check_if(f
, info
, source
)
201 def check_enum(expr
, info
):
203 members
= expr
['data']
204 prefix
= expr
.get('prefix')
206 if not isinstance(members
, list):
207 raise QAPISemError(info
, "'data' must be an array")
208 if prefix
is not None and not isinstance(prefix
, str):
209 raise QAPISemError(info
, "'prefix' must be a string")
211 permit_upper
= name
in info
.pragma
.name_case_whitelist
213 members
[:] = [m
if isinstance(m
, dict) else {'name': m
}
215 for member
in members
:
216 source
= "'data' member"
217 check_keys(member
, info
, source
, ['name'], ['if'])
218 check_name_is_str(member
['name'], info
, source
)
219 source
= "%s '%s'" % (source
, member
['name'])
220 check_name_str(member
['name'], info
, source
,
221 enum_member
=True, permit_upper
=permit_upper
)
222 check_if(member
, info
, source
)
225 def check_struct(expr
, info
):
226 name
= expr
['struct']
227 members
= expr
['data']
229 check_type(members
, info
, "'data'", allow_dict
=name
)
230 check_type(expr
.get('base'), info
, "'base'")
233 def check_union(expr
, info
):
235 base
= expr
.get('base')
236 discriminator
= expr
.get('discriminator')
237 members
= expr
['data']
239 if discriminator
is None: # simple union
241 raise QAPISemError(info
, "'base' requires 'discriminator'")
243 check_type(base
, info
, "'base'", allow_dict
=name
)
245 raise QAPISemError(info
, "'discriminator' requires 'base'")
246 check_name_is_str(discriminator
, info
, "'discriminator'")
248 for (key
, value
) in members
.items():
249 source
= "'data' member '%s'" % key
250 check_name_str(key
, info
, source
)
251 check_keys(value
, info
, source
, ['type'], ['if'])
252 check_if(value
, info
, source
)
253 check_type(value
['type'], info
, source
, allow_array
=not base
)
256 def check_alternate(expr
, info
):
257 members
= expr
['data']
260 raise QAPISemError(info
, "'data' must not be empty")
261 for (key
, value
) in members
.items():
262 source
= "'data' member '%s'" % key
263 check_name_str(key
, info
, source
)
264 check_keys(value
, info
, source
, ['type'], ['if'])
265 check_if(value
, info
, source
)
266 check_type(value
['type'], info
, source
)
269 def check_command(expr
, info
):
270 args
= expr
.get('data')
271 rets
= expr
.get('returns')
272 boxed
= expr
.get('boxed', False)
274 if boxed
and args
is None:
275 raise QAPISemError(info
, "'boxed': true requires 'data'")
276 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
277 check_type(rets
, info
, "'returns'", allow_array
=True)
280 def check_event(expr
, info
):
281 args
= expr
.get('data')
282 boxed
= expr
.get('boxed', False)
284 if boxed
and args
is None:
285 raise QAPISemError(info
, "'boxed': true requires 'data'")
286 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
289 def check_exprs(exprs
):
290 for expr_elem
in exprs
:
291 expr
= expr_elem
['expr']
292 info
= expr_elem
['info']
293 doc
= expr_elem
.get('doc')
295 if 'include' in expr
:
300 elif 'union' in expr
:
302 elif 'alternate' in expr
:
304 elif 'struct' in expr
:
306 elif 'command' in expr
:
308 elif 'event' in expr
:
311 raise QAPISemError(info
, "expression is missing metatype")
314 check_name_is_str(name
, info
, "'%s'" % meta
)
315 info
.set_defn(meta
, name
)
316 check_defn_name_str(name
, info
, meta
)
319 if doc
.symbol
!= name
:
321 info
, "documentation comment is for '%s'" % doc
.symbol
)
323 elif info
.pragma
.doc_required
:
324 raise QAPISemError(info
,
325 "documentation comment required")
328 check_keys(expr
, info
, meta
,
329 ['enum', 'data'], ['if', 'features', 'prefix'])
330 check_enum(expr
, info
)
331 elif meta
== 'union':
332 check_keys(expr
, info
, meta
,
334 ['base', 'discriminator', 'if', 'features'])
335 normalize_members(expr
.get('base'))
336 normalize_members(expr
['data'])
337 check_union(expr
, info
)
338 elif meta
== 'alternate':
339 check_keys(expr
, info
, meta
,
340 ['alternate', 'data'], ['if', 'features'])
341 normalize_members(expr
['data'])
342 check_alternate(expr
, info
)
343 elif meta
== 'struct':
344 check_keys(expr
, info
, meta
,
345 ['struct', 'data'], ['base', 'if', 'features'])
346 normalize_members(expr
['data'])
347 check_struct(expr
, info
)
348 elif meta
== 'command':
349 check_keys(expr
, info
, meta
,
351 ['data', 'returns', 'boxed', 'if', 'features',
352 'gen', 'success-response', 'allow-oob',
353 'allow-preconfig', 'coroutine'])
354 normalize_members(expr
.get('data'))
355 check_command(expr
, info
)
356 elif meta
== 'event':
357 check_keys(expr
, info
, meta
,
358 ['event'], ['data', 'boxed', 'if', 'features'])
359 normalize_members(expr
.get('data'))
360 check_event(expr
, info
)
362 assert False, 'unexpected meta type'
364 check_if(expr
, info
, meta
)
365 check_features(expr
.get('features'), info
)
366 check_flags(expr
, info
)