001package org.unix4j.builder;
002
003import org.unix4j.command.Command;
004import org.unix4j.command.ExitValueException;
005import org.unix4j.io.Output;
006import org.unix4j.line.Line;
007
008import java.io.File;
009import java.io.OutputStream;
010import java.io.Writer;
011import java.util.List;
012import java.util.stream.Stream;
013
014/**
015 * Interface defining command execution and output redirection methods.
016 */
017public interface To {
018        /**
019         * Executes the composite command and writes the result to the standard
020         * output.
021         */
022        void toStdOut();
023
024        /**
025         * Executes the composite command and returns the result as string. Line
026         * ending characters are inserted between lines if the result contains
027         * multiple lines. Note that the last line is NOT terminated with a line
028         * ending.
029         * <p>
030         * To return a representation of the command with its arguments without
031         * executing the command, {@link Command#toString() toString()} can be used
032         * instead.
033         * 
034         * @return the result as a string, possibly a multiline string with newline
035         *         characters between the lines but not after the last line
036         */
037        String toStringResult();
038
039        /**
040         * Executes the composite command and returns the result as a list
041         * containing the output lines.
042         * 
043         * @return the result as a list of lines
044         */
045        List<Line> toLineList();
046
047        /**
048         * Executes the composite command and returns the result as a list
049         * containing the output lines without line ending.
050         * 
051         * @return the result as a list of line strings
052         */
053        List<String> toStringList();
054
055        /**
056         * Executes the composite command and returns the result as a stream
057         * containing the output lines.
058         *
059         * @return the result as a stream of lines
060         */
061        Stream<Line> toLineStream();
062
063        /**
064         * Executes the composite command and returns the result as a stream
065         * containing the output lines without line endings.
066         *
067         * @return the result as a stream of line strings
068         */
069        Stream<String> toStringStream();
070
071        /**
072         * Executes the composite command and writes the result to the given file.
073         * 
074         * @param file
075         *            the target output file
076         */
077        void toFile(String file);
078
079        /**
080         * Executes the composite command and does not write the result anywhere.
081         */
082        void toDevNull();
083
084        /**
085         * Executes the composite command and writes the result to the given file.
086         * 
087         * @param file
088         *            the target output file
089         */
090        void toFile(File file);
091
092        /**
093         * Executes the composite command and writes the result to the given stream.
094         * 
095         * @param stream
096         *            the target output stream
097         */
098        void toOutputStream(OutputStream stream);
099
100        /**
101         * Executes the composite command and writes the result using the given
102         * writer.
103         * 
104         * @param writer
105         *            the writer used to write the output
106         */
107        void toWriter(Writer writer);
108
109        /**
110         * Executes the composite command and writes the result to the given output.
111         */
112        void toOutput(Output output);
113        
114        /**
115         * Executes the composite command returns its exit value, 0 if the command
116         * completes successfully and another command specific error value different
117         * from zero if the command throws an {@link ExitValueException}.
118         * 
119         * @return the exit value returned by the command, 0 for success
120         */
121        int toExitValue();
122
123}