qapi: Rename pragma *-whitelist to *-exceptions

Rename pragma returns-whitelist to command-returns-exceptions, and
name-case-whitelist to member-name-case-exceptions.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20210323094025.3569441-20-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

docs/devel/qapi-code-gen.txt

@@ -147,9 +147,10 @@ prevent incomplete include files.
 === Pragma directives ===
 
 Syntax:
-    PRAGMA = { 'pragma': { '*doc-required': BOOL,
+    PRAGMA = { 'pragma': {
-                           '*returns-whitelist': [ STRING, ... ],
+                   '*doc-required': BOOL,
-                           '*name-case-whitelist': [ STRING, ... ] } }
+                   '*command-returns-exceptions': [ STRING, ... ],
+                   '*member-name-exceptions': [ STRING, ... ] } }
 
 The pragma directive lets you control optional generator behavior.
 
@@ -159,11 +160,11 @@ pragma to different values in parts of the schema doesn't work.
 Pragma 'doc-required' takes a boolean value.  If true, documentation
 is required.  Default is false.
 
-Pragma 'returns-whitelist' takes a list of command names that may
+Pragma 'command-returns-exceptions' takes a list of commands that may
 violate the rules on permitted return types.  Default is none.
 
-Pragma 'name-case-whitelist' takes a list of names that may violate
+Pragma 'member-name-exceptions' takes a list of types whose member
-rules on use of upper- vs. lower-case letters.  Default is none.
+names may contain uppercase letters.  Default is none.
 
 
 === Enumeration types ===
@@ -490,9 +491,9 @@ are the arguments.  A union type requires 'boxed': true.
 Member 'returns' defines the command's return type.  It defaults to an
 empty struct type.  It must normally be a complex type or an array of
 a complex type.  To return anything else, the command must be listed
-in pragma 'returns-whitelist'.  If you do this, extending the command
+in pragma 'commands-returns-exceptions'.  If you do this, extending
-to return additional information will be harder.  Use of
+the command to return additional information will be harder.  Use of
-'returns-whitelist' for new commands is strongly discouraged.
+the pragma for new commands is strongly discouraged.
 
 A command's error responses are not specified in the QAPI schema.
 Error conditions should be documented in comments.
@@ -755,7 +756,7 @@ Any name (command, event, type, member, or enum value) beginning with
 "x-" is marked experimental, and may be withdrawn or changed
 incompatibly in a future release.
 
-Pragma 'name-case-whitelist' lets you violate the rules on use of
+Pragma 'member-name-exceptions' lets you violate the rules on use of
 upper and lower case.  Use for new code is strongly discouraged.
 
 

qapi/pragma.json

@@ -4,13 +4,13 @@
 # add to them!
 { 'pragma': {
     # Commands allowed to return a non-dictionary:
-    'returns-whitelist': [
+    'command-returns-exceptions': [
         'human-monitor-command',
         'qom-get',
         'query-tpm-models',
         'query-tpm-types',
         'ringbuf-read' ],
-    'name-case-whitelist': [
+    'member-name-exceptions': [
         'ACPISlotType',             # DIMM, visible through query-acpi-ospm-status
         'BlockdevVmdkSubformat',    # all members, to match VMDK spec spellings
         'BlockdevVmdkAdapterType',  # legacyESX, to match VMDK spec spellings

qga/qapi-schema.json

@@ -20,7 +20,7 @@
 # add to them!
 { 'pragma': {
     # Commands allowed to return a non-dictionary:
-    'returns-whitelist': [
+    'command-returns-exceptions': [
         'guest-file-open',
         'guest-fsfreeze-freeze',
         'guest-fsfreeze-freeze-list',

scripts/qapi/expr.py

@@ -181,7 +181,7 @@ def check_type(value, info, source,
         raise QAPISemError(info,
                            "%s should be an object or type name" % source)
 
-    permit_upper = allow_dict in info.pragma.name_case_whitelist
+    permit_upper = allow_dict in info.pragma.member_name_exceptions
 
     # value is a dictionary, check that each member is okay
     for (key, arg) in value.items():
@@ -224,7 +224,7 @@ def check_enum(expr, info):
     if prefix is not None and not isinstance(prefix, str):
         raise QAPISemError(info, "'prefix' must be a string")
 
-    permit_upper = name in info.pragma.name_case_whitelist
+    permit_upper = name in info.pragma.member_name_exceptions
 
     members[:] = [m if isinstance(m, dict) else {'name': m}
                   for m in members]

scripts/qapi/parser.py

@@ -132,12 +132,12 @@ def _pragma(self, name, value, info):
                 raise QAPISemError(info,
                                    "pragma 'doc-required' must be boolean")
             info.pragma.doc_required = value
-        elif name == 'returns-whitelist':
+        elif name == 'command-returns-exceptions':
             self._check_pragma_list_of_str(name, value, info)
-            info.pragma.returns_whitelist = value
+            info.pragma.command_returns_exceptions = value
-        elif name == 'name-case-whitelist':
+        elif name == 'member-name-exceptions':
             self._check_pragma_list_of_str(name, value, info)
-            info.pragma.name_case_whitelist = value
+            info.pragma.member_name_exceptions = value
         else:
             raise QAPISemError(info, "unknown pragma '%s'" % name)
 

scripts/qapi/schema.py

@@ -779,7 +779,7 @@ def check(self, schema):
         if self._ret_type_name:
             self.ret_type = schema.resolve_type(
                 self._ret_type_name, self.info, "command's 'returns'")
-            if self.name not in self.info.pragma.returns_whitelist:
+            if self.name not in self.info.pragma.command_returns_exceptions:
                 typ = self.ret_type
                 if isinstance(typ, QAPISchemaArrayType):
                     typ = self.ret_type.element_type

scripts/qapi/source.py

@@ -21,10 +21,10 @@ class QAPISchemaPragma:
     def __init__(self) -> None:
         # Are documentation comments required?
         self.doc_required = False
-        # Whitelist of commands allowed to return a non-dictionary
+        # Commands allowed to return a non-dictionary
-        self.returns_whitelist: List[str] = []
+        self.command_returns_exceptions: List[str] = []
-        # Whitelist of entities allowed to violate case conventions
+        # Types whose member names may violate case conventions
-        self.name_case_whitelist: List[str] = []
+        self.member_name_exceptions: List[str] = []
 
 
 class QAPISourceInfo:

tests/qapi-schema/enum-member-case.json

@@ -1,4 +1,4 @@
 # Member names should be 'lower-case' unless the enum is whitelisted
-{ 'pragma': { 'name-case-whitelist': [ 'UuidInfo' ] } }
+{ 'pragma': { 'member-name-exceptions': [ 'UuidInfo' ] } }
 { 'enum': 'UuidInfo', 'data': [ 'Value' ] } # UuidInfo is whitelisted
 { 'enum': 'NoWayThisWillGetWhitelisted', 'data': [ 'Value' ] }

tests/qapi-schema/pragma-value-not-list-of-str.err

@@ -1 +1 @@
-pragma-value-not-list-of-str.json:3: pragma returns-whitelist must be a list of strings
+pragma-value-not-list-of-str.json:3: pragma command-returns-exceptions must be a list of strings

tests/qapi-schema/pragma-value-not-list-of-str.json

@@ -1,3 +1,3 @@
 # pragma value must be list of strings
 
-{ 'pragma': { 'returns-whitelist': [ 'good', [ 'bad' ] ] } }
+{ 'pragma': { 'command-returns-exceptions': [ 'good', [ 'bad' ] ] } }

tests/qapi-schema/pragma-value-not-list.err

@@ -1 +1 @@
-pragma-value-not-list.json:3: pragma name-case-whitelist must be a list of strings
+pragma-value-not-list.json:2: pragma member-name-exceptions must be a list of strings

tests/qapi-schema/pragma-value-not-list.json

@@ -1,3 +1,2 @@
 # pragma value must be list
-
+{ 'pragma': { 'member-name-exceptions': false } }
-{ 'pragma': { 'name-case-whitelist': false } }

tests/qapi-schema/qapi-schema-test.json

@@ -7,7 +7,7 @@
 # Whitelists to permit QAPI rule violations
 { 'pragma': {
     # Commands allowed to return a non-dictionary:
-    'returns-whitelist': [
+    'command-returns-exceptions': [
         'guest-get-time',
         'guest-sync' ] } }
 

tests/qapi-schema/returns-bad-type.json

@@ -1,6 +1,6 @@
 # we enforce that 'returns' be a dict or array of dict unless whitelisted
 
-{ 'pragma': { 'returns-whitelist': [
+{ 'pragma': { 'command-returns-exceptions': [
     'human-monitor-command', 'query-tpm-models', 'guest-get-time' ] } }
 
 { 'command': 'human-monitor-command',