package Torello.HTML.Tools.Images;

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

import java.awt.image.BufferedImage;
import javax.imageio.ImageIO;
import java.util.Base64;
import java.net.URL;

import Torello.Java.Additional.Ret2;

/**
 * An enumeration of the primary image-types available on the internet.
 * 
 * <BR /><BR />This is just an enumerated-type used to ensure proper parameter-requests when
 * downloading images.  The type provides a simple means for storing words such as <code>'jpg,'
 * 'png,' 'gif,' etc...</code> when attempting to download images.
 *
 * @see ImageScrape
 * @see ImageScraper
 */
public enum IF
{
    // ********************************************************************************************
    // ********************************************************************************************
    // The Constants
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Used to indicate a picture using the common {@code '.jpg'} image format.
     * According to a <B>Yahoo! Search</B> link:
     * 
     * <BR /><BR /><CODE> The JPEG file extension is used interchangeably
     * with JPG. JPEG stands for Joint Photographic Experts Group who created the standard. 
     * JPG files have 2 sub-formats, JPG/ Exif (often used in digital cameras and photographic 
     * equipment), and JPG/ JFIF (often used on the World Wide Web).</CODE>
     * 
     * <BR /><BR />What is JPG? What Opens a JPG? Exact Link:
     * 
     * <BR /><BR /><A HREF="http://whatis.techtarget.com/fileformat/JPG-JPEG-bitmap" TARGET=_blank>
     * http://whatis.techtarget.com/fileformat/JPG-JPEG-bitmap</A>
     */
    JPG("jpg", "jpeg"),

    /** 
     * Used to indicate a picture using the common ommon {@code '.gif'} image format.
     * Short for <CODE><B>"Graphics Interchange Format".</B></CODE>
     */
    GIF("gif"),

    /**
     * Used to indicate a picture using the common ommon {@code '.bmp'} image format.
     * Abbreviation of the word <CODE><B>'Bit Map'</B></CODE>
     */
    BMP("bmp"),

    /**
     * Used to indicate a picture using the common {@code '.png'} image format.
     * <CODE><B>PNG</B></CODE> stands for <CODE><B>Portable Network Graphics.</B></CODE>
     * It is an open source file extension for raster graphics files. 
     */
    PNG("png");


    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** This is the actual file-name extension saved as a {@code String}.  */
    public final String extension;

    /**
     * This field is always just null, except for the case of the {@code 'JPG'} Enumeration
     * Constant.  For that Image-Format this simply evaluates to the {@code String 'jpeg'}.
     */
    public final String alternateExtension;

    /**
     * This will parse a {@code 'Base64' String} into two groups using Java's RegEx Tools.
     *
     * <BR /><DIV CLASS=EXAMPLE>{@code
     * import java.util.regex.Matcher;
     * ...
     * 
     * Matcher m = IF.B64_INIT_STRING.matcher(base64String);
     * if (m.find())
     * { ... }
     * }</DIV>
     * 
     * <BR /><BR /><OL CLASS=JDOL>
     * <LI> {@code m.group(1) => } Image Encoding Type-{@code String} ({@code "gif", "jpg",} etc..)
     *      <BR /><BR />
     *      </LI>
     * <LI>{@code m.gropu(2) => } Base 64 Encoded Image-{@code String}
     *      <BR />
     *      </LI>
     * </OL>
     */
    public static final Pattern B64_INIT_STRING = Pattern.compile(
        "^\\s*data:\\s*image\\/\\s*([A-Za-z]{3,4})\\s*;\\s*base64\\s*,(.*)$",
        Pattern.CASE_INSENSITIVE
    );

    private static final IF[] arr = { JPG, GIF, BMP, PNG };


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    // Used for GIF, BMP & PNG
    private IF(String extension)
    {
        this.extension          = extension;
        this.alternateExtension = null;
    }

    // Used for JPG
    private IF(String extension, String alternateExtension)
    {
        this.extension          = extension;
        this.alternateExtension = alternateExtension;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Guess the Extension" Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will extract the file-extension from an image {@code URL}.  Not all images on the
     * internet have {@code URL's} that end with the actual image-file-type.  In that case, or in
     * the case that the {@code 'uriStr'} is a pointer to a non-image-file, {@code 'null'} will
     * be returned.
     * 
     * @param uriStr Is the {@code uri} or File-Name of an image. 
     * 
     * @return If extension has a file-extension that is listed in the {@code IF[]} Array - that
     * file-extension will be returned, otherwise {@code 'null'} will be returned.
     */
    public static IF getGuess(String uriStr)
    {
        if (uriStr == null) return null;

        int pos = uriStr.lastIndexOf(".");

        if (pos == -1) return null;
        if (pos == uriStr.length() - 1) return null;

        String s = uriStr.substring(pos + 1).toLowerCase().trim();

        // The following array is a private & static array defined above
        // NOTE: private static final IF[] arr = { JPG, GIF, BMP, PNG };

        for (int i=0; i < arr.length; i++)

            if (arr[i].extension.equals(s)) return arr[i];

            else if (   (arr[i].alternateExtension != null)
                    &&  (arr[i].alternateExtension.equals(s)))

                return arr[i];

        return null;		
    }

    /**
     * Invokes {@link #getGuess(String)}, and returns the results - <I>unless the returned result
     * would be null, in which case a {@link UnrecognizedImageExtException} is thrown instead</I>.
     * 
     * @param uriStr Is the {@code uri} or File-Name of the image. 
     * 
     * @return The Image-Format of this Image, based on it's File-Name
     * 
     * @throws UnrecognizedImageExtException If the Image-Type cannot be determined (does not match
     * any) based on its File-Name Extension.  ({@code '.jpg', '.png', '.gif'} etc...)
     */
    public static IF guessOrThrow(String uriStr)
    {
        IF ret = getGuess(uriStr);
        if (ret != null) return ret;

        throw new UnrecognizedImageExtException(
            "The URI or File-Name\n" +
            "[" + uriStr + "]\n" +
            "doesn't have a File-Extension that matches any of the recognized Image-Types " +
            "('.jpg', '.png', '.gif' etc...)"
        );
    }

    /**
     * Converts a {@code String} image-extension to an instance this enumerated type.
     * @param extension A valid image-format extension
     * @return An instance of this enumeration, if applicable, or {@code 'null'} otherwise.
     */
    public static IF get(String extension)
    {
        extension = extension.toLowerCase().trim();

        // The following array is a private & static array defined above
        // NOTE: private static final IF[] arr = { JPG, GIF, BMP, PNG };

        for (int i=0; i < arr.length; i++)

            if (arr[i].extension.equals(extension)) return arr[i];

            else if (   (arr[i].alternateExtension != null)
                    &&  (arr[i].alternateExtension.equals(extension)))

                return arr[i];

        return null;
    }

    /**
     * This will retrieve the image name from a {@code java.net.URL} object.
     * 
     * @param url The {@code url} of the image.
     * 
     * @return If this {@code URL} has a file-extension that is listed in the {@code IF[]} Array,
     * that file-extension will be returned, otherwise {@code 'null'} will be returned.
     */
    public static IF getGuess(URL url)
    {
        String f = url.getFile();

        return (f != null) ? getGuess(f) : null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Decode Base-64 String Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This will retrieve a Buffered Image from a {@code String} retrieved from a string that
     * follows this format below.  This is the format usually found inside HTML Image Tags.
     * 
     * <BR /><BR /><B>SPECIFICALLY: </B><SPAN STYLE="color: green;">
     * {@code <IMG SRC="data:image/{png or gif or jpg etc};base64,...">}</SPAN>
     * 
     * <BR /><BR />The ellipsis (...) above represents the actual {@code Base-64} encoded
     * {@code String}.  Many web-sites return HTML image tags with the actual picture/image encoded
     * into a {@code String} and saved inside the {@code 'SRC'} attribute.  This method will decode
     * that image-as-a-{@code String} into a {@code java.awt.image.BufferedImage}
     * 
     * @param base64EncodedImageWithFormat The best way to obtain this {@code String} is to use the
     * command [{@code String encoded = imageTag.AV("src"); }], and pass this variable
     * {@code 'encoded'} to this parameter.  It is important to note that variable
     * {@code 'imageTag'} must be a {@code public class TagNode}, and that {@code TagNode} must:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> Have {@code public final String tok} equal to {@code 'img'}
     *      <BR /><BR />
     *      </LI>
     * 
     * <LI> The {@code <IMG>} represented must have a {@code SRC="..."} which contains a 
     *      {@code Base-64} encoded image.
     *      </LI>
     * </UL>
     * 
     * @return A decoded image that can be saved to file, and an instance of {@code IF} that
     * identifies what type of image was specified.
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code Ret2.a} (BufferedImage):} The Converted Image
     *      <BR /><BR />
     *      </LI>
     * 
     * <LI> {@code Ret2.b} (IF):} The Image Type
     *      </LI>
     * </UL>
     */
    public static Ret2<BufferedImage, IF>
        decodeBase64ToImage(String base64EncodedImageWithFormat)
    {
        // sourceData = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADwCAYAAAA+VemSA...==';
        Matcher m = B64_INIT_STRING.matcher(base64EncodedImageWithFormat);

        if (! m.find()) return null;
 
        String  imageFormatStr      = m.group(1);
        String  base64EncodedImage  = m.group(2);

        IF      imageFormat         = (imageFormatStr != null) ? IF.get(imageFormatStr) : null;

        if (imageFormat == null) return null;

        BufferedImage bi = decodeBase64ToImage(base64EncodedImage, imageFormat);

        if (bi == null) return null;

        return new Ret2<BufferedImage, IF>(bi, imageFormat);
    }

    /**
     * This will decode a {@code Base-64 String} into an image.  Here, the decoder used is the one
     * obtained from a call to: {@code java.util.Base64.getDecoder() }.
     *
     * <BR /><BR /><SPAN CLASS=CopiedJDK>Text copied from class:
     * {@code java.util.Base64}, <B>JDK 1.8</B></SPAN>
     * 
     * <BR /><BR /><B>Basic: </B> Uses "The Base64 Alphabet" as specified in <I><B>Table 1 of RFC
     * 4648 and RFC 2045</B></I> for encoding and decoding operation. The encoder does not add any
     * line feed (line separator) character. The decoder rejects data that contains characters
     * outside the base64 alphabet.
     *
     * @return A decoded image that can be saved to file.
     */
    public static BufferedImage decodeBase64ToImage(String base64EncodedImage, IF imageFormat)
    {
        try
            (ByteArrayInputStream bis = new ByteArrayInputStream
                (Base64.getDecoder().decode(base64EncodedImage)))

            { return ImageIO.read(bis); }

        catch (IOException e) { return null; }
    }

    /**
     * This will decode a base-64 String into an image.  Here, the decoder used is the one obtained
     * from a call to: {@code java.util.Base64.getURLDecoder() }.
     *
     * <BR /><BR /><SPAN CLASS=CopiedJDK>Text copied from class:
     * {@code java.util.Base64}, <B>JDK 1.8</B></SPAN>
     * 
     * <BR /><BR /><B>URL and Filename safe: </B> Uses the "URL and Filename safe Base64 Alphabet"
     * as specified in <B><I>Table 2 of RFC 4648</B></I> for encoding and decoding. The encoder
     * does not add any line feed (line separator) character. The decoder rejects data that
     * contains characters outside the base64 alphabet.
     *
     * @return A decoded image that can be saved to file.
     */
    public static BufferedImage decodeBase64ToImage_V2(String base64EncodedImage, IF imageFormat)
    {
        try
            (ByteArrayInputStream bis = new ByteArrayInputStream
                (Base64.getUrlDecoder().decode(base64EncodedImage)))

            { return ImageIO.read(bis); }

        catch (IOException e) { return null; }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************

    
    /**
     * Convert an instance of this enumerated-type to a {@code String}.
     * @return The image-format extension as a {@code String}.
     */
    public String toString() { return extension; }
}