System Feature
	Pipe

Purpose
	Redirects the contents of output stream from one command to the input stream of the following command.

Syntax
	<command1> | <Command2> [ | <command3> [ ... ] ]

	The <command>s are separated by the pipe character (|) .

Options
	None

Arguments
	<command1>
	The command whose stream output is to be redirected to the stream input of <command2>.

	<command2>
	The command whose stream input is to be redirected from the stream output of <command1>
	The stream output of this command is also redirected to the stream input of <command3>.

	<command3>
	The command whose stream input is to be redirected from the stream output of <command2>

Description
	The pipe command specifies redirection of streams. After <command1> is fully
	executed, its stream output is written to the stream input of <command2>, before
	execution of <command2> begins.

	Similarly after <command2> is fully executed, its stream output is written to the
	stream input of <command3>, before execution of <command3> begins.

	If any of <command1>, <command2> or <command3> result in errors, the remaining
	<command>s are not processed.

	Pipes work in addition to other forms of redirection. For example, a command
	can write its output to a variable, AND to a file, AND to a pipe.

	Any number of commands can be 'stringed' together using pipes. There is no limit
	on the number of pipes that can be 'stringed' together on one line.

	THE USE OF PIPES IS DISCOURAGED. Stream redirection to/from str variables and,
	even inline commands, provides a much more powerful and simpler way of redirection
	and redistribution of data (one-to-one, one-to-many, many-to-one, many-to-many).
	Pipes are provided merely for backward compatibility with older scripts you have
	developed.

		
Restrictions
	Pipes are not allowed, either before or after, the following.
	return
	if
	else
	endif
	function
	end
	while
	do
	done	

	Inline commands, by themselves, are not allowed as either origin or destination of a pipe.
	However, inline commands are allowed as arguments in commands that are either origin
	or destination of a pipe. See Invalid Examples.


Valid Examples
	echo x | repro
	The above will output x. This is an example of a straight pipe (one-to-one).

	var str output
	echo x >$output | repro
	The above will also output x. The output is ALSO available in $output.
	This is an example of a T-pipe (one-to-many).

	var str output
	echo x >$output
	echo y >>$output
	echo $output
	Will output x followed by y. This is an example of Y-pipe (many-to-one).
	

Invalid Examples
	echo x | { repro }

	Will result in an error. There is no valid command (outside of inline command)
	after the pipe. However, inline commands can be used as part(s) of a valid command
	either before or after a pipe. The following is an example.

	echo "The contents of all text files follow: " | repro { mf "*.txt" }

	The above will produce "The contents of all text files follow: " followed by the
	contents of all .txt files within the current directory.

	Inline commands can be used vary effectively in stream redirection.

	var str file
	set $file="z.txt"
	mf "*" > { echo $file }

	The above will write the output of the mf command to file z.txt .

	repro < { echo $file }

	The above will reproduce contents of file z.txt .

See Also
stream
error
input
output