Process class

The Process class is used to start external programs and to communicate with them. It can start programs in one of three modes, as described in the following table:

Mode	Function	Comments
Synchronous	Process.execute()	The calling script blocks until the external program has finished; stdout/stderr are collected in the corresponding properties
Asynchronous	new Process().start()	The calling script continues in parallel with the external program and can communicate with its stdin and stdout/stderr through the corresponding write...() and read...() functions
Detached	Process.startDetached()	The external program is started in a separate process; the calling script continues in parallel with the external program but it can NOT communicate with its stdin and stdout/stderr

Static properties

stdout : String: Contains the data sent to stdout during the last call to Process.execute(). This property is read-only.
stderr : String: Contains the data sent to stderr during the last call to Process.execute(). This property is read-only.

Static functions

execute( command : String, stdin : String ) : int: Executes command synchronously and passes stdin to its standard input if specified. When the program ends its output is accessible through Process.stdout and Process.stderr. command can contain both the program and command line arguments, separated by spaces. The function returns the executed command's return code on exit.
execute( command : String[ ], stdin : String ) : int: Same as above, except that command is an Array of strings, where the first item isthe name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you.
bool startDetached ( command : String ): Starts command in a new process and detaches from it. command can contain both the program and command line arguments, separated by spaces. The function returns true on success; otherwise returns false. The detached process will continue to live even if the calling process exits.
bool startDetached ( command : String, arguments : String[ ] ): Same as above, except that its is possible to provide a list of command line arguments.

Constructors

Process(): Creates a Process object without specifying the program or any arguments. This does not start a process.
Process( command : String ): Creates a Process object that will execute command. This does not start the process.
Process( command : String[ ] ): Same as above, except that command is an Array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you.

Properties

arguments : String[ ]: Contains an Array of strings where the first item is the program to execute and the following items are the command line arguments.
workingDirectory : String: Contains the working directory for the process.
running : Boolean: True if the process is currently running; otherwise false. This property is read-only.
exitStatus : Number: Contains the exitStatus of the program when it has finished. This property is read-only.

Member functions

start( env : String[ ] ): Tries to run a process for the command and arguments that were specified with the argument property or that were specified in the constructor. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is not specified, the process is started with the same environment as the starting process. If env is specified, then the values in the Array of strings are interpreted as environment settings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.
launch( stdin : String, env : String[ ] ): Runs the process and writes the data stdin to the process's standard input. If all the data is written to standard input, standard input is closed. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is unspecified, the process is started with the same environment as the starting process. If env is specified, then the values in the Array of strings are interpreted as environment settings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.
waitForStarted ( seconds : Number ): Blocks until the process has started or until the specified time (in seconds) has passed. Returns true if the process was started successfully; returns false if the operation timed out or if an error occurred.
waitForFinished ( seconds : Number ): Blocks until the process has finished or until the specified time (in seconds) has passed. Returns true if the process finished; returns false if the operation timed out or if an error occurred.
readStdout() : String: Reads what is currently available on the process's standard output.
readStderr() : String: Reads what is currently available on the process's standard error.
canReadLineStdout() : Boolean: Returns true if a line can be read from the process's standard output.
canReadLineStderr() : Boolean: Returns true if a line can be read from the process's standard error.
readLineStdout() : String: Reads one line of text from the process's standard output if available; otherwise returns an empty string.
readLineStderr() : String: Reads one line of text from the standard error stream of this process if available; otherwise returns an empty string.
writeToStdin( buffer : String ): Writes the data buffer to the standard input stream of this process. The process may or may not read this data.
closeStdin(): Closes the standard input stream of the process.
tryTerminate(): Asks the process to terminate. Processes can ignore this if they wish. If you want to be certain that the process really terminates, you can use kill() instead.
kill(): Terminates the process. This is not a safe way to end a process since the process will not be able to do any cleanup. tryTerminate() is safer, but processes can ignore tryTerminate().