package Torello.Java;

import java.util.function.*;
import java.util.regex.*;
import java.io.*;

import static Torello.Java.C.*;

/**
 * A functional-interface for specifying a regular-expression, and how to print the results,
 * to the <CODE>GREP</CODE> Tool.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=SEARCH_AND_PRNT>
 */
@FunctionalInterface
public interface SearchAndPrint extends java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDFI>  */
    public static final long serialVersionUID = 1;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=FUNC_INTER_METH>
     *
     * @param fileName The name of any file, from the File-System.
     *
     * @param fileContents The contents of that file as a {@code String}.
     *
     * @return A {@code TRUE} value should mean that the {@code FileNode} has passed the match test.
     * A return value of {@code FALSE} should indicate that the {@code FileNode} did not contain any
     * matches for the {@code GREP} search routine.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT NOTE:</B></SPAN> This method is also
     * expected to perform any printing and match-evaluating that needs to be performed when
     * {@code 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.
     */
    public boolean test(String fileName, String fileContents) throws IOException;


    // ********************************************************************************************
    // ********************************************************************************************
    // ALL, String-Token
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in
     * Java is referred to as a {@code FunctionalInterface} and may also be called a Lambda-Target.
     * 
     * <BR /><BR />The function that is returned will simply look through the contents of a file
     * which here is just called {@code 'fileContents'} (in the Method Body Code below) for a
     * particular substring {@code 'token.'}
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Matches Returned:</B>
     * 
     * <BR />All Regular-Expression Matches found in {@code 'fileContents'} shall be sent to the
     * User-Provided {@code Appendable} parameter {@code 'a'}.
     * 
     * @param token The UNIX-GREP command scours a single-file, or all files in a directory or tree
     * of directories for a particular {@code String}-token.  This parameter {@code 'token'} is the
     * {@code String} that the {@code GREP} Search-Logic will be using to search the files in the
     * File-System.
     *
     * @param ignoreCase This parameter will inform the Search-Logic to ignore case sensitivity
     * during the string comparisons of file-content.
     *
     * @param a Uses {@code java.lang.Appendable} to receive output-text information/messages.
     * If this parameter is 'null', then output will not be printed, with the intention being,
     * {@code GREP's} return value {@code Vector<FileNode>} is sufficient of a return-value.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param useUNIXColorChars If both of the following are true, then UNIX Color-Code Characters
     * will be appended to the output stream.
     *
     * @return An instance of {@code 'SearchAndPrint'} that obeys these search-criteria, and
     * sends output to the specified destination.
     */
    public static SearchAndPrint ALL
        (String token, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
    {
        // 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, Regular-Expression
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in
     * Java is referred to as a {@code FunctionalInterface} and may also be called a Lambda-Target.
     * 
     * <BR /><BR />The function that is returned will simply look through the contents of a file
     * which here is just called {@code 'fileContents'} (in the Method Body Code below) using a
     * Regular-Expression Matcher, which here is {@code Pattern} parameter {@code 'regEx'}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Matches Returned:</B>
     * 
     * <BR />All Regular-Expression Matches found in {@code 'fileContents'} shall be sent to the
     * User-Provided {@code Appendable} parameter {@code 'a'}.
     * 
     * @param 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 
     * {@code regEx}.
     *
     * @param a Uses {@code java.lang.Appendable} to receive output-text information/messages.
     * If this parameter is 'null', then output will not be printed, with the intention being,
     * {@code GREP's} return value {@code Vector<FileNode>} is sufficient of a return-value.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param useUNIXColorChars If both of the following are true, then UNIX Color-Code Characters
     * will be appended to the output stream.
     *
     * @return An instance of {@code 'SearchAndPrint'} that obeys these search-criteria, and sends
     * output to the specified destination.
     */
    public static SearchAndPrint ALL(Pattern regEx, boolean useUNIXColorChars, Appendable a)
    {
        // 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, String-Token
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in
     * Java is referred to as a {@code FunctionalInterface} and may also be called a Lambda-Target.
     * 
     * <BR /><BR />The function that is returned will simply look through the contents of a file
     * which here is just called {@code 'fileContents'} (in the Method Body Code below) for a
     * particular substring {@code 'token'}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Matches Returned:</B>
     * 
     * <BR />The first {@code 'n'} number of matches shall be sent to the User-Provided
     * {@code Appendable} parameter {@code 'a'}.
     * 
     * @param token The UNIX-GREP command scours a single-file, or all files in a directory or tree
     * of directories for a particular {@code String}-token.  This parameter {@code 'token'} is the
     * {@code String} that the {@code GREP} Search-Logic will be using to search the files in the
     * File-System.
     *
     * @param n This will put a 'maximum-count' on the number of {@code String}-token-matches
     * that the {@code GREP} Class / Command will return.  Here, {@code 'n'} must be a
     * positive-integer (greater-than 0), or an {@code 'NException'} will throw.
     *
     * @param ignoreCase This parameter will inform the Search-Logic to ignore case sensitivity
     * during the {@code String} comparisons of file-content.
     *
     * @param a Uses {@code java.lang.Appendable} to receive output-text information/messages.
     * If this parameter is 'null', then output will not be printed, with the intention being,
     * {@code GREP's} return value {@code Vector<FileNode>} is sufficient of a return-value.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param useUNIXColorChars If both of the following are true, then UNIX Color-Code
     * Characters will be appended to the output stream.
     *
     * @return An instance of {@code 'SearchAndPrint'} that obeys these search-criteria, and
     * sends output to the specified destination.
     *
     * @throws NException If {@code 'n'} is a negative integer, or zero.
     */
    public static SearchAndPrint FIRSTN
        (String token, int n, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
    {
        // 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, Regular-Expression
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in
     * Java is referred to as a {@code FunctionalInterface} and may also be called a Lambda-Target.
     * 
     * <BR /><BR />The function that is returned will simply look through the contents of a file
     * which here is just called {@code 'fileContents'} (in the Method Body Code below) using a
     * Regular-Expression Matcher, which here is {@code Pattern} parameter {@code 'regEx'}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Matches Returned:</B>
     * 
     * <BR />The first {@code 'n'} number of matches shall be sent to the User-Provided
     * {@code Appendable} parameter {@code 'a'}.
     * 
     * @param 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 
     * {@code 'regEx'}.
     *
     * @param n This will put a 'maximum-count' on the number of regular-expression matches that
     * the {@code GREP} Class / Command will return.  Here, {@code 'n'} must be a positive-integer
     * (greater-than 0), or an {@code 'NException'} will throw.
     *
     * @param a Uses {@code java.lang.Appendable} to receive output-text information/messages.
     * If this parameter is 'null', then output will not be printed, with the intention being,
     * {@code GREP's} return value {@code Vector<FileNode>} is sufficient of a return-value.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     *
     * @param useUNIXColorChars If both of the following are true, then UNIX Color-Code Characters
     * will be appended to the output stream.
     *
     * @return An instance of {@code 'SearchAndPrint'} that obeys these search-criteria, and sends
     * output to the specified destination.
     *
     * @throws NException If {@code 'n'} is a negative integer, or zero.
     */
    public static SearchAndPrint FIRSTN
        (Pattern regEx, int n, boolean useUNIXColorChars, Appendable a)
    { 
        // 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, String-Token
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This static-factory 'builder' method merely returns a C-Styled Function-Pointer, which in
     * Java is referred to as a {@code FunctionalInterface} and may also be called a Lambda-Target.
     * 
     * <BR /><BR />The function that is returned will simply look through the contents of a file
     * which here is just called {@code 'fileContents'} (in the Method Body Code below), for a
     * particular substring {@code 'token'}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Matches Returned:</B>
     * 
     * <BR />The last {@code 'n'} number of matches shall be sent to the User-Provided
     * {@code Appendable} parameter {@code 'a'}.
     * 
     * @param token The UNIX-GREP command scours a single-file, or all files in a directory or tree
     * of directories for a particular {@code String}-token.  This parameter {@code 'token'} is the
     * {@code String} that the {@code GREP} Search-Logic will be using to search the files in the
     * File-System.
     * 
     * @param n This will put a 'maximum-count' on the number of {@code String}-token-matches that
     * the {@code GREP} Class / Command will return. Here, {@code 'n'} must be a positive-integer
     * (greater-than 0), or an {@code 'NException'} will throw.
     * 
     * @param ignoreCase This parameter will inform the Search-Logic to ignore case sensitivity
     * during the {@code String} comparisons of file-content.
     * 
     * @param a Uses {@code java.lang.Appendable} to receive output-text information/messages.  If
     * this parameter is 'null', then output will not be printed, with the intention being,
     * {@code GREP's} return value {@code Vector<FileNode>} is sufficient of a return-value.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=APPENDABLE>
     * 
     * @param useUNIXColorChars If both of the following are true, then UNIX Color-Code Characters
     * will be appended to the output stream.
     * 
     * @return An instance of {@code 'SearchAndPrint'} that obeys these search-criteria, and sends
     * output to the specified destination.
     * 
     * @throws NException If {@code 'n'} is a negative integer, or zero.
     */
    public static SearchAndPrint LASTN
        (String token, int n, boolean ignoreCase, boolean useUNIXColorChars, Appendable a)
    {
        // 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);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PROTECTED TOP-LEVEL DISPATCH METHODS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will search through a file using a regular-expression.
     *
     * @param 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.
     *
     * <BR /><BR /><B>NOTE:</B> Setting this parameter to a negative number will disable the
     * counter, and all matches will be returned.
     *
     * @return {@code TRUE} if there was match in the file, and {@code FALSE} otherwise.
     */
    static boolean findAndPrint(
            String fileName, String fileContents, Pattern regEx, int numMatches,
            boolean useUNIXColorChars, Appendable a
        )
        throws IOException
    {
        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;
    }

    /**
     * This will search through a file by looking for a particular {@code String} 'token.'
     *=
     * @param 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.
     *
     * <BR /><BR /><B>NOTE:</B> Setting this parameter to a negative number will disable the
     * counter, and all matches will be returned.
     *
     * @param forwardOrReverse When this parameter is {@code 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 {@code FALSE}, the {@code String}-Token Matching shall start at the End-Of-File,
     * and work towards the beginning.
     *
     * @return {@code TRUE} if there was match in the file, and {@code FALSE} otherwise.
     */
    static boolean findAndPrint(
            String fileName, String fileContents, String token, int numMatches, boolean ignoreCase,
            boolean forwardOrReverse, boolean useUNIXColorChars, Appendable a
        )
        throws IOException
    {
        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;
    }
}