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.
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~.
#+BEGIN_SRC lisp
(load htop) ;; executes the htop binary, if htop is found on the users PATH
(l emacs) ;; executes the emacs binary, if emacs is found on the users PATH
#+END_SRC
The load command takes an infinite number of arguments and uses the following rules to construct a shell command from them:
+ symbols that are not set are taken as strings
#+BEGIN_SRC lisp
(l emacs -nw) ;; 'emacs' and '-nw' not defined
#+END_SRC
+ symbols that are set are replaced by their values
#+BEGIN_SRC lisp
(l ls -la HOME)
(let ((ping-count 4)
(domain "sunnypup.io"))
(l ping -c ping-count domain)
#+END_SRC
+ nested forms are evaluated
#+BEGIN_SRC lisp
(l cat (concat HOME "/notes.txt"))
#+END_SRC
Shell command evaluation rules apply to the following functions:
+ ~load~ / ~l~
+ ~pipe~
+ ~load-to-string~
+ ~load-with~
+ ~bg~
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 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).
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.
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:
There will be many times a user will want to directly process command output other than the process exit code. For this a function ~load-to-string~ is included. Below is an example of a series of commands that leverage this function to print a symbolic token based on the presence and status of a Git repository.
#+BEGIN_EXAMPLE shell
(def in-a-git-repo?
'returns true or false depending on if currently in a git repo'
This ~cd~ routine will keep the ~PWD~ variable up to date.
Every invokation of ~cd~ will call whatever lambda or function is stored in ~CFG_FLESH_CD_CB~ with no arguments. A function stored in this variable can then perform on the fly reconfiguration or set additional variables based on the directory that the user has entered.
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.
Typically, any call to an undefined function, lambda, or symbol will result in an undefined symbol error. For example, here is a call to GCC without explicitly prepending the ~load~ function:
#+BEGIN_EXAMPLE
> (gcc myfile.c -o myfile)
** ERROR TRACEBACK
> gdb: (is an undefined symbol)
Please refactor forms and try again...
#+END_EXAMPLE
With the ~implicit load~ feature any call to an undefined function will trigger the ~load~ function as if it had been there the whole time. The above example would yield a new subprocess running GCC (assuming it is installed and accessible). This allows users to quickly type shell commands at the prompt as if they were using a standard shell. Any reference to an undefined symbol outside of where a function would be will still cause an error.
