package Torello.JavaDoc;

/**
 * Print Flags: Flag-Constants for pretty-printing and selecting output to Reflection API
 * classes' {@code toString(flags)} methods.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PF_EXAMPLE>
 * 
 * @see Method#toString(int)
 * @see Field#toString(int)
 * @see Constructor#toString(int)
 * @see EnumConstant#toString(int)
 * @see AnnotationElem#toString(int)
 */
@StaticFunctional(Excused="MAX_STR_LEN", Excuses=Excuse.CONFIGURATION)
public class PF
{
    private PF() { }

    /**
     * This is the maximum allowed length of lines printed to the output-{@code String}
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Thread Un-Safe Configuration:</B>
     * 
     * <BR />This has <B STYLE='color: red;'>NOT</B> been declared <B>{@code 'final'}</B>, and it
     * may be changed to anything you wish, using the setter, {@link #setMaxStrLen(int)}
     * 
     * @see #setMaxStrLen(int)
     */
    protected static int MAX_STR_LEN = 110;

    /**
     * Sets the <B>{@code static}</B> configuration field {@link #MAX_STR_LEN}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Thread Un-Safe Configuration:</B>
     * 
     * <BR />This sets a {@code static} internal field, and it's value will, therefore, be 
     * reflected across all threads, not just the one in use.
     * 
     * @see #MAX_STR_LEN
     */
    public static void setMaxStrLen(int maxStrLen)
    {
        if (maxStrLen < 10) throw new IllegalArgumentException
            ("maxStrLen may only be set to a number greater than 10");

        MAX_STR_LEN = maxStrLen;
    }

    /**
     * This asks the {@code toString()} method to include JavaDoc comments in its return-value
     * {@code String}
     */
    public static final int JAVADOC_COMMENTS = 0b0001;

    /**
     * For class {@link Method} and class {@link Constructor} this flag will tell the
     * {@code toString()} method to include the code-body in its return-value {@code String}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>

     * <BR /> If both the flags {@code 'BODY'} and {@code 'BODY_SHORT'} have been applied to a
     * flag-mask, the {@code 'BODY_SHORT'} flag is the one that will be heeded, and the other
     * ignored.
     * 
     * @see #BODY_SHORT
     */
    public static final int BODY = 0b0010;

    /**
     * For class {@link Method} and class {@link Constructor} this flag will tell the
     * {@code toString()} method to include an <B STYLE='color: red;'><I>abbreviated</I></B>
     * code-body in its return-value {@code String}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>

     * <BR /> If both the flags {@code 'BODY'} and {@code 'BODY_SHORT'} have been applied to a
     * flag-mask, the {@code 'BODY_SHORT'} flag is the one that will be heeded, and the other
     * ignored.
     * 
     * @see #BODY
     */
    public static final int BODY_SHORT = 0b0100;

    /**
     * This flag will tell the {@code toString(int flags)} method to include UNIX Terminal Color
     * Codes in its return-value {@code String}.
     */
    public static final int UNIX_COLORS = 0b1000;

    /**
     * Asks that the <B STYLE='color: red;'><CODE>'JOW' - Just One Word</CODE></B> types to
     * be printed, <B STYLE='color: red;'><I>instead of</I></B> the complete
     * type-{@code String}.
     * 
     * <BR /><BR />Note that there are many cases where both the complete type-{@code String} and
     * the partial type-{@code String's} are actually identical.  This is due to a short-coming in
     * the software that has not applied the 'linker' code yet (Java Parser Symbol-Solver).  It
     * would add significant time-cost, and add very little to the final Tool's output.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>

     * <BR /> If both the flags {@code 'JOW_ALSO'} and {@code 'JOW_INSTEAD'} have been applied to a
     * flag-mask, the {@code 'JOW_INSTEAD'} flag is the one that will be heeded, and the other
     * ignored.
     * 
     * @see #JOW_ALSO
     */
    public static final int JOW_INSTEAD = 0b00010000;

    /**
     * Asks that the <B STYLE='color: red;'><CODE>'JOW' - Just One Word</CODE></B> types to
     * be printed, <B STYLE='color: red;'><I>in addition to</I></B> the complete
     * type-{@code String}.
     * 
     * <BR /><BR />Note that there are many cases where both the complete type-{@code String} and
     * the partial type-{@code String's} are actually identical.  This is due to a short-coming in
     * the software that has not applied the 'linker' code yet (Java Parser Symbol-Solver).  It
     * would add significant time-cost, and add very little to the final Tool's output.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>

     * <BR /> If both the flags {@code 'JOW_ALSO'} and {@code 'JOW_INSTEAD'} have been applied to a
     * flag-mask, the {@code 'JOW_INSTEAD'} flag is the one that will be heeded, and the other
     * ignored.
     * 
     * @see #JOW_INSTEAD
     */
    public static final int JOW_ALSO = 0b00100000;

    /**
     * Requests that only three line-numbers be printed when writing an entity's 
     * {@link Location} object.  The output will include:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link Location#signatureStartLine}</B></LI>
     * <LI><B>{@link Location#jdcStartLine}</B></LI>
     * <LI><B>{@link Location#bodyStartLine}</B></LI>
     * </UL>
     */
    public static final int BRIEF_LOCATION = 0b01000000;
}