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 <count> <files>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head <count> <paths>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count> <files>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code head [-cq] <count> <paths>}</td></tr> 029 * </table> 030 * <p> 031 * See {@link Interface} for the corresponding command signature methods. 032 * <p> 033 * <b>DESCRIPTION</b> 034 * <p> 035 * <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> 036 * 037 * <p> 038 * <b>Options</b> 039 * <p> 040 * The following options are supported: 041 * <p> 042 * <table> 043 * <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 044 lines. Starts from 1 and includes line ending characters.</td></tr> 045 * <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 046 examined.</td></tr> 047 * </table> 048 * <p> 049 * <b>OPERANDS</b> 050 * <p> 051 * The following operands are supported: 052 * <p> 053 * <table> 054 * <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 055 copied to standard output, starting from 1 (characters instead of 056 lines if the {@code -c} option is specified). Must be a non-negative 057 integer or an exception is thrown. If {@code count} is greater than 058 the number number of lines (characters) in the input, the 059 application will not error and send the whole file to the output.</td></tr> 060 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <paths>}</td><td> : </td><td nowrap="nowrap">{@code String...}</td><td> </td><td>Pathnames of the input files to be filtered; wildcards * and ? are 061 supported; relative paths are resolved on the basis of the current 062 working directory.</td></tr> 063 * <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 064 the string paths argument to enable relative path resolving based on 065 the current working directory).</td></tr> 066 * <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. 067 Options can be specified by acronym (with a leading dash "-") or by 068 long name (with two leading dashes "--"). Operands other than the 069 default "--paths" operand have to be prefixed with the operand 070 name (e.g. "--count" for a subsequent count operand value).</td></tr> 071 * <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> 072 * </table> 073 */ 074public final class Head { 075 /** 076 * The "head" command name. 077 */ 078 public static final String NAME = "head"; 079 080 /** 081 * Interface defining all method signatures for the "head" command. 082 * 083 * @param <R> 084 * the generic return type for all command signature methods 085 * to support different implementor types; the methods of a 086 * command factory for instance returns a command instance; 087 * command builders can also implement this interface, but their 088 * methods return the builder itself enabling for chained method 089 * invocation to create joined commands 090 */ 091 public static interface Interface<R> extends CommandInterface<R> { 092 /** 093 * Reads the first 10 lines from the standard input and writes them to 094 the standard output. 095 * 096 * @return the generic type {@code <R>} defined by the implementing class; 097 * the command itself returns no value and writes its result to the 098 * standard output; see class level parameter comments for more 099 * details 100 */ 101 R head(); 102 /** 103 * Reads the first n lines from each of the files specified and writes 104 them to the standard output. If more than a single file is 105 specified, each file is preceded by a header consisting of the 106 string {@code "==> XXX <=="} where {@code "XXX"} is the name 107 of the file. 108<p> 109 Options can be specified by acronym (with a leading dash "-") or by 110 long name (with two leading dashes "--"). Operands other than the 111 default "--paths" operand have to be prefixed with the operand 112 name. 113 * 114 * @param args String arguments defining the options and operands for the command. 115 Options can be specified by acronym (with a leading dash "-") or by 116 long name (with two leading dashes "--"). Operands other than the 117 default "--paths" operand have to be prefixed with the operand 118 name (e.g. "--count" for a subsequent count operand value). 119 * @return the generic type {@code <R>} defined by the implementing class; 120 * the command itself returns no value and writes its result to the 121 * standard output; see class level parameter comments for more 122 * details 123 */ 124 R head(String... args); 125 /** 126 * Reads the first {@code count} lines from the standard input and 127 writes them to the standard output. 128 * 129 * @param count The first {@code count} lines of each input file are 130 copied to standard output, starting from 1 (characters instead of 131 lines if the {@code -c} option is specified). Must be a non-negative 132 integer or an exception is thrown. If {@code count} is greater than 133 the number number of lines (characters) in the input, the 134 application will not error and send the whole file to the output. 135 * @return the generic type {@code <R>} defined by the implementing class; 136 * the command itself returns no value and writes its result to the 137 * standard output; see class level parameter comments for more 138 * details 139 */ 140 R head(long count); 141 /** 142 * Reads the first {@code count} lines or characters from the standard 143 input and writes them to the standard output. 144 * 145 * @param options Options for the head command. 146 * @param count The first {@code count} lines of each input file are 147 copied to standard output, starting from 1 (characters instead of 148 lines if the {@code -c} option is specified). Must be a non-negative 149 integer or an exception is thrown. If {@code count} is greater than 150 the number number of lines (characters) in the input, the 151 application will not error and send the whole file to the output. 152 * @return the generic type {@code <R>} defined by the implementing class; 153 * the command itself returns no value and writes its result to the 154 * standard output; see class level parameter comments for more 155 * details 156 */ 157 R head(HeadOptions options, long count); 158 /** 159 * Reads the first 10 lines from each of the specified files and writes 160 them to the standard output. If more than a single file is 161 specified, each file is preceded by a header consisting of the 162 string {@code "==> XXX <=="} where {@code "XXX"} is the name 163 of the file. 164 * 165 * @param files The input files to be filtered; relative paths are not resolved (use 166 the string paths argument to enable relative path resolving based on 167 the current working directory). 168 * @return the generic type {@code <R>} defined by the implementing class; 169 * the command itself returns no value and writes its result to the 170 * standard output; see class level parameter comments for more 171 * details 172 */ 173 R head(java.io.File... files); 174 /** 175 * Reads the first {@code count} lines from each of the specified files 176 and writes them to the standard output. If more than a single file 177 is specified, each file is preceded by a header consisting of the 178 string {@code "==> XXX <=="} where {@code "XXX"} is the name 179 of the file. 180 * 181 * @param count The first {@code count} lines of each input file are 182 copied to standard output, starting from 1 (characters instead of 183 lines if the {@code -c} option is specified). Must be a non-negative 184 integer or an exception is thrown. If {@code count} is greater than 185 the number number of lines (characters) in the input, the 186 application will not error and send the whole file to the output. 187 * @param files The input files to be filtered; relative paths are not resolved (use 188 the string paths argument to enable relative path resolving based on 189 the current working directory). 190 * @return the generic type {@code <R>} defined by the implementing class; 191 * the command itself returns no value and writes its result to the 192 * standard output; see class level parameter comments for more 193 * details 194 */ 195 R head(long count, java.io.File... files); 196 /** 197 * Reads the first {@code count} lines from each of the specified files 198 and writes them to the standard output. If more than a single file 199 is specified, each file is preceded by a header consisting of the 200 string {@code "==> XXX <=="} where {@code "XXX"} is the name 201 of the file. 202 * 203 * @param count The first {@code count} lines of each input file are 204 copied to standard output, starting from 1 (characters instead of 205 lines if the {@code -c} option is specified). Must be a non-negative 206 integer or an exception is thrown. If {@code count} is greater than 207 the number number of lines (characters) in the input, the 208 application will not error and send the whole file to the output. 209 * @param paths Pathnames of the input files to be filtered; wildcards * and ? are 210 supported; relative paths are resolved on the basis of the current 211 working directory. 212 * @return the generic type {@code <R>} defined by the implementing class; 213 * the command itself returns no value and writes its result to the 214 * standard output; see class level parameter comments for more 215 * details 216 */ 217 R head(long count, String... paths); 218 /** 219 * Reads the first {@code count} lines or characters from each of the 220 specified files and writes them to the standard output. If more than 221 a single file is specified and the {@code -q} option is not 222 specified, each file is preceded by a header consisting of the 223 string {@code "==> XXX <=="} where {@code "XXX"} is the name 224 of the file. 225 * 226 * @param options Options for the head command. 227 * @param count The first {@code count} lines of each input file are 228 copied to standard output, starting from 1 (characters instead of 229 lines if the {@code -c} option is specified). Must be a non-negative 230 integer or an exception is thrown. If {@code count} is greater than 231 the number number of lines (characters) in the input, the 232 application will not error and send the whole file to the output. 233 * @param files The input files to be filtered; relative paths are not resolved (use 234 the string paths argument to enable relative path resolving based on 235 the current working directory). 236 * @return the generic type {@code <R>} defined by the implementing class; 237 * the command itself returns no value and writes its result to the 238 * standard output; see class level parameter comments for more 239 * details 240 */ 241 R head(HeadOptions options, long count, java.io.File... files); 242 /** 243 * Reads the first {@code count} lines or characters from each of the 244 specified files and writes them to the standard output. If more than 245 a single file is specified and the {@code -q} option is not 246 specified, each file is preceded by a header consisting of the 247 string {@code "==> XXX <=="} where {@code "XXX"} is the name 248 of the file. 249 * 250 * @param options Options for the head command. 251 * @param count The first {@code count} lines of each input file are 252 copied to standard output, starting from 1 (characters instead of 253 lines if the {@code -c} option is specified). Must be a non-negative 254 integer or an exception is thrown. If {@code count} is greater than 255 the number number of lines (characters) in the input, the 256 application will not error and send the whole file to the output. 257 * @param paths Pathnames of the input files to be filtered; wildcards * and ? are 258 supported; relative paths are resolved on the basis of the current 259 working directory. 260 * @return the generic type {@code <R>} defined by the implementing class; 261 * the command itself returns no value and writes its result to the 262 * standard output; see class level parameter comments for more 263 * details 264 */ 265 R head(HeadOptions options, long count, String... paths); 266 } 267 268 /** 269 * Options for the "head" command: {@link HeadOption#chars c}, {@link HeadOption#suppressHeaders q}. 270 * <p> 271 * <table> 272 * <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 273 lines. Starts from 1 and includes line ending characters.</td></tr> 274 * <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 275 examined.</td></tr> 276 * </table> 277 */ 278 public static final HeadOptionSets Options = HeadOptionSets.INSTANCE; 279 280 /** 281 * Singleton {@link HeadFactory factory} instance for the "head" command. 282 */ 283 public static final HeadFactory Factory = HeadFactory.INSTANCE; 284 285 // no instances 286 private Head() { 287 super(); 288 } 289}