sh: Add optional ?tmpdir parameter to control tmpdir creation.

[goaljobs.git] / goaljobs.mli

diff --git a/goaljobs.mli b/goaljobs.mli
index 3d342fa..3e1ca0c 100644 (file)
--- a/goaljobs.mli
+++ b/goaljobs.mli
@@ -282,6 +282,14 @@ val quote : string -> string
       sh "rsync foo-%s.tar.gz example.com:/html/" version
     v}
 
+    Each shell runs in a new temporary directory.  The temporary
+    directory and all its contents is deleted after the shell exits.
+    If you want to save any data, [cd] somewhere.  If you don't
+    want the temporary directory creation, use [~tmpdir:false].
+
+    The environment variable [$builddir] is exported to the script.
+    This is the current directory when the goaljobs program was started.
+
     Each invocation of {!sh} (etc) is a single shell (this is slightly
     different from how [make] works).  For example:
 
@@ -295,38 +303,42 @@ val quote : string -> string
         ./configure
         make
      " version
-    }
+    v}
 
     The shell error mode is set such that if any single command
     returns an error then the {!sh} function as a whole exits with
     an error.  Write:
-    {v command ||: }
+    {v command ||: v}
     to ignore the result of a command.
 
-    Each shell runs in a new temporary directory.  The temporary
-    directory and all its contents is deleted after the shell exits.
-    If you want to save any data, [cd] somewhere.  The environment
-    variable [$builddir] is exported to the script.  This is the
-    current directory when the goaljobs program was started.
-
-    For example you could start the command sequence with
-    [cd $HOME/data/] or [cd $builddir].
 *)
 
-val sh : ('a, unit, string, unit) format4 -> 'a
-  (** Run the command(s). *)
+val sh : ?tmpdir:bool -> ('a, unit, string, unit) format4 -> 'a
+  (** Run the command(s).
+
+      The command runs in a newly created temporary directory (which
+      is deleted after the command exits), {i unless} you use
+      [~tmpdir:false]. *)
 
-val shout : ('a, unit, string, string) format4 -> 'a
+val shout : ?tmpdir:bool -> ('a, unit, string, string) format4 -> 'a
   (** Run the command(s).
 
       Anything printed on stdout is returned as a string.
-      The trailing [\n] character, if any, is not returned. *)
+      The trailing [\n] character, if any, is not returned.
+
+      The command runs in a newly created temporary directory (which
+      is deleted after the command exits), {i unless} you use
+      [~tmpdir:false]. *)
 
-val shlines : ('a, unit, string, string list) format4 -> 'a
+val shlines : ?tmpdir:bool -> ('a, unit, string, string list) format4 -> 'a
   (** Run the command(s).
 
       Any lines printed to stdout is returned as a list of strings.
-      Trailing [\n] characters are not returned. *)
+      Trailing [\n] characters are not returned.
+
+      The command runs in a newly created temporary directory (which
+      is deleted after the command exits), {i unless} you use
+      [~tmpdir:false]. *)
 
 val shell : string ref
   (** Set this variable to override the default shell ([/bin/sh]). *)