Proposed HRD File Format

Developer's Corner
21

For an off the shelf one, I think CUE is a very cool config format, and I hope it takes off. I don’t think a verifier would fit in genode’s core for the same reason an IDL generaror doesn’t though.

22

Coming to this rather late, but I wish to make two suggestions after having looked at the teaser:

This is a very tempting topic because I am designing a lightweight markup language of my own, with much the same design language (human readability, single line tokens, and two-space indentations) but for a complete writing system, not only config files. Anyway, it caught my attention.

My suggestions are intertwined.

Instead of:

+ input name: whatever
  |     rom: whatever2
  |     node: whatever3

It should be

+ input name : whatever
  |     rom  : whatever2
  |     node : whatever3

And instead of

+ inline
| : <tag1>
| :   <innertag1>
| :   <innertag2>
| : </tag1>

It should be

+ inline
| ` <tag1>
| `   <innertag1>
| `   <innertag2>
| ` </tag1>

These changes give you this:

+ input name : whatever
  |     rom  : whatever2
  |     node : whatever3
  + inline
  | ` <tag1>
  | `   <innertag1>
  | `   <innertag2>
  | ` </tag1>

Instead of this:

+ input name: whatever
  |     rom: whatever2
  |     node: whatever3
  + inline
  | : <tag1>
  | :   <innertag1>
  | :   <innertag2>
  | : </tag1>

The assignments in the first example are better aligned visually. Floating :s can of course be flush with the key, but you can move them which makes possible visual alignment of blocks of assignments.

Imagine sticking with existing tokens and adding assignment alignment:

+ input name : whatever
  |     rom  : whatever2
  |     node : whatever3
  + inline
  | : <tag1>
  | :   <innertag1>
  | :   <innertag2>
  | : </tag1>

Now code and assignment are competing visually with one another.

So it really is either/or, and I would vote to privilege assignment alignment (a new feature), which means : for raw code has to go. Thankfully there’s the universal literal syntax: `

Better late than never, as they say, and only a suggestion.

Two questions:

  1. A naive one: Why not use YAML, which solves human readability and is a universally supported standard?
  2. Under what license has HRD been released?
1 Like
23

Thanks for sharing your ideas.

Regarding your suggestion of allowing spaces between attribute names and colon, I am not convinced that the added creative freedom would be a net positive. By sticking to the approach of “decorating” the name with the colon suffix, we naturally maintain consistency between the the vertically spread-out listing of attributes (each on one line) and the compacted form (attributes on one line):

+ input name: whatever
        rom:  whatever2
        node: whatever3

+ input name: whatever | rom: whatever2 | node: whatever3

The option of putting spaces in front of colons adds wiggle room for spoiling the consistency.

Regarding the choice of the line prefix for quoted content, we settled on the colon to maintain the vertical flow along |(delimiter), . (comment), and :(quoted content). It contributes to the calmness of the result. We considered ticks and backticks among other characters. Whereas some choices (like your preference of using a backtick) look defensibly good when quoting multiple lines (given a vertical sequence of these characters), the syntax looks contrived when quoting only a single line. E.g., consider the definition of an environment variable:

+ env SHELL | : /bin/bash

vs.

+ env SHELL | ` /bin/bash

The former appears to me as less forced than the latter. I think this is because backticks normally appear pairwise after all.

Why not use YAML […]?

You have given a perfect example of a cheap question that demands an expensive answer. :wink: Where to start? Where to end? I’m a little bit afraid of entering such tit-for-tat talks because they can be rather endless without advancing the technical discussion. Nevertheless, since you asked, I don’t want to leave the question dangling.

  1. When I reviewed YAML, I admittedly struggled to see an obvious mapping between our existing XML structure and YAML. As the simple abstractions of XML (nested nodes and their attributes) served us well, the new syntax had to be structurally equivalent to XML. YAML did not appeal in this respect.
  2. The encoding of structure via mere indentation tends to become non-ergonomic once reaching a nesting depth of four or deeper. The sense of scope can (too) easily get lost. I think many Python programmers can relate. HRD’s (optional) use of pipe characters as part of the indentation can mitigate this effect. YAML has no such means, and extending it would be out of question.
  3. Despite of being painted as informal, YAML is rich of syntax and grammar. Look at all those special characters, braces, commas, brackets, magic character sequences, and special cases. In contrast, HRD’s syntax is deliberately as scarce as possible. There are no braces, parenthesis, brackets, quote characters, commas. It is indeed quite the opposite.
  4. There is no escaping of characters in HRD, which allows the interpretation of character sequences in place without decoding/copying. YAML of course supports the escaping of characters.
  5. HRD is opinionated towards the concrete use within Genode. Three examples: The predominant name attribute value can be specified directly following the node type, yielding natural expressions like + connector HDMI-1. Isn’t that wonderful? In a non-opinionated general-purpose syntax, this example would look like + connector name: HDMI-1. Details like this can make the difference between “practical” and “joyful”. The second example is the disabling of nodes (with their entire sub structures) by replacing + by x, which might appear as gimmicky until when using text as interactive user interface in the Sculpt-OS way of life. As the third example of being opinionated, HRD attribute values cannot have a | character because it delimits the attribute. One can paint that as limitation. But one can also live with it and enjoy the life without weird escaping rules. In contrast, a general-purpose (standard) syntax is rightfully not as opinionated, leaving such simplifications on the table.

Under what license has HRD been released?

We have now kicked off a phase practical evaluation. To unlock this step, we have added HRD to Genode, inheriting Genode’s regular AGPLv3(+commercial) license. If/once we decide to go for it, we will host HRD (including the tooling, documentation, and example implementations for different languages) at a separate repository, under liberal licensing terms (e.g., MIT). So there will be a central place of reference with no licensing friction.

2 Likes
24

As a heavy and comfortable XML user (of the same vanilla dialect that Genode uses), I was ambivalent about HRD in the beginning. But I have to say, the more I look at the examples, the more I appreciate the visual simplicity and clarity. I am very much looking forward to working with it.

And the killer feature for me is the ability to disable an entire branch with one character. (My persnickety side also appreciates the differentiation between disabling and “commenting”.) That’s what I call a feature!

2 Likes