shell/README.md

   1 ### A prototype shell for the Mu computer
   2
   3 Currently runs a tiny dialect of Lisp. Steps to run it from the top-level:
   4
   5 1. Build it:
   6
   7   ```sh
   8   ./translate shell/*.mu      # generates code.img
   9   ```
  10
  11   You can now already run it (under emulation):
  12   ```sh
  13   qemu-system-i386 code.img
  14   ```
  15
  16   But let's add some more 'meat' to play with.
  17
  18 2. Create a data disk with a library of functions.
  19
  20   ```sh
  21   dd if=/dev/zero of=data.img count=20160         # approximately 10MB
  22   dd if=shell/data.limg of=data.img conv=notrunc
  23   ```
  24
  25   Equivalently, use `tools/image-data`.
  26
  27   ```sh
  28   tools/image-data 10 < shell/data.limg
  29   ```
  30
  31 3. Run with data disk (and 2GB of RAM):
  32   ```sh
  33   qemu-system-i386 -m 2G -hda code.img -hdb data.img
  34   ```
  35
  36   <img alt='screenshot of the Mu shell' src='../html/20210624-shell.png'>
  37
  38   The Mu computer has a fixed-size screen, which the shell environment
  39   partitions into two major regions, with a context-sensitive menu of keyboard
  40   shortcuts along the bottom. (No mouse support at the moment.) On the left,
  41   two-thirds of the screen is for editing functions and viewing documentation
  42   on available primitives. On the right is a REPL where you can try out
  43   expressions and see their output. The REPL also has a little toy screen and
  44   keyboard for interactively playing with side effects of expressions.
  45
  46   Try typing in some expressions at the REPL and hitting `ctrl-s` to see their
  47   results. Hit `ctrl-m` to focus on the `...` after a run, and browse how the
  48   _trace_ of how the results were computed. [Here's a 2-minute demo](https://archive.org/details/akkartik-mu-2021-05-31).
  49
  50   To navigate to a function to edit, hit `ctrl-g`. The list of functions
  51   doubles as a bare-bones &ldquo;file system,&rdquo; and functions are
  52   rendered in order of most recently touched, like in [Tiddlywiki](https://tiddlywiki.com).
  53   There is no scrolling anywhere yet.
  54
  55 3. If your Qemu installation supports them, an `-accel` argument
  56    will speed up emulation. Try `-accel help` to list your options.
  57
  58   Once you select an accelerator, I recommend also adjusting the `responsiveness`
  59   mask in shell/evaluate.mu, which controls how frequently the fake screen
  60   updates within the REPL. Smaller values will seem more responsive, larger
  61   values will run your programs faster. I like to see the fake screen update
  62   about once a second. Some suggested values depending on how fast your Qemu
  63   is running:
  64
  65   - `-accel kvm` on a T420s running Linux: `0xffff/responsiveness=64k`
  66   - `-accel tcg` on a 2019 Mac: `0xfff/responsiveness=4k`
  67
  68   Putting it all together, here's the command I typically use on Linux:
  69
  70   ```
  71   qemu-system-i386 -m 2G -accel kvm -hda code.img -hdb data.img
  72   ```
  73
  74 ### Indent-sensitivity
  75
  76 The Mu shell is a Lisp under the hood. However, you'll see a lot fewer
  77 parentheses than most Lisps because it can often automatically insert them
  78 based on indentation.
  79
  80 If you're already used to Lisp and always type in all parens, everything will
  81 continue to work. In particular, paren-insertion is disabled inside explicitly
  82 added parens. Once Mu sees a `(`, it stops trying to be smart until it sees a
  83 `)`.
  84
  85 I recommend tastefully only removing parens from top-level (`def`, `mac`,
  86 `define`) and control-flow words (`if`, `while`, `for`, etc.) Continue using
  87 parens for most real function calls. When in doubt, insert parens.
  88
  89 The rule for when parens are inserted is:
  90
  91 > Multi-word lines without leading parens are implicitly grouped with later
  92 > indented lines
  93
  94 For example:
  95
  96 ```
  97 if (> n 0)      =>      (if (> n 0)
  98   34                      34)
  99 ```
 100
 101 No indented lines after? Parens go around a single line:
 102
 103 ```
 104 f a             =>      (f a)
 105 f b                     (f b)
 106 ```
 107
 108 Lines with a single word are never wrapped in parens:
 109
 110 ```
 111 def (foo)       =>      (def (foo)
 112   42                      42)
 113 ```
 114
 115 Lines with a leading paren never get more parens:
 116
 117 ```
 118 def (foo x)     =>      (def (foo x)
 119   (print x) x             (print x) x)
 120 ```
 121
 122 ### Infix
 123
 124 The Mu shell supports infix operators:
 125 ```
 126 (3 + 1)
 127 => 4
 128 ```
 129
 130 You don't need spaces around infix operators:
 131 ```
 132 3+1
 133 => 4
 134 ```
 135
 136 Operator precedence is not hardcoded. Instead, there is just one rule:
 137 operators surrounded by whitespace have lower precedence than operators that
 138 are not.
 139
 140 To see how an expression is parsed, quote it:
 141 ```
 142 '3+1
 143 => (+ 3 1)
 144 ```
 145
 146 You can create your own infix operators:
 147 ```
 148 def (a <> b)
 149   (not (a = b))
 150 ```
 151
 152 To permit arbitrary infix operators, the Mu shell partitions the space of
 153 characters (technically Unicode [`code-point`s](../mu.md#variables-registers-and-memory))
 154 between operators and regular symbols. As a result, you can't define symbols
 155 mixing the two.
 156 ```
 157 '*global*
 158 => ((* global) . *)                   # probably not what you want
 159
 160 'uppercase-char-p
 161 => (- (- uppercase char) p)           # probably not what you want
 162
 163 '(char> a p)
 164 => ((char . >) a p)                   # probably not what you want
 165 ```
 166
 167 Infix operators also work in prefix position:
 168 ```
 169 (+ 3 1)
 170 => 4
 171 ```
 172
 173 As a special case, operators can be unary. A silly example:
 174 ```
 175 def (+++ x)
 176   x+1
 177
 178 +++4
 179 => 5
 180 ```
 181
 182 To pass operators to higher-order functions, wrap them in parens
 183 ```
 184 (map1 (+++) '(1 2 3))
 185 => (2 3 4)
 186 ```
 187
 188 ### Known issues
 189
 190 * No mouse support.
 191
 192 * Mu currently assumes access to 2GB of RAM. To increase that, modify the
 193   definition of `Heap` in 120allocate.subx, and then modify the `-m 2G`
 194   argument in the Qemu commands above. Mu currently has no virtual
 195   memory. If your Heap is too large for RAM, allocating past the end of RAM
 196   will succeed. However, accessing addresses not backed by RAM will fail with
 197   this error:
 198
 199   ```
 200   lookup: failed
 201   ```