org.unix4j.unix.Grep Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of unix4j-command Show documentation

There is a newer version: 0.6

package org.unix4j.unix;

import org.unix4j.command.CommandInterface;

import org.unix4j.unix.grep.GrepFactory;
import org.unix4j.unix.grep.GrepOption;
import org.unix4j.unix.grep.GrepOptions;
import org.unix4j.unix.grep.GrepOptionSets;

/**
 * Non-instantiable module with inner types making up the grep command.
 * 
 * NAME
 * 

 * grep - print lines matching a pattern 
 * 

 * SYNOPSIS
 * 

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * {@code grep }
{@code grep }
{@code grep  }
{@code grep }
{@code grep  }
{@code grep  }
{@code grep [-ivFnclx] }
{@code grep [-ivFnclx] }
{@code grep [-ivFnclx]  }
{@code grep [-ivFnclx]  }
{@code grep [-ivFnclx]  }
{@code grep [-ivFnclx]  }
 * 
 * See {@link Interface} for the corresponding command signature methods.
 * 

 * DESCRIPTION
 * 

 * 
	The grep utility searches the input, selecting lines matching a pattern; 	the types of patterns are controlled by the options specified.
	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.
	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.
	Regular expressions used in this command must be based on the 	{@link java.util.regex.Pattern Java regular expression syntax}.
 * 
 * 
 * Options
 * 

 * The following options are supported:
 * 

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * {@code -i}    {@code --ignoreCase}   Match lines ignoring the case when comparing the strings, also known
			from Unix with its acronym 'i'.
{@code -v}    {@code --invertMatch}   Invert the match result, that is, a non-matching line is written to
			the output and a matching line is not. This option is also known 
			from Unix with its acronym 'v'.
{@code -F}    {@code --fixedStrings}   Use fixed-strings matching instead of regular expressions. This is
			usually faster than the standard regexp version.
			
			(This option is ignored if a {@code pattern} operand is specified
			instead of the {@code regexp} string).
{@code -n}    {@code --lineNumber}   Prefix each line of output with the line number within its input
			file.
{@code -c}    {@code --count}   Suppress normal output; instead print a count of matching lines for
			each input file. With the {@code -v}, {@code --invertMatch} option,
			count non-matching lines.
{@code -l}    {@code --matchingFiles}   Suppress normal output; instead print the name of each input file
			from which output would normally have been printed. The scanning
			will stop on the first match.
{@code -x}    {@code --wholeLine}   Select only those matches that exactly match the whole line
			excluding the terminating line ending.
			
			(This option is ignored if a {@code pattern} operand is specified
			instead of the {@code regexp} string).
 * 
 * OPERANDS
 * 

 * The following operands are supported:
 * 

 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * {@code }  :  {@code String}   Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
{@code }  :  {@code java.util.regex.Pattern}   Lines will be printed which match the given pattern.
{@code }  :  {@code String...}   Pathnames of the input files to be searched for the pattern;
			wildcards * and ? are supported; relative paths are resolved on the
            basis of the current working directory.
{@code }  :  {@code java.io.File...}   The input files to be searched for the pattern; relative paths are 
			not resolved (use the string paths argument to enable relative path 
			resolving based on the current working directory).
{@code }  :  {@code String...}   String arguments defining the options and operands for the command. 
			Options can be specified by acronym (with a leading dash "-") or by 
			long name (with two leading dashes "--"). Operands other than the
			default "--pattern" and "--paths" operands have to be prefixed with
			the operand name (e.g. "--files" for subsequent file operand values).
{@code }  :  {@code GrepOptions}   The options defining the types of patterns and command behavior.
 */
public final class Grep {
	/**
	 * The "grep" command name.
	 */
	public static final String NAME = "grep";

	/**
	 * Interface defining all method signatures for the "grep" command.
	 * 
	 * @param 
	 *            the generic return type for all command signature methods
	 *            to support different implementor types; the methods of a 
	 *            command factory for instance returns a command instance; 
	 *            command builders can also implement this interface, but their
	 *            methods return the builder itself enabling for chained method
	 *            invocation to create joined commands
	 */
	public static interface Interface extends CommandInterface {
		/**
		 * Filters the input lines from the standard input or the provided 
			input files and writes the matching lines to the standard output. A 
			line matches if it contains the given {@code "--regexp"} operand
			value (default operand).
			
			Options can be specified by acronym (with a leading dash "-") or by 
			long name (with two leading dashes "--"). Operands other than the 
			default "--regexp" and "--paths" operands have to be prefixed with 
			the operand name.
		 *
		 * @param args String arguments defining the options and operands for the command. 
			Options can be specified by acronym (with a leading dash "-") or by 
			long name (with two leading dashes "--"). Operands other than the
			default "--pattern" and "--paths" operands have to be prefixed with
			the operand name (e.g. "--files" for subsequent file operand values).
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(String... args);
		/**
		 * Filters the input lines from the standard input and writes the
			matching lines to the standard output. A line matches if it contains 
			the given {@code regexp} using case-sensitive string comparison.
		 *
		 * @param regexp Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(String regexp);
		/**
		 * Filters the lines from the specified input files and writes the
			matching lines to the standard output. Every line is matched against
			the given {@code regexp} string using case-sensitive comparison. 
			Line endings are not relevant for the comparison.
		 *
		 * @param regexp Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
		 * @param files The input files to be searched for the pattern; relative paths are 
			not resolved (use the string paths argument to enable relative path 
			resolving based on the current working directory).
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(String regexp, java.io.File... files);
		/**
		 * Filters the input lines from the standard input and writes the
			matching lines to the standard output. Every line is matched against
			the given regular expression {@code pattern} using case-sensitive 
			comparison. Line endings are not relevant for the comparison.
		 *
		 * @param pattern Lines will be printed which match the given pattern.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(java.util.regex.Pattern pattern);
		/**
		 * Filters the lines from the specified input files and writes the
			matching lines to the standard output. Every line is matched against
			the given regular expression {@code pattern} using case-sensitive 
			comparison. Line endings are not relevant for the comparison.
		 *
		 * @param pattern Lines will be printed which match the given pattern.
		 * @param files The input files to be searched for the pattern; relative paths are 
			not resolved (use the string paths argument to enable relative path 
			resolving based on the current working directory).
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(java.util.regex.Pattern pattern, java.io.File... files);
		/**
		 * Filters the lines from the specified input files and writes the
			matching lines to the standard output. Every line is matched against
			the given regular expression {@code pattern} using case-sensitive 
			comparison. Line endings are not relevant for the comparison.
		 *
		 * @param pattern Lines will be printed which match the given pattern.
		 * @param paths Pathnames of the input files to be searched for the pattern;
			wildcards * and ? are supported; relative paths are resolved on the
            basis of the current working directory.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(java.util.regex.Pattern pattern, String... paths);
		/**
		 * Filters the input lines from the standard input and writes the
			matching lines to the standard output. Every line is matched against
			the given {@code regexp} string; the exact comparison rules are 
			defined by the specified matching {@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param regexp Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, String regexp);
		/**
		 * Filters the input lines from the standard input and writes the
			matching lines to the standard output. Every line is matched against
			the given regular expression {@code pattern}; the exact comparison
			rules are defined by the specified matching {@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param pattern Lines will be printed which match the given pattern.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, java.util.regex.Pattern pattern);
		/**
		 * Filters the input lines from the specified input files and writes
			the matching lines to the standard output. Every line is matched 
			against the given {@code regexp} string; the exact comparison rules 
			are defined by the specified matching {@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param regexp Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
		 * @param files The input files to be searched for the pattern; relative paths are 
			not resolved (use the string paths argument to enable relative path 
			resolving based on the current working directory).
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, String regexp, java.io.File... files);
		/**
		 * Filters the input lines from the specified input files and writes
			the matching lines to the standard output. Every line is matched 
			against the given {@code regexp} string; the exact comparison rules 
			are defined by the specified matching {@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param regexp Lines will be printed which match the given regular expression. The 
			{@code regexp} string is surrounded with ".*" on both sides unless
			the {@code --wholeLine} option is specified. If the 
			{@code --fixedStrings} option is used, plain string comparison is
			used instead of regular expression matching.
		 * @param paths Pathnames of the input files to be searched for the pattern;
			wildcards * and ? are supported; relative paths are resolved on the
            basis of the current working directory.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, String regexp, String... paths);
		/**
		 * Filters the input lines from the specified input files and writes
			the matching lines to the standard output. Every line is matched 
			against the given regular expression {@code pattern}; the exact 
			comparison rules are defined by the specified matching 
			{@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param pattern Lines will be printed which match the given pattern.
		 * @param files The input files to be searched for the pattern; relative paths are 
			not resolved (use the string paths argument to enable relative path 
			resolving based on the current working directory).
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, java.util.regex.Pattern pattern, java.io.File... files);
		/**
		 * Filters the input lines from the specified input files and writes
			the matching lines to the standard output. Every line is matched 
			against the given regular expression {@code pattern}; the exact 
			comparison rules are defined by the specified matching 
			{@code options}.
		 *
		 * @param options The options defining the types of patterns and command behavior.
		 * @param pattern Lines will be printed which match the given pattern.
		 * @param paths Pathnames of the input files to be searched for the pattern;
			wildcards * and ? are supported; relative paths are resolved on the
            basis of the current working directory.
		 * @return the generic type {@code } defined by the implementing class;
		 *         the command itself returns no value and writes its result to the
		 *         standard output; see class level parameter comments for more 
		 *         details
		 */
		R grep(GrepOptions options, java.util.regex.Pattern pattern, String... paths);
	}

	/**
	 * 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}.
	 * 
 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * {@code -i}    {@code --ignoreCase}   Match lines ignoring the case when comparing the strings, also known
			from Unix with its acronym 'i'.
{@code -v}    {@code --invertMatch}   Invert the match result, that is, a non-matching line is written to
			the output and a matching line is not. This option is also known 
			from Unix with its acronym 'v'.
{@code -F}    {@code --fixedStrings}   Use fixed-strings matching instead of regular expressions. This is
			usually faster than the standard regexp version.
			
			(This option is ignored if a {@code pattern} operand is specified
			instead of the {@code regexp} string).
{@code -n}    {@code --lineNumber}   Prefix each line of output with the line number within its input
			file.
{@code -c}    {@code --count}   Suppress normal output; instead print a count of matching lines for
			each input file. With the {@code -v}, {@code --invertMatch} option,
			count non-matching lines.
{@code -l}    {@code --matchingFiles}   Suppress normal output; instead print the name of each input file
			from which output would normally have been printed. The scanning
			will stop on the first match.
{@code -x}    {@code --wholeLine}   Select only those matches that exactly match the whole line
			excluding the terminating line ending.
			
			(This option is ignored if a {@code pattern} operand is specified
			instead of the {@code regexp} string).
	 */
	public static final GrepOptionSets Options = GrepOptionSets.INSTANCE;

	/**
	 * Singleton {@link GrepFactory factory} instance for the "grep" command.
	 */
	public static final GrepFactory Factory = GrepFactory.INSTANCE;

	// no instances
	private Grep() {
		super();
	}
}

	{@code grep }
	{@code grep }
	{@code grep }
	{@code grep }
	{@code grep }
	{@code grep }
	{@code grep [-ivFnclx] }
	{@code grep [-ivFnclx] }
	{@code grep [-ivFnclx] }
	{@code grep [-ivFnclx] }
	{@code grep [-ivFnclx] }
	{@code grep [-ivFnclx] }

{@code -i}	{@code --ignoreCase}	Match lines ignoring the case when comparing the strings, also known from Unix with its acronym 'i'.
{@code -v}	{@code --invertMatch}	Invert the match result, that is, a non-matching line is written to the output and a matching line is not. This option is also known from Unix with its acronym 'v'.
{@code -F}	{@code --fixedStrings}	Use fixed-strings matching instead of regular expressions. This is usually faster than the standard regexp version. (This option is ignored if a {@code pattern} operand is specified instead of the {@code regexp} string).
{@code -n}	{@code --lineNumber}	Prefix each line of output with the line number within its input file.
{@code -c}	{@code --count}	Suppress normal output; instead print a count of matching lines for each input file. With the {@code -v}, {@code --invertMatch} option, count non-matching lines.
{@code -l}	{@code --matchingFiles}	Suppress normal output; instead print the name of each input file from which output would normally have been printed. The scanning will stop on the first match.
{@code -x}	{@code --wholeLine}	Select only those matches that exactly match the whole line excluding the terminating line ending. (This option is ignored if a {@code pattern} operand is specified instead of the {@code regexp} string).

{@code }	:	{@code String}	Lines will be printed which match the given regular expression. The {@code regexp} string is surrounded with ".*" on both sides unless the {@code --wholeLine} option is specified. If the {@code --fixedStrings} option is used, plain string comparison is used instead of regular expression matching.
{@code }	:	{@code java.util.regex.Pattern}	Lines will be printed which match the given pattern.
{@code }	:	{@code String...}	Pathnames of the input files to be searched for the pattern; wildcards * and ? are supported; relative paths are resolved on the basis of the current working directory.
{@code }	:	{@code java.io.File...}	The input files to be searched for the pattern; relative paths are not resolved (use the string paths argument to enable relative path resolving based on the current working directory).
{@code }	:	{@code String...}	String arguments defining the options and operands for the command. Options can be specified by acronym (with a leading dash "-") or by long name (with two leading dashes "--"). Operands other than the default "--pattern" and "--paths" operands have to be prefixed with the operand name (e.g. "--files" for subsequent file operand values).
{@code }	:	{@code GrepOptions}	The options defining the types of patterns and command behavior.