xemu-project/xemu
1
0
Fork 0
mirror of https://github.com/xemu-project/xemu.git synced 2024-11-27 05:20:50 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

qapi/parser: Introduce NullSection

Browse Source 
Here's the weird bit. QAPIDoc generally expects -- virtually everywhere
-- that it will always have a current section. The sole exception to
this is in the case that end_comment() is called, which leaves us with
*no* section. However, in this case, we also don't expect to actually
ever mutate the comment contents ever again.

NullSection is just a Null-object that allows us to maintain the
invariant that we *always* have a current section, enforced by static
typing -- allowing us to type that field as QAPIDoc.Section instead of
the more ambiguous Optional[QAPIDoc.Section].

end_section is renamed to switch_section and now accepts as an argument
the new section to activate, clarifying that no callers ever just
unilaterally end a section; they only do so when starting a new section.

Signed-off-by: John Snow <jsnow@redhat.com>

Message-Id: <20210930205716.1148693-8-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2021-09-30 16:57:10 -04:00 committed by Markus Armbruster
parent 1e20a77576
commit f4c05aaf14
1 changed files with 16 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
scripts/qapi/parser.py
View File

@ -478,6 +478,13 @@ class QAPIDoc:
def connect(self, member): def connect(self, member):
self.member = member self.member = member
class NullSection(Section):
"""
Immutable dummy section for use at the end of a doc block.
"""
def append(self, line):
assert False, "Text appended after end_comment() called."
def __init__(self, parser, info): def __init__(self, parser, info):
# self._parser is used to report errors with QAPIParseError. The # self._parser is used to report errors with QAPIParseError. The
# resulting error position depends on the state of the parser. # resulting error position depends on the state of the parser.
@ -525,7 +532,7 @@ class QAPIDoc:
self._append_line(line) self._append_line(line)
def end_comment(self): def end_comment(self):
self._end_section() self._switch_section(QAPIDoc.NullSection(self._parser))
@staticmethod @staticmethod
def _is_section_tag(name): def _is_section_tag(name):
@ -699,9 +706,9 @@ class QAPIDoc:
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"'%s' parameter name duplicated" % name) "'%s' parameter name duplicated" % name)
assert not self.sections assert not self.sections
self._end_section() new_section = QAPIDoc.ArgSection(self._parser, name, indent)
self._section = QAPIDoc.ArgSection(self._parser, name, indent) self._switch_section(new_section)
symbols_dict[name] = self._section symbols_dict[name] = new_section
def _start_args_section(self, name, indent): def _start_args_section(self, name, indent):
self._start_symbol_section(self.args, name, indent) self._start_symbol_section(self.args, name, indent)
@ -713,13 +720,11 @@ class QAPIDoc:
if name in ('Returns', 'Since') and self.has_section(name): if name in ('Returns', 'Since') and self.has_section(name):
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"duplicated '%s' section" % name) "duplicated '%s' section" % name)
self._end_section() new_section = QAPIDoc.Section(self._parser, name, indent)
self._section = QAPIDoc.Section(self._parser, name, indent) self._switch_section(new_section)
self.sections.append(self._section) self.sections.append(new_section)
def _end_section(self):
assert self._section is not None
def _switch_section(self, new_section):
text = self._section.text = self._section.text.strip() text = self._section.text = self._section.text.strip()
# Only the 'body' section is allowed to have an empty body. # Only the 'body' section is allowed to have an empty body.
@ -732,7 +737,7 @@ class QAPIDoc:
self._parser, self._parser,
"empty doc section '%s'" % self._section.name) "empty doc section '%s'" % self._section.name)
self._section = None self._section = new_section
def _append_freeform(self, line): def _append_freeform(self, line):
match = re.match(r'(@\S+:)', line) match = re.match(r'(@\S+:)', line)