001package org.unix4j.unix; 002 003import org.unix4j.command.CommandInterface; 004 005import org.unix4j.unix.head.HeadFactory; 006import org.unix4j.unix.head.HeadOption; 007import org.unix4j.unix.head.HeadOptions; 008import org.unix4j.unix.head.HeadOptionSets; 009 010/** 011 * Non-instantiable module with inner types making up the <b>head</b> command. 012 * <p> 013 * <b>NAME</b> 014 * <p> 015 * head - display first lines of a file 016 * <p> 017 * <b>SYNOPSIS</b> 018 * <p> 019 * <table> 020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head}</td></tr> 021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <args>}</td></tr> 022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <count>}</td></tr> 023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <files>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <inputs>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <count> <files>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <count> <paths>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <count> <inputs>}</td></tr> 029 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count> <files>}</td></tr> 030 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count> <paths>}</td></tr> 031 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count> <inputs>}</td></tr> 032 * </table> 033 * <p> 034 * See {@link Interface} for the corresponding command signature methods. 035 * <p> 036 * <b>DESCRIPTION</b> 037 * <p> 038 * <p> This filter displays the first <i>count</i> lines or characters of each of the specified files, or of the standard input if no files are specified. If <i>count</i> is omitted it defaults to 10. Both line and character counts start from 1. </p> <p> If more than a single file is specified, each file is preceded by a header consisting of the string {@code "==> XXX <=="} where {@code "XXX"} is the name of the file. </p> 039 * 040 * <p> 041 * <b>Options</b> 042 * <p> 043 * The following options are supported: 044 * <p> 045 * <table> 046 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td> </td><td nowrap="nowrap">{@code --chars}</td><td> </td><td>The {@code count} argument is in units of characters instead of 047 lines. Starts from 1 and includes line ending characters.</td></tr> 048 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -q}</td><td> </td><td nowrap="nowrap">{@code --suppressHeaders}</td><td> </td><td>Suppresses printing of headers when multiple files are being 049 examined.</td></tr> 050 * </table> 051 * <p> 052 * <b>OPERANDS</b> 053 * <p> 054 * The following operands are supported: 055 * <p> 056 * <table> 057 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <count>}</td><td> : </td><td nowrap="nowrap">{@code long}</td><td> </td><td>The first {@code count} lines of each input file are 058 copied to standard output, starting from 1 (characters instead of 059 lines if the {@code -c} option is specified). Must be a non-negative 060 integer or an exception is thrown. If {@code count} is greater than 061 the number number of lines (characters) in the input, the 062 application will not error and send the whole file to the output.</td></tr> 063 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <paths>}</td><td> : </td><td nowrap="nowrap">{@code String...}</td><td> </td><td>Path names of the input files to be filtered; wildcards * and ? are 064 supported; relative paths are resolved on the basis of the current 065 working directory.</td></tr> 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 input files to be filtered; relative paths are not resolved (use 067 the string paths argument to enable relative path resolving based on 068 the current working directory).</td></tr> 069 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <inputs>}</td><td> : </td><td nowrap="nowrap">{@code org.unix4j.io.Input...}</td><td> </td><td>The inputs to be filtered.</td></tr> 070 * <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. 071 Options can be specified by acronym (with a leading dash "-") or by 072 long name (with two leading dashes "--"). Operands other than the 073 default "--paths" operand have to be prefixed with the operand 074 name (e.g. "--count" for a subsequent count operand value).</td></tr> 075 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td> : </td><td nowrap="nowrap">{@code HeadOptions}</td><td> </td><td>Options for the head command.</td></tr> 076 * </table> 077 */ 078public final class Head { 079 /** 080 * The "head" command name. 081 */ 082 public static final String NAME = "head"; 083 084 /** 085 * Interface defining all method signatures for the "head" command. 086 * 087 * @param <R> 088 * the generic return type for all command signature methods 089 * to support different implementor types; the methods of a 090 * command factory for instance returns a command instance; 091 * command builders can also implement this interface, but their 092 * methods return the builder itself enabling for chained method 093 * invocation to create joined commands 094 */ 095 public static interface Interface<R> extends CommandInterface<R> { 096 /** 097 * Reads the first 10 lines from the standard input and writes them to 098 the standard output. 099 * 100 * @return the generic type {@code <R>} defined by the implementing class; 101 * the command itself returns no value and writes its result to the 102 * standard output; see class level parameter comments for more 103 * details 104 */ 105 R head(); 106 /** 107 * Reads the first n lines from each of the files specified and writes 108 them to the standard output. If more than a single file is 109 specified, each file is preceded by a header consisting of the 110 string {@code "==> XXX <=="} where {@code "XXX"} is the name 111 of the file. 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 head(String... args); 129 /** 130 * Reads the first {@code count} lines from the standard input and 131 writes them to the standard output. 132 * 133 * @param count The first {@code count} lines of each input file are 134 copied to standard output, starting from 1 (characters instead of 135 lines if the {@code -c} option is specified). Must be a non-negative 136 integer or an exception is thrown. If {@code count} is greater than 137 the number number of lines (characters) in the input, the 138 application will not error and send the whole file to the output. 139 * @return the generic type {@code <R>} defined by the implementing class; 140 * the command itself returns no value and writes its result to the 141 * standard output; see class level parameter comments for more 142 * details 143 */ 144 R head(long count); 145 /** 146 * Reads the first {@code count} lines or characters from the standard 147 input and writes them to the standard output. 148 * 149 * @param options Options for the head command. 150 * @param count The first {@code count} lines of each input file are 151 copied to standard output, starting from 1 (characters instead of 152 lines if the {@code -c} option is specified). Must be a non-negative 153 integer or an exception is thrown. If {@code count} is greater than 154 the number number of lines (characters) in the input, the 155 application will not error and send the whole file to the output. 156 * @return the generic type {@code <R>} defined by the implementing class; 157 * the command itself returns no value and writes its result to the 158 * standard output; see class level parameter comments for more 159 * details 160 */ 161 R head(HeadOptions options, long count); 162 /** 163 * Reads the first 10 lines from each of the specified files and writes 164 them to the standard output. If more than a single file is 165 specified, each file is preceded by a header consisting of the 166 string {@code "==> XXX <=="} where {@code "XXX"} is the name 167 of the file. 168 * 169 * @param files The input files to be filtered; relative paths are not resolved (use 170 the string paths argument to enable relative path resolving based on 171 the current working directory). 172 * @return the generic type {@code <R>} defined by the implementing class; 173 * the command itself returns no value and writes its result to the 174 * standard output; see class level parameter comments for more 175 * details 176 */ 177 R head(java.io.File... files); 178 /** 179 * Reads the first 10 lines from each of the specified inputs and writes 180 them to the standard output. If more than a input is 181 specified, each file is preceded by a header consisting of the 182 string {@code "==> XXX <=="} where {@code "XXX"} is the input's 183 string representation. 184 * 185 * @param inputs The inputs to be filtered. 186 * @return the generic type {@code <R>} defined by the implementing class; 187 * the command itself returns no value and writes its result to the 188 * standard output; see class level parameter comments for more 189 * details 190 */ 191 R head(org.unix4j.io.Input... inputs); 192 /** 193 * Reads the first {@code count} lines from each of the specified files 194 and writes them to the standard output. If more than a single file 195 is specified, each file is preceded by a header consisting of the 196 string {@code "==> XXX <=="} where {@code "XXX"} is the name 197 of the file. 198 * 199 * @param count The first {@code count} lines of each input file are 200 copied to standard output, starting from 1 (characters instead of 201 lines if the {@code -c} option is specified). Must be a non-negative 202 integer or an exception is thrown. If {@code count} is greater than 203 the number number of lines (characters) in the input, the 204 application will not error and send the whole file to the output. 205 * @param files The input files to be filtered; relative paths are not resolved (use 206 the string paths argument to enable relative path resolving based on 207 the current working directory). 208 * @return the generic type {@code <R>} defined by the implementing class; 209 * the command itself returns no value and writes its result to the 210 * standard output; see class level parameter comments for more 211 * details 212 */ 213 R head(long count, java.io.File... files); 214 /** 215 * Reads the first {@code count} lines from each of the specified files 216 and writes them to the standard output. If more than a single file 217 is specified, each file is preceded by a header consisting of the 218 string {@code "==> XXX <=="} where {@code "XXX"} is the name 219 of the file. 220 * 221 * @param count The first {@code count} lines of each input file are 222 copied to standard output, starting from 1 (characters instead of 223 lines if the {@code -c} option is specified). Must be a non-negative 224 integer or an exception is thrown. If {@code count} is greater than 225 the number number of lines (characters) in the input, the 226 application will not error and send the whole file to the output. 227 * @param paths Path names of the input files to be filtered; wildcards * and ? are 228 supported; relative paths are resolved on the basis of the current 229 working directory. 230 * @return the generic type {@code <R>} defined by the implementing class; 231 * the command itself returns no value and writes its result to the 232 * standard output; see class level parameter comments for more 233 * details 234 */ 235 R head(long count, String... paths); 236 /** 237 * Reads the first {@code count} lines from each of the specified inputs 238 and writes them to the standard output. If more than a single input 239 is specified, each file is preceded by a header consisting of the 240 string {@code "==> XXX <=="} where {@code "XXX"} is the input's 241 string representation. 242 * 243 * @param count The first {@code count} lines of each input file are 244 copied to standard output, starting from 1 (characters instead of 245 lines if the {@code -c} option is specified). Must be a non-negative 246 integer or an exception is thrown. If {@code count} is greater than 247 the number number of lines (characters) in the input, the 248 application will not error and send the whole file to the output. 249 * @param inputs The inputs to be filtered. 250 * @return the generic type {@code <R>} defined by the implementing class; 251 * the command itself returns no value and writes its result to the 252 * standard output; see class level parameter comments for more 253 * details 254 */ 255 R head(long count, org.unix4j.io.Input... inputs); 256 /** 257 * Reads the first {@code count} lines or characters from each of the 258 specified files and writes them to the standard output. If more than 259 a single file is specified and the {@code -q} option is not 260 specified, each file is preceded by a header consisting of the 261 string {@code "==> XXX <=="} where {@code "XXX"} is the name 262 of the file. 263 * 264 * @param options Options for the head command. 265 * @param count The first {@code count} lines of each input file are 266 copied to standard output, starting from 1 (characters instead of 267 lines if the {@code -c} option is specified). Must be a non-negative 268 integer or an exception is thrown. If {@code count} is greater than 269 the number number of lines (characters) in the input, the 270 application will not error and send the whole file to the output. 271 * @param files The input files to be filtered; relative paths are not resolved (use 272 the string paths argument to enable relative path resolving based on 273 the current working directory). 274 * @return the generic type {@code <R>} defined by the implementing class; 275 * the command itself returns no value and writes its result to the 276 * standard output; see class level parameter comments for more 277 * details 278 */ 279 R head(HeadOptions options, long count, java.io.File... files); 280 /** 281 * Reads the first {@code count} lines or characters from each of the 282 specified files and writes them to the standard output. If more than 283 a single file is specified and the {@code -q} option is not 284 specified, each file is preceded by a header consisting of the 285 string {@code "==> XXX <=="} where {@code "XXX"} is the name 286 of the file. 287 * 288 * @param options Options for the head command. 289 * @param count The first {@code count} lines of each input file are 290 copied to standard output, starting from 1 (characters instead of 291 lines if the {@code -c} option is specified). Must be a non-negative 292 integer or an exception is thrown. If {@code count} is greater than 293 the number number of lines (characters) in the input, the 294 application will not error and send the whole file to the output. 295 * @param paths Path names of the input files to be filtered; wildcards * and ? are 296 supported; relative paths are resolved on the basis of the current 297 working directory. 298 * @return the generic type {@code <R>} defined by the implementing class; 299 * the command itself returns no value and writes its result to the 300 * standard output; see class level parameter comments for more 301 * details 302 */ 303 R head(HeadOptions options, long count, String... paths); 304 /** 305 * Reads the first {@code count} lines or characters from each of the 306 specified inputs and writes them to the standard output. If more than 307 a single input is specified and the {@code -q} option is not 308 specified, each file is preceded by a header consisting of the 309 string {@code "==> XXX <=="} where {@code "XXX"} is the input's 310 string representation. 311 * 312 * @param options Options for the head command. 313 * @param count The first {@code count} lines of each input file are 314 copied to standard output, starting from 1 (characters instead of 315 lines if the {@code -c} option is specified). Must be a non-negative 316 integer or an exception is thrown. If {@code count} is greater than 317 the number number of lines (characters) in the input, the 318 application will not error and send the whole file to the output. 319 * @param inputs The inputs to be filtered. 320 * @return the generic type {@code <R>} defined by the implementing class; 321 * the command itself returns no value and writes its result to the 322 * standard output; see class level parameter comments for more 323 * details 324 */ 325 R head(HeadOptions options, long count, org.unix4j.io.Input... inputs); 326 } 327 328 /** 329 * Options for the "head" command: {@link HeadOption#chars c}, {@link HeadOption#suppressHeaders q}. 330 * <p> 331 * <table> 332 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td> </td><td nowrap="nowrap">{@code --chars}</td><td> </td><td>The {@code count} argument is in units of characters instead of 333 lines. Starts from 1 and includes line ending characters.</td></tr> 334 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -q}</td><td> </td><td nowrap="nowrap">{@code --suppressHeaders}</td><td> </td><td>Suppresses printing of headers when multiple files are being 335 examined.</td></tr> 336 * </table> 337 */ 338 public static final HeadOptionSets Options = HeadOptionSets.INSTANCE; 339 340 /** 341 * Singleton {@link HeadFactory factory} instance for the "head" command. 342 */ 343 public static final HeadFactory Factory = HeadFactory.INSTANCE; 344 345 // no instances 346 private Head() { 347 super(); 348 } 349}