Re: [Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite section on schema syntax

[Marc-André Lureau]

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