# Testable primitives for writing to screen.
#
# Mu mostly uses the screen for text, but it builds it out of pixel graphics
# and a bitmap font. There is no support for a blinking cursor, scrolling and
# so on.
#
# Fake screens are primarily for testing text-mode prints. However, they do
# support some rudimentary pixel operations as well. Caveats:
#
# - Drawing pixels atop text or vice versa is not supported. Results in a fake
# screen will not mimic real screens in these situations.
# - Fake screens currently also assume a fixed-width 8x16 font.
type screen {
# text mode
width: int
height: int
data: (handle array screen-cell)
cursor-x: int # [0..width)
cursor-y: int # [0..height)
# pixel graphics
pixels: (handle array byte)
}
type screen-cell {
data: grapheme
color: int
background-color: int
}
fn initialize-screen _screen: (addr screen), width: int, height: int, pixel-graphics?: boolean {
var screen/esi: (addr screen) <- copy _screen
var tmp/eax: int <- copy 0
var dest/edi: (addr int) <- copy 0
# screen->width = width
dest <- get screen, width
tmp <- copy width
copy-to *dest, tmp
# screen->height = height
dest <- get screen, height
tmp <- copy height
copy-to *dest, tmp
# populate screen->data
{
var data-ah/edi: (addr handle array screen-cell) <- get screen, data
var capacity/eax: int <- copy width
capacity <- multiply height
populate data-ah, capacity
}
# if necessary, populate screen->pixels
{
compare pixel-graphics?, 0/false
break-if-=
var pixels-ah/edi: (addr handle array byte) <- get screen, pixels
var capacity/eax: int <- copy width
capacity <- shift-left 3/log2-font-width
capacity <- multiply height
capacity <- shift-left 4/log2-font-height
populate pixels-ah, capacity
}
# screen->cursor-x = 0
dest <- get screen, cursor-x
copy-to *dest, 0
# screen->cursor-y = 0
dest <- get screen, cursor-y
copy-to *dest, 0
}
# in graphemes
fn screen-size _screen: (addr screen) -> _/eax: int, _/ecx: int {
var screen/esi: (addr screen) <- copy _screen
var width/eax: int <- copy 0
var height/ecx: int <- copy 0
compare screen, 0
{
break-if-!=
return 0x80/128, 0x30/48
}
# fake screen
var tmp/edx: (addr int) <- get screen, width
width <- copy *tmp
tmp <- get screen, height
height <- copy *tmp
return width, height
}
# testable screen primitive
fn draw-grapheme _screen: (addr screen), g: grapheme, x: int, y: int, color: int, background-color: int {
var screen/esi: (addr screen) <- copy _screen
{
compare screen, 0
break-if-!=
draw-grapheme-on-real-screen g, x, y, color, background-color
return
}
# fake screen
var idx/ecx: int <- screen-cell-index screen, x, y
var data-ah/eax: (addr handle array screen-cell) <- get screen, data
var data/eax: (addr array screen-cell) <- lookup *data-ah
var offset/ecx: (offset screen-cell) <- compute-offset data, idx
var dest-cell/ecx: (addr screen-cell) <- index data, offset
var dest-grapheme/eax: (addr grapheme) <- get dest-cell, data
var g2/edx: grapheme <- copy g
copy-to *dest-grapheme, g2
var dest-color/eax: (addr int) <- get dest-cell, color
var src-color/edx: int <- copy color
copy-to *dest-color, src-color
dest-color <- get dest-cell, background-color
src-color <- copy background-color
copy-to *dest-color, src-color
}
# we can't really render non-ASCII yet, but when we do we'll be ready
fn draw-code-point screen: (addr screen), c: code-point, x: int, y: int, color: int, background-color: int {
var g/eax: grapheme <- copy c
draw-grapheme screen, g, x, y, color, background-color
}
# not really needed for a real screen, though it shouldn't do any harm
fn screen-cell-index _screen: (addr screen), x: int, y: int -> _/ecx: int {
var screen/esi: (addr screen) <- copy _screen
{
compare x, 0
break-if->=
abort "screen-cell-index: negative x"
}
{
var xmax/eax: (addr int) <- get screen, width
var xcurr/ecx: int <- copy x
compare xcurr, *xmax
break-if-<
abort "screen-cell-index: x too high"
}
{
compare y, 0
break-if->=
abort "screen-cell-index: negative y"
}
{
var ymax/eax: (addr int) <- get screen, height
var ycurr/ecx: int <- copy y
compare ycurr, *ymax
break-if-<
abort "screen-cell-index: y too high"
}
var width-addr/eax: (addr int) <- get screen, width
var result/ecx: int <- copy y
result <- multiply *width-addr
result <- add x
return result
}
fn cursor-position _screen: (addr screen) -> _/eax: int, _/ecx: int {
var screen/esi: (addr screen) <- copy _screen
{
compare screen, 0
break-if-!=
var x/eax: int <- copy 0
var y/ecx: int <- copy 0
x, y <- cursor-position-on-real-screen
return x, y
}
# fake screen
var cursor-x-addr/eax: (addr int) <- get screen, cursor-x
var cursor-y-addr/ecx: (addr int) <- get screen, cursor-y
return *cursor-x-addr, *cursor-y-addr
}
fn set-cursor-position _screen: (addr screen), x: int, y: int {
var screen/esi: (addr screen) <- copy _screen
{
compare screen, 0
break-if-!=
set-cursor-position-on-real-screen x, y
return
}
# fake screen
# ignore x < 0
{
compare x, 0
break-if->=
return
}
# ignore x >= width
{
var width-addr/eax: (addr int) <- get screen, width
var width/eax: int <- copy *width-addr
compare x, width
break-if-<=
return
}
# ignore y < 0
{
compare y, 0
break-if->=
return
}
# ignore y >= height
{
var height-addr/eax: (addr int) <- get screen, height
var height/eax: int <- copy *height-addr
compare y, height
break-if-<
return
}
# screen->cursor-x = x
var dest/edi: (addr int) <- get screen, cursor-x
var src/eax: int <- copy x
copy-to *dest, src
# screen->cursor-y = y
dest <- get screen, cursor-y
src <- copy y
copy-to *dest, src
}
fn draw-cursor screen: (addr screen), g: grapheme {
{
compare screen, 0
break-if-!=
draw-cursor-on-real-screen g
return
}
# fake screen
var cursor-x/eax: int <- copy 0
var cursor-y/ecx: int <- copy 0
cursor-x, cursor-y <- cursor-position screen
draw-grapheme screen, g, cursor-x, cursor-y, 0/fg, 7/bg
}
fn clear-screen _screen: (addr screen) {
var screen/esi: (addr screen) <- copy _screen
{
compare screen, 0
break-if-!=
clear-real-screen
return
}
# fake screen
set-cursor-position screen, 0, 0
var y/eax: int <- copy 0
var height/ecx: (addr int) <- get screen, height
{
compare y, *height
break-if->=
var x/edx: int <- copy 0
var width/ebx: (addr int) <- get screen, width
{
compare x, *width
break-if->=
draw-code-point screen, 0x20/space, x, y, 0/fg=black, 0/bg=black
x <- increment
loop
}
y <- increment
loop
}
set-cursor-position screen, 0, 0
var pixels-ah/eax: (addr handle array byte) <- get screen, pixels
var pixels/eax: (addr array byte) <- lookup *pixels-ah
var i/ecx: int <- copy 0
var max/edx: int <- length pixels
{
compare i, max
break-if->=
var curr/eax: (addr byte) <- index pixels, i
var zero/ebx: byte <- copy 0
copy-byte-to *curr, zero
i <- increment
loop
}
}
fn fake-screen-empty? _screen: (addr screen) -> _/eax: boolean {
var screen/esi: (addr screen) <- copy _screen
var y/eax: int <- copy 0
var height/ecx: (addr int) <- get screen, height
{
compare y, *height
break-if->=
var x/edx: int <- copy 0
var width/ebx: (addr int) <- get screen, width
{
compare x, *width
break-if->=
var g/eax: grapheme <- screen-grapheme-at screen, x, y
{
compare g, 0
break-if-=
compare g, 0x20/space
break-if-=
return 0/false
}
x <- increment
loop
}
y <- increment
loop
}
var pixels-ah/eax: (addr handle array byte) <- get screen, pixels
var pixels/eax: (addr array byte) <- lookup *pixels-ah
var y/ebx: int <- copy 0
var height-addr/edx: (addr int) <- get screen, height
var height/edx: int <- copy *height-addr
height <- shift-left 4/log2-font-height
{
compare y, height
break-if->=
var width-addr/edx: (addr int) <- get screen, width
var width/edx: int <- copy *width-addr
width <- shift-left 3/log2-font-width
var x/edi: int <- copy 0
{
compare x, width
break-if->=
var idx/ecx: int <- pixel-index screen, x, y
var color-addr/ecx: (addr byte) <- index pixels, idx
var color/ecx: byte <- copy-byte *color-addr
compare color, 0
{
break-if-=
return 0/false
}
x <- increment
loop
}
y <- increment
loop
}
return 1/true
}
fn clear-rect _screen: (addr screen), xmin: int, ymin: int, xmax: int, ymax: int, background-color: int {
var screen/esi: (addr screen) <- copy _screen
{
compare screen, 0
break-if-!=
clear-rect-on-real-screen xmin, ymin, xmax, ymax, background-color
return
}
# fake screen
set-cursor-position screen, 0, 0
var y/eax: int <- copy ymin
var ymax/ecx: int <- copy ymax
{
compare y, ymax
break-if->=
var x/edx: int <- copy xmin
var xmax/ebx: int <- copy xmax
{
compare x, xmax
break-if->=
draw-code-point screen, 0x20/space, x, y, 0/fg, background-color
x <- increment
loop
}
y <- increment
loop
}
set-cursor-position screen, 0, 0
}
# there's no grapheme that guarantees to cover every pixel, so we'll bump down
# to pixels for a real screen
fn clear-real-screen {
var y/eax: int <- copy 0
{
compare y, 0x300/screen-height=768
break-if->=
var x/edx: int <- copy 0
{
compare x, 0x400/screen-width=1024
break-if->=
pixel-on-real-screen x, y, 0/color=black
x <- increment
loop
}
y <- increment
loop
}
}
fn clear-rect-on-real-screen xmin: int, ymin: int, xmax: int, ymax: int, background-color: int {
var y/eax: int <- copy ymin
y <- shift-left 4/log2-font-height
var ymax/ecx: int <- copy ymax
ymax <- shift-left 4/log2-font-height
{
compare y, ymax
break-if->=
var x/edx: int <- copy xmin
x <- shift-left 3/log2-font-width
var xmax/ebx: int <- copy xmax
xmax <- shift-left 3/log2-font-width
{
compare x, xmax
break-if->=
pixel-on-real-screen x, y, background-color
x <- increment
loop
}
y <- increment
loop
}
}
fn screen-grapheme-at _screen: (addr screen), x: int, y: int -> _/eax: grapheme {
var screen/esi: (addr screen) <- copy _screen
var idx/ecx: int <- screen-cell-index screen, x, y
var result/eax: grapheme <- screen-grapheme-at-idx screen, idx
return result
}
fn screen-grapheme-at-idx _screen: (addr pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight .c { color: #888888 } /* Comment */
.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
.highlight .k { color: #008800; font-weight: bold } /* Keyword */
.highlight .ch { color: #888888 } /* Comment.Hashbang */
.highlight .cm { color: #888888 } /* Comment.Multiline */
.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.highlight .cpf { color: #888888 } /* Comment.PreprocFile */
.highlight .c1 { color: #888888 } /* Comment.Single */
.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #aa0000 } /* Generic.Error */
.highlight .gh { color: #333333 } /* Generic.Heading */
.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.highlight .go { color: #888888 } /* Generic.Output */
.highlight .gp { color: #555555 } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #666666 } /* Generic.Subheading */
.highlight .gt { color: #aa0000 } /* Generic.Traceback */
.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008800 } /* Keyword.Pseudo */
.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.highlight .na { color: #336699 } /* Name.Attribute */
.highlight .nb { color: #003388 } /* Name.Builtin */
.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
.highlight .nd { color: #555555 } /* Name.Decorator */
.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #336699 } /* Name.Variable */
.highlight .ow { color: #008800 } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.highlight .sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.highlight .dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.highlight .vc { color: #336699 } /* Name.Variable.Class */
.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
.highlight .vm { color: #336699 } /* Name.Variable.Magic */
.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */Mu explores ways to turn arbitrary manual tests into reproducible automated
tests. Hoped-for benefits:
1. Projects release with confidence without requiring manual QA or causing
regressions for their users.
1. Open source projects become easier for outsiders to comprehend, since they
can more confidently try out changes with the knowledge that they'll get
rapid feedback if they break something. As a result projects become more
*rewrite-friendly*: it's easier to leave your project's historical
accidents and other baggage behind if you can be confident of not causing
regressions.
1. It becomes easier to teach programming by emphasizing tests far earlier
than we do today.
In this quest, Mu is currently experimenting with the following mechanisms:
1. New, testable interfaces for the operating system. Currently manual tests
are hard to automate because a file you assumed might vanish, the network
might go down, etc. To make manual tests reproducible it suffices to
improve the 15 or so OS syscalls through which a computer talks to the
outside world. We have to allow programs to transparently write to a fake
screen, read from a fake disk/network, etc. In Mu, printing to screen
explicitly takes a screen object, so it can be called on the real screen,
or on a fake screen inside tests, so that we can then check the expected
state of the screen at the end of a test. Here's a test for a little
text-mode chessboard program in Mu (delimiting the edge of the 'screen'
with dots):
<br> <img alt='a screen test' src='html/chessboard-test.png'>
<br>I'm building up similarly *dependency-injected* interfaces to the
keyboard, mouse, touch screen, disk, network, etc.
1. Support for testing side-effects like performance, deadlock-freedom,
race-freeness, memory usage, etc. Mu's *white-box tests* can check not just
the results of a function call, but also the presence or absence of
specific events in the log of its progress. For example, here's a test that
our string-comparison function doesn't scan individual characters unless it
has to:
<br> <img alt='white-box test' src='html/tracing-test.png'>
<br>Another example: if a sort function logs each swap, a performance test can
ensure that the number of swaps doesn't quadruple when the size of the
input doubles.
<p>Besides expanding the scope of tests, this ability also allows more
radical refactoring without needing to modify tests. All Mu's tests call a
top-level function rather than individual sub-systems directly. As a result
the way the subsystems are invoked can be radically changed (interface
changes, making synchronous functions asynchronous, etc.). As long as the
new versions emit the same implementation-independent events in the logs,
the tests will continue to pass. ([More information.](http://akkartik.name/post/tracing-tests))
1. Organizing code and tests in layers of functionality, so that outsiders can
build simple and successively more complex versions of a project, gradually
enabling more peripheral features. Think of it as a cleaned-up `git log`
for the project. ([More information.](http://akkartik.name/post/wart-layers))
Since I don't understand how Linux and other modern platforms work, Mu is
built on an idealized VM while I learn. Eventually the plan is to transplant
what I learn back to Linux.
To minimize my workload, Mu doesn't have a high-level language yet. Instead,
I've been programming directly in the VM's idealized assembly language. I
expected this to be painful, but it's had some surprising benefits. First,
programs as lists of instructions seem to be easier for non-programmers to
comprehend than programs as trees of expressions. Second, I've found that
Literate Programming using layers makes assembly much more ergonomic. Third,
labels for gotos turn out to be great waypoints to insert code at from future
layers; when I tried to divide C programs into layers, I sometimes had to
split statements in two so I could insert code between them.
High level languages today seem to provide three kinds of benefits:
expressiveness (e.g. nested expressions, classes), safety (e.g. type checking)
and automation (e.g. garbage collection). Mu gives up some expressiveness by
not providing recursive expressions, but still supports lexical scope, generic
types, and higher-order functions. It provides strong memory safety in spite
of having manual memory management and supporting full-scale pointer
operations (albeit at the cost of some runtime checks).
*Taking Mu for a spin*
Mu is currently implemented in C++ and requires a unix-like environment. It's
been tested on Ubuntu and Mac OS X, on x86, x86\_64 and ARMv7 with recent
versions of gcc and clang. Since it uses no recent language features and has
no exotic dependencies, it should work with most reasonable versions,
compilers or processors.
[](https://travis-ci.org/akkartik/mu)
Running Mu will always recompile it if necessary:
```shell
$ cd mu
$ ./mu
```
As a simple example, here's a program with some arithmetic:
<img alt='code example' src='html/example1.png'>
As I said before, Mu functions are lists of instructions, one to a line. Each
instruction operates on some *ingredients* and returns some *products*.
```
[products] <- instruction [ingredients]
```
Result and ingredient *reagents* cannot contain instructions or infix
expressions. On the other hand, you can have any number of them. In
particular, you can have any number of products. For example, you can perform
integer division as follows:
```
quotient:number, remainder:number <- divide-with-remainder 11, 3
```
Each reagent consists of a name and its type, separated by a colon. You only
have to specify the type the first time you mention a name, but you can be
more explicit if you choose. Types can be multiple words and even arbitrary
trees, like:
```nim
x:array:number:3 # x is an array of 3 numbers
y:list:number # y is a list of numbers
# ':' is just syntactic sugar
{z: (map (address array character) (list number))} # map from string to list of numbers
```
Try out the program now:
```shell
$ ./mu example1.mu
$
```
Not much to see yet, since it doesn't print anything. To print the result, try
adding the instruction `$print a` to the function.
---
Here's a second example, of a function that can take ingredients:
<img alt='fahrenheit to celsius' src='html/f2c-1.png'>
Functions can specify headers showing their expected ingredients and products,
separated by `->` (unlike the `<-` in calls).
Since Mu is a low-level VM language, it provides extra control at the cost of
verbosity. Using `local-scope`, you have explicit control over stack frames to
isolate your functions in a type-safe manner. You can also create more
sophisticated setups like closures. One consequence of this extra control: you
have to explicitly `load-ingredients` after you set up the stack.
An alternative syntax is what the above example is converted to internally:
<img alt='fahrenheit to celsius desugared' src='html/f2c-2.png'>
The header gets dropped after checking types at call-sites, and after
replacing `load-ingredients` with explicit instructions to load each
ingredient separately, and to explicitly return products to the caller. After
this translation functions are once again just lists of instructions.
This alternative syntax isn't just an implementation detail. I've actually
found it easier to teach functions to non-programmers by starting with this
syntax, so that they can visualize a pipe from caller to callee, and see the
names of variables get translated one by one through the pipe.
---
A third example, this time illustrating conditionals:
<img alt='factorial example' src='html/factorial.png'>
In spite of how it looks, this is still just a list of instructions and
labels. Internally, the instructions `break` and `loop` get converted to
`jump` instructions to after the enclosing `}` or `{` labels, respectively.
Try out the factorial program now:
```shell
$ ./mu factorial.mu
result: 120 # factorial of 5
```
You can also run its unit tests:
```shell
$ ./mu test factorial.mu
```
Here's what one of the tests inside `factorial.mu` looks like:
<img alt='test example' src='html/factorial-test.png'>
Every test conceptually spins up a really lightweight virtual machine, so you
can do things like check the value of specific locations in memory. You can
also print to screen and check that the screen contains what you expect at the
end of a test. For example, you've seen earlier how `chessboard.mu` checks the
initial position of a game of chess (delimiting the edges of the screen with
dots):
<img alt='screen test' src='html/chessboard-test.png'>
Similarly you can fake the keyboard to pretend someone typed something:
```
assume-keyboard [a2-a4]
```
As we add a file system, graphics, audio, network support and so on, we'll
augment scenarios with corresponding abilities.
---
You can append arbitrary properties to reagents besides types and spaces. Just
separate them with slashes.
```nim
x:array:number:3/uninitialized
y:string/tainted:yes
z:number/assign-once:true/assigned:false
```
Most properties are meaningless to Mu, and it'll silently skip them when
running, but they are fodder for *meta-programs* to check or modify your
programs, a task other languages typically hide from their programmers. For
example, where other programmers are restricted to the checks their type
system permits and forces them to use, you'll learn to create new checks that
make sense for your specific program. If it makes sense to perform different
checks in different parts of your program, you'll be able to do that.
You can imagine each reagent as a table, rows separated by slashes, columns
within a row separated by colons. So the last example above would become
something like this:
```
z : integer /
assign-once : true /
assigned : false
```
---
An alternative way to define factorial is by inserting labels and later
inserting code at them.
<img alt='literate programming' src='html/tangle.png'>
(You'll find this version in `tangle.mu`.)
By convention we use the prefix '+' to indicate function-local label names you
can jump to, and surround in '<>' global label names for inserting code at.
---
Another example, this time with concurrency:
<img alt='forking concurrent routines' src='html/fork.png'>
```shell
$ ./mu fork.mu
```
Notice that it repeatedly prints either '34' or '35' at random. Hit ctrl-c to
stop.
[Yet another example](http://akkartik.github.io/mu/html/channel.mu.html) forks
two 'routines' that communicate over a channel:
```shell
$ ./mu channel.mu
produce: 0
produce: 1
produce: 2
produce: 3
consume: 0
consume: 1
consume: 2
produce: 4
consume: 3
consume: 4
# The exact order above might shift over time, but you'll never see a number
# consumed before it's produced.
```
Channels are the unit of synchronization in Mu. Blocking on a channel is the
only way for the OS to put a task to sleep. The plan is to do all I/O over
channels.
Routines are expected to communicate purely by message passing, though nothing
stops them from sharing memory since all routines share a common address
space. However, idiomatic Mu will make it hard to accidentally read or clobber
random memory locations. Bounds checking is baked deeply into the semantics,
and pointers can never be invalidated.
---
If you're still reading, here are some more things to check out:
a) Look at the [chessboard program](http://akkartik.github.io/mu/html/chessboard.mu.html)
for a more complex example where I write tests showing blocking reads from the
keyboard and what gets printed to the screen -- things we don't typically
associate with automated tests.
b) Try skimming the [colorized source code](https://akkartik.github.io/mu).
I'd like it to eventually be possible to get a pretty good sense for how
things work just by skimming the files in order, skimming the top of each file
and ignoring details lower down. Tell me how successful my efforts are.
c) Try running the tests:
```shell
$ ./mu test
```
d) Try out the programming environment:
```shell
$ ./mu test edit
$ ./mu edit
```
Screenshot:
<img alt='programming environment' src='html/edit.png'>
You write functions on the left and try them out in *sandboxes* on the right.
Hit F4 to rerun all sandboxes with the latest version of the code. More
details: http://akkartik.name/post/mu. Beware, it won't save your edits by
default. But if you create a sub-directory called `lesson/` under `mu/` it
will. If you turn that directory into a git repo with `git init`, it will also
back up your changes each time you hit F4.
Once you have a sandbox you can click on its result to mark it as expected:
<img alt='expected result' src='html/expected-result.png'>
Later if the result changes it'll be flagged in red to draw your attention to
it. Thus, manually tested sandboxes become reproducible automated tests.
<img alt='unexpected result' src='html/unexpected-result.png'>
Another feature: Clicking on the code in a sandbox expands its trace for you
to browse. To add to the trace, use `stash`. For example:
```nim
stash [first ingredient is], x
```
Invaluable for understanding complex control flow without cluttering up the
screen.
The next major milestone on Mu's roadmap is dependency-injected interfaces for
the network and file system.
**Credits**
Mu builds on many ideas that have come before, especially:
- [Peter Naur](http://alistair.cockburn.us/ASD+book+extract%3A+%22Naur,+Ehn,+Musashi%22)
for articulating the paramount problem of programming: communicating a
codebase to others;
- [Christopher Alexander](http://www.amazon.com/Notes-Synthesis-Form-Harvard-Paperbacks/dp/0674627512)
and [Richard Gabriel](http://dreamsongs.net/Files/PatternsOfSoftware.pdf) for
the intellectual tools for reasoning about the higher order design of a
codebase;
- Unix and C for showing us how to co-evolve language and OS, and for teaching
the (much maligned, misunderstood and underestimated) value of concise
*implementation* in addition to a clean interface;
- Donald Knuth's [literate programming](http://www.literateprogramming.com/knuthweb.pdf)
for liberating "code for humans to read" from the tyranny of compiler order;
- [David Parnas](http://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf)
and others for highlighting the value of separating concerns and stepwise
refinement;
- [Lisp](http://www.paulgraham.com/rootsoflisp.html) for showing the power of
dynamic languages, late binding and providing the right primitives *a la
carte*, especially lisp macros;
- The folklore of debugging by print and the trace facility in many lisp
systems;
- Automated tests for showing the value of developing programs inside an
elaborate harness;
- [Python doctest](http://docs.python.org/2/library/doctest.html) for
exemplifying interactive documentation that doubles as tests;
- [ReStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)
and [its antecedents](https://en.wikipedia.org/wiki/Setext) for showing that
markup can be clean;
- BDD for challenging us all to write tests at a higher level;
- JavaScript and CSS for demonstrating the power of a DOM for complex
structured documents.
- Rust for demonstrating that a system-programming language can be safe.