flesh/Shell.org

Flesh as a Shell

• Description
  • Launch a command
  • Special command forms
    • Command short circuiting
    • Command piping
    • Processing command output
    • Redirecting command output to or from files
  • Control background and foreground processes
  • Changing directories
  • Creating bindings for shell commands
• Implicit Load

Note: this document is best read using a dedicated ORG mode editor

Description

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 general Flesh documentation. With the exception of the circuit function, all facilities introduced in this document apply only to flesh interpreters compiled with the 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.

  (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

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

    (l emacs -nw) ;; 'emacs' and '-nw' not defined

• symbols that are set are replaced by their values

    (l ls -la HOME)
    (let ((ping-count 4)
          (domain "sunnypup.io"))
      (l ping -c ping-count domain)

• nested forms are evaluated

    (l cat (concat HOME "/notes.txt"))

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).

Special command forms

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:

  $ apt update && apt upgrade && echo "Success!"

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.

(circuit
  (l apt update)  ;; if this fails, no upgrade is made
  (l apt upgrade) ;; if this fails, "Success!" is not printed
  (l echo "Success!"))

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 Flesh processes:

  $ ps aux | grep flesh | wc -l

In order to provide such a facility in Flesh, the pipe function is provided.

(pipe
  (ps aux)
  (grep flesh)
  (wc -l))

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.

(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)

(Example is from 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:

  $ find / -iname "needle.haystack" 2> /dev/null

Flesh can redirect "stdin", "stdout", or "stderr" of a shell command using the load-with function.

(load-with (("stderr" "/dev/null"))
  (find /  -iname "needle.haystack"))

Or, a more comprehensive example using hypothetical commands and data:

(load-with (("stdin"  "img.png")
            ("stdout" "img.jpg")
            ("stderr" "/dev/null"))
  (my-img-convert))

Control background and foreground processes

Flesh implements fully interactive job control. To launch a background process use the bg function:

(bg emacs -nw)

To get all jobs in your shell use the system ps binary:

(l ps)

To foreground a background process use the fg function:

(fg <pid>)

Changing directories

Flesh also provides a cd utility to change current working directory:

(cd (concat HOME '/repositories')) ;; $ cd ~/repositories

Creating bindings for shell commands

Daily Flesh users will long for first class shell commands that are accounted for in autocomplete.

A simple solution:

(def lis 'shortcut for ls -la'
  (lambda (dir) (l ls -la dir)))

(lis HOME)

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 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.

(def g-add 'shortcut for git add'
  (gen-binding "git" "add"))

(g-add ("src" "docs"))

Or:

;; 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")

Implicit Load

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:

  > (gcc myfile.c -o myfile)

  ** ERROR TRACEBACK
   > gdb: (is an undefined symbol)
  Please refactor forms and try again...

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.

  > ls -la .config

  ...... (redacted directory list) .....

Implicit load can be used by building flesh with the following command:

cargo build -F implicit-load