class:: Pipe
summary:: pipe stdin to, or stdout from, a UNIX shell command
related:: Classes/UnixFILE
categories:: Files

description::
Pipe stdin to, or stdout from, a UNIX shell command. Pipe treats the shell command as if it were a UnixFILE, and returns nil when done. See link::Classes/UnixFILE:: for details of the access methods. Pipe must be explicitly closed. Do not rely on the garbage collector to do this for you!

ClassMethods::

method::new

argument::commandLine
A link::Classes/String:: representing a valid shell command.

argument::mode
A link::Classes/String:: representing the mode. Valid modes are "w" (pipe to stdin) and "r" (pipe from stdout).

method::argv

argument::args
A link::Classes/SequenceableCollection:: containining strings where the first string is the path to the executable to be run and all other strings are passed as arguments to the executable. This method starts the process directly without using a shell.

argument::mode
A link::Classes/String:: representing the mode. Valid modes are "w" (pipe to stdin) and "r" (pipe from stdout).

InstanceMethods::

private::prClose, prOpen, prOpenArgv

method::open
Open the file.

argument::commandLine
A command line link::Classes/String:: passed to popen.

argument::mode
A link::Classes/String:: passed to popen, so should be one of: "r","w"

method::openArgv
Open the file.

argument::args
A link::Classes/SequenceableCollection:: containining strings where the first string is the path to the executable to be run and all other strings are passed as arguments to the executable. This method starts the process directly without using a shell.

argument::mode
A link::Classes/String:: passed to popen, so should be one of: "r","w"

method::close
Closes the pipe, waiting for the command to finish. You must do this explicitly before the Pipe object is garbage collected.

returns:: The exit status of the command (an Integer).

Examples::

code::
// this pipes in stdout from ls
(
var p, l;
p = Pipe.new("ls -l", "r");			// list directory contents in long format
l = p.getLine;					// get the first line
while({l.notNil}, {l.postln; l = p.getLine; });	// post until l = nil
p.close;					// close the pipe to avoid that nasty buildup
)
::

without using a shell:

code::
// this pipes in stdout from ls
(
var p, l;
p = Pipe.argv(["ls","-l"], "r");			// list directory contents in long format
l = p.getLine;					// get the first line
while({l.notNil}, {l.postln; l = p.getLine; });	// post until l = nil
p.close;					// close the pipe to avoid that nasty buildup
)
::

A more time-intensive request:
code::
(
var p, l;
p = Pipe.new("ping -c10 sourceforge.net", "r");	// list directory contents in long format
l = p.getLine;					// get the first line
while({l.notNil}, {l.postln; l = p.getLine; });	// post until l = nil
p.close;					// close the pipe to avoid that nasty buildup
)
::
