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.

The following is s-expressions explained intuitively in
something that looks a bit like a BNF:
```
S-expression := Atom | List
Atom := Operator | Value | Variable ...
List := (S-expression ... S-expression)
Don't take it to be exact. For example lists are actually
implemented as linked lists.

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 versions 1.88.0 and 1.89.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

So, for example on some linux systems featuring the `apt`
package manager, the following works (tested on Debian 13)`:
```console
$ sudo apt install curl git builb-essential
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ . "$HOME/.cargo/env"
$ 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
$ mkdir -p ~/.local/bin
$ export PATH="$PATH:~/.local/bin"
$ echo 'export PATH="$PATH:~/.local/bin"' >> ~/.bashrc
$ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
$ myslip
```

Installation has been tested on Aalto SSH servers in addition
to debian/13 in case you prefer that. Here is how to install
and compile the project there:
```console
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ ~/.cargo/bin/cargo --version
$ git clone 'https://git.cron4.fi/myslip.git'
$ cd myslip/
$ ~/.cargo/bin/cargo build
$ mkdir -p ~/.local/bin
$ ln "$(pwd)/target/debug/myslip" ~/.local/bin/myslip
$ export PATH="$PATH:~/.local/bin"
$ myslip
```
Of course you must update your path next time when you open
your shell too, so you might want to add
`export PATH=$PATH:~/.local/bin` to your `~/.bashrc` in case
you don't have a personal preference on how to manage your
`$PATH` and other environment variables.

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`. It also contains additional features
which are omitted here as they are not relevant for
grading.

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`.