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 "Factory" or "Builder" static-methods that produce appropriate instances of the SearchAndPrint interface.

    The factory-methods in this interface accept quite a few variations of the old UNIX grep tool. The factory-builder methods provided allow for instances of both java.io.Writer, and instances of java.io.PrintStream. There are 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.


    • 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
        FunctionalInterface Target-Method:
        This method corresponds to the @FunctionalInterface Annotation's method requirement. It is the only non-default, non-static method in this interface, and may be the target of a Lambda-Expression or '::' (double-colon) Function-Pointer.
        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-Target.

        The function that is returned will simply look through the contents of a file which here is just called 'fileContents' (in the Method Body Code below) for a particular substring 'token.'

        Matches Returned:
        All Regular-Expression Matches found in 'fileContents' shall be sent to the User-Provided Appendable parameter 'a'.
        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 expects an implementation of Java's java.lang.Appendable interface 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

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) 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-Target.

        The function that is returned will simply look through the contents of a file which here is just called 'fileContents' (in the Method Body Code below) using a Regular-Expression Matcher, which here is Pattern parameter 'regEx'.

        Matches Returned:
        All Regular-Expression Matches found in 'fileContents' shall be sent to the User-Provided Appendable parameter 'a'.
        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 expects an implementation of Java's java.lang.Appendable interface 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

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) 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-Target.

        The function that is returned will simply look through the contents of a file which here is just called 'fileContents' (in the Method Body Code below) for a particular substring 'token'.

        Matches Returned:
        The first 'n' number of matches shall be sent to the User-Provided Appendable parameter 'a'.
        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 expects an implementation of Java's java.lang.Appendable interface 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

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) 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-Target.

        The function that is returned will simply look through the contents of a file which here is just called 'fileContents' (in the Method Body Code below) using a Regular-Expression Matcher, which here is Pattern parameter 'regEx'.

        Matches Returned:
        The first 'n' number of matches shall be sent to the User-Provided Appendable parameter 'a'.
        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 expects an implementation of Java's java.lang.Appendable interface 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

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) 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-Target.

        The function that is returned will simply look through the contents of a file which here is just called 'fileContents' (in the Method Body Code below), for a particular substring 'token'.

        Matches Returned:
        The last 'n' number of matches shall be sent to the User-Provided Appendable parameter 'a'.
        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 expects an implementation of Java's java.lang.Appendable interface 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

        Checked IOException:
        The Appendable interface requires that the Checked-Exception IOException be caught when using its append(...) 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:
        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.
        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:
        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.
        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.
        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;