ref: d94a0eaa3b19e2ae41afb4c0514d17db664d8a4c
dir: /README.md/
# ORCΛ
<img src='https://raw.githubusercontent.com/hundredrabbits/Orca/master/resources/logo.png' width="600"/>
**Each letter of the alphabet is an operation**, lowercase letters typically operate on bang(`*`), uppercase letters operate on each frame. Bangs can be generated by various operations, such as `E` colliding with a `0`, see the [bang.orca](https://github.com/hundredrabbits/Orca/blob/master/examples/bang.orca) example. Watch a music video of [ORCΛ in action](https://twitter.com/neauoire/status/1069129232708657152).
**C Port** for the [ORCΛ](https://github.com/hundredrabbits/Orca) programming environment, with a commandline interpreter.
## Prerequisites
Core library: A C99 compiler (no VLAs required), plus enough libc for `malloc`, `realloc`, `free`, `memcpy` and `memset`.
Command-line interpreter: The above, plus POSIX.
Interactive terminal UI: The above, plus ncurses (or compatible curses library).
## Build
The build script is in `bash`. It should work with `gcc` (including the `musl-gcc` wrapper) and `clang`, and will automatically detect your compiler.
Currently known to build on macOS (`gcc`, `clang`) and Linux (`gcc`, `musl-gcc`, and `clang`, optionally with `LLD`).
Not yet tested on Windows, but it's likely that it already works under `cygwin`. Further testing will be performed soon.
There is a fire-and-forget `make` wrapper around the build script.
### Make
```sh
make debug # debugging build, binary placed at build/debug/orca
make release # optimized build, binary placed at build/release/orca
make clean # removes build/
```
### Build Script
Run `./tool --help` to see usage info.
```sh
./tool build debug tui
# debug build of the terminal ui
# binary placed at build/debug/tui
./tool -c clang-7 build release tui
# build the terminal ui with a compiler named
# clang-7, with optimizations enabled.
# binary placed at build/release/tui
./tool clean
# same as make clean, removes build/
```
## Run
### CLI interpreter
The CLI (`orca` binary) reads from a file and runs the orca simulation for 1 timestep (default) or a specified number (`-t` option) and writes the resulting state of the grid to stdout.
```sh
orca [-t timesteps] infile
```
You can also make orca read from stdin:
```sh
echo -e "...\na34\n..." | orca /dev/stdin
```
### Interactive terminal UI
```sh
tui [options] [file]
```
Run the interactive terminal UI, useful for debugging or observing behavior.
#### Controls
- `ctrl+q` or `ctrl+d` or `ctrl+g`: quit
- Arrow keys or `ctrl+h/j/k/l`: move cursor
- `A`-`Z`, `a`-`z`, `0`-`9`, and other printable characters: write character to grid at cursor
- Spacebar: step the simulation one tick
- `ctrl+u`: undo
- `[` and `]`: Adjust cosmetic grid rulers horizontally
- `{` and `}`: Adjust cosmetic grid rulers vertically
- `(` and `)`: resize grid horizontally
- `_` and `+`: resize grid vertically
## Extras
- Support this project through [Patreon](https://patreon.com/100).
- See the [License](LICENSE.md) file for license rights and limitations (MIT).
- Pull Requests are welcome!