Cmd

Module	ejs
Definition	class Cmd
Inheritance	Cmd Object
Specified	ejscript-2.5

The Cmd class supports invoking other programs as separate processes on the same system.

Properties

Qualifiers	Property	Type	Description
get set	env	Object	Hash of environment strings to pass to the command.
get	error	String	Command error output data as a string. The first time this property is read, the error content will be read and buffered.
get	errorStream	Stream	The error stream object for the command's standard error output.
get	pid	Number	Process ID of the the command. This is set to the process ID (PID) of the command. If no command has started or the command has called close the call with throw an exception.
get	response	String	Command output data as a string. This is an alias for readString() but it will cache the output data and may be called multiple times. This reads from the command's standard output. 0.
get	status	Number	Get the command exit status. This command will block until the command has completed. Use wait(0) to test if the command has completed.
get set	timeout	Number	Default command timeout for wait(), read(), and blocking start(). If the timeout expires, the command is not killed. Rather any blocking calls will simply return. This is the number of milliseconds for the call to complete.

Inherited Properties

Cmd Class Methods

Qualifiers	Method
static	daemon(cmdline: Object, options: Object = null): Number
	Start a command in the background as a daemon.
static	exec(cmdline: String = null, options: Object = expression): Void
	Execute a new program by the current process.
static	kill(pid: Number, signal: Number = 2): Boolean
	Kill the specified process.
static	locate(program: Path, search = expression): Path
	Locate a program using the application PATH.
static	run(command: Object, options: Object = expression, data: Object = null): String
	Execute a command/program and return the output as a result.
static	sh(command: Object, options: Object = null, data: Object = null): String
	Run a command using the system command shell and wait for completion.

Inherited Methods

Cmd Instance Methods

Qualifiers	Method
	Cmd(command: Object = null, options: Object = null)
	Create an Cmd object.
	close(): Void
	Close the connection to the command and free up all associated resources.
	finalize(): Void
	Signal the end of writing data to the command.
	on(name, observer: Function): Cmd
	Add an observer to the stream for the named events.
	read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number
	Read a data from the stream.If no observer has been defined via on() this call will block if there is no data to be read.
	readLines(count: Number = -1): Array
	Read the data from the command as an array of lines.
	readString(count: Number = -1): String
	Read the data from the command output as a string.
	readXml(): XML
	Read the command output as an XML document.
	start(cmdline: Object, options: Object = null): Void
	Start the command.
	stop(signal: Number = 2): Boolean
	Stop the current command.
	wait(timeout: Number = -1): Boolean
	Wait for a command to complete.
	write(data: Array): Number
	Write data to the stream.Call finalize() to signify the end of write data.

Inherited Methods

Method Detail

Cmd(command: Object = null, options: Object = null)

Description: Create an Cmd object. If a command line is provided, the command is immediately started.

Parameters

command: Object	The (optional) command line to initialize with. If a command line is provided, the start() method is automatically invoked after the command is constructed. The command may be either a string or an array of arguments. Using an array of args can simplify quoting if the args have embedded spaces or quotes. [default: null]
options: Object	Command options hash. Supported options are:. [default: null]
options: Object	null [default: null]

Options

detach	Boolean If true, run the command and return immediately. If detached, finalize() must be called to signify the end of data being written to the command's stdin.
dir	Path or String. Directory to set as the current working directory for the command.
exceptions	Boolean If true, throw exceptions if the command returns a non-zero status code. Defaults to false.
timeout	Number This is the default number of milliseconds for the command to complete.

close(): Void

Description: Close the connection to the command and free up all associated resources. It is not normally required to call close but it can be useful to force a command termination. After calling close, the command status and unread response data are not accessible.

static daemon(cmdline: Object, options: Object = null): Number

Description: Start a command in the background as a daemon. The daemon command is detached and the application continues immediately in the foreground. Note: No data can be written to the daemon's stdin.

Parameters

cmdline: Object	Command line to use. The cmdline may be either a string or an array of strings.
options: Object	null [default: null]

Returns: The process ID. This PID can be used with kill().

static exec(cmdline: String = null, options: Object = expression): Void

Description: Execute a new program by the current process. This Replaces the current program with another without creating a new process.

Parameters

cmdline: String	Command line to use. The cmdline may be either a string or an array of strings. [default: null]
options: Object	Command options. Sames as options in Cmd. [default: expression]

Throws: IOError: if the request was cannot be issued to the remote server.

static kill(pid: Number, signal: Number = 2): Boolean

Description: Kill the specified process.

Parameters

pid: Number	Process ID of the process to kill.
signal: Number	If pid is greater than zero, the signal is sent to the process whoes ID is pid. If pid is zero, the process is tested but no signal is sent. [default: 2]

Returns: True if successful.

Throws: IOError: if the pid is invalid or if the requesting process does not have sufficient privilege to send the signal.

finalize(): Void

Description: Signal the end of writing data to the command. The finalize() call must be invoked to properly signify the end of write data.

static locate(program: Path, search = expression): Path

Description: Locate a program using the application PATH.

Parameters

program: Path	Program to find.
search	Optional additional search paths to use before using PATH. [default: expression]

Returns: Located path or null.

on(name, observer: Function): Cmd

Description: Add an observer to the stream for the named events.

Parameters

name: [String\|Array]	Name of the event to listen for. The name may be an array of events.
observer: Function	Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.
writable	Issued when the command can accept more write data.
complete	Issued when the command completes.
error	Issued if the error stream is readable. All events are called with the signature: function (event: String, cmd: Cmd): Void.

read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number

Description: Read a data from the stream.If no observer has been defined via on() this call will block if there is no data to be read. If data is available, the call will return immediately. If no data is available and the stream is in sync mode, the call will block until data is available. If no data is available and the stream is in async mode, the call will not block and will return immediately. In this case a "readable" event will be issued when data is available for reading.

Parameters

buffer: ByteArray	Destination byte array for read data.
offset: Number	Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. If offset is >= 0, the data is read to the offset and the read pointer is set to the offset and the write pointer to one past the end of the data just read. [default: 0]
count: Number	Read up to this number of bytes. If -1, read as much as the buffer will hold up. If the stream is of fixed and known length (such as a file) and the buffer is of sufficient size or is growable, read the entire stream. If the buffer is of a fixed size, ready only what will fit into the buffer. [default: -1]

Events

readable	Issued when there is new read data available.
writable	Issued when the stream becomes empty. `.

Returns: A count of the bytes actually read. Returns null on EOF or errors.

readLines(count: Number = -1): Array

Description: Read the data from the command as an array of lines. This reads from the command's standard output.

Parameters

count: Number

Of linese to read. Returns the entire output contents if count is -1. [default: -1]

Returns: A string containing count lines of data starting with the first line of output data.

Throws: IOError: if an I/O error occurs.

readString(count: Number = -1): String

Description: Read the data from the command output as a string. This reads from the command's standard output.

Parameters

count: Number

Of bytes to read. Returns the entire output data contents if count is -1. [default: -1]

Returns: A string of count characters beginning at the start of the output data.

Throws: IOError: if an I/O error occurs.

readXml(): XML

Description: Read the command output as an XML document. This reads from the command's standard output.

Returns: The output content as an XML object.

Throws: IOError: if an I/O error occurs.

static run(command: Object, options: Object = expression, data: Object = null): String

Description: Execute a command/program and return the output as a result. The call blocks while executing the command.

Parameters

command: Object	Command or program to execute.
options: Object	Command options hash. Supported options are:. [default: expression]
data: Object	Optional data to write to the command on it's standard input. [default: null]

Options

detach	Boolean If true, run the command and return immediately. If detached, finalize() must be called to signify the end of data being written to the command's stdin. In this case, run returns null.
dir	Path or String. Directory to set as the current working directory for the command.
exceptions	Boolean If true, throw exceptions if the command returns a non-zero status code. Defaults to true.
noio	Boolean If true, do not capture or redirect the commands stdin, stdout or stderr.
timeout	Number This is the default number of milliseconds for the command to complete.
stream	Stream the stdout from the command to the current standard output. Defaults to false.

Returns: The command output from the standard output.

Throws: IOError: if the command exits with non-zero status. The exception object will contain the command's standard error output.

static sh(command: Object, options: Object = null, data: Object = null): String

Description: Run a command using the system command shell and wait for completion. On Windows, this requires that sh.exe is installed (See Cygwin).

Parameters

command: Object	The (optional) command line to initialize with. The command may be either a string or an array of arguments.
options: Object	Command options hash. Supported options are:. [default: null]
data: Object	Optional data to write to the command on it's standard input. [default: null]

Options

detach	Boolean If true, run the command and return immediately. If detached, finalize() must be called to signify the end of data being written to the command's stdin. In this case, sh returns null.
dir	Path or String. Directory to set as the current working directory for the command.
exceptions	Boolean If true, throw exceptions if the command returns a non-zero status code. Defaults to true.
timeout	Number This is the default number of milliseconds for the command to complete.
stream	Stream the stdout from the command to the current standard output. Defaults to false.

Returns: The command output from the standard output.

Throws: IOError: if the command exits with non-zero status. The exception object will contain the command's standard error output.

start(cmdline: Object, options: Object = null): Void

Description: Start the command.

Parameters

cmdline: Object	Command line to use. The cmdline may be either a string or an array of strings.
options: Object	Command options. Sames as options in Cmd. [default: null]

Throws: IOError: if the request was cannot be issued to the remote server.

stop(signal: Number = 2): Boolean

Description: Stop the current command. After stopping, the command exit status and any response or error data are available for interrogation.

Parameters

signal: Number

Signal to send the the active process. [default: 2]

Returns: True if the command is successfully stopped or the command has completed.

wait(timeout: Number = -1): Boolean

Description: Wait for a command to complete.

Parameters

timeout: Number

Time in milliseconds to wait for the command to complete. If unspecified, the timeout propoperty value is used instead. [default: -1]

Returns: True if the request successfully completes.

write(data: Array): Number

Description: Write data to the stream.Call finalize() to signify the end of write data. If the stream can accept all the write data, the call returns immediately with the number of bytes written. If writing more data than the stream can absorb in sync mode, the call will block until the data is written. If writing more data than the stream can absorb in async mode, the call will not block and will buffer the data and return immediately. Some streams will require a flush() call to actually send the data. A "writable" event will be issued when the stream can again absorb more data.Failure to call finalize() may prevent some commands from exiting.

Parameters

data: Array

Data to write.

Events

readable	Issued when data is written and a consumer can read without blocking.
writable	Issued when the stream becomes empty and it is ready to be written to.

Returns: A count of the bytes actually written.

Throws: IOError: if there is an I/O error.