affine/flesh
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

rename relish to flesh

Browse source
This commit is contained in:
Ava Apples Affine 2024-02-06 22:39:08 +00:00
parent 415b1181fa
commit 9b447eb5b7
58 changed files with 252 additions and 245 deletions
Download patch file Download diff file Expand all files Collapse all files

34
Shell.org
View file

@ -1,10 +1,10 @@
#+Title: Relish as a Shell
#+Author: Ava Hahn
#+Title: Flesh as a Shell
#+Author: Ava Affine
Note: this document is best read using a dedicated ORG mode editor
* Description
This document outlines the ways that Relish can be used as a shell for daily administration or scripting purposes. Readers should have already read through the [[file:Readme.org][general Relish documentation]]. With the exception of the ~circuit~ function, all facilities introduced in this document apply only to relish interpreters compiled with the [[file:/src/stl/posix.rs][POSIX module]] enabled and ~CFG_RELISH_POSIX~ set at load time.
This document outlines the ways that Flesh can be used as a shell for daily administration or scripting purposes. Readers should have already read through the [[file:Readme.org][general Flesh documentation]]. With the exception of the ~circuit~ function, all facilities introduced in this document apply only to flesh interpreters compiled with the [[file:/src/stl/posix.rs][POSIX module]] enabled and ~CFG_FLESH_POSIX~ set at load time.
** Launch a command
For the most common uses (executing shell commands) a function is provided to find and load binaries from entries in the ~PATH~ variable. This function may be called either with ~load~ or ~l~.
@ -39,10 +39,10 @@ Shell command evaluation rules apply to the following functions:
With the exception of the ~load-to-string~ function and the ~bg~ function, each of the aforementioned functions returns the exit code of a new process as an integer.
Symbols set in the Relish REPL are converted to strings and placed in the environment as well, so ~def~ can be used to define environment variables for a process (but not ~let~, which only creates form-local symbols).
Symbols set in the Flesh REPL are converted to strings and placed in the environment as well, so ~def~ can be used to define environment variables for a process (but not ~let~, which only creates form-local symbols).
** Special command forms
A number of forms are provided to offer a first class experience when running Relish as a shell.
A number of forms are provided to offer a first class experience when running Flesh as a shell.
*** Command short circuiting
In a shell such as Bash or Zsh, commands can be chained with the ~&&~ operator:
@ -50,7 +50,7 @@ In a shell such as Bash or Zsh, commands can be chained with the ~&&~ operator:
$ apt update && apt upgrade && echo "Success!"
#+END_EXAMPLE
In these chains, if one command fails the next one(s) are not run. Colloquially, the command short-circuits. A similar construct is offered in Relish called ~circuit~. Circuit will evaluate one or more forms (all expected to evaluate to either an integer (shell command) or a boolean (more general form). If a form returns false (or non-zero) no other forms are evaluated. The printed error message will identify where in the sequence evaluation was halted.
In these chains, if one command fails the next one(s) are not run. Colloquially, the command short-circuits. A similar construct is offered in Flesh called ~circuit~. Circuit will evaluate one or more forms (all expected to evaluate to either an integer (shell command) or a boolean (more general form). If a form returns false (or non-zero) no other forms are evaluated. The printed error message will identify where in the sequence evaluation was halted.
#+BEGIN_EXAMPLE lisp
(circuit
(l apt update) ;; if this fails, no upgrade is made
@ -59,16 +59,16 @@ In these chains, if one command fails the next one(s) are not run. Colloquially,
#+END_EXAMPLE
*** Command piping
In a shell such as Bash or Zsh, the output of one command may be automatically looped into the input of another command. Below is an example of three shell commands piped together. On execution this example counts the number of running Relish processes:
In a shell such as Bash or Zsh, the output of one command may be automatically looped into the input of another command. Below is an example of three shell commands piped together. On execution this example counts the number of running Flesh processes:
#+BEGIN_EXAMPLE shell
$ ps aux | grep relish | wc -l
$ ps aux | grep flesh | wc -l
#+END_EXAMPLE
In order to provide such a facility in Relish, the ~pipe~ function is provided.
In order to provide such a facility in Flesh, the ~pipe~ function is provided.
#+BEGIN_EXAMPLE lisp
(pipe
(ps aux)
(grep relish)
(grep flesh)
(wc -l))
#+END_EXAMPLE
@ -98,7 +98,7 @@ There will be many times a user will want to directly process command output oth
(git-status)
#+END_EXAMPLE
(Example is from [[file:snippets/avas-laptop-prompt.rls][Ava's Laptop Prompt]])
(Example is from [[file:snippets/avas-laptop-prompt.f][Ava's Laptop Prompt]])
*** Redirecting command output to or from files
Another common shell feature is the redirection of input/output to/from files. For example:
@ -106,7 +106,7 @@ Another common shell feature is the redirection of input/output to/from files. F
$ find / -iname "needle.haystack" 2> /dev/null
#+END_EXAMPLE
Relish can redirect "stdin", "stdout", or "stderr" of a shell command using the ~load-with~ function.
Flesh can redirect "stdin", "stdout", or "stderr" of a shell command using the ~load-with~ function.
#+BEGIN_EXAMPLE lisp
(load-with (("stderr" "/dev/null"))
(find / -iname "needle.haystack"))
@ -121,7 +121,7 @@ Or, a more comprehensive example using hypothetical commands and data:
#+END_EXAMPLE
** Control background and foreground processes
Relish implements fully interactive job control.
Flesh implements fully interactive job control.
To launch a background process use the ~bg~ function:
#+BEGIN_EXAMPLE lisp
(bg emacs -nw)
@ -138,13 +138,13 @@ To foreground a background process use the ~fg~ function:
#+END_EXAMPLE
** Changing directories
Relish also provides a ~cd~ utility to change current working directory:
Flesh also provides a ~cd~ utility to change current working directory:
#+BEGIN_EXAMPLE lisp
(cd (concat HOME '/repositories')) ;; $ cd ~/repositories
#+END_EXAMPLE
** Creating bindings for shell commands
Daily Relish users will long for first class shell commands that are accounted for in autocomplete.
Daily Flesh users will long for first class shell commands that are accounted for in autocomplete.
A simple solution:
#+BEGIN_EXAMPLE lisp
@ -154,7 +154,7 @@ A simple solution:
(lis HOME)
#+END_EXAMPLE
The reader may also wish for a utility that allows them to create first-class shortcuts to shell subcommands. It is for this purpose that [[file:snippets/genbind.rls][genbind]] was written. Genbind allows the user to create globally defined functions that reference shell commands (more specifically, subcommands) from their shell. The reader is advised to refer to the documentation in Genbind for more information.
The reader may also wish for a utility that allows them to create first-class shortcuts to shell subcommands. It is for this purpose that [[file:snippets/genbind.f][genbind]] was written. Genbind allows the user to create globally defined functions that reference shell commands (more specifically, subcommands) from their shell. The reader is advised to refer to the documentation in Genbind for more information.
#+BEGIN_EXAMPLE lisp
(def g-add 'shortcut for git add'
(gen-binding "git" "add"))
@ -189,7 +189,7 @@ With the ~implicit load~ feature any call to an undefined function will trigger
...... (redacted directory list) .....
#+END_EXAMPLE
Implicit load can be used by building relish with the following command:
Implicit load can be used by building flesh with the following command:
#+BEGIN_EXAMPLE
cargo build -F implicit-load