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 <pattern>}</td></tr> 024 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern> <files>}</td></tr> 025 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep <pattern> <paths>}</td></tr> 026 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp>}</td></tr> 027 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern>}</td></tr> 028 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp> <files>}</td></tr> 029 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <regexp> <paths>}</td></tr> 030 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern> <files>}</td></tr> 031 * <tr><td width="10px"></td><td nowrap="nowrap">{@code grep [-ivFnclx] <pattern> <paths>}</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> 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> 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 -i}</td><td> </td><td nowrap="nowrap">{@code --ignoreCase}</td><td> </td><td>Match lines ignoring the case when comparing the strings, also known 047 from Unix with its acronym 'i'.</td></tr> 048 * <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 049 the output and a matching line is not. This option is also known 050 from Unix with its acronym 'v'.</td></tr> 051 * <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 052 usually faster than the standard regexp version. 053 <p> 054 (This option is ignored if a {@code pattern} operand is specified 055 instead of the {@code regexp} string).</td></tr> 056 * <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 057 file.</td></tr> 058 * <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 059 each input file. With the {@code -v}, {@code --invertMatch} option, 060 count non-matching lines.</td></tr> 061 * <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 062 from which output would normally have been printed. The scanning 063 will stop on the first match.</td></tr> 064 * <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 065 excluding the terminating line ending. 066 <p> 067 (This option is ignored if a {@code pattern} operand is specified 068 instead of the {@code regexp} string).</td></tr> 069 * </table> 070 * <p> 071 * <b>OPERANDS</b> 072 * <p> 073 * The following operands are supported: 074 * <p> 075 * <table> 076 * <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 077 {@code regexp} string is surrounded with ".*" on both sides unless 078 the {@code --wholeLine} option is specified. If the 079 {@code --fixedStrings} option is used, plain string comparison is 080 used instead of regular expression matching.</td></tr> 081 * <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> 082 * <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 searched for the pattern; 083 wildcards * and ? are supported; relative paths are resolved on the 084 basis of the current working directory.</td></tr> 085 * <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 086 not resolved (use the string paths argument to enable relative path 087 resolving based on the current working directory).</td></tr> 088 * <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. 089 Options can be specified by acronym (with a leading dash "-") or by 090 long name (with two leading dashes "--"). Operands other than the 091 default "--pattern" and "--paths" operands have to be prefixed with 092 the operand name (e.g. "--files" for subsequent file operand values).</td></tr> 093 * <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> 094 * </table> 095 */ 096public final class Grep { 097 /** 098 * The "grep" command name. 099 */ 100 public static final String NAME = "grep"; 101 102 /** 103 * Interface defining all method signatures for the "grep" command. 104 * 105 * @param <R> 106 * the generic return type for all command signature methods 107 * to support different implementor types; the methods of a 108 * command factory for instance returns a command instance; 109 * command builders can also implement this interface, but their 110 * methods return the builder itself enabling for chained method 111 * invocation to create joined commands 112 */ 113 public static interface Interface<R> extends CommandInterface<R> { 114 /** 115 * Filters the input lines from the standard input or the provided 116 input files and writes the matching lines to the standard output. A 117 line matches if it contains the given {@code "--regexp"} operand 118 value (default operand). 119 <p> 120 Options can be specified by acronym (with a leading dash "-") or by 121 long name (with two leading dashes "--"). Operands other than the 122 default "--regexp" and "--paths" operands have to be prefixed with 123 the operand name. 124 * 125 * @param args String arguments defining the options and operands for the command. 126 Options can be specified by acronym (with a leading dash "-") or by 127 long name (with two leading dashes "--"). Operands other than the 128 default "--pattern" and "--paths" operands have to be prefixed with 129 the operand name (e.g. "--files" for subsequent file operand values). 130 * @return the generic type {@code <R>} defined by the implementing class; 131 * the command itself returns no value and writes its result to the 132 * standard output; see class level parameter comments for more 133 * details 134 */ 135 R grep(String... args); 136 /** 137 * Filters the input lines from the standard input and writes the 138 matching lines to the standard output. A line matches if it contains 139 the given {@code regexp} using case-sensitive string comparison. 140 * 141 * @param regexp Lines will be printed which match the given regular expression. The 142 {@code regexp} string is surrounded with ".*" on both sides unless 143 the {@code --wholeLine} option is specified. If the 144 {@code --fixedStrings} option is used, plain string comparison is 145 used instead of regular expression matching. 146 * @return the generic type {@code <R>} defined by the implementing class; 147 * the command itself returns no value and writes its result to the 148 * standard output; see class level parameter comments for more 149 * details 150 */ 151 R grep(String regexp); 152 /** 153 * Filters the lines from the specified input files and writes the 154 matching lines to the standard output. Every line is matched against 155 the given {@code regexp} string using case-sensitive comparison. 156 Line endings are not relevant for the comparison. 157 * 158 * @param regexp Lines will be printed which match the given regular expression. The 159 {@code regexp} string is surrounded with ".*" on both sides unless 160 the {@code --wholeLine} option is specified. If the 161 {@code --fixedStrings} option is used, plain string comparison is 162 used instead of regular expression matching. 163 * @param files The input files to be searched for the pattern; relative paths are 164 not resolved (use the string paths argument to enable relative path 165 resolving based on the current working directory). 166 * @return the generic type {@code <R>} defined by the implementing class; 167 * the command itself returns no value and writes its result to the 168 * standard output; see class level parameter comments for more 169 * details 170 */ 171 R grep(String regexp, java.io.File... files); 172 /** 173 * Filters the input lines from the standard input and writes the 174 matching lines to the standard output. Every line is matched against 175 the given regular expression {@code pattern} using case-sensitive 176 comparison. Line endings are not relevant for the comparison. 177 * 178 * @param pattern Lines will be printed which match the given pattern. 179 * @return the generic type {@code <R>} defined by the implementing class; 180 * the command itself returns no value and writes its result to the 181 * standard output; see class level parameter comments for more 182 * details 183 */ 184 R grep(java.util.regex.Pattern pattern); 185 /** 186 * Filters the lines from the specified input files and writes the 187 matching lines to the standard output. Every line is matched against 188 the given regular expression {@code pattern} using case-sensitive 189 comparison. Line endings are not relevant for the comparison. 190 * 191 * @param pattern Lines will be printed which match the given pattern. 192 * @param files The input files to be searched for the pattern; relative paths are 193 not resolved (use the string paths argument to enable relative path 194 resolving based on the current working directory). 195 * @return the generic type {@code <R>} defined by the implementing class; 196 * the command itself returns no value and writes its result to the 197 * standard output; see class level parameter comments for more 198 * details 199 */ 200 R grep(java.util.regex.Pattern pattern, java.io.File... files); 201 /** 202 * Filters the lines from the specified input files and writes the 203 matching lines to the standard output. Every line is matched against 204 the given regular expression {@code pattern} using case-sensitive 205 comparison. Line endings are not relevant for the comparison. 206 * 207 * @param pattern Lines will be printed which match the given pattern. 208 * @param paths Pathnames of the input files to be searched for the pattern; 209 wildcards * and ? are supported; relative paths are resolved on the 210 basis of the current working directory. 211 * @return the generic type {@code <R>} defined by the implementing class; 212 * the command itself returns no value and writes its result to the 213 * standard output; see class level parameter comments for more 214 * details 215 */ 216 R grep(java.util.regex.Pattern pattern, String... paths); 217 /** 218 * Filters the input lines from the standard input and writes the 219 matching lines to the standard output. Every line is matched against 220 the given {@code regexp} string; the exact comparison rules are 221 defined by the specified matching {@code options}. 222 * 223 * @param options The options defining the types of patterns and command behavior. 224 * @param regexp Lines will be printed which match the given regular expression. The 225 {@code regexp} string is surrounded with ".*" on both sides unless 226 the {@code --wholeLine} option is specified. If the 227 {@code --fixedStrings} option is used, plain string comparison is 228 used instead of regular expression matching. 229 * @return the generic type {@code <R>} defined by the implementing class; 230 * the command itself returns no value and writes its result to the 231 * standard output; see class level parameter comments for more 232 * details 233 */ 234 R grep(GrepOptions options, String regexp); 235 /** 236 * Filters the input lines from the standard input and writes the 237 matching lines to the standard output. Every line is matched against 238 the given regular expression {@code pattern}; the exact comparison 239 rules are defined by the specified matching {@code options}. 240 * 241 * @param options The options defining the types of patterns and command behavior. 242 * @param pattern Lines will be printed which match the given pattern. 243 * @return the generic type {@code <R>} defined by the implementing class; 244 * the command itself returns no value and writes its result to the 245 * standard output; see class level parameter comments for more 246 * details 247 */ 248 R grep(GrepOptions options, java.util.regex.Pattern pattern); 249 /** 250 * Filters the input lines from the specified input files and writes 251 the matching lines to the standard output. Every line is matched 252 against the given {@code regexp} string; the exact comparison rules 253 are defined by the specified matching {@code options}. 254 * 255 * @param options The options defining the types of patterns and command behavior. 256 * @param regexp Lines will be printed which match the given regular expression. The 257 {@code regexp} string is surrounded with ".*" on both sides unless 258 the {@code --wholeLine} option is specified. If the 259 {@code --fixedStrings} option is used, plain string comparison is 260 used instead of regular expression matching. 261 * @param files The input files to be searched for the pattern; relative paths are 262 not resolved (use the string paths argument to enable relative path 263 resolving based on the current working directory). 264 * @return the generic type {@code <R>} defined by the implementing class; 265 * the command itself returns no value and writes its result to the 266 * standard output; see class level parameter comments for more 267 * details 268 */ 269 R grep(GrepOptions options, String regexp, java.io.File... files); 270 /** 271 * Filters the input lines from the specified input files and writes 272 the matching lines to the standard output. Every line is matched 273 against the given {@code regexp} string; the exact comparison rules 274 are defined by the specified matching {@code options}. 275 * 276 * @param options The options defining the types of patterns and command behavior. 277 * @param regexp Lines will be printed which match the given regular expression. The 278 {@code regexp} string is surrounded with ".*" on both sides unless 279 the {@code --wholeLine} option is specified. If the 280 {@code --fixedStrings} option is used, plain string comparison is 281 used instead of regular expression matching. 282 * @param paths Pathnames of the input files to be searched for the pattern; 283 wildcards * and ? are supported; relative paths are resolved on the 284 basis of the current working directory. 285 * @return the generic type {@code <R>} defined by the implementing class; 286 * the command itself returns no value and writes its result to the 287 * standard output; see class level parameter comments for more 288 * details 289 */ 290 R grep(GrepOptions options, String regexp, String... paths); 291 /** 292 * Filters the input lines from the specified input files and writes 293 the matching lines to the standard output. Every line is matched 294 against the given regular expression {@code pattern}; the exact 295 comparison rules are defined by the specified matching 296 {@code options}. 297 * 298 * @param options The options defining the types of patterns and command behavior. 299 * @param pattern Lines will be printed which match the given pattern. 300 * @param files The input files to be searched for the pattern; relative paths are 301 not resolved (use the string paths argument to enable relative path 302 resolving based on the current working directory). 303 * @return the generic type {@code <R>} defined by the implementing class; 304 * the command itself returns no value and writes its result to the 305 * standard output; see class level parameter comments for more 306 * details 307 */ 308 R grep(GrepOptions options, java.util.regex.Pattern pattern, java.io.File... files); 309 /** 310 * Filters the input lines from the specified input files and writes 311 the matching lines to the standard output. Every line is matched 312 against the given regular expression {@code pattern}; the exact 313 comparison rules are defined by the specified matching 314 {@code options}. 315 * 316 * @param options The options defining the types of patterns and command behavior. 317 * @param pattern Lines will be printed which match the given pattern. 318 * @param paths Pathnames of the input files to be searched for the pattern; 319 wildcards * and ? are supported; relative paths are resolved on the 320 basis of the current working directory. 321 * @return the generic type {@code <R>} defined by the implementing class; 322 * the command itself returns no value and writes its result to the 323 * standard output; see class level parameter comments for more 324 * details 325 */ 326 R grep(GrepOptions options, java.util.regex.Pattern pattern, String... paths); 327 } 328 329 /** 330 * 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}. 331 * <p> 332 * <table> 333 * <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 334 from Unix with its acronym 'i'.</td></tr> 335 * <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 336 the output and a matching line is not. This option is also known 337 from Unix with its acronym 'v'.</td></tr> 338 * <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 339 usually faster than the standard regexp version. 340 <p> 341 (This option is ignored if a {@code pattern} operand is specified 342 instead of the {@code regexp} string).</td></tr> 343 * <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 344 file.</td></tr> 345 * <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 346 each input file. With the {@code -v}, {@code --invertMatch} option, 347 count non-matching lines.</td></tr> 348 * <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 349 from which output would normally have been printed. The scanning 350 will stop on the first match.</td></tr> 351 * <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 352 excluding the terminating line ending. 353 <p> 354 (This option is ignored if a {@code pattern} operand is specified 355 instead of the {@code regexp} string).</td></tr> 356 * </table> 357 */ 358 public static final GrepOptionSets Options = GrepOptionSets.INSTANCE; 359 360 /** 361 * Singleton {@link GrepFactory factory} instance for the "grep" command. 362 */ 363 public static final GrepFactory Factory = GrepFactory.INSTANCE; 364 365 // no instances 366 private Grep() { 367 super(); 368 } 369}