001package org.unix4j.unix;
002
003import org.unix4j.command.CommandInterface;
004
005import org.unix4j.unix.echo.EchoFactory;
006import org.unix4j.unix.echo.EchoOption;
007import org.unix4j.unix.echo.EchoOptions;
008import org.unix4j.unix.echo.EchoOptionSets;
009
010/**
011 * Non-instantiable module with inner types making up the <b>echo</b> command.
012 * <p>
013 * <b>NAME</b>
014 * <p>
015 * echo - write arguments to standard output 
016 * <p>
017 * <b>SYNOPSIS</b>
018 * <p>
019 * <table>
020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code echo <args>}</td></tr>
021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code echo [-n] <string>}</td></tr>
022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code echo [-n] <strings>}</td></tr>
023 * </table>
024 * <p>
025 * See {@link Interface} for the corresponding command signature methods.
026 * <p>
027 * <b>DESCRIPTION</b>
028 * <p>
029 *  <p> The echo utility writes any specified operands, separated by single blank       ({@code ' '}) characters and followed by a line ending, to the standard output. The line ending is usually one or two characters depending on the       operating system where the command is run. </p>
030 * 
031 * <p>
032 * <b>Options</b>
033 * <p>
034 * The following options are supported:
035 * <p>
036 * <table>
037 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --noNewline}</td><td>&nbsp;</td><td>Do not print the trailing newline character(s).</td></tr>
038 * </table>
039 * <p>
040 * <b>OPERANDS</b>
041 * <p>
042 * The following operands are supported:
043 * <p>
044 * <table>
045 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <string>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String}</td><td>&nbsp;</td><td>A string to be written to standard output.</td></tr>
046 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <strings>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String...}</td><td>&nbsp;</td><td>Strings to be written to standard output, separated by single blank 
047                        characters.</td></tr>
048 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <args>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String...}</td><td>&nbsp;</td><td>String arguments defining the options for the command and the 
049                        strings to be written to the output. Options can be specified by 
050                        acronym (with a leading dash "-") or by long name (with two leading 
051                        dashes "--").</td></tr>
052 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code EchoOptions}</td><td>&nbsp;</td><td>Options for the echo command.</td></tr>
053 * </table>
054 */
055public final class Echo {
056        /**
057         * The "echo" command name.
058         */
059        public static final String NAME = "echo";
060
061        /**
062         * Interface defining all method signatures for the "echo" command.
063         * 
064         * @param <R>
065         *            the generic return type for all command signature methods
066         *            to support different implementor types; the methods of a 
067         *            command factory for instance returns a command instance; 
068         *            command builders can also implement this interface, but their
069         *            methods return the builder itself enabling for chained method
070         *            invocation to create joined commands
071         */
072        public static interface Interface<R> extends CommandInterface<R> {
073                /**
074                 * Writes any of the specified strings, separated by single blank 
075                         ({@code ' '}) characters to the standard output suppressing the
076                         trailing line ending if the {@code "-n"} option is specified.
077                 *
078                 * @param args String arguments defining the options for the command and the 
079                        strings to be written to the output. Options can be specified by 
080                        acronym (with a leading dash "-") or by long name (with two leading 
081                        dashes "--").
082                 * @return the generic type {@code <R>} defined by the implementing class;
083                 *         the command itself returns no value and writes its result to the
084                 *         standard output; see class level parameter comments for more 
085                 *         details
086                 */
087                R echo(String... args);
088                /**
089                 * Writes the specified string followed by a newline character to 
090                         the standard output suppressing the trailing line ending if the
091                         {@code -n} option is specified.
092                 *
093                 * @param options Options for the echo command.
094                 * @param string A string to be written to standard output.
095                 * @return the generic type {@code <R>} defined by the implementing class;
096                 *         the command itself returns no value and writes its result to the
097                 *         standard output; see class level parameter comments for more 
098                 *         details
099                 */
100                R echo(EchoOptions options, String string);
101                /**
102                 * Writes any of the specified strings, separated by single blank 
103                         ({@code ' '}) characters to the standard output suppressing the
104                         trailing line ending if the {@code -n} option is specified.
105                 *
106                 * @param options Options for the echo command.
107                 * @param strings Strings to be written to standard output, separated by single blank 
108                        characters.
109                 * @return the generic type {@code <R>} defined by the implementing class;
110                 *         the command itself returns no value and writes its result to the
111                 *         standard output; see class level parameter comments for more 
112                 *         details
113                 */
114                R echo(EchoOptions options, String... strings);
115        }
116
117        /**
118         * Options for the "echo" command: {@link EchoOption#noNewline n}.
119         * <p> 
120 * <table>
121 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --noNewline}</td><td>&nbsp;</td><td>Do not print the trailing newline character(s).</td></tr>
122 * </table>
123         */
124        public static final EchoOptionSets Options = EchoOptionSets.INSTANCE;
125
126        /**
127         * Singleton {@link EchoFactory factory} instance for the "echo" command.
128         */
129        public static final EchoFactory Factory = EchoFactory.INSTANCE;
130
131        // no instances
132        private Echo() {
133                super();
134        }
135}