myslip README
=============

Below is a short introduction to this programming language
and instructions on setting it up.
`TUTORIAL.md` may help getting familiar with the language.


Language introduction
---------------------

Myslip is a functional, symbolically interpreted programming
language. It's syntax is inspired by lisp and polish
notation. The author hasn't programmed much in lisp-variants
or in (non-general-purpose) functional languages, so the
language might include some slips or oddities, hence
the name. But the language is coherent within itself,
so learning it shouldn't be too hard.

Valid myslip s-expressions may be atoms of different types
or lists of them, though not all syntactically valid
myslip expressions are ones that can be evaluated.

S-expression := Atom | List
Atom := TODO
List := (S-expression ... S-expression)

The myslip interpreter performs type checking on
s-expressions and evaluates them according to polish
notation, ie. the first S-expression of a list is taken to
be the operator that is passed the rest of the expressions
as arguments.


Running myslip
--------------

myslip can be built using cargo 1.88.0. Instructions to
install cargo can be found online:
https://doc.rust-lang.org/cargo/getting-started/installation.html

If you are having trouble due to having a different version
and you used rustup for your cargo installation, you can
follow these instructions on how to change the rust version
https://rust-lang.github.io/rustup/overrides.html

TODO: system requirements? try it out on debian
So, for example
```console
$ sudo apt install curl git
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ git clone 'https://git.cron4.fi/myslip.git'
$ cd myslip
```
and then myslip can be accessed either via `cargo run`,
or alternatively you can add it to your `$PATH`:
```console
$ cargo build
$ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
$ myslip
```

Exit the REPL by pressing CTRL+C, CTRL+D or entering "exit".

For a quick reference on how to use the `myslip` command,
see `myslip --help`.

Running `myslip filename.slip` tries to read a file named
`filename.slip` as an s-expression and evaluates it.

On the other hand, running `myslip` without specifying an
executable file opens a REPL, in which you can enter
one s-expression per line for evaluation. Variables bound
in earlier expressions can be used.

If you wish to load a set of definitions from a file, say
`header.slip`, use the `--load`-argument (`-l` for short):
```console
$ myslip -l header.slip
```
The standard library, found in `stdlib.slip`, is loaded
in an equivalent way by default. If you wish to disable
it, you can use the option `--no-stdlib`.