tools/tangle.readme.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

[Literate Programming](https://en.wikipedia.org/wiki/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>
```