diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 82 |
1 files changed, 52 insertions, 30 deletions
@@ -4,24 +4,24 @@ 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. +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. +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. +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: @@ -29,22 +29,20 @@ 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. +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: +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 @@ -52,21 +50,45 @@ 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 +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 +$ 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`: +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". @@ -79,15 +101,15 @@ 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. +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`. +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`. |