001package org.unix4j.unix; 002 003import org.unix4j.command.CommandInterface; 004 005import org.unix4j.unix.grep.GrepFactory; 006import org.unix4j.unix.grep.GrepOption; 007import org.unix4j.unix.grep.GrepOptions; 008import org.unix4j.unix.grep.GrepOptionSets; 009 010/** 011 * Non-instantiable module with inner types making up the <b>grep</b> command. 012 * <p> 013 * <b>NAME</b> 014 * <p> 015 * grep - print lines matching a pattern 016 * <p> 017 * <b>SYNOPSIS</b> 018 * <p> 019 * <table> 020 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <args>}</td></tr> 021 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <regexp>}</td></tr> 022 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <regexp> <files>}</td></tr> 023 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <regexp> <inputs>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern> <files>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern> <paths>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern> <inputs>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp>}</td></tr> 029 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern>}</td></tr> 030 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp> <files>}</td></tr> 031 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp> <paths>}</td></tr> 032 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp> <inputs>}</td></tr> 033 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern> <files>}</td></tr> 034 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern> <paths>}</td></tr> 035 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern> <inputs>}</td></tr> 036 * </table> 037 * <p> 038 * See {@link Interface} for the corresponding command signature methods. 039 * <p> 040 * <b>DESCRIPTION</b> 041 * <p> 042 * <p> The grep utility searches the input, selecting lines matching a pattern; the types of patterns are controlled by the options specified.</p><p> By default, an input line is selected if any pattern, treated as an entire regular expression matches any part of the line excluding the terminating newline character(s). By default, each selected input line is written to the output.</p><p> Regular expression matching is based on text lines. Since newline character(s) separate or terminate patterns, regular expressions cannot contain newline character(s). Similarly, since patterns are matched against individual lines (excluding the terminating newline character(s)) of the input, there is no way for a pattern to match newline character(s) found in the input.</p><p> Regular expressions used in this command must be based on the {@link java.util.regex.Pattern Java regular expression syntax}.</p> 043 * 044 * <p> 045 * <b>Options</b> 046 * <p> 047 * The following options are supported: 048 * <p> 049 * <table> 050 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -i}</td><td> </td><td nowrap="nowrap">{@code --ignoreCase}</td><td> </td><td>Match lines ignoring the case when comparing the strings, also known 051 from Unix with its acronym 'i'.</td></tr> 052 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -v}</td><td> </td><td nowrap="nowrap">{@code --invertMatch}</td><td> </td><td>Invert the match result, that is, a non-matching line is written to 053 the output and a matching line is not. This option is also known 054 from Unix with its acronym 'v'.</td></tr> 055 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -F}</td><td> </td><td nowrap="nowrap">{@code --fixedStrings}</td><td> </td><td>Use fixed-strings matching instead of regular expressions. This is 056 usually faster than the standard regexp version. 057 <p> 058 (This option is ignored if a {@code pattern} operand is specified 059 instead of the {@code regexp} string).</td></tr> 060 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td> </td><td nowrap="nowrap">{@code --lineNumber}</td><td> </td><td>Prefix each line of output with the line number within its input 061 file.</td></tr> 062 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td> </td><td nowrap="nowrap">{@code --count}</td><td> </td><td>Suppress normal output; instead print a count of matching lines for 063 each input file. With the {@code -v}, {@code --invertMatch} option, 064 count non-matching lines.</td></tr> 065 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td> </td><td nowrap="nowrap">{@code --matchingFiles}</td><td> </td><td>Suppress normal output; instead print the name of each input file 066 from which output would normally have been printed. The scanning 067 will stop on the first match.</td></tr> 068 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -x}</td><td> </td><td nowrap="nowrap">{@code --wholeLine}</td><td> </td><td>Select only those matches that exactly match the whole line 069 excluding the terminating line ending. 070 <p> 071 (This option is ignored if a {@code pattern} operand is specified 072 instead of the {@code regexp} string).</td></tr> 073 * </table> 074 * <p> 075 * <b>OPERANDS</b> 076 * <p> 077 * The following operands are supported: 078 * <p> 079 * <table> 080 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <regexp>}</td><td> : </td><td nowrap="nowrap">{@code String}</td><td> </td><td>Lines will be printed which match the given regular expression. The 081 {@code regexp} string is surrounded with ".*" on both sides unless 082 the {@code --wholeLine} option is specified. If the 083 {@code --fixedStrings} option is used, plain string comparison is 084 used instead of regular expression matching.</td></tr> 085 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <pattern>}</td><td> : </td><td nowrap="nowrap">{@code java.util.regex.Pattern}</td><td> </td><td>Lines will be printed which match the given pattern.</td></tr> 086 * <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 searched for the pattern; 087 wildcards * and ? are supported; relative paths are resolved on the 088 basis of the current working directory.</td></tr> 089 * <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 searched for the pattern; relative paths are 090 not resolved (use the string paths argument to enable relative path 091 resolving based on the current working directory).</td></tr> 092 * <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 searched for the pattern.</td></tr> 093 * <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. 094 Options can be specified by acronym (with a leading dash "-") or by 095 long name (with two leading dashes "--"). Operands other than the 096 default "--pattern" and "--paths" operands have to be prefixed with 097 the operand name (e.g. "--files" for subsequent file operand values).</td></tr> 098 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code <options>}</td><td> : </td><td nowrap="nowrap">{@code GrepOptions}</td><td> </td><td>The options defining the types of patterns and command behavior.</td></tr> 099 * </table> 100 */ 101public final class Grep { 102 /** 103 * The "grep" command name. 104 */ 105 public static final String NAME = "grep"; 106 107 /** 108 * Interface defining all method signatures for the "grep" command. 109 * 110 * @param <R> 111 * the generic return type for all command signature methods 112 * to support different implementor types; the methods of a 113 * command factory for instance returns a command instance; 114 * command builders can also implement this interface, but their 115 * methods return the builder itself enabling for chained method 116 * invocation to create joined commands 117 */ 118 public static interface Interface<R> extends CommandInterface<R> { 119 /** 120 * Filters the input lines from the standard input or the provided 121 input files and writes the matching lines to the standard output. A 122 line matches if it contains the given {@code "--regexp"} operand 123 value (default operand). 124 <p> 125 Options can be specified by acronym (with a leading dash "-") or by 126 long name (with two leading dashes "--"). Operands other than the 127 default "--regexp" and "--paths" operands have to be prefixed with 128 the operand name. 129 * 130 * @param args String arguments defining the options and operands for the command. 131 Options can be specified by acronym (with a leading dash "-") or by 132 long name (with two leading dashes "--"). Operands other than the 133 default "--pattern" and "--paths" operands have to be prefixed with 134 the operand name (e.g. "--files" for subsequent file operand values). 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 grep(String... args); 141 /** 142 * Filters the input lines from the standard input and writes the 143 matching lines to the standard output. A line matches if it contains 144 the given {@code regexp} using case-sensitive string comparison. 145 * 146 * @param regexp Lines will be printed which match the given regular expression. The 147 {@code regexp} string is surrounded with ".*" on both sides unless 148 the {@code --wholeLine} option is specified. If the 149 {@code --fixedStrings} option is used, plain string comparison is 150 used instead of regular expression matching. 151 * @return the generic type {@code <R>} defined by the implementing class; 152 * the command itself returns no value and writes its result to the 153 * standard output; see class level parameter comments for more 154 * details 155 */ 156 R grep(String regexp); 157 /** 158 * Filters the lines from the specified input files and writes the 159 matching lines to the standard output. Every line is matched against 160 the given {@code regexp} string using case-sensitive comparison. 161 Line endings are not relevant for the comparison. 162 * 163 * @param regexp Lines will be printed which match the given regular expression. The 164 {@code regexp} string is surrounded with ".*" on both sides unless 165 the {@code --wholeLine} option is specified. If the 166 {@code --fixedStrings} option is used, plain string comparison is 167 used instead of regular expression matching. 168 * @param files The input files to be searched for the pattern; relative paths are 169 not resolved (use the string paths argument to enable relative path 170 resolving based on the current working directory). 171 * @return the generic type {@code <R>} defined by the implementing class; 172 * the command itself returns no value and writes its result to the 173 * standard output; see class level parameter comments for more 174 * details 175 */ 176 R grep(String regexp, java.io.File... files); 177 /** 178 * Filters the lines from the specified inputs and writes the 179 matching lines to the standard output. Every line is matched against 180 the given {@code regexp} string using case-sensitive comparison. 181 Line endings are not relevant for the comparison. 182 * 183 * @param regexp Lines will be printed which match the given regular expression. The 184 {@code regexp} string is surrounded with ".*" on both sides unless 185 the {@code --wholeLine} option is specified. If the 186 {@code --fixedStrings} option is used, plain string comparison is 187 used instead of regular expression matching. 188 * @param inputs The inputs to be searched for the pattern. 189 * @return the generic type {@code <R>} defined by the implementing class; 190 * the command itself returns no value and writes its result to the 191 * standard output; see class level parameter comments for more 192 * details 193 */ 194 R grep(String regexp, org.unix4j.io.Input... inputs); 195 /** 196 * Filters the input lines from the standard input and writes the 197 matching lines to the standard output. Every line is matched against 198 the given regular expression {@code pattern} using case-sensitive 199 comparison. Line endings are not relevant for the comparison. 200 * 201 * @param pattern Lines will be printed which match the given pattern. 202 * @return the generic type {@code <R>} defined by the implementing class; 203 * the command itself returns no value and writes its result to the 204 * standard output; see class level parameter comments for more 205 * details 206 */ 207 R grep(java.util.regex.Pattern pattern); 208 /** 209 * Filters the lines from the specified input files and writes the 210 matching lines to the standard output. Every line is matched against 211 the given regular expression {@code pattern} using case-sensitive 212 comparison. Line endings are not relevant for the comparison. 213 * 214 * @param pattern Lines will be printed which match the given pattern. 215 * @param files The input files to be searched for the pattern; relative paths are 216 not resolved (use the string paths argument to enable relative path 217 resolving based on the current working directory). 218 * @return the generic type {@code <R>} defined by the implementing class; 219 * the command itself returns no value and writes its result to the 220 * standard output; see class level parameter comments for more 221 * details 222 */ 223 R grep(java.util.regex.Pattern pattern, java.io.File... files); 224 /** 225 * Filters the lines from the specified input files and writes the 226 matching lines to the standard output. Every line is matched against 227 the given regular expression {@code pattern} using case-sensitive 228 comparison. Line endings are not relevant for the comparison. 229 * 230 * @param pattern Lines will be printed which match the given pattern. 231 * @param paths Path names of the input files to be searched for the pattern; 232 wildcards * and ? are supported; relative paths are resolved on the 233 basis of the current working directory. 234 * @return the generic type {@code <R>} defined by the implementing class; 235 * the command itself returns no value and writes its result to the 236 * standard output; see class level parameter comments for more 237 * details 238 */ 239 R grep(java.util.regex.Pattern pattern, String... paths); 240 /** 241 * Filters the lines from the specified inputs and writes the 242 matching lines to the standard output. Every line is matched against 243 the given regular expression {@code pattern} using case-sensitive 244 comparison. Line endings are not relevant for the comparison. 245 * 246 * @param pattern Lines will be printed which match the given pattern. 247 * @param inputs The inputs to be searched for the pattern. 248 * @return the generic type {@code <R>} defined by the implementing class; 249 * the command itself returns no value and writes its result to the 250 * standard output; see class level parameter comments for more 251 * details 252 */ 253 R grep(java.util.regex.Pattern pattern, org.unix4j.io.Input... inputs); 254 /** 255 * Filters the input lines from the standard input and writes the 256 matching lines to the standard output. Every line is matched against 257 the given {@code regexp} string; the exact comparison rules are 258 defined by the specified matching {@code options}. 259 * 260 * @param options The options defining the types of patterns and command behavior. 261 * @param regexp Lines will be printed which match the given regular expression. The 262 {@code regexp} string is surrounded with ".*" on both sides unless 263 the {@code --wholeLine} option is specified. If the 264 {@code --fixedStrings} option is used, plain string comparison is 265 used instead of regular expression matching. 266 * @return the generic type {@code <R>} defined by the implementing class; 267 * the command itself returns no value and writes its result to the 268 * standard output; see class level parameter comments for more 269 * details 270 */ 271 R grep(GrepOptions options, String regexp); 272 /** 273 * Filters the input lines from the standard input and writes the 274 matching lines to the standard output. Every line is matched against 275 the given regular expression {@code pattern}; the exact comparison 276 rules are defined by the specified matching {@code options}. 277 * 278 * @param options The options defining the types of patterns and command behavior. 279 * @param pattern Lines will be printed which match the given pattern. 280 * @return the generic type {@code <R>} defined by the implementing class; 281 * the command itself returns no value and writes its result to the 282 * standard output; see class level parameter comments for more 283 * details 284 */ 285 R grep(GrepOptions options, java.util.regex.Pattern pattern); 286 /** 287 * Filters the input lines from the specified input files and writes 288 the matching lines to the standard output. Every line is matched 289 against the given {@code regexp} string; the exact comparison rules 290 are defined by the specified matching {@code options}. 291 * 292 * @param options The options defining the types of patterns and command behavior. 293 * @param regexp Lines will be printed which match the given regular expression. The 294 {@code regexp} string is surrounded with ".*" on both sides unless 295 the {@code --wholeLine} option is specified. If the 296 {@code --fixedStrings} option is used, plain string comparison is 297 used instead of regular expression matching. 298 * @param files The input files to be searched for the pattern; relative paths are 299 not resolved (use the string paths argument to enable relative path 300 resolving based on the current working directory). 301 * @return the generic type {@code <R>} defined by the implementing class; 302 * the command itself returns no value and writes its result to the 303 * standard output; see class level parameter comments for more 304 * details 305 */ 306 R grep(GrepOptions options, String regexp, java.io.File... files); 307 /** 308 * Filters the input lines from the specified input files and writes 309 the matching lines to the standard output. Every line is matched 310 against the given {@code regexp} string; the exact comparison rules 311 are defined by the specified matching {@code options}. 312 * 313 * @param options The options defining the types of patterns and command behavior. 314 * @param regexp Lines will be printed which match the given regular expression. The 315 {@code regexp} string is surrounded with ".*" on both sides unless 316 the {@code --wholeLine} option is specified. If the 317 {@code --fixedStrings} option is used, plain string comparison is 318 used instead of regular expression matching. 319 * @param paths Path names of the input files to be searched for the pattern; 320 wildcards * and ? are supported; relative paths are resolved on the 321 basis of the current working directory. 322 * @return the generic type {@code <R>} defined by the implementing class; 323 * the command itself returns no value and writes its result to the 324 * standard output; see class level parameter comments for more 325 * details 326 */ 327 R grep(GrepOptions options, String regexp, String... paths); 328 /** 329 * Filters the input lines from the specified inputs and writes 330 the matching lines to the standard output. Every line is matched 331 against the given {@code regexp} string; the exact comparison rules 332 are defined by the specified matching {@code options}. 333 * 334 * @param options The options defining the types of patterns and command behavior. 335 * @param regexp Lines will be printed which match the given regular expression. The 336 {@code regexp} string is surrounded with ".*" on both sides unless 337 the {@code --wholeLine} option is specified. If the 338 {@code --fixedStrings} option is used, plain string comparison is 339 used instead of regular expression matching. 340 * @param inputs The inputs to be searched for the pattern. 341 * @return the generic type {@code <R>} defined by the implementing class; 342 * the command itself returns no value and writes its result to the 343 * standard output; see class level parameter comments for more 344 * details 345 */ 346 R grep(GrepOptions options, String regexp, org.unix4j.io.Input... inputs); 347 /** 348 * Filters the input lines from the specified input files and writes 349 the matching lines to the standard output. Every line is matched 350 against the given regular expression {@code pattern}; the exact 351 comparison rules are defined by the specified matching 352 {@code options}. 353 * 354 * @param options The options defining the types of patterns and command behavior. 355 * @param pattern Lines will be printed which match the given pattern. 356 * @param files The input files to be searched for the pattern; relative paths are 357 not resolved (use the string paths argument to enable relative path 358 resolving based on the current working directory). 359 * @return the generic type {@code <R>} defined by the implementing class; 360 * the command itself returns no value and writes its result to the 361 * standard output; see class level parameter comments for more 362 * details 363 */ 364 R grep(GrepOptions options, java.util.regex.Pattern pattern, java.io.File... files); 365 /** 366 * Filters the input lines from the specified input files and writes 367 the matching lines to the standard output. Every line is matched 368 against the given regular expression {@code pattern}; the exact 369 comparison rules are defined by the specified matching 370 {@code options}. 371 * 372 * @param options The options defining the types of patterns and command behavior. 373 * @param pattern Lines will be printed which match the given pattern. 374 * @param paths Path names of the input files to be searched for the pattern; 375 wildcards * and ? are supported; relative paths are resolved on the 376 basis of the current working directory. 377 * @return the generic type {@code <R>} defined by the implementing class; 378 * the command itself returns no value and writes its result to the 379 * standard output; see class level parameter comments for more 380 * details 381 */ 382 R grep(GrepOptions options, java.util.regex.Pattern pattern, String... paths); 383 /** 384 * Filters the input lines from the specified inputs and writes 385 the matching lines to the standard output. Every line is matched 386 against the given regular expression {@code pattern}; the exact 387 comparison rules are defined by the specified matching 388 {@code options}. 389 * 390 * @param options The options defining the types of patterns and command behavior. 391 * @param pattern Lines will be printed which match the given pattern. 392 * @param inputs The inputs to be searched for the pattern. 393 * @return the generic type {@code <R>} defined by the implementing class; 394 * the command itself returns no value and writes its result to the 395 * standard output; see class level parameter comments for more 396 * details 397 */ 398 R grep(GrepOptions options, java.util.regex.Pattern pattern, org.unix4j.io.Input... inputs); 399 } 400 401 /** 402 * Options for the "grep" command: {@link GrepOption#ignoreCase i}, {@link GrepOption#invertMatch v}, {@link GrepOption#fixedStrings F}, {@link GrepOption#lineNumber n}, {@link GrepOption#count c}, {@link GrepOption#matchingFiles l}, {@link GrepOption#wholeLine x}. 403 * <p> 404 * <table> 405 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -i}</td><td> </td><td nowrap="nowrap">{@code --ignoreCase}</td><td> </td><td>Match lines ignoring the case when comparing the strings, also known 406 from Unix with its acronym 'i'.</td></tr> 407 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -v}</td><td> </td><td nowrap="nowrap">{@code --invertMatch}</td><td> </td><td>Invert the match result, that is, a non-matching line is written to 408 the output and a matching line is not. This option is also known 409 from Unix with its acronym 'v'.</td></tr> 410 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -F}</td><td> </td><td nowrap="nowrap">{@code --fixedStrings}</td><td> </td><td>Use fixed-strings matching instead of regular expressions. This is 411 usually faster than the standard regexp version. 412 <p> 413 (This option is ignored if a {@code pattern} operand is specified 414 instead of the {@code regexp} string).</td></tr> 415 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -n}</td><td> </td><td nowrap="nowrap">{@code --lineNumber}</td><td> </td><td>Prefix each line of output with the line number within its input 416 file.</td></tr> 417 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -c}</td><td> </td><td nowrap="nowrap">{@code --count}</td><td> </td><td>Suppress normal output; instead print a count of matching lines for 418 each input file. With the {@code -v}, {@code --invertMatch} option, 419 count non-matching lines.</td></tr> 420 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -l}</td><td> </td><td nowrap="nowrap">{@code --matchingFiles}</td><td> </td><td>Suppress normal output; instead print the name of each input file 421 from which output would normally have been printed. The scanning 422 will stop on the first match.</td></tr> 423 * <tr valign="top"><td width="10px"></td><td nowrap="nowrap">{@code -x}</td><td> </td><td nowrap="nowrap">{@code --wholeLine}</td><td> </td><td>Select only those matches that exactly match the whole line 424 excluding the terminating line ending. 425 <p> 426 (This option is ignored if a {@code pattern} operand is specified 427 instead of the {@code regexp} string).</td></tr> 428 * </table> 429 */ 430 public static final GrepOptionSets Options = GrepOptionSets.INSTANCE; 431 432 /** 433 * Singleton {@link GrepFactory factory} instance for the "grep" command. 434 */ 435 public static final GrepFactory Factory = GrepFactory.INSTANCE; 436 437 // no instances 438 private Grep() { 439 super(); 440 } 441}