package shexp

README.org

[[./images/logo.png]]

Shexp is composed of two parts: a library providing a process monad
for shell scripting in OCaml as well as a simple s-expression based
shell interpreter. Both provide good debugging support.

Shexp works on both Unix and Windows and depends only on Base.

** The Shexp_process library

The Shexp_process library exposes a single =Process= module allowing
one to construct complex pipelines such as pipes and other
redirections. It is intended to replace shell scripts as well as
provide a more complete alternative to =Async.Process= like
modules.

On Unix, Shexp_process uses the specific *at system calls (such as
=openat=) to reliably maintain several working directories inside the
same system process as well as =vfork= to avoid performance problems
with large processes.

*** Usage

One creates a value of type ='a Process.t= which represent a process
pipeline. Using the combinators of the process module, one can modify
the execution environment (current working directory, environment
variables, ...) as well as construct complex redirections.

To effectively execute the pipeline and get a result, one has to call
=Process.eval=.

Essentially you get the same primitives as what you would get from a
shell, except that everything is typed:

#+begin_src ocaml
(** Run an external program *)
val run : string -> string list -> unit t

(** Equivalent of a shell pipe *)
val pipe : unit t -> 'a t -> 'a t

(** Same thing, but you get the values from both sides of the pipe *)
val pipe_both : 'a t -> 'b t -> ('a * 'b) t

(** Read all of the process' standard input  *)
val read_all : string t

(** [chdir dir k] executes [k] with the current directory set to [dir] *)
val chdir : string -> 'a t -> 'a t
#+end_src

For instance, to run an external command in a given directory and
capture its standard output, where =|-= is infix operator for =pipe=:

#+begin_src ocaml
let f ~dir prog args = eval (chdir dir (run prog args |- read_all))
#+end_src

*** Debugging

Shexp_process allows one to plug a debugger in the evaluator. A
debugger is essentially a set of hooks called at the appropriate
places by Shexp_process. Shexp_process itself provides two
non-interactive debuggers: a logger and a tracer.

The logger is intended for printing command synchrously as they are a
run, a bit like =set -x= in bash.

The tracer provides a full trace of execution. The trace is presented
as a tree, so you can see clearly what happens on both sides of a
fork.

For instance the following process:

#+begin_src ocaml
echo "Hello, world!" |- run "blah" []
#+end_src

would produce the following trace:

#+begin_src scheme
((create-pipe)
 (-> (4 5))
 (fork
   (
    (do
      (set-ios (stdout) 5)
      (echo "Hello, world!"))
    (close-fd 36)
   )
   (
    (do
      (set-ios (stdin) 4)
      (run blah ())
      (raised (Failure "blah: command not found")))
    (close-fd 35)
   )
 )
)
#+end_src