4a943d4ed3
I've been saying for a while[1][2][3] that adding extra abstractions makes things harder for newcomers, and adding new notations doubly so. And then I notice this DSL in my own backyard. Makes me feel like a hypocrite. [1] https://news.ycombinator.com/item?id=13565743#13570092 [2] https://lobste.rs/s/to8wpr/configuration_files_are_canary_warning [3] https://lobste.rs/s/mdmcdi/little_languages_by_jon_bentley_1986#c_3miuf2 The implementation of the DSL was also highly hacky: a) It was happening in the tangle/ tool, but was utterly unrelated to tangling layers. b) There were several persnickety constraints on the different kinds of lines and the specific order they were expected in. I kept finding bugs where the translator would silently do the wrong thing. Or the error messages sucked, and readers may be stuck looking at the generated code to figure out what happened. Fixing error messages would require a lot more code, which is one of my arguments against DSLs in the first place: they may be easy to implement, but they're hard to design to go with the grain of the underlying platform. They require lots of iteration. Is that effort worth prioritizing in this project? On the other hand, the DSL did make at least some readers' life easier, the ones who weren't immediately put off by having to learn a strange syntax. There were fewer quotes to parse, fewer backslash escapes. Anyway, since there are also people who dislike having to put up with strange syntaxes, we'll call that consideration a wash and tear this DSL out. --- This commit was sheer drudgery. Hopefully it won't need to be redone with a new DSL because I grow sick of backslashes. |
||
|---|---|---|
| .. | ||
| 000test.cc | ||
| 001trace.cc | ||
| 001trace.test.cc | ||
| 002main.cc | ||
| 003tangle.cc | ||
| 003tangle.test.cc | ||
| Readme.md | ||
| boot.cc | ||
Readme.md
Literate Programming tool to convert Mu's layers into compilable form.
Mu's tangling directives differ from Knuth's classic implementation. The classical approach starts out with labeled subsystems that are initially empty, and adds code to them using two major directives:
<name> ≡
<code>
<name> +≡
<code>
(<code> can span multiple lines.)
This approach is best suited for top-down exposition.
On the other hand, Mu's tangling directives are better suited for a cleaned-up history of a codebase. Subsystems start out with a simple skeleton of the core of the program. Later versions then tell a story of the evolution of the program, with each version colocating all the code related to new features.
Read more:
- http://akkartik.name/post/wart-layers
- http://akkartik.name/post/literate-programming
- https://github.com/akkartik/mu/blob/master/000organization.cc
directives
Add code to a project:
:(code)
<code>
Insert code before a specific line:
:(before <waypoint>)
<code>
Here <waypoint> is a substring matching a single line in the codebase. (We
never use regular expressions.) Surround the substring in " quotes if it
spans multiple words.
Insert code after a specific line:
:(after <waypoint>)
<code>
Delete a specific previously-added line (because it's not needed in a newer version).
:(delete <line>)
Delete a block of code starting with a given header and surrounded by { and
}:
:(delete{} <header>)
(Caveat: doesn't directly support C's do..while loops.)
Replace a specific line with new code:
:(replace <line>)
<code>
This is identical to:
:(before <line>)
<code>
:(delete <line>)
(Assuming <code> did not insert a new line matching the substring <line>.)
Replace a block of code with another:
:(replace{} <header>)
<code>
Insert code before or after a substring pattern that isn't quite a unique waypoint in the whole codebase:
:(before <line> following <waypoint>)
<code>
:(after <line> following <waypoint>)
<code>
:(before <waypoint> then <line>)
<code>
:(after <waypoint> then <line>)
<code>