Ask HN: Please critique my metalanguage: “Dogma” | Hacker News Reader

Ask HN: Please critique my metalanguage: “Dogma”

14 pointskstenerud11 comments

Hi HN!

Dogma (formerly KBNF) is a modernized metalanguage with better expressiveness and binary support, focusing on documentation. It follows the familiar patterns of Backus-Naur Form, and includes a number of innovations that make it also suitable for describing binary data.

Link here: https://github.com/kstenerud/dogma/blob/master/dogma_v1.md

I've been working hard after the feedback I got in https://news.ycombinator.com/item?id=34720488 and would really appreciate another round of critiques :)

A lot of the changes were to harmonize the grammar so that the language "feels" more consistent with fewer surprising behaviors and edge cases.

If you use metalanguage grammars, please take a gander and let me know where Dogma might cause problems in your use cases!

Thanks :)

View on HN

Specific changes to address previous feedback:

* Added an "above-the-fold" introductory example.

* Added the "eod" function to match the end of the input.

* Removed the "when" function and replaced it with switch syntax.

* Renamed the "bind" function to the "var" function.

* Removed "any_type" from the grammar.

* Introduced "bits" as a formal type. "expression" now refers to expressions of any type.

* The "bits" type can also be compared to produce a condition.

* Added the "!="" comparator.

* Split numbers into singular types and set types.

* Number sets can now be constructed using alternatives and exclusion.

* Removed "real" since it's just a number with no invariant. Use "number" and "numbers" instead.

* "signed" and "unsigned" have been renamed to "sinteger" and "uinteger" to emphasize the integer invariant.

* ieee754 special floating point values NaN, inf, and negative 0 are now generated via special functions, and have no "number" representation.

* Modulo division now uses truncation, following with most popular languages.

* Undefined arithmetic operations are no longer allowed.

* The variadic parameter specifier can only be applied to the last argument of a function (bugfix).

* Clarified what the parameter value 0 does in some functions.

* Removed alternatives operation for type names.

* Added note about Unicode equivalence and normalization.

* Removed character encoding length restriction.

* Switched out some contrived examples for real-world examples (UDP, Ethernet, RTP, TR-DOS file descriptor).

Improve the tooling more. Formatters, syntax highlighters, language servers, host language integration. Too many languages remain toys because their creators do not address the infrastructure issue and only work on the compiler.

Looks cool. Great first example, it's highly applicable and actually doesn't look bad.

Perhaps adding a few more "marketing" things to the readme - or at least, perhaps a few questions you might answer here.

- Is this a toy? Or is your intent to polish this for real world use? Just curious.

- How does error handling work?

- Does this compile down to a language for integration into an application? It's unclear (at least, from reading the docs for a few minutes) what the output artifacts for this are.

It's to scratch a personal itch of mine: formal, human readable descriptions of binary data formats. I couldn't find anything suitable for describing the binary format for Concise Encoding (https://concise-encoding.org/), so I did the crazy thing, thinking "how hard could it be?" But it worked out and I have a formal description for it now:

* https://github.com/kstenerud/concise-encoding/blob/master/cb...

* https://github.com/kstenerud/concise-encoding/blob/master/ct...

So it's primarily geared towards documentation. That being said, there's no reason why tools couldn't use it as well (I'm trying to keep it consistent enough that tools could be built, or possibly even a specialized parser-generator language that uses Dogma as a base, similar to how Antlr uses a modified EBNF). But I've got too many projects going on as it is, so anyone who wants to build tooling, I'm all for it and will help where I can :)

Error handling would be an implementation detail. The spec only describes what counts as a malformed grammar, and what counts as an ambiguous grammar (and a small bit about undefined behaviour, which counts as ambiguous).

Apart from clearly specifying the binary format, do you have any tools to generate code to process said format? What do you envision this will be used for -- apart from documentation?

It's just for documentation atm. I'm already three levels deep into yak shaving for what I actually want to accomplish, so tools and such will have to wait until my primary project is done :)

In expressions such as:

    uint(48, ~);

What does ~ mean? If it means anything is allowed, then it would be more concise to simply say:

    uint(48);

Yes I thought about that, but then it would require allowing function overloads, which adds complexity to the metalanguage. Since the purpose is for documentation, I think it's better to be explicit anyway.

It's your metalanguage so you should make it the way you like. If I was doing it, I'd allow for default values for stuff.

how this compares to, say, https://preserves.dev/ ?

i thought of similar thing/lang very long time ago, then for reverse engineering purposes. e.g. describe old (pre-)M$ word doc binary format, have an interpreter over it, then use it to add some changes to a document..

This looks similar to https://concise-encoding.org/

Dogma was developed as a consequence of trying to describe Concise Binary Encoding. The CBE spec used to look like the preserves binary spec, full of hex values, tables and various ad-hoc illustrations: https://preserves.dev/preserves-binary.html

Now the CBE formal description looks like this: https://github.com/kstenerud/concise-encoding/blob/master/cb...

And the regular documentation looks like this: https://github.com/kstenerud/concise-encoding/blob/master/cb...

Dogma also does text formats because Concise Encoding has a text and binary format, so I needed a metalanguage that could do both in order to make it less jarring for a reader:

Docs: https://github.com/kstenerud/concise-encoding/blob/master/ct...

Formal: https://github.com/kstenerud/concise-encoding/blob/master/ct...

Reply on news.ycombinator.com