From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: peter.maydell@linaro.org, John Snow <jsnow@redhat.com>
Subject: [PULL 15/15] qapi/parser: add docstrings
Date: Thu, 20 May 2021 19:52:56 +0200 [thread overview]
Message-ID: <20210520175256.1119684-16-armbru@redhat.com> (raw)
In-Reply-To: <20210520175256.1119684-1-armbru@redhat.com>
From: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20210519183951.3946870-16-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Doc string spacing tweaked slightly]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/parser.py | 69 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index b0f18c0d17..f03ba2cfec 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -47,7 +47,27 @@ def __init__(self, parser: 'QAPISchemaParser', msg: str):
class QAPISchemaParser:
+ """
+ Parse QAPI schema source.
+ Parse a JSON-esque schema file and process directives. See
+ qapi-code-gen.txt section "Schema Syntax" for the exact syntax.
+ Grammatical validation is handled later by `expr.check_exprs()`.
+
+ :param fname: Source file name.
+ :param previously_included:
+ The absolute names of previously included source files,
+ if being invoked from another parser.
+ :param incl_info:
+ `QAPISourceInfo` belonging to the parent module.
+ ``None`` implies this is the root module.
+
+ :ivar exprs: Resulting parsed expressions.
+ :ivar docs: Resulting parsed documentation blocks.
+
+ :raise OSError: For problems reading the root schema document.
+ :raise QAPIError: For errors in the schema source.
+ """
def __init__(self,
fname: str,
previously_included: Optional[Set[str]] = None,
@@ -73,6 +93,11 @@ def __init__(self,
self._parse()
def _parse(self) -> None:
+ """
+ Parse the QAPI schema document.
+
+ :return: None. Results are stored in ``.exprs`` and ``.docs``.
+ """
cur_doc = None
# May raise OSError; allow the caller to handle it.
@@ -199,6 +224,50 @@ def check_list_str(name: str, value: object) -> List[str]:
raise QAPISemError(info, "unknown pragma '%s'" % name)
def accept(self, skip_comment: bool = True) -> None:
+ """
+ Read and store the next token.
+
+ :param skip_comment:
+ When false, return COMMENT tokens ("#").
+ This is used when reading documentation blocks.
+
+ :return:
+ None. Several instance attributes are updated instead:
+
+ - ``.tok`` represents the token type. See below for values.
+ - ``.info`` describes the token's source location.
+ - ``.val`` is the token's value, if any. See below.
+ - ``.pos`` is the buffer index of the first character of
+ the token.
+
+ * Single-character tokens:
+
+ These are "{", "}", ":", ",", "[", and "]".
+ ``.tok`` holds the single character and ``.val`` is None.
+
+ * Multi-character tokens:
+
+ * COMMENT:
+
+ This token is not normally returned by the lexer, but it can
+ be when ``skip_comment`` is False. ``.tok`` is "#", and
+ ``.val`` is a string including all chars until end-of-line,
+ including the "#" itself.
+
+ * STRING:
+
+ ``.tok`` is "'", the single quote. ``.val`` contains the
+ string, excluding the surrounding quotes.
+
+ * TRUE and FALSE:
+
+ ``.tok`` is either "t" or "f", ``.val`` will be the
+ corresponding bool value.
+
+ * EOF:
+
+ ``.tok`` and ``.val`` will both be None at EOF.
+ """
while True:
self.tok = self.src[self.cursor]
self.pos = self.cursor
--
2.26.3
next prev parent reply other threads:[~2021-05-20 18:01 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-20 17:52 [PULL 00/15] QAPI patches patches for 2021-05-20 Markus Armbruster
2021-05-20 17:52 ` [PULL 01/15] qapi/parser: Don't try to handle file errors Markus Armbruster
2021-05-20 17:52 ` [PULL 02/15] qapi: Add test for nonexistent schema file Markus Armbruster
2021-05-20 17:52 ` [PULL 03/15] qapi/source: Remove line number from QAPISourceInfo initializer Markus Armbruster
2021-05-20 17:52 ` [PULL 04/15] qapi/parser: factor parsing routine into method Markus Armbruster
2021-05-20 17:52 ` [PULL 05/15] qapi/parser: Assert lexer value is a string Markus Armbruster
2021-05-20 17:52 ` [PULL 06/15] qapi/parser: enforce all top-level expressions must be dict in _parse() Markus Armbruster
2021-05-20 17:52 ` [PULL 07/15] qapi/parser: assert object keys are strings Markus Armbruster
2021-05-20 17:52 ` [PULL 08/15] qapi/parser: Use @staticmethod where appropriate Markus Armbruster
2021-05-20 17:52 ` [PULL 09/15] qapi: add must_match helper Markus Armbruster
2021-05-20 17:52 ` [PULL 10/15] qapi/parser: Fix token membership tests when token can be None Markus Armbruster
2021-05-20 17:52 ` [PULL 11/15] qapi/parser: Rework _check_pragma_list_of_str as a TypeGuard Markus Armbruster
2021-05-20 17:52 ` [PULL 12/15] qapi/parser: add type hint annotations Markus Armbruster
2021-05-20 17:52 ` [PULL 13/15] qapi/parser: Remove superfluous list comprehension Markus Armbruster
2021-05-20 17:52 ` [PULL 14/15] qapi/parser: allow 'ch' variable name Markus Armbruster
2021-05-20 17:52 ` Markus Armbruster [this message]
2021-05-21 8:54 ` [PULL 00/15] QAPI patches patches for 2021-05-20 Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210520175256.1119684-16-armbru@redhat.com \
--to=armbru@redhat.com \
--cc=jsnow@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).