PipeFittingDoc.tioga
Peter Kessler, December 19, 1985 2:56:34 pm PST
PipeFitting
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
PipeFitting
Tools for constructing pipelines
Peter B. Kessler
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: PipeFitting provides a programmer's and CommandTool interface for constructing pipelines.
Created by: Peter Kessler
Maintained by: Peter Kessler <PeterKessler.pa>
Keywords: concatentation of files, pipes, pipelines, tees
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. PipeFitting Commands
How could anyone have built a CommandTool with pipes without having tools for inserting files into pipelines and extracting pipeline contents into files? I don't know, so I wrote those two tools. In the UNIXTM world these commands are called (respectively) ``cat'' and ``tee'', and those seem mnemonic enough. To like these tools you have to believe that pipes are good things. Since in Cedar they aren't (yet?), maybe these tools won't be so useful. Maybe these tools will make pipes more useful.
Stuffing files into pipelines: Cat
Here you are, you've written a nice filter that reads data from cmd^.in and you want to give it some data. In the easy case, the data is in one file and you can use the CommandTool's input redirection (``<'') facility. What if your data is spread across several files? What you want to do is concatentate those files together and feed them into a pipeline to your filter. The ``cat'' command does just that. It takes a list of file names and concatentates their contents onto cmd^.out, so you can pipe it to whatever you want.
As a special case, if any of the file names is a single dash (`-'), cmd^.in will be concatentated at that point. Thus for pipelines where there are some fixed sources and some sources from previous filters, one might want to use:
filter1 ... | cat source1 source2 - source3 | filter2 ...
which will concatenate the contents of source1, the contents of source2, the output of filter1, and the contents of source3 and ship that off to filter2.
You are hereby warned that Cedar doesn't have a way of typing an end-of-file character from the keyboard (that I could find), so you shouldn't try to cat from the CommandTool's top cmd^.in.
Extracting the contents of pipelines: Tee
Here you are, you've written a nice filter that writes data onto cmd^.out and you want to check on what it's doing. In the easy case you can just break the pipeline after your filter and use the CommandTool's output redirection (``>'') facility to dump the pipeline into a file. What if you want to examine your data as it trickles through the pipeline? What you want is something that sits in a pipeline and copies its input to its output, but also copies its input to a file. The ``tee'' command does just that. It takes a list of file names and writes whatever it receives on its cmd^.in onto each of those files and also onto its cmd^.out.
2. The Programmer's Interface
Cat
Cat defines two procedures: Cat.FromNames and Cat.FromStreams. Cat.FromNames takes an input stream, an output stream, and a list of file names, and concatenates the contents of the named files onto the output stream. Cat.FromNames handles the special cases of file names listed above. Cat.FromStreams takes a list of input streams and an output stream and concatenates the contents of the input streams onto the output stream.
Tee
Tee defines two procedures: Tee.ToNames and Tee.ToStreams. Tee.ToNames takes an input stream, an output stream, and a list of file names, and copies the contents of the input stream onto each of the named files and the output stream. Tee.ToStreams takes an input stream and a list of output streams and copies the contents of the input stream onto each of the output streams.