rename relish to flesh
This commit is contained in:
parent
415b1181fa
commit
9b447eb5b7
58 changed files with 252 additions and 245 deletions
85
Readme.org
85
Readme.org
|
|
@ -1,10 +1,10 @@
|
|||
#+Title: Relish: Rusty Expressive LIsp SHell
|
||||
#+Author: Ava Hahn
|
||||
#+Title: Flesh: Flexible Shell
|
||||
#+Author: Ava Affine
|
||||
|
||||
Note: this document is best read using a dedicated ORG mode editor
|
||||
|
||||
* Purpose statement
|
||||
The purpose of Relish is to create a highly portable, easy to integrate language that can be used in many environments.
|
||||
The purpose of Flesh is to create a highly portable, easy to integrate language that can be used in many environments.
|
||||
|
||||
* Goals
|
||||
- Iterate on the ideas and designs that were tested with [[https://gitlab.com/whom/shs][SHS]]
|
||||
|
|
@ -14,7 +14,7 @@ The purpose of Relish is to create a highly portable, easy to integrate language
|
|||
- No unsafe code nessesary
|
||||
|
||||
Note: as of release 0.3.0, the Posix module requires unsafe code in order to interface with libc.
|
||||
Users are still able to compile and use Relish without any of the unsafe code involved by removing
|
||||
Users are still able to compile and use Flesh without any of the unsafe code involved by removing
|
||||
the POSIX module. See the Compilation section for more details.
|
||||
|
||||
** Stretch Goals
|
||||
|
|
@ -25,31 +25,32 @@ The purpose of Relish is to create a highly portable, easy to integrate language
|
|||
* Contact
|
||||
[[https://matrix.to/#/#relish:matrix.sunnypup.io][Matrix chat: #relish:matrix.sunnypup.io]]
|
||||
|
||||
If you like Relish and want to support me in working on it consider donating: [[https://ko-fi.com/avaaffine][Ava's Ko-Fi]].
|
||||
If you like Flesh and want to support me in working on it consider donating: [[https://ko-fi.com/avaaffine][Ava's Ko-Fi]].
|
||||
|
||||
* 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
|
||||
** Writing in Flesh
|
||||
Users who are new to Flesh, or who are seeking documentation on how to effectively write in Flesh should reference [[file:Writing.org][the main language documentation]]. This will go over the following:
|
||||
- How Flesh operates under the hood
|
||||
- Flesh syntax
|
||||
- Flesh 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.
|
||||
- Common patterns in using Flesh
|
||||
|
||||
** Using Flesh as your shell
|
||||
As of version 0.3.0 Flesh 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
|
||||
- How to start and view jobs in Flesh
|
||||
- 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
|
||||
* Configuration
|
||||
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.
|
||||
See [[file:snippets/basic_minimal_configuration.rls][the minimal shell configuration example]] for an example of a basic configuration file.
|
||||
By default Flesh will read from ~/.fleshrc for configuration, but the default shell will also accept a filename from the FLESH_CFG_FILE environment variable.
|
||||
See [[file:snippets/basic_minimal_configuration.f][the minimal shell configuration example]] for an example of a basic configuration file.
|
||||
Other snippets, including mood-prompt and avas-laptop-prompt demonstrate more complex configurations.
|
||||
|
||||
** The configuration file
|
||||
The configuration file is a script containing arbitrary Relish code.
|
||||
The configuration file is a script containing arbitrary Flesh code.
|
||||
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.
|
||||
The configuration file is evaluated and run as a standalone script and may include arbitrary executable code.
|
||||
Afterwards, configuration values found in the variable map will be used to configure the standard library function mappings that the shell will use.
|
||||
|
|
@ -62,54 +63,54 @@ Errors during configuration are non-terminal. In such a case any defaults which
|
|||
- 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.
|
||||
|
||||
** Configuration Values
|
||||
- CFG_RELISH_POSIX (default true): when true, enables POSIX style job control and shell features.
|
||||
- CFG_RELISH_ENV (default true): when true, interpreter's variable table and environment variable table are kept in sync.
|
||||
- CFG_RELISH_L_PROMPT (default 'λ'): a function that is called with no arguments to output the left hand of the prompt
|
||||
- CFG_RELISH_R_PROMPT (default ''): a function that is called with no arguments to output the right hand of the prompt
|
||||
- CFG_RELISH_PROMPT_DELIMITER (default '>'): a function that is called with no arguments to output the delimiter separating prompt from user input
|
||||
- CFG_FLESH_POSIX (default true): when true, enables POSIX style job control and shell features.
|
||||
- CFG_FLESH_ENV (default true): when true, interpreter's variable table and environment variable table are kept in sync.
|
||||
- CFG_FLESH_L_PROMPT (default 'λ'): a function that is called with no arguments to output the left hand of the prompt
|
||||
- CFG_FLESH_R_PROMPT (default ''): a function that is called with no arguments to output the right hand of the prompt
|
||||
- CFG_FLESH_PROMPT_DELIMITER (default '>'): a function that is called with no arguments to output the delimiter separating prompt from user input
|
||||
|
||||
** Prompt design
|
||||
For an example of prompt design see [[file:snippets/mood-prompt.rls][the mood prompt]]
|
||||
For a more complex example see [[file:snippets/avas-laptop-prompt.rls][Ava's laptop prompt]]
|
||||
For an example of prompt design see [[file:snippets/mood-prompt.f][the mood prompt]]
|
||||
For a more complex example see [[file:snippets/avas-laptop-prompt.f][Ava's laptop prompt]]
|
||||
|
||||
** Further configuration
|
||||
Further configuration can be done by loading scripts that contain more functions and data to evaluate.
|
||||
Variables and functions defined in an external script loaded by your interpreter will persist in the symbol table.
|
||||
|
||||
#+BEGIN_SRC lisp
|
||||
(call "my-extra-library-functions.rls")
|
||||
(call "my-extra-library-functions.f")
|
||||
#+END_SRC
|
||||
|
||||
* Syntax Highlighting
|
||||
Syntax Highlighting is implemented for Emacs under [[file:snippets/relish-mode.el][the Relish Mode module (snippets/relish-mode.el)]].
|
||||
Syntax Highlighting is implemented for Emacs under [[file:snippets/flesh-mode.el][the Flesh Mode module (snippets/flesh-mode.el)]].
|
||||
For installation, consider adding the following to your ~\~/.emacs~:
|
||||
#+BEGIN_SRC el
|
||||
(load-file "/PATH/TO/relish/snippets/relish-mode.el")
|
||||
(load-file "/PATH/TO/flesh/snippets/flesh-mode.el")
|
||||
#+END_SRC
|
||||
|
||||
* Compilation
|
||||
Compiling Relish is as simple as kicking off a build with Cargo.
|
||||
Compiling Flesh is as simple as kicking off a build with Cargo.
|
||||
#+BEGIN_EXAMPLE sh
|
||||
cargo build
|
||||
#+END_EXAMPLE
|
||||
|
||||
This will produce a binary at [[file:target/debug/relish][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:
|
||||
This will produce a binary at [[file:target/debug/flesh][target/debug/flesh]] which includes all of the features flesh 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][target/debug/relish]].
|
||||
In order to run Flesh it is recommended to run the resulting binary at [[file:target/debug/flesh][target/debug/flesh]].
|
||||
|
||||
** Testing
|
||||
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:
|
||||
Flesh 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:
|
||||
#+BEGIN_EXAMPLE sh
|
||||
cargo test
|
||||
#+END_EXAMPLE
|
||||
|
||||
Userlib tests can be triggered by loading the userlib as well as its test suite directly from a ~cargo run~ invocation:
|
||||
#+BEGIN_EXAMPLE sh
|
||||
cargo run snippets/userlib.rls snippets/userlib-tests.rls
|
||||
cargo run snippets/userlib.f snippets/userlib-tests.f
|
||||
#+END_EXAMPLE
|
||||
|
||||
* The codebase
|
||||
|
|
@ -125,12 +126,12 @@ These tests verify the handling of syntax.
|
|||
*** Lib tests: (tests/test_lib*)
|
||||
These tests are unique per stdlib module and work to prove the functionality of builtin functions in the language.
|
||||
** [[file:src][Source directory]]
|
||||
This directory contains all of the user facing code in relish.
|
||||
This directory contains all of the user facing code in flesh.
|
||||
Just a few entries of note:
|
||||
*** [[file:src/segment.rs][Segment module]]
|
||||
This file lays out the data structures that the interpreter operates on.
|
||||
Representation of code trees, traversals, and type annotations all live here.
|
||||
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.
|
||||
It provides the core representation of data used in Flesh, and could provide supplementary refrence material for users seeking a deeper understanding of how their code is stored in memory.
|
||||
*** [[file:src/lib.rs][lib.rs]]
|
||||
This defines a library that can be included to provide an interpreter interface within any Rust project.
|
||||
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.
|
||||
|
|
@ -151,7 +152,7 @@ Any new addition to the stdlib must make its way here to be included in the main
|
|||
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.
|
||||
You can view the code for standard library functions in [[file:src/stl/][the standard library directory]].
|
||||
*** [[file:src/bin/][binary directory]]
|
||||
This contains any executable target of this project. Notably [[file:src/bin/relish.rs][the main shell]].
|
||||
This contains any executable target of this project. Notably [[file:src/bin/flesh.rs][the main shell]].
|
||||
* Current Status / TODO list
|
||||
Note: this section will not show the status of each item unless you are viewing it with a proper orgmode viewer.
|
||||
Note: this section only tracks the state of incomplete TODO items. Having everything on here would be cluttered.
|
||||
|
|
@ -161,18 +162,20 @@ Note: this section only tracks the state of incomplete TODO items. Having everyt
|
|||
** DONE Beta tasks
|
||||
(See tag: v0.3.0)
|
||||
** TODO v1.0 tasks
|
||||
- Can pass args to relish scripts (via command line)
|
||||
- Can pass args to relish scripts (via interpreter)
|
||||
- finish basic goals in the [[file:snippets/interactive-devel.rls][interactive development library]]
|
||||
- Can pass args to flesh scripts (via command line)
|
||||
- Can pass args to flesh scripts (via interpreter)
|
||||
- Pipe also operates on stderr
|
||||
- ~ if possible (string replacement?
|
||||
- tab completion for symbols also attempts to complete binaries
|
||||
- tab completion for symbols also attempts to complete paths
|
||||
- finish basic goals in the [[file:snippets/interactive-devel.f][interactive development library]]
|
||||
- Release CI
|
||||
- Rename to Flesh
|
||||
- Make an icon if you feel like it
|
||||
- Post release to relevant channels
|
||||
** TODO v1.1 tasks
|
||||
- emacs lsp implementation
|
||||
- finish stretch goals in the [[file:snippets/interactive-devel.rls][interactive development library]]
|
||||
- finish stretch goals in the [[file:snippets/interactive-devel.f][interactive development library]]
|
||||
- History length configurable (env var?)
|
||||
- Lex function
|
||||
- execute configurable function on cd
|
||||
- Post to relevant channels
|
||||
- Implement Compose for lambdas
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue