qemu/tests/qapi-schema/test-qapi.py

72 lines
2.2 KiB
Python
Raw Normal View History

#
# QAPI parser test harness
#
# Copyright (c) 2013 Red Hat Inc.
#
# Authors:
# Markus Armbruster <armbru@redhat.com>
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.
#
from qapi import *
from pprint import pprint
import os
import sys
class QAPISchemaTestVisitor(QAPISchemaVisitor):
def visit_enum_type(self, name, info, values, prefix):
print 'enum %s %s' % (name, values)
if prefix:
print ' prefix %s' % prefix
def visit_object_type(self, name, info, base, members, variants):
print 'object %s' % name
if base:
print ' base %s' % base.name
for m in members:
print ' member %s: %s optional=%s' % \
(m.name, m.type.name, m.optional)
self._print_variants(variants)
def visit_alternate_type(self, name, info, variants):
print 'alternate %s' % name
self._print_variants(variants)
def visit_command(self, name, info, arg_type, ret_type,
gen, success_response, boxed):
print 'command %s %s -> %s' % \
(name, arg_type and arg_type.name, ret_type and ret_type.name)
print ' gen=%s success_response=%s boxed=%s' % \
(gen, success_response, boxed)
def visit_event(self, name, info, arg_type, boxed):
print 'event %s %s' % (name, arg_type and arg_type.name)
print ' boxed=%s' % boxed
@staticmethod
def _print_variants(variants):
if variants:
print ' tag %s' % variants.tag_member.name
for v in variants.variants:
print ' case %s: %s' % (v.name, v.type.name)
schema = QAPISchema(sys.argv[1])
schema.visit(QAPISchemaTestVisitor())
qapi: add qapi2texi script As the name suggests, the qapi2texi script converts JSON QAPI description into a texi file suitable for different target formats (info/man/txt/pdf/html...). It parses the following kind of blocks: Free-form: ## # = Section # == Subsection # # Some text foo with *emphasis* # 1. with a list # 2. like that # # And some code: # | $ echo foo # | -> do this # | <- get that # ## Symbol description: ## # @symbol: # # Symbol body ditto ergo sum. Foo bar # baz ding. # # @param1: the frob to frobnicate # @param2: #optional how hard to frobnicate # # Returns: the frobnicated frob. # If frob isn't frobnicatable, GenericError. # # Since: version # Notes: notes, comments can have # - itemized list # - like this # # Example: # # -> { "execute": "quit" } # <- { "return": {} } # ## That's roughly following the following EBNF grammar: api_comment = "##\n" comment "##\n" comment = freeform_comment | symbol_comment freeform_comment = { "# " text "\n" | "#\n" } symbol_comment = "# @" name ":\n" { member | tag_section | freeform_comment } member = "# @" name ':' [ text ] "\n" freeform_comment tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ] "\n" freeform_comment text = free text with markup Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed both as freeform_comment and as symbol_comment. The actual parser recognizes symbol_comment. See docs/qapi-code-gen.txt for more details. Deficiencies and limitations: - the generated QMP documentation includes internal types - union type support is lacking - type information is lacking in generated documentation - doc comment error message positions are imprecise, they point to the beginning of the comment. - a few minor issues, all marked TODO/FIXME in the code Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [test-qapi.py tweaked to avoid trailing empty lines in .out] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2017-01-13 17:41:29 +03:00
for doc in schema.docs:
if doc.symbol:
print 'doc symbol=%s expr=%s' % \
(doc.symbol, doc.expr.items()[0])
else:
print 'doc freeform'
for arg, section in doc.args.iteritems():
print ' arg=%s\n%s' % (arg, section)
for section in doc.sections:
print ' section=%s\n%s' % (section.name, section)
body = str(doc.body)
if body:
print ' body=\n%s' % body