package Torello.JavaDoc;

import java.io.IOException;
import java.util.Vector;

import Torello.HTML.HTMLNode;

import Torello.HTML.Tools.SyntaxHiLite.HiLiteCache;
import Torello.HTML.Tools.SyntaxHiLite.PygmentsOrg;

/**
 * A simple Functional-Interface allowing a user to swap in any customized, alternate or
 * proprietary Syntax HiLiter to replace the default HiLiter used by this Upgrader Tool.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=HILITER>
 */
@FunctionalInterface
public interface HiLiter
{
    /**
     * This {@code Functional Interface} expects this method to be implemented.  Any HiLiter that
     * would be "plugged into" this Documentation Tool must be able to <B>Pretty-Print HiLite</B>
     * input Source-Code (passed as a {@code java.lang.String}) <I>and return HTML</I>.
     * 
     * <BR /><BR /><B>NOTE:</B> Any Code HiLiter that can operate with this input may be plugged
     * in here.  In order to "Vectorize" HTML, just use the
     * {@code HTMLPage.getPageTokens(String, false)} method.
     *
     * @param code This is the Source-Code as a {@code java.lang.String}
     * 
     * @param codeType This is a short descriptor of what kind of code is being passed.  The most
     * frequent values for this parameter are: {@code 'java', 'html', 'js'} etc...
     * 
     * @param snippetOrComplete This is a {@code boolean} that when {@code TRUE}, indicates that
     * a <B>code-snippet</B> has been passed, and when {@code FALSE} indicates that a <B>complete
     * source code file</B> has been passed.
     * 
     * @return The intention is to return a Vectorized-HTML page (or sub-page) that contains a
     * <B>HiLited &AMP; Pretty-Printed</B> version of the source-code.
     * 
     * @throws IOException This method is not defined, but it is permitted to throw 
     * {@code IOException} - if there have been I/O problems when attempting to transform the
     * source-code.
     *
     * @throws HiLiteException This exception may be used if other problems occur during the
     * transformation process.
     */
    public Vector<HTMLNode> hiLite
        (String code, String codeType, boolean snippetOrComplete)
        throws IOException, HiLiteException;

    /**
     * The Default <B>Code HiLiter</B> uses the package
     * {@code Torello.HTML.Tools.SyntaxHiLite}.
     * 
     * @param cache This is the HiLiter-Cache that <I>may or may not be used</I>.  If this parameter
     * is passed {@code 'null'}, it will be ignored.
     * 
     * @param snippetStyleCode Some of the source-code passed to this {@code HiLiter} will be
     * short <I>code-snippets</I>, while other passed values of source-code will be <I>complete
     * source-code files.</I>  This {@code String} is the {@code 'Style Parameter'} used for
     * code-snippets.
     * 
     * <BR /><BR />You may view the complete-list of valid Style Parameters in use with this
     * HiLiter with {@link PygmentsOrg#getStyleTypes()}.
     * 
     * @param completeStyleCode When the {@code HiLiter} is asked to Hi-Lite and entire source
     * code file, this parameter will be used for a {@code 'Style Parameter'} with the 
     * {@code HiLiter}.
     * 
     * @return An instance of {@code HiLiter} that can be used by the {@code Upgrade} Tool
     * 
     * @throws IllegalArgumentException If invalid Styling-Parameters were passed either to
     * {@code 'snippetStyleCode'} or {@code 'completeStyleCode'}.
     * 
     * @see PygmentsOrg#prettyPrintScrapeToVectorAndSimplify(String, String, String, boolean)
     * @see PygmentsOrg#prettyPrintScrapeToVectorAndSimplify(String, String, String, boolean, HiLiteCache)
     */
    public static HiLiter getDefault(
            final HiLiteCache   cache,
            final String        snippetStyleCode,
            final String        completeStyleCode
        )
    {
        return Torello.HTML.Tools.SyntaxHiLite.JDUExport.JDUHiLiter.getDefault
            (cache, snippetStyleCode, completeStyleCode);
    }

}