flesh/Shell.org

#+Title: Relish as a Shell
#+Author: Ava Hahn

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.

** 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~.
#+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 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).

** Special command forms
A number of forms are provided to offer a first class experience when running Relish as a shell.

*** Command short circuiting
In a shell such as Bash or Zsh, commands can be chained with the ~&&~ operator:
#+BEGIN_EXAMPLE shell
  $ 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.
#+BEGIN_EXAMPLE lisp
(circuit
  (l apt update)  ;; if this fails, no upgrade is made
  (l apt upgrade) ;; if this fails, "Success!" is not printed
  (l echo "Success!"))
#+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:
#+BEGIN_EXAMPLE shell
  $ ps aux | grep relish | wc -l
#+END_EXAMPLE

In order to provide such a facility in Relish, the ~pipe~ function is provided. 
#+BEGIN_EXAMPLE lisp
(pipe
  (ps aux)
  (grep relish)
  (wc -l))
#+END_EXAMPLE

*** Processing command output
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'
  () (eq? (load-to-string git rev-parse --is-inside-work-tree) "true"))

(def git-repo-is-dirty?
'returns true or false depending on if current dir is a dirty git repo'
  () (not (eq? (load-to-string git diff '--stat') "")))

(def git-status 'returns "(git:<branch>{!,})" if dir is in a git repository'
  ()
  (if (in-a-git-repo?)
    (concat
      "(git:"
      (load-to-string git rev-parse --abbrev-ref HEAD)
      (if (git-repo-is-dirty?)
        "!"
        "")
      ")")
    ''))

(git-status)
#+END_EXAMPLE

(Example is from [[file:snippets/avas-laptop-prompt.rls][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:
#+BEGIN_EXAMPLE shell
  $ 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.
#+BEGIN_EXAMPLE lisp
(load-with (("stderr" "/dev/null"))
  (find /  -iname "needle.haystack"))
#+END_EXAMPLE

Or, a more comprehensive example using hypothetical commands and data:
#+BEGIN_EXAMPLE lisp
(load-with (("stdin"  "img.png")
            ("stdout" "img.jpg")
            ("stderr" "/dev/null"))
  (my-img-convert))
#+END_EXAMPLE

** Control background and foreground processes
Relish implements fully interactive job control.
To launch a background process use the ~bg~ function:
#+BEGIN_EXAMPLE lisp
(bg emacs -nw)
#+END_EXAMPLE

To get all jobs in your shell use the system ~ps~ binary:
#+BEGIN_EXAMPLE lisp
(l ps)
#+END_EXAMPLE

To foreground a background process use the ~fg~ function:
#+BEGIN_EXAMPLE
(fg <pid>)
#+END_EXAMPLE

** Changing directories
Relish 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.

A simple solution:
#+BEGIN_EXAMPLE lisp
(def lis 'shortcut for ls -la'
  (lambda (dir) (l ls -la dir)))

(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.
#+BEGIN_EXAMPLE lisp
(def g-add 'shortcut for git add'
  (gen-binding "git" "add"))

(g-add ("src" "docs"))
#+END_EXAMPLE

Or:
#+BEGIN_EXAMPLE lisp
;; REQUIRES USERLIB FOR PREPEND (or write your own)
(def pacman-search 'shortcut for sudo pacman -Ss'
  (lambda (many-dirs) ((gen-binding "sudo" "pacman") (prepend "-Ss" many-dirs))))

(pacman-search "xfce4")
#+END_EXAMPLE