1. Yaron Minsky
  2. js-elisp


js-elisp / process.mli

open Core.Std
open Async.Std

module Output : sig
  type 'a t = {
    stdout: 'a;
    stderr: 'a

(** [create_process cmd f] runs cmd and hands details of the process to f.  When f
  is determined, or when f throws an exception, the background process is killed
  gracefully (TERM, wait, then KILL), all file descriptors are closed, and the
  process is reaped *)
val create :
  ?kill:unit Deferred.t
  -> prog:string
  -> args:string list
  -> env:[`Replace of (string * string) list | `Extend of (string * string) list]
  -> ?working_dir:string
  -> ?stdin:string
  -> f:(Pid.t -> stdin:Writer.t -> stdout:Reader.t -> stderr:Reader.t -> 'a Deferred.t)
  -> unit
  -> ('a * Core.Std.Unix.Exit_or_signal.t) Deferred.t

type file_descr = Core.Std.Unix.File_descr.t

(** [create_fds...] like create, except that the three file_descrs to be used 
    for the stdin/stdout/stderr of the forked process are passed in. The passed-in
    file_descrs might for example have been obtained by a called to Unix.pipe().
val create_fds :
  kill:unit Deferred.t
  -> prog:string
  -> args:string list
  -> stdin:file_descr
  -> stdout:file_descr
  -> stderr:file_descr
  -> f:(Pid.t -> unit)
  -> Unix.Exit_or_signal.t Deferred.t
(** [open_in ~prog ~args] runs prog with args and returns a readers connected to
  stdout and stderr.  When both of those readers are closed then the process is
  reaped (and killed if necessary).  is_ok defaults to Core.Std.Unix.Exit_or_signal.ok  *)
val open_in :
  ?is_ok:(Core.Std.Unix.Exit_or_signal.t -> bool)
  -> ?kill:unit Deferred.t
  -> prog:string
  -> args:string list
  -> unit
  -> Reader.t Output.t Deferred.t

type 'a backtick =
  ?kill:unit Deferred.t
  -> ?env:[`Replace of (string * string) list | `Extend of (string * string) list]
  -> prog:string
  -> args:string list
  -> ?working_dir:string
  -> ?stdin:string
  -> unit
  -> 'a

(** [backtick_status ~prog ~args] runs prog with args and returns the full
    stdout and stderr as strings, together with the process status.  If
    [stdin] is provided, it will be written to the stdin of the program, but
    no guarantees are made as to whether the program actually reads this
    data.  In particular, the program may close stdin, or exit before the
    data has been read; no error is raised in these circumstances.  This
    behaviour is akin to:
        echo stdin | ...
    at the shell prompt. *)
val backtick_status : (string Output.t * Unix.Exit_or_signal.t) Deferred.t backtick

(* CR sweeks for mshinwell: I would like to get rid of [backtick], which
   encourages people to ignore exit status, which I think is bad practice.  I
   would instead like to have [backtick_new] and [backtick_new_exn] as I have
   below (renamed as "backtick" and "backtick_exn").  My thinking is that those
   pay attention to exit status, give clients easy access to stdout, and give
   access to a nice error exn/message that includes stderr, if there was an

(** [backtick ~prog ~args] runs prog with args and returns the full stdout and stderr
    as strings (ignoring the process status) *)
val backtick : string Output.t Deferred.t backtick

val backtick_new : (string, exn) Result.t Deferred.t backtick

val backtick_new_exn : string Deferred.t backtick