path: root/src/library/scala/sys/process/package.scala

/*                     __                                               *\
**     ________ ___   / /  ___     Scala API                            **
**    / __/ __// _ | / /  / _ |    (c) 2003-2013, LAMP/EPFL             **
**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
** /____/\___/_/ |_/____/_/ | |                                         **
**                          |/                                          **
\*                                                                      */

// Developer note:
//   scala -J-Dscala.process.debug
// for process debugging output.
//
package scala.sys {
  /** This package handles the execution of external processes.  The contents of
    * this package can be divided in three groups, according to their
    * responsibilities:
    *
    *   - Indicating what to run and how to run it.
    *   - Handling a process input and output.
    *   - Running the process.
    *
    * For simple uses, the only group that matters is the first one. Running an
    * external command can be as simple as `"ls".!`, or as complex as building a
    * pipeline of commands such as this:
    *
    * {{{
    * import scala.sys.process._
    * "ls" #| "grep .scala" #&& Seq("sh", "-c", "scalac *.scala") #|| "echo nothing found" lineStream
    * }}}
    *
    * We describe below the general concepts and architecture of the package,
    * and then take a closer look at each of the categories mentioned above.
    *
    * ==Concepts and Architecture==
    *
    * The underlying basis for the whole package is Java's `Process` and
    * `ProcessBuilder` classes. While there's no need to use these Java classes,
    * they impose boundaries on what is possible. One cannot, for instance,
    * retrieve a ''process id'' for whatever is executing.
    *
    * When executing an external process, one can provide a command's name,
    * arguments to it, the directory in which it will be executed and what
    * environment variables will be set. For each executing process, one can
    * feed its standard input through a `java.io.OutputStream`, and read from
    * its standard output and standard error through a pair of
    * `java.io.InputStream`. One can wait until a process finishes execution and
    * then retrieve its return value, or one can kill an executing process.
    * Everything else must be built on those features.
    *
    * This package provides a DSL for running and chaining such processes,
    * mimicking Unix shells ability to pipe output from one process to the input
    * of another, or control the execution of further processes based on the
    * return status of the previous one.
    *
    * In addition to this DSL, this package also provides a few ways of
    * controlling input and output of these processes, going from simple and
    * easy to use to complex and flexible.
    *
    * When processes are composed, a new `ProcessBuilder` is created which, when
    * run, will execute the `ProcessBuilder` instances it is composed of
    * according to the manner of the composition. If piping one process to
    * another, they'll be executed simultaneously, and each will be passed a
    * `ProcessIO` that will copy the output of one to the input of the other.
    *
    * ==What to Run and How==
    *
    * The central component of the process execution DSL is the
    * [[scala.sys.process.ProcessBuilder]] trait. It is `ProcessBuilder` that
    * implements the process execution DSL, that creates the
    * [[scala.sys.process.Process]] that will handle the execution, and return
    * the results of such execution to the caller. We can see that DSL in the
    * introductory example: `#|`, `#&&` and `#!!` are methods on
    * `ProcessBuilder` used to create a new `ProcessBuilder` through
    * composition.
    *
    * One creates a `ProcessBuilder` either through factories on the
    * [[scala.sys.process.Process]]'s companion object, or through implicit
    * conversions available in this package object itself.  Implicitly, each
    * process is created either out of a `String`, with arguments separated by
    * spaces -- no escaping of spaces is possible -- or out of a
    * [[scala.collection.Seq]], where the first element represents the command
    * name, and the remaining elements are arguments to it. In this latter case,
    * arguments may contain spaces.
    *
    * To further control what how the process will be run, such as specifying
    * the directory in which it will be run, see the factories on
    * [[scala.sys.process.Process]]'s object companion.
    *
    * Once the desired `ProcessBuilder` is available, it can be executed in
    * different ways, depending on how one desires to control its I/O, and what
    * kind of result one wishes for:
    *
    *   - Return status of the process (`!` methods)
    *   - Output of the process as a `String` (`!!` methods)
    *   - Continuous output of the process as a `Stream[String]` (`lineStream` methods)
    *   - The `Process` representing it (`run` methods)
    *
    * Some simple examples of these methods:
    * {{{
    * import scala.sys.process._
    *
    * // This uses ! to get the exit code
    * def fileExists(name: String) = Seq("test", "-f", name).! == 0
    *
    * // This uses !! to get the whole result as a string
    * val dirContents = "ls".!!
    *
    * // This "fire-and-forgets" the method, which can be lazily read through
    * // a Stream[String]
    * def sourceFilesAt(baseDir: String): Stream[String] = {
    *   val cmd = Seq("find", baseDir, "-name", "*.scala", "-type", "f")
    *   cmd.lineStream
    * }
    * }}}
    *
    * We'll see more details about controlling I/O of the process in the next
    * section.
    *
    * ==Handling Input and Output==
    *
    * In the underlying Java model, once a `Process` has been started, one can
    * get `java.io.InputStream` and `java.io.OutputStream` representing its
    * output and input respectively. That is, what one writes to an
    * `OutputStream` is turned into input to the process, and the output of a
    * process can be read from an `InputStream` -- of which there are two, one
    * representing normal output, and the other representing error output.
    *
    * This model creates a difficulty, which is that the code responsible for
    * actually running the external processes is the one that has to take
    * decisions about how to handle its I/O.
    *
    * This package presents an alternative model: the I/O of a running process
    * is controlled by a [[scala.sys.process.ProcessIO]] object, which can be
    * passed _to_ the code that runs the external process. A `ProcessIO` will
    * have direct access to the java streams associated with the process I/O. It
    * must, however, close these streams afterwards.
    *
    * Simpler abstractions are available, however. The components of this
    * package that handle I/O are:
    *
    *   - [[scala.sys.process.ProcessIO]]: provides the low level abstraction.
    *   - [[scala.sys.process.ProcessLogger]]: provides a higher level abstraction
    *   for output, and can be created through its object companion
    *   - [[scala.sys.process.BasicIO]]: a library of helper methods for the
    *   creation of `ProcessIO`.
    *   - This package object itself, with a few implicit conversions.
    *
    * Some examples of I/O handling:
    * {{{
    * import scala.sys.process._
    *
    * // An overly complex way of computing size of a compressed file
    * def gzFileSize(name: String) = {
    *   val cat = Seq("zcat", name)
    *   var count = 0
    *   def byteCounter(input: java.io.InputStream) = {
    *     while(input.read() != -1) count += 1
    *     input.close()
    *   }
    *   val p = cat run new ProcessIO(_.close(), byteCounter, _.close())
    *   p.exitValue()
    *   count
    * }
    *
    * // This "fire-and-forgets" the method, which can be lazily read through
    * // a Stream[String], and accumulates all errors on a StringBuffer
    * def sourceFilesAt(baseDir: String): (Stream[String], StringBuffer) = {
    *   val buffer = new StringBuffer()
    *   val cmd = Seq("find", baseDir, "-name", "*.scala", "-type", "f")
    *   val lineStream = cmd lineStream_! ProcessLogger(buffer append _)
    *   (lineStream, buffer)
    * }
    * }}}
    *
    * Instances of the java classes `java.io.File` and `java.net.URL` can both
    * be used directly as input to other processes, and `java.io.File` can be
    * used as output as well. One can even pipe one to the other directly
    * without any intervening process, though that's not a design goal or
    * recommended usage. For example, the following code will copy a web page to
    * a file:
    * {{{
    * import java.io.File
    * import java.net.URL
    * import scala.sys.process._
    * new URL("http://www.scala-lang.org/") #> new File("scala-lang.html") !
    * }}}
    *
    * More information about the other ways of controlling I/O can be looked at
    * in the scaladoc for the associated objects, traits and classes.
    *
    * ==Running the Process==
    *
    * Paradoxically, this is the simplest component of all, and the one least
    * likely to be interacted with. It consists solely of
    * [[scala.sys.process.Process]], and it provides only two methods:
    *
    *   - `exitValue()`: blocks until the process exit, and then returns the exit
    *   value. This is what happens when one uses the `!` method of
    *   `ProcessBuilder`.
    *   - `destroy()`: this will kill the external process and close the streams
    *   associated with it.
    */
  package object process extends ProcessImplicits {
    /** The arguments passed to `java` when creating this process */
    def javaVmArguments: List[String] = {
      import scala.collection.JavaConversions._

      java.lang.management.ManagementFactory.getRuntimeMXBean().getInputArguments().toList
    }
    /** The input stream of this process */
    def stdin  = java.lang.System.in
    /** The output stream of this process */
    def stdout = java.lang.System.out
    /** The error stream of this process */
    def stderr = java.lang.System.err
  }
  // private val shell: String => Array[String] =
  //   if (isWin) Array("cmd.exe", "/C", _)
  //   else Array("sh", "-c", _)

  package process {
    // These are in a nested object instead of at the package level
    // due to the issues described in tickets #3160 and #3836.
    private[process] object processInternal {
      final val processDebug = props contains "scala.process.debug"
      dbg("Initializing process package.")

      type =?>[-A, +B]     = PartialFunction[A, B]
      type Closeable       = java.io.Closeable
      type File            = java.io.File
      type IOException     = java.io.IOException
      type InputStream     = java.io.InputStream
      type JProcess        = java.lang.Process
      type JProcessBuilder = java.lang.ProcessBuilder
      type OutputStream    = java.io.OutputStream
      type SyncVar[T]      = scala.concurrent.SyncVar[T]
      type URL             = java.net.URL

      def onInterrupt[T](handler: => T): Throwable =?> T = {
        case _: InterruptedException => handler
      }

      def ioFailure[T](handler: IOException => T): Throwable =?> T = {
        case e: IOException => handler(e)
      }

      def dbg(msgs: Any*) = if (processDebug) {
        Console.println("[process] " + (msgs mkString " "))
      }
    }
  }
}