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
    SearchAndPrint - Documentation.

    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.



    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods 
      Modifier and Type Method
      static SearchAndPrint ALL​(String token, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
      static SearchAndPrint ALL​(Pattern regEx, boolean useUNIXColorChars, Appendable a)
      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)
      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 SearchAndPrint LASTN​(String token, int n, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
      boolean test​(String fileName, String fileContents)
    • 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:
        1
        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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         // 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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
        1
        2
        3
        4
        5
        6
        7
        8
        9
         // 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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
         // 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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
         // 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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
         // 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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
         Matcher m   = regEx.matcher(fileContents);
         boolean ret = false;
        
         while ((numMatches != 0) && m.find())
         {
             ret = true;
        
             if (a != null) a.append(
                 C.BRED + "File: " + C.RESET + C.BYELLOW + fileName + C.RESET + ", " + C.BRED + "Line: " + C.RESET +
                 StringParse.lineOrLines(fileContents, m.start(), m.end() - m.start(), C.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 InstanceUse & Purpose
        'System.out'Sends text to the standard-out terminal
        Torello.Java.StorageWriterSends text to System.out, and saves it, internally.
        FileWriter, PrintWriter, StringWriterGeneral purpose java text-output classes
        FileOutputStream, PrintStreamMore 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:
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
        49
        50
        51
        52
        53
        54
         int     pos = forwardOrReverse ? 0 : (fileContents.length() - 1);
         int     len = token.length();
         boolean ret = false;
         if (ignoreCase) /* IGNORE-CASE */
         {
             if (forwardOrReverse)   /* Search Forward, from beginning of fileContents */
                 while ((numMatches != 0) && ((pos = StrIndexOf.first_CI(fileContents, pos, -1, token)) != -1))
                 {
                     ret = true;
                     if (a != null) a.append(
                         C.BRED + "File: " + C.RESET + C.BYELLOW + fileName + C.RESET + ", " + C.BRED + "Line: " + C.RESET +
                         StringParse.lineOrLines(fileContents, pos, len, C.BCYAN) + '\n'
                     );
                     pos += len;
                     if (numMatches > 0) numMatches--;
                 }
             else   /* Search Backwards, from ending of fileContents */
                 while ((numMatches != 0) && ((pos = StrIndexOf.left(fileContents, pos, token)) != -1))
                 {
                     ret = true;
                     if (a != null) a.append(
                         C.BRED + "File: " + C.RESET + C.BYELLOW + fileName + C.RESET + ", " + C.BRED + "Line: " + C.RESET +
                         StringParse.lineOrLines(fileContents, pos, len, C.BCYAN) + '\n'
                     );
                     pos--;
                     if (numMatches > 0) numMatches--;
                 }
         }   
         else /* else DO-NOT IGNORE-CASE */
         {
             if (forwardOrReverse)   /* Search Forward, from beginning of fileContents */
                 while ((numMatches != 0) && ((pos = fileContents.indexOf(token, pos)) != -1))
                 {
                     ret = true;
                     if (a != null) a.append(
                         C.BRED + "File: " + C.RESET + C.BYELLOW + fileName + C.RESET + ", " + C.BRED + "Line: " + C.RESET +
                         StringParse.lineOrLines(fileContents, pos, len, C.BCYAN) + '\n'
                     );
                     pos += len;
                     if (numMatches > 0) numMatches--;
                 }
             else   /* Search Backwards, from ending of fileContents */
                 while ((numMatches != 0) && ((pos = StrIndexOf.left(fileContents, pos, token)) != -1))
                 {
                     ret = true;
                     if (a != null) a.append(
                         C.BRED + "File: " + C.RESET + C.BYELLOW + fileName + C.RESET + ", " + C.BRED + "Line: " + C.RESET +
                         StringParse.lineOrLines(fileContents, pos, len, C.BCYAN) + '\n'
                     );
                     pos--;
                     if (numMatches > 0) numMatches--;
                 }
         }
         return ret;