Package Torello.Java

Interface SearchAndPrint

All Superinterfaces:

java.io.Serializable

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface SearchAndPrint
extends java.io.Serializable

A functional-interface for specifying a regular-expression, and how to print the results, to the GREP Tool.

This is just a simple interface that is used to search a text-file, and print any search results to some form of text-output class. This interface is largely a lot of "Factor" or "Builder" static-methods that produce appropriate instances of the interface SearchAndPrint.

The factory-methods in this interface accept quite a few variations of the old UNIX grep tool. One important point to note, is that this interface implements the java.util.function.BiPredicate interface, rather than the interface BiConsumer. There is a subtle, but important, point to remember, the primary goal of instances-objects and classes that implement this interface is that they, not only must print out file-text contents search-results to some form of output, but also because this is a Predicate, a boolean return value is also expected. Implementations of this interface should return a TRUE value when a search-match was found in a given file. FALSE should mean no match was found.

The factory-builder methods provided allow for instances of both java.io.Writer, and instances of java.io.PrintStream. There is also 'default' versions where System.out is used to print text-file grep-search results.

Most importantly, since this is Java - not UNIX - a programmer can implement his own "Search And Print" version in whatever way he/she wishes, and extend the traditional version of UNIX 'grep' command in whatever way he wishes.

Hi-Lited Source-Code:

• View Here: Torello/Java/SearchAndPrint.java
• Open New Browser-Tab: Torello/Java/SearchAndPrint.java

File Size: 25,204 Bytes Line Count: 515 '\n' Characters Found

Field Summary

Fields

Modifier and Type	Field
static long	serialVersionUID

Method Summary

@FunctionalInterface (Lambda) Method
Modifier and Type	Method
boolean	test(String fileName, String fileContents)
Static-Factory Builder: First N Matches
Modifier and Type	Method
static SearchAndPrint	FIRSTN(String token, int n, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
static SearchAndPrint	FIRSTN(Pattern regEx, int n, boolean useUNIXColorChars, Appendable a)
Static-Factory Builder: Last N Matches
Modifier and Type	Method
static SearchAndPrint	LASTN(String token, int n, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
Static-Factory Builder: All Matches
Modifier and Type	Method
static SearchAndPrint	ALL(String token, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
static SearchAndPrint	ALL(Pattern regEx, boolean useUNIXColorChars, Appendable a)
Used Internally (Helper)
Modifier and Type	Method
static boolean	findAndPrint(String fileName, String fileContents, String token, int numMatches, boolean ignoreCase, boolean forwardOrReverse, boolean useUNIXColorChars, Appendable a)
static boolean	findAndPrint(String fileName, String fileContents, Pattern regEx, int numMatches, boolean useUNIXColorChars, Appendable a)

Field Detail

serialVersionUID

🡇 ⇈ ⮫

static final long serialVersionUID

This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

Functional Interfaces are usually not thought of as Data Objects that need to be saved, stored and retrieved; however, having the ability to store intermediate results along with the lambda-functions that helped get those results can make debugging easier.

See Also:

Constant Field Values

Code:

Exact Field Declaration Expression:

 public static final long serialVersionUID = 1;

Method Detail

test

🡅 🡇 ⇈ ⮫

boolean test(java.lang.String fileName,
             java.lang.String fileContents)
      throws java.io.IOException

FUNCTIONAL-INTERFACE BOOLEAN METHOD: This is the method that fulfils this FunctionalInterface 'test' method.

Parameters:

fileName - The name of any file, from the file-system.

fileContents - The contents of that file as a String.

Returns:

A TRUE value should mean that the FileNode has passed the match test. A return value of FALSE should indicate that the FileNode did not contain any matches for the GREP search routine.

IMPORTANT NOTE: This method is also expected to perform any printing and match-evaluating that needs to be performed when GREP'ING a directory, or directory-tree, of files. This is in addition to the simple job of returning a true/false boolean indicating whether a match occurred.

Throws:

java.io.IOException

ALL

🡅 🡇 ⇈ ⮫

static SearchAndPrint ALL(java.lang.String token,
                          boolean ignoreCase,
                          boolean useUNIXColorChars,
                          java.lang.Appendable a)

This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in java is referred to as a FunctionalInterface and may also be called a "Lambda". The function that is returned will simply look through the contents of a file which here is just called 'fileContents' for a particular substring 'token.'

MATCHES-RETURNED: All String-Token Matches found in fileContents shall be sent to the provided Consumer<String> c parameter.

Parameters:

token - The UNIX-GREP command scours a single-file, or all files in a directory or tree of directories for a particular string-token. This parameter 'token' is the String that the GREP Search-Logic will be using to search the files in the file-system.

ignoreCase - This parameter will inform the Search-Logic to ignore case sensitivity during the string comparisons of file-content.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

Returns:

An instance of 'SearchAndPrint' that obeys these search-criteria, and sends output to the specified destination.

Code:

Exact Method Body:

 // FAIL-FAST: Before building a Lambda-Predicate, make sure the testing-supplies work.
 if (token == null)  throw new NullPointerException(
     "String-Parameter 'token' was passed null to static-factory method 'ALL'."
 );

 // Build & Generate an instance of 'SearchAndPrint', a @FunctionalInterface that is highly
 // similar to java.util.function.BiPredicate (but throws IOException), and return it.

 return (String fileName, String fileContents) ->
     findAndPrint
         (fileName, fileContents, token, -1, ignoreCase, true, useUNIXColorChars, a);

ALL

🡅 🡇 ⇈ ⮫

static SearchAndPrint ALL(java.util.regex.Pattern regEx,
                          boolean useUNIXColorChars,
                          java.lang.Appendable a)

This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in java is referred to as a FunctionalInterface and may also be called a "Lambda". The function that is returned will simply look through the contents of a file which here is just called 'fileContents' using a regular-expression matcher, which here is parameter Pattern regEx.

MATCHES-RETURNED: All Regular-Expression Matches found in fileContents shall be sent to the provided Consumer<String> c parameter.

Parameters:

regEx - The UNIX-GREP command scours a single-file, or all files in a directory or tree of directories for a match using a regular-expression matcher. This parameter regEx.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

Returns:

An instance of 'SearchAndPrint' that obeys these search-criteria, and sends output to the specified destination.

Code:

Exact Method Body:

 // FAIL-FAST: Before building a Lambda-Predicate, make sure the testing-supplies work.
 if (regEx == null)  throw new NullPointerException(
     "Regular-Expression Parameter 'regEx' was passed null to static-factory method 'ALL'."
 );

 // Build & Generate an instance of 'SearchAndPrint', a @FunctionalInterface that is highly
 // similar to java.util.function.BiPredicate (but throws IOException), and return it.

 return (String fileName, String fileContents) ->
     findAndPrint(fileName, fileContents, regEx, -1, useUNIXColorChars, a);

FIRSTN

🡅 🡇 ⇈ ⮫

static SearchAndPrint FIRSTN(java.lang.String token,
                             int n,
                             boolean ignoreCase,
                             boolean useUNIXColorChars,
                             java.lang.Appendable a)

This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in java is referred to as a FunctionalInterface and may also be called a "Lambda". The function that is returned will simply look through the contents of a file which here is just called 'fileContents' for a particular substring 'token.'

MATCHES-RETURNED: The first 'n' number of matches shall be sent to the provided Consumer<{@code String}> c parameter.

Parameters:

token - The UNIX-GREP command scours a single-file, or all files in a directory or tree of directories for a particular String-token. This parameter 'token' is the String that the GREP Search-Logic will be using to search the files in the file-system.

n - This will put a 'maximum-count' on the number of String-token-matches that the GREP Class / Command will return. Here, 'n' must be a positive-integer (greater-than 0), or an 'NException' will throw.

ignoreCase - This parameter will inform the Search-Logic to ignore case sensitivity during the String comparisons of file-content.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

Returns:

An instance of 'SearchAndPrint' that obeys these search-criteria, and sends output to the specified destination.

Throws:

NException - If 'n' is a negative integer, or zero.

Code:

Exact Method Body:

 // FAIL-FAST: Before building a Lambda-Predicate, make sure the testing-supplies work.
 if (token == null)  throw new NullPointerException(
     "String-Parameter 'token' was passed null to static-factory method 'FIRSTN'."
 );

 // FAIL-FAST: Simple check on the value of 'n' - to make sure n is not negative, or zero.
 NException.check(n);

 // Build & Generate an instance of 'SearchAndPrint', a @FunctionalInterface that is highly
 // similar to java.util.function.BiPredicate (but throws IOException), and return it.

 return (String fileName, String fileContents) ->
     findAndPrint(fileName, fileContents, token, n, ignoreCase, true, useUNIXColorChars, a);

FIRSTN

🡅 🡇 ⇈ ⮫

static SearchAndPrint FIRSTN(java.util.regex.Pattern regEx,
                             int n,
                             boolean useUNIXColorChars,
                             java.lang.Appendable a)

This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in java is referred to as a FunctionalInterface and may also be called a "Lambda". The function that is returned will simply look through the contents of a file which here is just called 'fileContents' using a regular-expression matcher, which here is parameter Pattern regEx.

MATCHES-RETURNED: The first 'n' number of matches shall be sent to the provided PrintStream ps parameter.

Parameters:

regEx - The UNIX-GREP command scours a single-file, or all files in a directory or tree of directories for a match using a regular-expression matcher. This parameter 'regEx'.

n - This will put a 'maximum-count' on the number of regular-expression matches that the GREP Class / Command will return. Here, 'n' must be a positive-integer (greater-than 0), or an 'NException' will throw.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

Returns:

An instance of 'SearchAndPrint' that obeys these search-criteria, and sends output to the specified destination.

Throws:

NException - If 'n' is a negative integer, or zero.

Code:

Exact Method Body:

 // FAIL-FAST: Before building a Lambda-Predicate, make sure the testing-supplies work.
 if (regEx == null)  throw new NullPointerException(
     "Regular-Expression Parameter 'regEx' was passed null to static-factory method 'FIRSTN'."
 );

 // FAIL-FAST: Simple check on the value of 'n' - to make sure n is not negative, or zero.
 NException.check(n);

 // Build & Generate an instance of 'SearchAndPrint', a @FunctionalInterface that is highly
 // similar to java.util.function.BiPredicate (but throws IOException), and return it.

 return (String fileName, String fileContents) -> 
     findAndPrint(fileName, fileContents, regEx, n, useUNIXColorChars, a);

LASTN

🡅 🡇 ⇈ ⮫

static SearchAndPrint LASTN(java.lang.String token,
                            int n,
                            boolean ignoreCase,
                            boolean useUNIXColorChars,
                            java.lang.Appendable a)

This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in java is referred to as a FunctionalInterface and may also be called a "Lambda". The function that is returned will simply look through the contents of a file which here is just called 'fileContents' for a particular substring 'token.'

MATCHES-RETURNED: The last 'n' number of matches shall be sent to the provided Consumer<String> c parameter.

Parameters:

token - The UNIX-GREP command scours a single-file, or all files in a directory or tree of directories for a particular String-token. This parameter 'token' is the String that the GREP Search-Logic will be using to search the files in the file-system.

n - This will put a 'maximum-count' on the number of String-token-matches that the GREP Class / Command will return. Here, 'n' must be a positive-integer (greater-than 0), or an 'NException' will throw.

ignoreCase - This parameter will inform the Search-Logic to ignore case sensitivity during the String comparisons of file-content.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

Returns:

An instance of 'SearchAndPrint' that obeys these search-criteria, and sends output to the specified destination.

Throws:

NException - If 'n' is a negative integer, or zero.

Code:

Exact Method Body:

 // FAIL-FAST: Before building a Lambda-Predicate, make sure the testing-supplies work.
 if (token == null)  throw new NullPointerException(
     "String-Parameter 'token' was passed null to static-factory method 'FIRSTN'."
 );

 // FAIL-FAST: Simple check on the value of 'n' - to make sure n is not negative, or zero.
 NException.check(n);

 // Build & Generate an instance of 'SearchAndPrint', a @FunctionalInterface that is highly
 // similar to java.util.function.BiPredicate (but throws IOException), and return it.

 return (String fileName, String fileContents) ->
     findAndPrint
         (fileName, fileContents, token, n, ignoreCase, false, useUNIXColorChars, a);

findAndPrint

🡅 🡇 ⇈ ⮫

static boolean findAndPrint(java.lang.String fileName,
                            java.lang.String fileContents,
                            java.util.regex.Pattern regEx,
                            int numMatches,
                            boolean useUNIXColorChars,
                            java.lang.Appendable a)
                     throws java.io.IOException

This will search through a file using a regular-expression.

Parameters:

fileName - This is the name of the file that is being "GREP-ED." This name will be printed out alongside match information.

fileContents - This must be the contents of the entire file as a String.

regEx - This is the Regular-Expression that does the matching. When a match is found, it is reported to the printer.

numMatches - This is the number of matches to print before exiting. Each match will decrement the counter by 1, and this method shall exit once this reaches zero, or once the number of matches has exceeded this count.

NOTE: Setting this parameter to a negative number will disable the counter, and all matches will be returned.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

Returns:

TRUE if there was match in the file, and FALSE otherwise.

Throws:

java.io.IOException

Code:

Exact Method Body:

 Matcher m   = regEx.matcher(fileContents);
 boolean ret = false;

 while ((numMatches != 0) && m.find())
 {
     ret = true;

     if (a != null) a.append(
         BRED + "File: " + RESET + BYELLOW + fileName + RESET + ", " +
         BRED + "Line: " + RESET + StrPrint.lineOrLines
             (fileContents, m.start(), m.end() - m.start(), BCYAN) + '\n'
     );

     if (numMatches > 0) numMatches--;
 }

 return ret;

findAndPrint

🡅 ⇈ ⮫

static boolean findAndPrint(java.lang.String fileName,
                            java.lang.String fileContents,
                            java.lang.String token,
                            int numMatches,
                            boolean ignoreCase,
                            boolean forwardOrReverse,
                            boolean useUNIXColorChars,
                            java.lang.Appendable a)
                     throws java.io.IOException

This will search through a file by looking for a particular String 'token.'

Parameters:

fileName - This is the name of the file that is being "GREP-ED." This name will be printed out alongside match information.

fileContents - This must be the contents of the entire file as a String.

token - This is the token used in the match-comparison. When an instance of this token is found, the match is reported to the 'printer.'

numMatches - This is the number of matches to print before exiting. Each match will decrement the counter by 1, and this method shall exit once this reaches zero, or once the number of matches has exceeded this count.

NOTE: Setting this parameter to a negative number will disable the counter, and all matches will be returned.

ignoreCase - When this parameter is TRUE all String Comparison's shall be performed in a CASE-INSENSITIVE manner. When this parameter is FALSE, matching shall require String-Comparison to MATCH-CASE.

forwardOrReverse - When this parameter is TRUE, then the search shall begin at the start of the file-contents, and continue forward towards the End-Of-File. When this parameter is FALSE, the String-Token Matching shall start at the End-Of-File, and work towards the beginning.

useUNIXColorChars - If both of the following are true, then UNIX Color-Code Characters will be appended to the output stream.

a - Uses java.lang.Appendable to receive output-text information/messages. If this parameter is 'null', then output will not be printed, with the intention being, GREP's return value Vector<FileNode> is sufficient of a return-value. This parameter expects an implementation of Java's interface java.lang.Appendable which allows for a wide range of options when logging intermediate messages.

Class or Interface Instance	Use & Purpose
'System.out'	Sends text to the standard-out terminal
Torello.Java.StorageWriter	Sends text to System.out, and saves it, internally.
FileWriter, PrintWriter, StringWriter	General purpose java text-output classes
FileOutputStream, PrintStream	More general-purpose java text-output classes

IMPORTANT: The interface Appendable requires that the check exception IOException must be caught when using its append(CharSequence) methods.

Returns:

TRUE if there was match in the file, and FALSE otherwise.

Throws:

java.io.IOException

Code:

Exact Method Body:

 int     pos = forwardOrReverse ? 0 : (fileContents.length() - 1);
 int     len = token.length();
 boolean ret = false;

 // IGNORE-CASE
 if (ignoreCase)
 {
     // Search Forward, from beginning of fileContents
     if (forwardOrReverse)

         while (     (numMatches != 0)
                 &&  ((pos = StrIndexOf.first_CI(fileContents, pos, -1, token)) != -1)
         )
         {
             ret = true;

             if (a != null) a.append(
                 BRED + "File: " + RESET + BYELLOW + fileName + RESET + ", " +
                 BRED + "Line: " + RESET + StrPrint.lineOrLines
                     (fileContents, pos, len, BCYAN) + '\n'
             );

             pos += len;
             if (numMatches > 0) numMatches--;
         }

     // Search Backwards, from ending of fileContents
     else

         while (     (numMatches != 0)
                 &&  ((pos = StrIndexOf.left(fileContents, pos, token)) != -1)
         )
         {
             ret = true;

             if (a != null) a.append(
                 BRED + "File: " + RESET + BYELLOW + fileName + RESET + ", " +
                 BRED + "Line: " + RESET + StrPrint.lineOrLines
                     (fileContents, pos, len, BCYAN) + '\n'
             );

             pos--;
             if (numMatches > 0) numMatches--;
         }
 }   

 // else DO-NOT IGNORE-CASE
 else
 {
     // Search Forward, from beginning of fileContents
     if (forwardOrReverse)

         while (     (numMatches != 0)
                 &&  ((pos = fileContents.indexOf(token, pos)) != -1)
         )
         {
             ret = true;

             if (a != null) a.append(
                 BRED + "File: " + RESET + BYELLOW + fileName + RESET + ", " +
                 BRED + "Line: " + RESET + StrPrint.lineOrLines
                     (fileContents, pos, len, BCYAN) + '\n'
             );

             pos += len;
             if (numMatches > 0) numMatches--;
         }

     // Search Backwards, from ending of fileContents
     else
         while (     (numMatches != 0)
                 &&  ((pos = StrIndexOf.left(fileContents, pos, token)) != -1)
         )
         {
             ret = true;

             if (a != null) a.append(
                 BRED + "File: " + RESET + BYELLOW + fileName + RESET + ", " +
                 BRED + "Line: " + RESET + StrPrint.lineOrLines
                     (fileContents, pos, len, BCYAN) + '\n'
             );

             pos--;
             if (numMatches > 0) numMatches--;
         }
 }

 return ret;