[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite
From: |
Marc-André Lureau |
Subject: |
Re: [Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite section on schema syntax |
Date: |
Wed, 4 Oct 2017 13:59:23 +0200 |
On Mon, Oct 2, 2017 at 5:25 PM, Markus Armbruster <address@hidden> wrote:
> Section "QMP/Guest agent schema" is one big paragraph, encumbered with
> more detail than necessary. It also claims JSON null isn't supported,
> which is untrue since commit e53188a, v2.4.0. Rewrite it.
>
> Signed-off-by: Markus Armbruster <address@hidden>
Reviewed-by: Marc-André Lureau <address@hidden>
> ---
> docs/devel/qapi-code-gen.txt | 36 ++++++++++++++++++------------------
> 1 file changed, 18 insertions(+), 18 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index f5b7659caf..3186c36460 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -25,24 +25,24 @@ how the schemas, scripts, and resulting code are used.
>
> == QMP/Guest agent schema ==
>
> -A QAPI schema file is designed to be loosely based on JSON
> -(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
> -and the use of comments; a QAPI schema file is then parsed by a python
> -code generation program. A valid QAPI schema consists of a series of
> -top-level expressions, with no commas between them. Where
> -dictionaries (JSON objects) are used, they are parsed as python
> -OrderedDicts so that ordering is preserved (for predictable layout of
> -generated C structs and parameter lists). Ordering doesn't matter
> -between top-level expressions or the keys within an expression, but
> -does matter within dictionary values for 'data' and 'returns' members
> -of a single expression. QAPI schema input is written using 'single
> -quotes' instead of JSON's "double quotes" (in contrast, Client JSON
> -Protocol uses no comments, and while input accepts 'single quotes' as
> -an extension, output is strict JSON using only "double quotes"). As
> -in JSON, trailing commas are not permitted in arrays or dictionaries.
> -Input must be ASCII (although QMP supports full Unicode strings, the
> -QAPI parser does not). At present, there is no place where a QAPI
> -schema requires the use of JSON numbers or null.
> +Schema syntax is based on JSON (RFC 7159), with the following
> +differences:
> +
> +* Comments (see below)
> +
> +* No JSON numbers
> +
> +* Strings use 'single quotes' instead of "double quotes"
> +
> +* The input character set is plain ASCII
> +
> + Unicode characters need to be escaped. In contrast, the Client JSON
> + Protocol uses UTF-8.
> +
> +A QAPI schema consists of a sequence of JSON values (top-level
> +expressions), with no commas between them. The order of top-level
> +expressions doesn't matter. The order of keys in JSON objects is
> +generally relevant.
>
>
> === Comments ===
> --
> 2.13.6
>
>
--
Marc-André Lureau
- [Qemu-devel] [RFC PATCH 00/32] Command line QAPIfication, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 24/32] qapi-options: Generate help string, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite section on schema syntax, Markus Armbruster, 2017/10/02
- Re: [Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite section on schema syntax,
Marc-André Lureau <=
- [Qemu-devel] [RFC PATCH 16/32] qapi: Factor out _make_implicit_wrapper_type(), Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 01/32] tests/qapi-schema: Improve coverage of '@', Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 04/32] qapi2texi: Fix for '@' not followed by \w character, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 09/32] qapi: check_type() parameter allow_optional is now unused, drop, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 13/32] qapi: Use argparse to open schema file, Markus Armbruster, 2017/10/02