Enaml - part 3

Enaml - part 3

in

This is the third post about my Domain Specific Language (DSL). See part 1 here if you missed it. There’s also part 2 here.

Last time we went through the basic tags and this time we will go through the advanced or meta tags.

Meta tags

Now we get into the real juicy stuff. These are more advanced tags that let nodes inherit from other nodes or otherwise indirectly affect the node. They heavily utilize the node’s path so if you skipped the key tag section in part 2, make sure you read that first.

Inheritance tag

The inheritance tag copies the contents (including children) of the given node into this one:

@ui.checkbox

The tag simply contains the path of the inherited node. For example, here we specify once the font values for a label:

:ui.label .font.courier .font-size.1 .color.255.0.0 

Which we can then use in a different context:

:header
  "Menu" @ui.label .font-size.2
  "Sandwich" @ui.label
  "Salmon tofurkey" @ui.label
  "Coffee" @ui.label

Note that the font-size attribute overrides the inherited value so the “Menu” title is bigger. We could also use multiple inheritance like this if we wanted to make it into a widget of its own:

:ui.title @ui.label .font-size.2

This is not object-oriented style inheritance; more like the prototype style inheritance used in some languages but even simpler. The contents of the source node are simply copied into the current one at parse time from left to right.

This reduces the amount of copy-paste an author has to do. It’s an especially common pattern in traditional roguelike codebases where there are a lot of variants of a base object (like a basic goblin, a goblin mage, king, etc.)

Because the inherited node can be anywhere in the tree, the user is free to define their own “node template” libraries how they see fit.

But the true power of inheritance comes when combined with the last two tags; overwriting and replacement.

Overwrite tag

The overwrite tag tells the parses how to handle existing data when we are defining a node on top of an already existing one. It is a series of flags after the tag prefix semicolon:

;a.t.c

If you recall the key tag definition above, in Enaml you can define a node anywhere in the file you want, even multiple times. Imagine a situation where a mod wants to add location data to existing entities:

:entities
  :lakes
    :ontario "Lake Ontario"
    :algae "Algae Lake"
# ...other data...
:entities.lakes.ontario .location.canada
:entities.lakes.algae .location.antarctica

This works but produces a warning because Enaml doesn’t know if the user added the data intentionally or not. Adding the overwrite tag removes the warning:

:entities.lakes.ontario ; .location.canada
:entities.lakes.algae ; .location.antarctica

Note that the tag is empty since we are not doing anything special.

Overwrite flags

The default behavior for overwriting is to:

  • replace the original text with the new text, if any
  • add any new basic tags to the list of original tags
  • keep the child nodes as-is

If the user wants to do something special, these are the flags they can give:

  • a to append the text instead of replacing it
  • p to prepend the text instead of replacing it
  • t to remove original basic tags
  • c to remove original child nodes
  • d to delete the original node itself

Not all combinations of flags are valid, obviously. The delete flag especially makes the other flags meaningless.

Multiline nodes

Some of you may have noticed last time is that if every line is a node and tags, how the heck do multiline strings work? Or a particularly long list of tags?

Well, first of all I did deliberately choose the single line format default because I want to guide myself away both from complicating things and from writing walls of text. A lot of the philosophy around this project revolves around the YAGNI and especially KISS principles.

But the reality is that sometimes you really need that ability to add a linebreak or two. For this the overwrite tag has a special case.

If you define a node without a key, it usually gets a generated one automatically. However, if it is at the same indentation as the previous line, and it has an overwrite tag, it is instead used to overwrite the previous node. So if you have a wall of text, you can write it like this (text from Wikipedia):

:blatherings
  :feature-creep
  ;a "Feature creep is the "
  ;a "excessive ongoing "
  ;a "expansion or addition of "
  ;a "new features in a product, "
  ;a "especially in computer "
  ;a "software, video games "
  ;a "(where it should not be "
  ;a "confused with power creep) "
  ;a "and consumer and business "
  ;a "electronics."

The same principle works for tags.

This has the added benefit of being able to line up the multiline strings which is important for readability.

Localization

Another thing that might have raised concerns from people about the previous post is the question of localization. It is a bad habit in the game dev community to mix code and UI text. This results in problems down the line.

I don’t think localization will be that relevant for me because lots of very dynamic text is notoriously difficult to localize. English is also particularly good for dynamic text (lots and lots of synonyms, regular verbs, non-gendered nouns, etc.)

But still, it is pretty easy to process your translations into and out of a replacement data file which only affects the text fields:

:entities.car ; "auto"
:entities.boat ; "vene"
:animals._0.the-name ; "kissa"
:animals._1.the-name , "koira"
# ...etc...

Note how the third and fourth rows have a node which did not have an explicit key so an implicit one was generated for them and therefore they can still be overwritten here.

Extracting the above file should also be easy to add if the need arises since I already have a parser that turns Enaml into EDN. Some translation file formats can also contain hints to the context of the translation. The system could also use the inherent structure of the Enaml source files to provide this automatically.

Replacement tag

The replacement tag allows the user to do a find & replace operation on the current node:

=X.5.Y.6

Here we are replacing each X with 5 and each Y with 6 in the current node and its child nodes. Any number of replacements are accepted, could be just one =X.5 or three =X.5.Y.6.Z.true.

I guess you could use it on a single node, but its true power comes with being combined with the other meta tags.

Meta tags combined

You can use inheritance to copy a complex node and then selectively overwrite its children. Like this:

:hard-mode @ui.checkbox =FLAG.hard-mode
  :label ; "Hard mode"

Where checkbox is a user-defined widget made of primitive UI components like images and labels. Inheritance allows us to hide most of the repetitive stuff in ui.checkbox and replacement allows us to reach into it to change what value the checkbox affects.

It is almost like defining functions or macros in an actual programming language.

Conclusion

This was pretty technical and I think enough about Enaml for now.

If you want to read more writing like this, one of my favorites is the documentation for Versu and especially the DSL for it called Praxis. You can probably see how it has been an inspiration, what with the logic programming and dot notation. Although Praxis has a more focused scope.

Other inspirations are of course YAML and XML. From the Clojure ecosystem also re-frame with its data-oriented events and hiccup syntax. Maybe more about this when it’s time to write about the event handling.

But a less technical post for next time so see you then!