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
,
41 # Enum members can start with a digit, because the generated C
42 # code always prefixes it with the enum name
43 if enum_member
and membername
[0].isdigit():
44 membername
= 'D' + membername
45 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
46 # and 'q_obj_*' implicit type names.
47 if not valid_name
.match(membername
) or \
48 c_name(membername
, False).startswith('q_'):
49 raise QAPISemError(info
, "%s has an invalid name" % source
)
50 if not permit_upper
and name
.lower() != name
:
52 info
, "%s uses uppercase in name" % source
)
55 def check_defn_name_str(name
, info
, meta
):
56 check_name_str(name
, info
, meta
, permit_upper
=True)
57 if name
.endswith('Kind') or name
.endswith('List'):
59 info
, "%s name should not end in '%s'" % (meta
, name
[-4:]))
62 def check_keys(value
, info
, source
, required
, optional
):
65 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
67 missing
= set(required
) - set(value
)
72 % (source
, 's' if len(missing
) > 1 else '',
74 allowed
= set(required
+ optional
)
75 unknown
= set(value
) - allowed
79 "%s has unknown key%s %s\nValid keys are %s."
80 % (source
, 's' if len(unknown
) > 1 else '',
81 pprint(unknown
), pprint(allowed
)))
84 def check_flags(expr
, info
):
85 for key
in ['gen', 'success-response']:
86 if key
in expr
and expr
[key
] is not False:
88 info
, "flag '%s' may only use false value" % key
)
89 for key
in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']:
90 if key
in expr
and expr
[key
] is not True:
92 info
, "flag '%s' may only use true value" % key
)
93 if 'allow-oob' in expr
and 'coroutine' in expr
:
94 # This is not necessarily a fundamental incompatibility, but
95 # we don't have a use case and the desired semantics isn't
96 # obvious. The simplest solution is to forbid it until we get
98 raise QAPISemError(info
, "flags 'allow-oob' and 'coroutine' "
102 def check_if(expr
, info
, source
):
104 def check_if_str(ifcond
, info
):
105 if not isinstance(ifcond
, str):
108 "'if' condition of %s must be a string or a list of strings"
110 if ifcond
.strip() == '':
113 "'if' condition '%s' of %s makes no sense"
116 ifcond
= expr
.get('if')
119 if isinstance(ifcond
, list):
122 info
, "'if' condition [] of %s is useless" % source
)
124 check_if_str(elt
, info
)
126 check_if_str(ifcond
, info
)
127 expr
['if'] = [ifcond
]
130 def normalize_members(members
):
131 if isinstance(members
, OrderedDict
):
132 for key
, arg
in members
.items():
133 if isinstance(arg
, dict):
135 members
[key
] = {'type': arg
}
138 def check_type(value
, info
, source
,
139 allow_array
=False, allow_dict
=False):
144 if isinstance(value
, list):
146 raise QAPISemError(info
, "%s cannot be an array" % source
)
147 if len(value
) != 1 or not isinstance(value
[0], str):
148 raise QAPISemError(info
,
149 "%s: array type must contain single type name" %
154 if isinstance(value
, str):
160 raise QAPISemError(info
, "%s should be a type name" % source
)
162 if not isinstance(value
, OrderedDict
):
163 raise QAPISemError(info
,
164 "%s should be an object or type name" % source
)
166 permit_upper
= allow_dict
in info
.pragma
.name_case_whitelist
168 # value is a dictionary, check that each member is okay
169 for (key
, arg
) in value
.items():
170 key_source
= "%s member '%s'" % (source
, key
)
171 if key
.startswith('*'):
173 check_name_str(key
, info
, key_source
,
174 permit_upper
=permit_upper
)
175 if c_name(key
, False) == 'u' or c_name(key
, False).startswith('has_'):
176 raise QAPISemError(info
, "%s uses reserved name" % key_source
)
177 check_keys(arg
, info
, key_source
, ['type'], ['if', 'features'])
178 check_if(arg
, info
, key_source
)
179 check_features(arg
.get('features'), info
)
180 check_type(arg
['type'], info
, key_source
, allow_array
=True)
183 def check_features(features
, info
):
186 if not isinstance(features
, list):
187 raise QAPISemError(info
, "'features' must be an array")
188 features
[:] = [f
if isinstance(f
, dict) else {'name': f
}
191 source
= "'features' member"
192 assert isinstance(f
, dict)
193 check_keys(f
, info
, source
, ['name'], ['if'])
194 check_name_is_str(f
['name'], info
, source
)
195 source
= "%s '%s'" % (source
, f
['name'])
196 check_name_str(f
['name'], info
, source
)
197 check_if(f
, info
, source
)
200 def check_enum(expr
, info
):
202 members
= expr
['data']
203 prefix
= expr
.get('prefix')
205 if not isinstance(members
, list):
206 raise QAPISemError(info
, "'data' must be an array")
207 if prefix
is not None and not isinstance(prefix
, str):
208 raise QAPISemError(info
, "'prefix' must be a string")
210 permit_upper
= name
in info
.pragma
.name_case_whitelist
212 members
[:] = [m
if isinstance(m
, dict) else {'name': m
}
214 for member
in members
:
215 source
= "'data' member"
216 check_keys(member
, info
, source
, ['name'], ['if'])
217 check_name_is_str(member
['name'], info
, source
)
218 source
= "%s '%s'" % (source
, member
['name'])
219 check_name_str(member
['name'], info
, source
,
220 enum_member
=True, permit_upper
=permit_upper
)
221 check_if(member
, info
, source
)
224 def check_struct(expr
, info
):
225 name
= expr
['struct']
226 members
= expr
['data']
228 check_type(members
, info
, "'data'", allow_dict
=name
)
229 check_type(expr
.get('base'), info
, "'base'")
232 def check_union(expr
, info
):
234 base
= expr
.get('base')
235 discriminator
= expr
.get('discriminator')
236 members
= expr
['data']
238 if discriminator
is None: # simple union
240 raise QAPISemError(info
, "'base' requires 'discriminator'")
242 check_type(base
, info
, "'base'", allow_dict
=name
)
244 raise QAPISemError(info
, "'discriminator' requires 'base'")
245 check_name_is_str(discriminator
, info
, "'discriminator'")
247 for (key
, value
) in members
.items():
248 source
= "'data' member '%s'" % key
249 check_name_str(key
, info
, source
)
250 check_keys(value
, info
, source
, ['type'], ['if'])
251 check_if(value
, info
, source
)
252 check_type(value
['type'], info
, source
, allow_array
=not base
)
255 def check_alternate(expr
, info
):
256 members
= expr
['data']
259 raise QAPISemError(info
, "'data' must not be empty")
260 for (key
, value
) in members
.items():
261 source
= "'data' member '%s'" % key
262 check_name_str(key
, info
, source
)
263 check_keys(value
, info
, source
, ['type'], ['if'])
264 check_if(value
, info
, source
)
265 check_type(value
['type'], info
, source
)
268 def check_command(expr
, info
):
269 args
= expr
.get('data')
270 rets
= expr
.get('returns')
271 boxed
= expr
.get('boxed', False)
273 if boxed
and args
is None:
274 raise QAPISemError(info
, "'boxed': true requires 'data'")
275 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
276 check_type(rets
, info
, "'returns'", allow_array
=True)
279 def check_event(expr
, info
):
280 args
= expr
.get('data')
281 boxed
= expr
.get('boxed', False)
283 if boxed
and args
is None:
284 raise QAPISemError(info
, "'boxed': true requires 'data'")
285 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
288 def check_exprs(exprs
):
289 for expr_elem
in exprs
:
290 expr
= expr_elem
['expr']
291 info
= expr_elem
['info']
292 doc
= expr_elem
.get('doc')
294 if 'include' in expr
:
299 elif 'union' in expr
:
301 elif 'alternate' in expr
:
303 elif 'struct' in expr
:
305 elif 'command' in expr
:
307 elif 'event' in expr
:
310 raise QAPISemError(info
, "expression is missing metatype")
313 check_name_is_str(name
, info
, "'%s'" % meta
)
314 info
.set_defn(meta
, name
)
315 check_defn_name_str(name
, info
, meta
)
318 if doc
.symbol
!= name
:
320 info
, "documentation comment is for '%s'" % doc
.symbol
)
322 elif info
.pragma
.doc_required
:
323 raise QAPISemError(info
,
324 "documentation comment required")
327 check_keys(expr
, info
, meta
,
328 ['enum', 'data'], ['if', 'features', 'prefix'])
329 check_enum(expr
, info
)
330 elif meta
== 'union':
331 check_keys(expr
, info
, meta
,
333 ['base', 'discriminator', 'if', 'features'])
334 normalize_members(expr
.get('base'))
335 normalize_members(expr
['data'])
336 check_union(expr
, info
)
337 elif meta
== 'alternate':
338 check_keys(expr
, info
, meta
,
339 ['alternate', 'data'], ['if', 'features'])
340 normalize_members(expr
['data'])
341 check_alternate(expr
, info
)
342 elif meta
== 'struct':
343 check_keys(expr
, info
, meta
,
344 ['struct', 'data'], ['base', 'if', 'features'])
345 normalize_members(expr
['data'])
346 check_struct(expr
, info
)
347 elif meta
== 'command':
348 check_keys(expr
, info
, meta
,
350 ['data', 'returns', 'boxed', 'if', 'features',
351 'gen', 'success-response', 'allow-oob',
352 'allow-preconfig', 'coroutine'])
353 normalize_members(expr
.get('data'))
354 check_command(expr
, info
)
355 elif meta
== 'event':
356 check_keys(expr
, info
, meta
,
357 ['event'], ['data', 'boxed', 'if', 'features'])
358 normalize_members(expr
.get('data'))
359 check_event(expr
, info
)
361 assert False, 'unexpected meta type'
363 check_if(expr
, info
, meta
)
364 check_features(expr
.get('features'), info
)
365 check_flags(expr
, info
)