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> </td><td nowrap="nowrap">{@code --allFiles}</td><td> </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> </td><td nowrap="nowrap">{@code --humanReadable}</td><td> </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> </td><td nowrap="nowrap">{@code --longFormat}</td><td> </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> </td><td nowrap="nowrap">{@code --recurseSubdirs}</td><td> </td><td>Recursively lists subdirectories encountered.</td></tr> 054 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td> </td><td nowrap="nowrap">{@code --reverseOrder}</td><td> </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> </td><td nowrap="nowrap">{@code --timeSorted}</td><td> </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> : </td><td nowrap="nowrap">{@code java.io.File...}</td><td> </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> : </td><td nowrap="nowrap">{@code String...}</td><td> </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> : </td><td nowrap="nowrap">{@code String...}</td><td> </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> : </td><td nowrap="nowrap">{@code LsOptions}</td><td> </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> </td><td nowrap="nowrap">{@code --allFiles}</td><td> </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> </td><td nowrap="nowrap">{@code --humanReadable}</td><td> </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> </td><td nowrap="nowrap">{@code --longFormat}</td><td> </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> </td><td nowrap="nowrap">{@code --recurseSubdirs}</td><td> </td><td>Recursively lists subdirectories encountered.</td></tr> 199 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -r}</td><td> </td><td nowrap="nowrap">{@code --reverseOrder}</td><td> </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> </td><td nowrap="nowrap">{@code --timeSorted}</td><td> </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}