qapi-schema

Package qapi-schema is a fully compliant¹ QAPI² schema language parser. The QAPI schema language looks approximately like JSON, but it differs slightly in many ways, which can confuse a regular JSON parser.

Usage

If you want to parse QAPI schema from your Go code, all you have to do is called qapischema.Parse:

input := `{ 'struct': 'DiskThing',
            'data': {
                'diskname': {
                    'type':'str',
                    'if':'DISKS_HAVE_NAMES' } } }`
schema, _ := qapischema.Parse(input)

The above code snippet would produce a *qapischema.Tree that looks like this:

&qapischema.Tree{
  Node: qapischema.Root{  },
  Children: []*qapischema.Tree{
    {
      Node: &qapischema.Struct{
        Name: "DiskThing",
        Members: []qapischema.Member{
          {
            Name: "diskname",
            Type: qapischema.TypeRef{
              Type: "str",
            },
            If: &qapischema.Cond{
              If: &qapischema.CondIf("DISKS_HAVE_NAMES"),
            },
          },
        },
      },
    },
  },
}

Once the QAPI has been parsed, you can walk the *qapischema.Tree and do whatever it is that you need to do.

The Node field in *qapischema.Tree is an interface type, and so a type assertion is required to identify and access the QAPI-type-specific data in the node you're visiting within the tree.

func visit(tree *qapischema.Tree) {
	switch data := tree.Node.(type) {
	// Root node, no data, traverse the subtrees in the .Children field.
	case qapischema.Root:
	case qapischema.Include:
	case qapischema.Pragma:
	case *qapischema.Struct:
	case *qapischema.Union:
	case *qapischema.Event:
	case *qapischema.Command:
	case *qapischema.Alternate:
	}

	// Process the rest of the document
	for _, t := range tree.Children {
		visit(t)
	}
}

func main() {
	tree, _ := qapischema.Parse(input)

	visit(tree)
}

Reporting defects

There is a lot of room for improvement with how this parser emits diagnostic information. That is, it doesn't emit any at all. The parser will simply stop parsing when it's not able to parse something. It won't complain, it will just stop.

So, when it comes to identifying which part of the document the parser did not understand, just compare the input schema to the output until you find the first element in the input schema that is missing from the parse tree.

There are two utilities included in this module: qapilex and qapiparse.

qapiparse parses QAPI from its stdin and prints a pretty string representation of the parse tree to stdout. This can be very helpful for figuring out where the parser stopped.

In your bug report, please include the QAPI input that surfaced the failure to parse. If possible, try to reduce the QAPI input down to a minimal viable reproducer.

Acknowledgements

Many thanks to:

• Thorsten Ball, the author of Writing an Interpreter in Go³. The lessons in that book's chapter on lexing were directly applied to create package internal/lex.
• Jeremy Brown, whose GopherCon 2022 talk⁴ demonstrated simple and elegant ways to write parser combinators in Go, which directly inspired much of package internal/parse.