Re: [Qemu-devel] [PATCH 3/5] qapi: add qapi2texi script

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3566 bytes --]

On 07/03/2015 03:51 AM, Marc-André Lureau wrote:
> From: Marc-André Lureau <marcandre.lureau@gmail.com>
> 
> As the name suggests, the qapi2texi script converts JSON QAPI
> description into a standalone texi file suitable for different target
> formats.
> 
> As the documentation format doesn't seem to be specified, it parses the
> following blocks before each declaration with some variations:

docs/qapi-code-gen.txt tried to give a sample documentation.  Feel free
to formalize that, and to fix non-conforming uses, if you desire.  It'll
be a big one-time audit of the .json files, but getting things
consistent, _and keeping them that way by automatic conformance checks
in your conversion tool_, is fine by me.

> 
>   ##
>   # @symbol
>   #
>   # body
>   #
>   # @arg: foo
>   # @arg: #optional foo
>   #
>   # Returns: returns
>   # Since: version
>   # Notes: notes
>   ##
> 
> Using the json declaration, it's able to give extra information about
> the type of arguments and return value expected.
> 
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  scripts/qapi.py      |  78 ++++++++++++++++++-
>  scripts/qapi2texi.py | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 286 insertions(+), 4 deletions(-)
>  create mode 100644 scripts/qapi2texi.py

Are you intending to apply this after Markus' big work on QMP Introspection?

> 
> diff --git a/scripts/qapi.py b/scripts/qapi.py
> index 06d7fc2..70208e8 100644
> --- a/scripts/qapi.py
> +++ b/scripts/qapi.py
> @@ -103,6 +103,53 @@ class QAPIExprError(Exception):
>          return error_path(self.info['parent']) + \
>              "%s:%d: %s" % (self.info['file'], self.info['line'], self.msg)
>  
> +class QAPIDoc:

In particular, this should probably be QAPIDoc(object) (new style class
declaration).

> @@ -762,6 +823,15 @@ def parse_schema(fname):
>          print >>sys.stderr, e
>          exit(1)
>  
> +def parse_schema_full(fname):
> +    try:
> +        schema = QAPISchema(open(fname, "r"))
> +        check_exprs(schema.exprs)
> +        return schema.exprs
> +    except (QAPISchemaError, QAPIExprError), e:
> +        print >>sys.stderr, e
> +        exit(1)

and this may need to be reworked on top of Markus' new parser class.

> +++ b/scripts/qapi2texi.py
> @@ -0,0 +1,212 @@
> +# QAPI texi generator
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2.
> +# See the COPYING file in the top-level directory.

Although I'm not a lawyer, my understanding is that for GPL to apply,
there has to be an explicit mention of Copyright.

> +exprs = parse_schema_full(sys.argv[4])

And you'll probably want to rewrite this in terms of the visitor interface.

> +for cmd in exprs:
> +    expr = cmd['expr']
> +    docs = cmd['info']['doc']
> +    (kind, name) = expr.items()[0]
> +
> +    for d in docs[0:-1]:
> +        print d.comment
> +
> +    texi = {"command": texi_command,
> +            "struct": texi_struct,
> +            "enum": texi_enum,
> +            "union": texi_union,
> +            "alternate": texi_alternate,
> +            "event": texi_event}
> +    try:
> +        texi[kind](expr, docs[-1])
> +    except KeyError:
> +        raise ValueError("Unknown expression kind '%s'" % kind)

although this is a rather cute way to polymorphically invoke the correct
helper function.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]