Metadesk is an ergonomic parser library for a simple—yet versatile—plaintext language. The language lets you create simple structures and define their meaning with your own code. The library provides the parser, and helpers for introspection and code generation.
The language defines a syntax for common structures, like hierarchical lists of strings with metatags. While the structures you form have a consistent pattern, the full meaning of your files is not determined by Metadesk. Take the following example of some Metadesk code:
This may seem like a variation on the C syntax for structs. However, in Metadesk, the above code is parsed as a generic hierarchy of strings, producing an abstract syntax tree that looks like this:
So what's going on here?
In the above diagram, every piece of text you see—Vec3, x, F32, struct—is a Metadesk node. Every node has the same basic structure:
Every node can have a string. For the purpose of this explanation, we will use node strings as shorthand to denote the nodes themselves. For instance, we may say that the root node of this tree is Vec3, because that is the string that was parsed to form that node.
Every node can have zero or more children. In this case, Vec3 has three children: x, y, and z. All of Vec3's children have one child each, and those all happen to have the string F32.
Each node can also have a list of tags. In this case, Vec3 has a single tag: struct.
Tags can also have children. Syntactically, they look like tag arguments. Take the following example:
Once again, this may first appear to be a different syntax for C's enum. But in Metadesk it is just a structure of nodes:
Think of tags as an additional list of children that can be attached to any node.
In this example enum is a tag on Foo and enum has one child: base_type. The base_type node itself has the child: U64. Note that the tag and its children have a unique syntax, but they all share the same structure after the parse.
Metadesk provides a flexible syntax to represent parent-children relationships. The string denoting a parent node must be separated from its children with a :, but there are many legal ways of delimiting the children list:
It is also possible to have nodes without strings, but with children, in which case you'd omit the Foo:, and just delimit the list:
So, now that we know how to build structured data with Metadesk... what's the point?
The answer to that question is really "whatever is useful for you". To give a few examples, we've internally used Metadesk for many purposes, including code and data generation. This very website is generated with a tool that uses Metadesk!
The Metadesk library provides a simple Metadesk parser, as well as a number of helpers for introspection and generation using parsed Metadesk structures. It is intended to provide a lightweight way to start working with Metadesk data in your tools.
To get started with Metadesk, go to the GitHub repository and either git clone the repository, or download the ZIP file. It is then recommended that you copy and paste all of the code in the source/ folder into a folder that is local to your program, so that your Metadesk programs will continue working even if the library is updated.
To start using the library, all you need to do is then include the Metadesk files and start using the library's API:
We'll be releasing an official reference for Metadesk soon. That will include more information, like guides, examples, and documentation for the library's API.
Provided some MD_Node *node, we can iterate node's children like so using the MD_EachNode helper macro.
Here is an example of iterating the first code example referenced earlier and printing it out:
This is the output of the above program:
Given some MD_Node *node, we can check if node has a tag like so:
Given some MD_Node *node, if we expect node to have children labeled with certain strings, we can avoid explicitly iterating over them and instead rely on helpers provided by the library: