001package org.unix4j.unix;
002
003import org.unix4j.command.CommandInterface;
004
005import org.unix4j.unix.ls.LsFactory;
006import org.unix4j.unix.ls.LsOption;
007import org.unix4j.unix.ls.LsOptions;
008import org.unix4j.unix.ls.LsOptionSets;
009
010/**
011 * Non-instantiable module with inner types making up the <b>ls</b> command.
012 * <p>
013 * <b>NAME</b>
014 * <p>
015 * ls - list directory contents 
016 * <p>
017 * <b>SYNOPSIS</b>
018 * <p>
019 * <table>
020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls}</td></tr>
021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls <args>}</td></tr>
022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls <files>}</td></tr>
023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls [-ahlRrt]}</td></tr>
024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls [-ahlRrt] <files>}</td></tr>
025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code ls [-ahlRrt] <paths>}</td></tr>
026 * </table>
027 * <p>
028 * See {@link Interface} for the corresponding command signature methods.
029 * <p>
030 * <b>DESCRIPTION</b>
031 * <p>
032 *  <p> For each operand that names a file of a type other than directory or symbolic link to a directory, <code>ls</code> writes the name of the file as well as any requested, associated information. For each operand that names a file of type directory, <code>ls</code> writes the names of files contained within the directory as well as any requested, associated information. If the <b>-l</b> option is specified, for each operand that names a file of type symbolic link to a directory, <code>ls</code> writes the name of the file as well as any requested, associated information. If the <b>-l</b> option is not specified, for each operand that names a file of type symbolic link to a directory, <code>ls</code> writes the names of files contained within the directory as well as any requested, associated information. </p> <p> If no operands are specified, <code>ls</code> writes the contents of the current directory. If more than one operand is specified, <code>ls</code> writes non-directory operands first; it sorts directory and non-directory operands separately according to the name of the file or directory. </p> <p> TODO The <code>ls</code> utility detects infinite loops; that is, entering a previously visited directory that is an ancestor of the last file encountered. When it detects an infinite loop, <code>ls</code> aborts the recursion. </p> 
033 * 
034 * <p>
035 * <b>NOTES</b>
036 * <p>
037 * <ul>
038 * <li>Infinite loop detection is currently NOT implemented.</li>
039 * </ul>
040 * 
041 * <p>
042 * <b>Options</b>
043 * <p>
044 * The following options are supported:
045 * <p>
046 * <table>
047 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -a}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --allFiles}</td><td>&nbsp;</td><td>Lists all files in the given directory, including hidden files
048                        (those whose names start with \".\" in Unix). By default, these 
049                        files are excluded from the list.</td></tr>
050 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -h}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --humanReadable}</td><td>&nbsp;</td><td>Print sizes in human readable format. (e.g., 1K, 234M, 2G, etc.)</td></tr>
051 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --longFormat}</td><td>&nbsp;</td><td>Long format, displaying file types, permissions, number of hard 
052                        links, owner, group, size, date, and filename.</td></tr>
053 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -R}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --recurseSubdirs}</td><td>&nbsp;</td><td>Recursively lists subdirectories encountered.</td></tr>
054 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --reverseOrder}</td><td>&nbsp;</td><td>Reverses the order of the sort to get reverse collating sequence or 
055                        oldest first.</td></tr>
056 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --timeSorted}</td><td>&nbsp;</td><td>Sorts with the primary key being time modified (most recently 
057                        modified first) and the secondary key being filename in the 
058                        collating sequence.</td></tr>
059 * </table>
060 * <p>
061 * <b>OPERANDS</b>
062 * <p>
063 * The following operands are supported:
064 * <p>
065 * <table>
066 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <files>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code java.io.File...}</td><td>&nbsp;</td><td>The files or directories used as starting point for the listing; 
067                        relative paths are not resolved (use the string path argument to 
068                        enable relative path resolving based on the current working 
069                        directory).</td></tr>
070 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <paths>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code String...}</td><td>&nbsp;</td><td>The files or directories used as starting point for the listing; 
071                        wildcards * and ? are supported; relative paths are resolved on the
072            basis of the current working directory.</td></tr>
073 * <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 and operands for the command. 
074                        Options can be specified by acronym (with a leading dash "-") or by 
075                        long name (with two leading dashes "--"). Operands other than the
076                        default "--paths" operand have to be prefixed with the operand 
077                        name (e.g. "--count" for a subsequent count operand value).</td></tr>
078 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td>&nbsp;:&nbsp;</td><td nowrap="nowrap">{@code LsOptions}</td><td>&nbsp;</td><td>The options defining the output format.</td></tr>
079 * </table>
080 */
081public final class Ls {
082        /**
083         * The "ls" command name.
084         */
085        public static final String NAME = "ls";
086
087        /**
088         * Interface defining all method signatures for the "ls" command.
089         * 
090         * @param <R>
091         *            the generic return type for all command signature methods
092         *            to support different implementor types; the methods of a 
093         *            command factory for instance returns a command instance; 
094         *            command builders can also implement this interface, but their
095         *            methods return the builder itself enabling for chained method
096         *            invocation to create joined commands
097         */
098        public static interface Interface<R> extends CommandInterface<R> {
099                /**
100                 * Lists all files and directories in the user's current working 
101                        directory and writes them to the output.
102                 *
103                 * @return the generic type {@code <R>} defined by the implementing class;
104                 *         the command itself returns no value and writes its result to the
105                 *         standard output; see class level parameter comments for more 
106                 *         details
107                 */
108                R ls();
109                /**
110                 * Prints the name of the specified files and lists all files contained 
111                        in directories for every directory in those files. 
112                        <p>
113                        Options can be specified by acronym (with a leading dash "-") or by 
114                        long name (with two leading dashes "--"). Operands other than the 
115                        default "--paths" operand have to be prefixed with the operand 
116                        name.
117                 *
118                 * @param args String arguments defining the options and operands for the command. 
119                        Options can be specified by acronym (with a leading dash "-") or by 
120                        long name (with two leading dashes "--"). Operands other than the
121                        default "--paths" operand have to be prefixed with the operand 
122                        name (e.g. "--count" for a subsequent count operand value).
123                 * @return the generic type {@code <R>} defined by the implementing class;
124                 *         the command itself returns no value and writes its result to the
125                 *         standard output; see class level parameter comments for more 
126                 *         details
127                 */
128                R ls(String... args);
129                /**
130                 * Prints the name of the given files and lists all files contained in 
131                        directories for every directory in {@code files}.
132                 *
133                 * @param files The files or directories used as starting point for the listing; 
134                        relative paths are not resolved (use the string path argument to 
135                        enable relative path resolving based on the current working 
136                        directory).
137                 * @return the generic type {@code <R>} defined by the implementing class;
138                 *         the command itself returns no value and writes its result to the
139                 *         standard output; see class level parameter comments for more 
140                 *         details
141                 */
142                R ls(java.io.File... files);
143                /**
144                 * Lists all files and directories in the user's current working 
145                        directory and writes them to the output using the given options 
146                        specifying the details of the output format.
147                 *
148                 * @param options The options defining the output format.
149                 * @return the generic type {@code <R>} defined by the implementing class;
150                 *         the command itself returns no value and writes its result to the
151                 *         standard output; see class level parameter comments for more 
152                 *         details
153                 */
154                R ls(LsOptions options);
155                /**
156                 * Prints the name of the given files and lists all files contained in
157                        directories for every directory in {@code files}. The given options
158                        define the details of the output format.
159                 *
160                 * @param options The options defining the output format.
161                 * @param files The files or directories used as starting point for the listing; 
162                        relative paths are not resolved (use the string path argument to 
163                        enable relative path resolving based on the current working 
164                        directory).
165                 * @return the generic type {@code <R>} defined by the implementing class;
166                 *         the command itself returns no value and writes its result to the
167                 *         standard output; see class level parameter comments for more 
168                 *         details
169                 */
170                R ls(LsOptions options, java.io.File... files);
171                /**
172                 * Prints the name of the given files and lists all files contained in
173                        directories for every directory in {@code files}. The given options
174                        define the details of the output format.
175                 *
176                 * @param options The options defining the output format.
177                 * @param paths The files or directories used as starting point for the listing; 
178                        wildcards * and ? are supported; relative paths are resolved on the
179            basis of the current working directory.
180                 * @return the generic type {@code <R>} defined by the implementing class;
181                 *         the command itself returns no value and writes its result to the
182                 *         standard output; see class level parameter comments for more 
183                 *         details
184                 */
185                R ls(LsOptions options, String... paths);
186        }
187
188        /**
189         * Options for the "ls" command: {@link LsOption#allFiles a}, {@link LsOption#humanReadable h}, {@link LsOption#longFormat l}, {@link LsOption#recurseSubdirs R}, {@link LsOption#reverseOrder r}, {@link LsOption#timeSorted t}.
190         * <p> 
191 * <table>
192 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -a}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --allFiles}</td><td>&nbsp;</td><td>Lists all files in the given directory, including hidden files
193                        (those whose names start with \".\" in Unix). By default, these 
194                        files are excluded from the list.</td></tr>
195 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -h}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --humanReadable}</td><td>&nbsp;</td><td>Print sizes in human readable format. (e.g., 1K, 234M, 2G, etc.)</td></tr>
196 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --longFormat}</td><td>&nbsp;</td><td>Long format, displaying file types, permissions, number of hard 
197                        links, owner, group, size, date, and filename.</td></tr>
198 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -R}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --recurseSubdirs}</td><td>&nbsp;</td><td>Recursively lists subdirectories encountered.</td></tr>
199 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --reverseOrder}</td><td>&nbsp;</td><td>Reverses the order of the sort to get reverse collating sequence or 
200                        oldest first.</td></tr>
201 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -t}</td><td>&nbsp;&nbsp;</td><td nowrap="nowrap">{@code --timeSorted}</td><td>&nbsp;</td><td>Sorts with the primary key being time modified (most recently 
202                        modified first) and the secondary key being filename in the 
203                        collating sequence.</td></tr>
204 * </table>
205         */
206        public static final LsOptionSets Options = LsOptionSets.INSTANCE;
207
208        /**
209         * Singleton {@link LsFactory factory} instance for the "ls" command.
210         */
211        public static final LsFactory Factory = LsFactory.INSTANCE;
212
213        // no instances
214        private Ls() {
215                super();
216        }
217}