If you like Relish and want to support me in working on it consider donating:
https://ko-fi.com/avaaffine
* Documentation
** Writing in Relish
Users who are new to Relish, or who are seeking documentation on how to effectively write in Relish should reference [[file:Writing.org][the main language documentation]]. This will go over the following:
- How Relish operates under the hood
- Relish's syntax
- Relish control flow constructs
- Stdlib functions
- Builting documentation
- Common patterns in using Relish
** Using Relish as your shell
As of version 0.3.0 Relish implements all the features of an interactive shell.
See further documentation in [[file:Shell.org][the shell documentation]]. This material goes over the following:
- How to start and view jobs in Relish
- Special forms for modifying the file descriptors of new jobs
- Piping and other special shell control flow
- Special snippets used to provide a first class shell experience
By default Relish will read from ~/.relishrc for configuration, but the default shell will also accept a filename from the RELISH_CFG_FILE environment variable.
On start, any shell which leverages the configuration code in the config module ([[file:src/run.rs][run.rs]]) will create a clean seperate context, including default configuration values, within which the standard library will be initialized.
- Variables and functions defined during configuration will carry over to the user/script interpreter, allowing the user to load any number of custom functions and variables.
This will produce a binary at file:target/debug/relish which includes all of the features relish has to offer. This provides a REPL with a full interactive shell that also can manage variables in the Unix environment. It is possible to compile a smaller REPL that does not interact with environment variables and does not offer any shell features. Simply pass the ~--no-default-features~ flag to cargo:
#+BEGIN_EXAMPLE sh
cargo build --no-default-features
#+END_EXAMPLE
In order to run Relish it is recommended to run the resulting binary at file:target/debug/relish.
Relish has upwards of 120 unit tests. Full functionality of the core AST with lex, parse, and eval routines as well as the symbol table and relevant code can be tested with Cargo. Unit tests are also included for the standard library of data manipulations and special cases around quote/eval and lambda use:
It provides the core representation of data used in Relish, and could provide supplementary refrence material for users seeking a deeper understanding of how their code is stored in memory.
The components defined here can certainly be used to support language development for other LISP (or non LISP) langauges. An external project may use or not use any number of these components.
Any new addition to the stdlib must make its way here to be included in the main shell (and any other shell using the included stdlib functions).
You may choose to override these functions if you would like to include your own special functions in your own special interpreter, or if you would like to pare down the stdlib to a lighter subet of what it is.
Special thanks to [[https://nul.srht.site/]['Underscore Nul']] for consulting with me in the early stages of this project. Meeting my goal of only using safe rust (with the exception of the posix module) would have been a much bigger challenge if not for having someone to experiment on design ideas with.
