package Torello.Java;

import Torello.Java.HelperPackages.StrPrint.*;

import Torello.Java.Function.IntTFunction;
import static Torello.Java.C.*;

// Needed for a few JavaDoc Comments
import Torello.JavaDoc.Field;
import Torello.JavaDoc.Constructor;
import Torello.JavaDoc.Method;
import Torello.JavaDoc.AnnotationElem;

/**
 * This class provides several {@code String} printing utilities such as abbreviation and list
 * printing.
 */
@Torello.JavaDoc.StaticFunctional
public class StrPrint
{
    private StrPrint() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPER & BASIC
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts every line-character ({@code '\n'}) - <I>and any white-space before or after
     * that character</I>, into the {@code String} - {@code "\\n"} - which is the actual two
     * character sequence of a back-slash ({@code '\'}), followed by the letter {@code 'n'}.
     * 
     * <BR /><BR />After new-line characters are replaced, the method will remove any duplicate
     * spaces that are present in the {@code String}, and reduce them to a single space character
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR><TH>Input {@code String}</TH><TH>Returned {@code String}</TH></TR>
     * <TR><TD>"Hello World"</TD><TD>"Hello World"</TD></TR>
     * <TR><TD>"Hello &nbsp;&nbsp;\t &nbsp;&nbsp;World"</TD><TD>"Hello World"</TD></TR>
     * <TR><TD>"Hello World\n"</TD><TD>"Hello World\\n"</TD></TR>
     * <TR><TD>"Hello &nbsp;&nbsp;World &nbsp;\n\t &nbsp;\n"</TD><TD>"Hello World\\n\\n"</TD></TR>
     * <TR>
     *      <TD>"Hello Today!\nHow Are You?"</TD>
     *      <TD>"Hello Today!\\nHow Are You?"</TD>
     * </TR>
     * <TR>
     *      <TD>"Hello,\n &nbsp;&nbsp;Testing &nbsp;&nbsp;1, &nbsp;2, &nbsp;3\n"</TD>
     *      <TD>"Hello,\\nTesting 1, 2, 3\\n"</TD>
     * </TR>
     * <TR>
     *      <TD>"Hello,\n &nbsp;&nbsp;Testing 1, 2, 3 &nbsp;&nbsp;\n\t\t\t"</TD>
     *      <TD>"Hello,\\nTesting 1, 2, 3\\n"</TD>
     * </TR>
     * <TR><TD>"\n"</TD><TD>"\\n"</TD></TR>
     * <TR><TD>"\n&nbsp;\t"</TD><TD>"\\n"</TD></TR>
     * <TR><TD>"\n\t&nbsp;\n\t&nbsp;\n\t&nbsp;"</TD><TD>"\\n\\n\\n"</TD></TR>
     * </TABLE>
     * 
     * <BR />This method is used in printing Java Source Code to a terminal - in an abbreviated
     * way!  After this method is finished, java-source-as-text is actually <B><I>still</I></B>
     * look readable, and can be printed in a table of methods on a page.  It is used in the Java
     * Doc Upgrader tool, and makes printing up <B><I>both</I></B> method-signatures
     * <B><I>and</I></B> method bodies quite a bit easier.
     * 
     * <BR /><BR />For a better understanding of the use and application of this function, please
     * take a look at the <B>{@code 'toString'}</B> methods: <B>{@link Method#toString()},
     * {@link Constructor#toString()}, {@link Field#toString()} and
     * {@link AnnotationElem#toString()}</B>
     *  
     * <BR /><BR /><B CLASS=JDDescLabel>Regular Expressions:</B>
     * 
     * <BR />This method uses regular-expressions, rather performing an optimized, in-place,
     * {@code String} replacement (such as one with a {@code for} or {@code while} loop).  This
     * means that there is a little efficiency sacrificed in the name of brevity.
     * 
     * <BR /><BR />The replacement used in the {@code String.replaceAll} method was thouroughly
     * tested.  The quadruple-backslash {@code '\n'} <I>is actually necessary!</I>  The first
     * escape used is to communicate with the Java-Compiler, and the second round of escaping is
     * communicating with the Regular Expression Processor.
     * 
     * @param s Any {@code java.lang.String}, preferably one with multiple lines of text.
     * 
     * @return A {@code String}, where each line of text has been "trimmed", and the two
     * character sequence {@code "\\n"} inserted in-between each line.
     * 
     * @see #abbrevStartRDSF(String, int, boolean)
     * @see #abbrevEndRDSF(String, int, boolean)
     */
    public static String newLinesAsText(String s)
    {
        return s
            .replaceAll(
                    // White-Space-Except-Newline, THEN newline, THEN White-SpaceExcept-Newline
                    "[ \t\r\f\b]*\n[ \t\r\f\b]*",

                    // Replace Each Occurence of that with:
                    // == COMPILES-TO ==> "\\n" == REG-EX-READS ==> BackSlash and letter 'n'
                    "\\\\n"
            )
            // == COMPILES-TO ==> "\s+" == REG-EX-READS ==> 'spaces'
            .replaceAll("\\s+", " ")

            // Don't forget about leading and trailing stuff...
            .trim();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviating Text, with "newLinesAsText" - Helper
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B>
     * <BR />Invokes:    {@link StringParse#removeDuplicateSpaces(String)} 
     * <BR />Or Invokes: {@link #newLinesAsText(String)}
     * <BR />Finally:    {@link #abbrevStart(String, boolean, int)}
     */
    public static String abbrevStartRDSF
        (String s, int maxLength, boolean seeEscapedNewLinesAsText)
    {
        // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios
        // of this conditional-statement, the new-lines have already been removed by the previous
        // method call.
        //
        // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines

        return seeEscapedNewLinesAsText
            ? abbrevStart(newLinesAsText(s), false, maxLength)
            : abbrevStart(StringParse.removeDuplicateSpaces(s), false, maxLength);
    }

    /**
     * Convenience Method.
     * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B>
     * <BR />Invokes: {@link StringParse#removeDuplicateSpaces(String)}
     * <BR />Or Invokes: {@link #newLinesAsText(String)}
     * <BR />Finally: {@link #abbrevEnd(String, boolean, int)}
     */
    public static String abbrevEndRDSF
        (String s, int maxLength, boolean seeEscapedNewLinesAsText)
    {
        // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios
        // of this conditional-statement, the new-lines have already been removed by the previous
        // method call.
        //
        // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines

        return seeEscapedNewLinesAsText
            ? abbrevEnd(newLinesAsText(s), false, maxLength)
            : abbrevEnd(StringParse.removeDuplicateSpaces(s), false, maxLength);
    }

    /**
     * Convenience Method.
     * <BR />Passes: {@code '0'} to parameter {@code 'abbrevPos'}, forcing the abbreviation to
     * occur at the <B>start</B> of the {@code String} (if long enough to be abbreviated)
     * @see #abbrev(String, int, boolean, String, int)
     */
    public static String abbrevStart(String s, boolean escNewLines, int maxLength)
    { return Abbrev.print(s, 0, escNewLines, null, maxLength); }

    /**
     * This will abbreviate any {@code String} using either the ellipsis ({@code '...'}), or some
     * other use provided abbreviation-{@code String} - <I>as long as the provided {@code String}
     * is longer than {@code 'maxLength'}.</I>  When {@code 's'} is, indeed, longer than
     * {@code 'maxLength'} the returned-{@code String} will contain the ellipsis abbreviation
     * beginning at {@code String}-index {@code 'abbrevPos'}.
     *
     * <BR /><BR />You have the option of asking that new-line characters ({@code '\n'}) be
     * escaped into the two-character {@code String: "\\n"}.  This optional is provided so that
     * the output may fit on a single-line, for readability purposes.  It will look somewhat like
     * an escaped {@code JSON} file, which also substitues {@code '\n'} characters for the
     * 'escaped' version {@code "\\n"}.  <I>Note that when this occurs, the replaced-{@code String}
     * actually only contains two characters, <B>not three,</B> since the first back-slash your are
     * looking right here is, itself, an escape character!</I>
     *
     * @param s This may be any Java (non-null) {@code String}
     *
     * @param abbrevPos This parameter is used to indicate where the abbreviation-{@code String}
     * should occur - <I>if this {@code String 's'} is long enough to be abbreviated.</I>  For
     * instance, if {@code '0'} (zero) were passed to this parameter, and {@code 's'} were longer
     * than parameter {@code 'maxLength'}, then an ellipsis would be appended to the beginning of
     * the returned-{@code 'String'}.  (Or, if some other {@code 'abbrevStr'} were specified, that
     * other abbreviation would be appended to the beginning of the returned-{@code String})
     * 
     * @param escapeNewLines <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL>
     * @param abbrevStr <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL>
     *
     * @return If the input {@code String} has a <I>length less-than {@code 'maxLength'}</I>, then
     * it is returned, unchanged.  If the input contained new-line characters, and you have 
     * requested to escape them, that replacement is performed first (which makes the original 
     * {@code String}} longer).  Then, if the {@code String} is longer than {@code 'maxLength'},
     * it is abbreviated, and either the default ellipsis <I>or the user-provided
     * {@code 'abbrevStr'}</I> are inserted at location {@code 'abbrevPos'} and returned.
     * 
     * <BR /><BR />If, after the new-line escape-replacement, the returned-{@code String} would not
     * be longer than {@code 'maxLength'}, then that escaped-{@code String} is returned, as is
     * (without any elliptical-characters).
     *
     * @throws IllegalArgumentException If the value for {@code 'maxLength'} is negative, or if it
     * is less than the length of the abbreviation.
     * 
     * <BR /><BR />Specifically, if {@code 'maxLength'} isn't even long enough to fit the abbreviation
     * itself, then this exception will throw.
     * 
     * <BR /><BR />If the value passed to {@code 'abbrevPos'} is negative or longer than the value
     * passed to {@code 'maxLength'} minus the length of the ellipsis-{@code String}, then this 
     * exception will also throw.
     */
    public static String abbrev(
            String  s,
            int     abbrevPos,
            boolean escapeNewLines,
            String  abbrevStr,
            int     maxLength
        )
    { return Abbrev.print(s, abbrevPos, escapeNewLines, abbrevStr, maxLength); }

    /**
     * Convenience Method.
     * <BR />Parameter: {@code spaceBeforeAbbrev} set to {@code FALSE}
     * <BR />Abbreviates: Default ellipsis ({@code '...'}) are placed at the end of the
     * {@code String}
     * @see #abbrev(String, boolean, boolean, String, int)
     */
    public static String abbrevEnd(String s, boolean escapeNewLines, int maxLength)
    { return Abbrev.print(s, false, escapeNewLines, null, maxLength); }

    /**
     * This will abbreviate any {@code String} using either the ellipsis ({@code '...'}), or some
     * other use provided abbreviation-{@code String}, if the provided {@code String} is longer 
     * than {@code 'maxLength'}.  If the returned-{@code String} is, indeed, abbreviated then the
     * elliptical-abbreviation {@code String} will be placed <I>at the end of the
     * returned-{@code String}</I>
     *
     * <BR /><BR />You have the option of asking that new-line characters ({@code '\n'}) be
     * escaped into the two-character {@code String: "\\n"}.  This optional is provided so that
     * the output may fit on a single-line, for readability purposes.  It will look somewhat like
     * an escaped {@code JSON} file, which also substitues {@code '\n'} characters for the
     * 'escaped' version {@code "\\n"}.  <I>Note that when this occurs, the replaced-{@code String}
     * actually only contains two characters, <B>not three,</B> since the first back-slash your are
     * looking right here is, itself, an escape character!</I>
     * 
     * @param s This may be any Java (non-null) {@code String}
     *
     * @param spaceBeforeAbbrev This ensures that for whatever variant of ellipsis being used, the
     * space-character is inserted directly before appending the ellipsis {@code "..."} or the
     * user-provided {@code 'abbrevStr'}.
     *
     * @param escapeNewLines <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL>
     * @param abbrevStr <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL>
     *
     * @return If the input {@code String} has a <I>length less-than {@code 'maxLength'}</I>, then
     * it is returned, unchanged.  If the input contained new-line characters, and you have 
     * requested to escape them, that replacement is performed first (which makes the original 
     * {@code String}} longer).  Then, if the {@code String} is longer than {@code 'maxLength'},
     * it is abbreviated, and either the default ellipsis <I>or the user-provided
     * {@code 'abbrevStr'}</I> are are appended to the end and returned.
     *
     * @throws IllegalArgumentException If the value for {@code 'maxLength'} is negative, or if it
     * is less than the length of the abbreviation plus the value of {@code 'spaceBeforeAbbrev'}.
     * <BR /><BR />Specifically, if {@code 'maxLength'} isn't even long enough to fit the abbreviation
     * itself, then this exception will throw.
     */
    public static String abbrev(
            String  s,
            boolean spaceBeforeAbbrev,
            boolean escapeNewLines,
            String  abbrevStr,
            int     maxLength
        )
    { return Abbrev.print(s, spaceBeforeAbbrev, escapeNewLines, abbrevStr, maxLength); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviated List Printing
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'}
     * @see #printListAbbrev(Iterable, IntTFunction, int, int, boolean, boolean, boolean)
     */
    public static <ELEM> String printListAbbrev(
            Iterable<ELEM> list, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText,
            boolean printNulls, boolean showLineNumbers
        )
    {
        return PrintListAbbrev.print(
            list, (int i, Object o) -> o.toString(), lineWidth, indentation,
            seeEscapedNewLinesAsText, printNulls, showLineNumbers
        );
    }

    /**
     * <EMBED CLASS=defs DATA-LIST_TYPE=Array>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION>
     * @param list Any iterable-list of Java Object's
     * @param listItemPrinter <EMBED CLASS='extenal-html' DATA-FILE-ID=SP_PLA_LIST_ITEM_PR>
     * @param lineWidth <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_LINE_WIDTH>
     * @param indentation <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_INDENTATION>
     * @param seeEscapedNewLinesAsText <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SEE_ESC_NL>
     * @param printNulls <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_PRINT_NULLS>
     * @param showLineNumbers <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SHOW_LNUMS>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_RETURNS>
     * @see StringParse#zeroPad10e2(int)
     * @see #abbrevEndRDSF(String, int, boolean)
     * @see StringParse#nChars(char, int)
     * @see StringParse#trimLeft(String)
     */
    public static <ELEM> String printListAbbrev(
            Iterable<ELEM>                      list,
            IntTFunction<? super ELEM, String>  listItemPrinter,
            int                                 lineWidth,
            int                                 indentation,
            boolean                             seeEscapedNewLinesAsText,
            boolean                             printNulls,
            boolean                             showLineNumbers
        )
    {
        return PrintListAbbrev.print(
            list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText,
            printNulls, showLineNumbers
        );
    }

    /**
     * Convenience Method.
     * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'}
     * @see #printListAbbrev(Object[], IntTFunction, int, int, boolean, boolean, boolean)}
     */
    public static <ELEM> String printListAbbrev(
            ELEM[]  arr,
            int     lineWidth,
            int     indentation,
            boolean seeEscapedNewLinesAsText,
            boolean printNulls,
            boolean showLineNumbers
        )
    {
        return PrintListAbbrev.print(
            arr, (int i, Object o) -> o.toString(), lineWidth, indentation,
            seeEscapedNewLinesAsText, printNulls, showLineNumbers
        );
    }

    /**
     * <EMBED CLASS=defs DATA-LIST_TYPE=Array>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION>
     * @param list Any iterable-list of Java Object's
     * @param listItemPrinter <EMBED CLASS='extenal-html' DATA-FILE-ID=SP_PLA_LIST_ITEM_PR>
     * @param lineWidth <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_LINE_WIDTH>
     * @param indentation <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_INDENTATION>
     * @param seeEscapedNewLinesAsText <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SEE_ESC_NL>
     * @param printNulls <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_PRINT_NULLS>
     * @param showLineNumbers <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_SHOW_LNUMS>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_RETURNS>
     * @see StringParse#zeroPad10e2(int)
     * @see #abbrevEndRDSF(String, int, boolean)
     * @see StringParse#trimLeft(String)
     */
    public static <ELEM> String printListAbbrev(
            ELEM[]                              list,
            IntTFunction<? super ELEM, String>  listItemPrinter,
            int                                 lineWidth,
            int                                 indentation,
            boolean                             seeEscapedNewLinesAsText,
            boolean                             printNulls,
            boolean                             showLineNumbers
        )
    {
        return PrintListAbbrev.print(
            list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText,
            printNulls, showLineNumbers
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Line(s) of Text
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will return the complete text-lines of character data for the line identified by
     * token-substring position parameters {@code pos} and {@code len}.  This method will search,
     * in the left-direction (decreasing {@code String} index) for the first new-line character
     * identified. It will also search, starting at position {@code pos + len}, for the first
     * new-line character in the right-direction (increasing {@code String} index).
     * 
     * <BR /><BR />If the token-substring identified by {@code s.substring(pos, len)} itself
     * contains any new-line characters, these will neither affect the prepended, nor the
     * post-pended search {@code String}.  To be precise, any newline characters between
     * {@code 'pos'} and {@code 'len'} will be irrelevant to the left-wards and right-wards
     * newlines searches for new-line characters.
     * 
     * @param s This may be any valid Java {@code String}.  It ought to be some variant of a
     * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both
     * directions, left and right</I> - from parameter {@code int 'pos'} and parameter
     * {@code int 'len'}
     * 
     * @param pos This is a position in the input-parameter {@code String 's'}.  The nearest
     * {@code '\n'} (new-line) character, <I>to the left</I> of this position, will be found and
     * identified.  If the {@code char} at {@code s.charAt(pos)} is, itself, a {@code '\n'}
     * (newline) character, then no left-direction search will be performed.  The left-most
     * position of the returned substring would then be {@code pos + 1}.
     * 
     * @param len The search for the 'right-most' {@code '\n'} (newline-character) will begin at
     * position {@code 'len'}.  If the character at {@code s.charAt(pos + len)} is, itself, a 
     * new-line character, then no right-direction search will be performed.  The right-most
     * position of the returned substring would be {@code pos + len - 1}.
     * 
     * @param unixColorCode If this {@code String} is null, it will be ignored.  If this
     * {@code String} is non-null, it will be inserted before the "Matching {@code String}"
     * indicated by the index-boundaries {@code pos} <I>TO</I> {@code pos + len}.
     * 
     * <BR /><BR /><B>NOTE:</B> No Validity Check shall be performed on this {@code String}, and
     * the user is not obligated to provide a {@link C} valid UNIX Color-Code {@code String}.
     * Also, a closing {@code C.RESET} is inserted after the terminus of the match.
     * 
     * @return The {@code String} demarcated by the first new-line character PLUS 1
     * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1
     * <I><B>AFTER</I></B> index {@code pos + len}.
     * 
     * <BR /><BR /><B>NOTE:</B> The above does mean, indeed, that the starting and ending
     * new-lines <B>WILL NOT</B> be included in the returned {@code String}.
     * 
     * <BR /><BR /><B>ALSO:</B> Also, if there are no new-line characters before position 
     * {@code 'pos'}, then every character beginning at position zero will be included in the
     * returned {@code String} result.  Also, if there are no new-line characters after position
     * {@code pos + len} then every character after position {@code pos + len} will be appended to
     * the returned {@code String} result.
     * 
     * @throws StringIndexOutOfBoundsException If either {@code 'pos'}, or {@code 'pos + len'} are
     * not within the bounds of the input {@code String 's'}
     * 
     * @throws IllegalArgumentException If the value passed to parameter {@code 'len'} is zero or
     * negative.
     */
    public static String lineOrLines(String s, int pos, int len, String unixColorCode)
    {
        if ((pos >= s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException(
            "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end " +
            "of String 's', which has length [" + s.length() + "]"
        );

        if (len <= 0) throw new IllegalArgumentException
            ("The value passed to parameter 'len' [" + len + "], may not be negative.");

        if ((pos + len) > s.length()) throw new StringIndexOutOfBoundsException(
            "The total of parameter 'pos' [" + pos + "], and parameter 'len' [" + len + "], is: " +
            "[" + (pos + len) + "].  Unfortunately, String parameter 's' only has length " +
            "[" + s.length() + "]"
        );

        int linesStart, linesEnd, temp;

        if (pos == 0)                                           linesStart  = 0;
        else if (s.charAt(pos) == '\n')                         linesStart  = pos + 1; 
        else if ((temp = StrIndexOf.left(s, pos, '\n')) != -1)  linesStart  = temp + 1;
        else                                                    linesStart  = 0;

        if ((pos + len) == s.length())                          linesEnd    = s.length();
        else if (s.charAt(pos + len) == '\n')                   linesEnd    = pos + len;
        else if ((temp = s.indexOf('\n', pos + len)) != -1)     linesEnd    = temp;
        else                                                    linesEnd    = s.length();

        /*
        // VERY USEFUL FOR DEBUGGING.  DO NOT DELETE...
        // NOTE: This method is the one that GREP uses.
        System.out.println("s.charAt(pos)\t\t= "    + "[" + s.charAt(pos) + "]");
        System.out.println("s.charAt(pos+len)\t= "  + "[" + s.charAt(pos+len) + "]");
        System.out.println("s.length()\t\t= "       + s.length());
        System.out.println("pos\t\t\t= "            + pos);
        System.out.println("pos + len\t\t= "        + (pos + len));
        System.out.println("linesStart\t\t= "       + linesStart);
        System.out.println("linesEnd\t\t= "         + linesEnd);
        */

        return  (unixColorCode != null)
            ?   s.substring(linesStart, pos) + 
                unixColorCode + s.substring(pos, pos + len) + RESET + 
                s.substring(pos + len, linesEnd)
            :   s.substring(linesStart, linesEnd);
                /*
                OOPS.... For Posterity, this shall remain, here, but commented
                s.substring(linesStart, pos) + 
                s.substring(pos, pos + len) + 
                s.substring(pos + len, linesEnd);
                */
    }

    /**
     * This will return the complete text-line of character data from 'inside' the input-parameter
     * {@code String s}.  The meaning of {@code 'complete text-line'}, in this method, is that any
     * and all character data between the first {@code '\n'} (new-line character) when scanning
     * towards <I>the right</I> (increasing {@code String}-index) and the first {@code '\n'}
     * character when scanning towards <I>the left</I> (decreasing index) constitutes
     * {@code 'a line'} (of text-data).
     * 
     * <BR /><BR />This scan shall for the left-most and right-most new-line shall begin at 
     * {@code String}-index parameter {@code pos}.  If either the left-direction or
     * right-direction scan does not find any new-line characters, then start and end indices of
     * the returned line of text shall be demarcated by input-{@code String} index {@code '0'} and
     * index {@code String.length()}, <I><B>respectively</B></I>
     * 
     * @param s This may be any valid Java {@code String}.  It ought to be some variant of a
     * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both
     * directions, left and right</I> - from parameter {@code int 'pos'}.
     * 
     * @param pos This is a position in the input-parameter {@code String 's'}.  The nearest
     * new-line character both to the left of this position, and to the right, will be found and
     * identified. If the character at {@code s.charAt(pos)} is itself a newline {@code '\n'}
     * character, then <I>an exception shall throw</I>.
     * 
     * @return The {@code String} identified by the first new-line character PLUS 1
     * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1
     * <I><B>AFTER</I></B> index {@code 'pos + len'}.
     * 
     * <BR /><BR /><B>NOTE:</B> The above means, that the starting and ending new-lines,
     * themselves, will not be included in the {@code String} that is returned.
     * 
     * <BR /><BR /><B>ALSO:</B> Also, if there are no new-line characters before position 
     * {@code 'pos'}, then every character beginning at position zero will be included in the
     * returned {@code String} result.  Also, if there are no new-line characters after position
     * {@code 'pos + len'} then every character after position {@code 'pos + len'} will be appended
     * to the returned {@code String} result.
     * 
     * @throws StringIndexOutOfBoundsException If {@code 'pos'} is not within the bounds of the 
     * input {@code String 's'}
     * 
     * @throws IllegalArgumentException If the character in {@code String 's'} at position
     * {@code 'pos'} is a newline {@code '\n'}, itself.
     */
    public static String line(String s, int pos)
    {
        if ((pos > s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException(
            "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end of " +
            "String 's', which has length [" + s.length() + "]"
        );

        if (s.charAt(pos) == '\n') throw  new IllegalArgumentException(
            "The position-index for string-parameter 's' contains, itself, a new line character " +
            "'\\n.'  This is not allowed here."
        );

        int lineStart, lineEnd;

        // Prevents StrIndexOf from throwing StringINdexOutOfBounds
        if (pos == 0) lineStart = 0;

        // Also prevent lineStart equal-to '-1'
        else if ((lineStart = StrIndexOf.left(s, pos, '\n')) == -1) lineStart = 0;

        // Prevent lineEnd equal to '-1'
        if ((lineEnd = s.indexOf('\n', pos)) == -1) lineEnd = s.length();

        // if this is the first line, there was no initial '\n', so don't skip it!
        return (lineStart == 0)

            // This version returns the String from the position-0 (Pay Attention!)
            ? s.substring(0, lineEnd)

            // This version simply eliminates the '\n' that is in the directly-preceeding character
            : s.substring(lineStart + 1, lineEnd);
    }

    /**
     * This will retrieve the first {@code 'n'} lines of a {@code String} - where a line is defined
     * as everything up to and including the next newline {@code '\n'} character.
     * 
     * @param s Any java {@code String}.
     * 
     * @param n This is the number of lines of text to retrieve.
     * 
     * @return a substring of s where the last character in the {@code String} is a {@code '\n'}.
     * The last character should be the nth {@code '\n'} character found in s.  If there is no such
     * character, then the original {@code String} shall be returned instead.
     * 
     * @throws NException This exception shall throw if parameter {@code 'n'} is less than 1, or
     * longer than {@code s.length()}.
     */
    public static String firstNLines(String s, int n)
    {
        NException.check(n, s);
        int pos = StrIndexOf.nth(s, n, '\n');

        if (pos != -1)  return s.substring(0, pos + 1);
        else            return s;
    }

    /**
     * This will retrieve the last 'n' lines of a {@code String} - where a line is defined as
     * everything up to and including the next newline {@code '\n'} character.
     * 
     * @param s Any java {@code String}.
     * 
     * @param n This is the number of lines of text to retrieve.
     * 
     * @return a substring of {@code 's'} where the last character in the {@code String} is a
     * new-line character {@code '\n'}, and the first character is the character directly before
     * the nth newline {@code '\n'} found in {@code 's'} - starting the count at the end of the
     * {@code String}.  If there is no such substring, then the original {@code String} shall be
     * returned.
     * 
     * @throws NException This exception shall throw if {@code 'n'} is less than 1, or longer
     * {@code s.length()}.
     */
    public static String lastNLines(String s, int n)
    {
        NException.check(n, s);
        int pos = StrIndexOf.nthFromEnd(s, n, '\n');

        if (pos != -1)  return s.substring(pos + 1);
        else            return s;
    }

    /**
     * This is used for "trimming each line" of an input {@code String}.  Generally, when dealing
     * with HTML there may be superfluous white-space that is useful in some places, but not
     * necessarily when HTML is copied and pasted to other sections of a page (or to another page,
     * altogether).  This will split a {@code String} by new-line characters, and then trim each
     * line, and afterward rebuild the {@code String} and return it. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>CRLF Issues:</B>
     * 
     * <BR />This will only split the {@code String} using the standard {@code '\n'} character.  If
     * the {@code String} being used uses {@code '\r'} or {@code '\n\r'}, use a different trim
     * method.
     * 
     * @param str This may be any {@code String}.  It will be split by new-line characters
     * {@code '\n'}
     * 
     * @return Returns the rebuilt {@code String}, with each line having a {@code String.trim();}
     * operation performed.
     */
    public static String trimEachLine(String str)
    {
        StringBuilder sb = new StringBuilder();

        for (String s : str.split("\\n"))

            if ((s = s.trim()).length() == 0)   continue;
            else                                sb.append(s + '\n');

        return sb.toString().trim();
    }

    /**
     * Interprets an input {@code String} as one which was read out of a Text-File.  Counts the
     * number of new-line ({@code '\n'}) characters between {@code String} indices {@code '0'} and
     * {@code 'pos'}
     * 
     * <BR /><BR />This is intended be the Line-Number where {@code String}-Index parameter
     * {@code 'pos'} is located inside the {@code 'str'} (presuming {@code 'str'} was retrieved
     * from a Text-File).
     * 
     * @param str Any Java {@code String}, preferably one with multiple lines of text.
     * @param pos Any valid {@code String}-Index that occurs ithin {@code 'str'}
     * 
     * @return The Line-Number within Text-File parameter {@code 'str'} which contains
     * {@code String}-Index parameter {@code 'pos'}
     * 
     * @throws StringIndexOutOfBoundsException If integer-parameter {@code 'pos'} is negative or
     * past the length of the {@code String}-Parameter {@code 'str'}.
     * 
     * @see #lineNumberSince(String, int, int, int)
     */
    public static int lineNumber(String str, int pos)
    {
        if (pos < 0) throw new StringIndexOutOfBoundsException
            ("The number provided to index parameter 'pos' : [" + pos + "] is negative.");

        if (pos >= str.length()) throw new StringIndexOutOfBoundsException(
            "The number provided to index parameter 'pos' : [" + pos + "] is greater than the " +
            "length of the input String-Parameter 'str' [" + str.length() + "]."
        );

        int lineNum = 1;

        for (int i=0; i <= pos; i++) if (str.charAt(i) == '\n') lineNum++;

        return lineNum;
    }

    /**
     * This methe may be used, iteratively, inside of a loop for finding the location of any
     * subsequent {@code String}-Index within a Text-File, based on the information obtained from
     * a previous Line-Number retrieval.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Use inside For-Loop:</B>
     * 
     * <BR />This method is designed to be used within a {@code 'for'} or {@code 'while'} loop.  
     * Though it is true that the exception-check which occurs inside this method is superfluous
     * and redundant, the cost incurred by the two {@code if}-statements is minimal.  These checks
     * are used here, in the code, primarily for readability.
     * 
     * <BR /><BR />If maximum efficiency is needed, then copy and paste the bottom two lines of
     * code into your editor, and use that instead, without the exception-checks.
     * 
     * <BR />In the example below, it should be noted how to use both methods to iterate through
     * the line numbers in a Text-File, efficiently.
     * 
     * <DIV CLASS=EXAMPLE>{@code
     * 
     * int[]    posArr      = findIndices(myString, "Raindrops on Roses", "Whiskers on Kittens");
     * int      lineNumber  = StrPrint.lineNumber(myString, posArr[0]);
     * int      prevPos     = posArr[0];
     * 
     * System.out.println("There is a match on line: " + lineNumber);
     * 
     * for (int i=1; i < posArr.length; i++)
     * {
     *      lineNumber = StrPrint.lineNumberSince(myString, posArr[i], lineNumber, prevPos);
     *      System.out.println("There is a match on line: " + lineNumber);
     * 
     *      prevPos = posArr[i];
     * }
     * }</DIV>
     * 
     * @param str Any Java {@code String}.  This {@code String} will be interpreted as a Text-File
     * whose newline characters ({@code '\n'} chars) represent lines of text.
     * 
     * @param pos Any valid {@code String}-index within {@code 'str'}
     * 
     * @param prevLineNum This should be the Line-Number that contains the {@code String}-index
     * {@code 'prevPos'}
     * 
     * @param prevPos This may be any index contained by {@code String} parameter {@code 'str'}.
     * It is expected that this parameter be an index that occured on Line-Number
     * {@code 'prevLineNum'} of the Text-File {@code 'str'}
     * 
     * @return The Line-Number within Text-File parameter {@code 'str'} that contains
     * {@code String}-index {@code 'pos'}
     * 
     * @throws IllegalArgumentException If {@code 'pos'} is less than or equal to
     * {@code 'prevPos'}, or if {@code 'prevLineNum'} is less than zero.
     * 
     * @see #lineNumber(String, int)
     */
    public static int lineNumberSince(String str, int pos, int prevLineNum, int prevPos)
    {
        if (pos <= prevPos) throw new IllegalArgumentException(
            "The number provided to index parameter 'pos' : [" + pos + "] is less than or equal " +
            "to previous-match index-parameter prevPos : [" + prevPos + "]"
        );

        if (prevLineNum < 0) throw new IllegalArgumentException(
            "You have provided a negative number to Line-Number parameter 'prevLineNum' : " +
            "[" + prevLineNum + "]"
        );

        for (int i = (prevPos + 1); i <= pos; i++) if (str.charAt(i) == '\n') prevLineNum++;

        return prevLineNum;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviation: Line-Length **AND** Number of Lines
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method allows for printing an abbreviation of a {@code String} such that
     * <B STYLE='color: red;'><I>BOTH</I></B> the number of lines (height),
     * <B STYLE='color: red;'><I>AND</I></B> the length of each line of text (width) can both be
     * abbreviated.  There is even a third abbreviation that is possible, and that is where 
     * blank-links can be compacted / flattened first (before the abbreviation process starts).
     * 
     * <BR /><BR />This method is being used for printing JSON-Response Objects that contain large
     * HTML-Page {@code String's}.  Primarily, if you want to see a message, but do not want
     * hundreds or even thousands of lines of HTML blasted across your terminal, then this method is
     * for you!
     * 
     * <BR /><BR />The package {@code Torello.Browser's} Web-Sockets Communications is making use
     * of this for printing Chrome-Browser Messages to the terminal.
     * 
     * @param s Any Java {@code String}
     * 
     * @param horizAbbrevStr If you have a specific Abbreviation-{@code String} that you would like
     * to see used in Horizontally-Abbreviated Lines, please pass it here.
     * 
     * <BR /><BR />Note that this value is directly passed to the {@code 'abbrevStr'} parameters
     * in the Standard {@code String}-Abbreviation methods.  This means that when this parameter is
     * null, it will be ignored - <I>and if any horizontal (line-length) abbreviattions occur, then
     *  the 'Default-Abbreviation {@code String}' {@code "..."} will be used</I>.
     * 
     * <BR ><BR />Also note that if parameter {@code 'maxLineLength'} is passed null, then lines of
     * text will not be shortened.  In that case, each line of text will retain its exact length 
     * that occured prior to the internal {@code String.split()} invocation.
     * 
     * @param maxLineLength If you would like to shorten each line of text which is appended to the
     * returned {@code String}, then pass a positive value to this parameter.
     * 
     * <BR /><BR />This parameter may be null, and if it is, it will be ignored.  In such cases, 
     * individual lines of text will retain their original length.
     * 
     * @param maxNumLines This is the maximum number of lines of text that will appear in the
     * returned {@code String}.  Note, under normal operation, if this parameter is passed 
     * {@code '3'}, then there will be exactly three lines of text.  Furthermore there will be
     * exactly {@code '2'} newline {@code '\n'} characters.
     * 
     * @param compactConsecutiveBlankLines When this parameter is passed {@code TRUE}, any 
     * series of Empty-Lines, or lines only containing White-Space will be compacted to a single 
     * line of text that simply states {@code "[Compacted 10 Blank Lines]"} (or however many 
     * White-Space-Only Lines were actually compacted, if that number isn't {@code '10'})
     * 
     * @return The modified {@code String}.
     * 
     * @throws IllegalArgumentException If parameter {@code 'maxNumLines'} is less than 3.  The
     * returned {@code String} must be long enough to keep the first line, the last line and the
     * abbreviation note.
     * 
     * <BR /><BR />This exception will also throw if the internal invocation of the standard 
     * {@code String}-abbreviation method is passed a {@code 'maxLineLength'} that is less than
     * the minimum line-length requirements for a successful horizontal abbreviation.
     * 
     * <BR /><BR />Finally, this exception throws if {@code 'maxLineLength'} and
     * {@code 'maxNumLines'} are both passed null, and {@code 'compactConsecutiveBlankLines'}.
     * This scenario is considered an error-case because there it would exact a situation where 
     * there is nothing for this method to do.
     */
    public static String widthHeightAbbrev(
            final String    s,
            final String    horizAbbrevStr,
            final Integer   maxLineLength,
            final Integer   maxNumLines,
            final boolean   compactConsecutiveBlankLines
        )
    {
        return VertAndHorizAbbrev.print
            (s, horizAbbrevStr, maxLineLength, maxNumLines, compactConsecutiveBlankLines);
    }
}