001package Torello.JavaDoc;
002
003/**
004 * Print Flags: Flag-Constants for pretty-printing and selecting output to Reflection API
005 * classes' {@code toString(flags)} methods.
006 * 
007 * <EMBED CLASS='external-html' DATA-FILE-ID=PF_EXAMPLE>
008 * 
009 * @see Method#toString(int)
010 * @see Field#toString(int)
011 * @see Constructor#toString(int)
012 * @see EnumConstant#toString(int)
013 * @see AnnotationElem#toString(int)
014 */
015@StaticFunctional(Excused="MAX_STR_LEN", Excuses=Excuse.CONFIGURATION)
016public class PF
017{
018    private PF() { }
019
020    /**
021     * This is the maximum allowed length of lines printed to the output-{@code String}
022     * 
023     * <BR /><BR /><B CLASS=JDDescLabel>Thread Un-Safe Configuration:</B>
024     * 
025     * <BR />This has <B STYLE='color: red;'>NOT</B> been declared <B>{@code 'final'}</B>, and it
026     * may be changed to anything you wish, using the setter, {@link #setMaxStrLen(int)}
027     * 
028     * @see #setMaxStrLen(int)
029     */
030    protected static int MAX_STR_LEN = 110;
031
032    /**
033     * Sets the <B>{@code static}</B> configuration field {@link #MAX_STR_LEN}.
034     * 
035     * <BR /><BR /><B CLASS=JDDescLabel>Thread Un-Safe Configuration:</B>
036     * 
037     * <BR />This sets a {@code static} internal field, and it's value will, therefore, be 
038     * reflected across all threads, not just the one in use.
039     * 
040     * @see #MAX_STR_LEN
041     */
042    public static void setMaxStrLen(int maxStrLen)
043    {
044        if (maxStrLen < 10) throw new IllegalArgumentException
045            ("maxStrLen may only be set to a number greater than 10");
046
047        MAX_STR_LEN = maxStrLen;
048    }
049
050    /**
051     * This asks the {@code toString()} method to include JavaDoc comments in its return-value
052     * {@code String}
053     */
054    public static final int JAVADOC_COMMENTS = 0b0001;
055
056    /**
057     * For class {@link Method} and class {@link Constructor} this flag will tell the
058     * {@code toString()} method to include the code-body in its return-value {@code String}.
059     * 
060     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
061
062     * <BR /> If both the flags {@code 'BODY'} and {@code 'BODY_SHORT'} have been applied to a
063     * flag-mask, the {@code 'BODY_SHORT'} flag is the one that will be heeded, and the other
064     * ignored.
065     * 
066     * @see #BODY_SHORT
067     */
068    public static final int BODY = 0b0010;
069
070    /**
071     * For class {@link Method} and class {@link Constructor} this flag will tell the
072     * {@code toString()} method to include an <B STYLE='color: red;'><I>abbreviated</I></B>
073     * code-body in its return-value {@code String}.
074     *
075     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
076
077     * <BR /> If both the flags {@code 'BODY'} and {@code 'BODY_SHORT'} have been applied to a
078     * flag-mask, the {@code 'BODY_SHORT'} flag is the one that will be heeded, and the other
079     * ignored.
080     * 
081     * @see #BODY
082     */
083    public static final int BODY_SHORT = 0b0100;
084
085    /**
086     * This flag will tell the {@code toString(int flags)} method to include UNIX Terminal Color
087     * Codes in its return-value {@code String}.
088     */
089    public static final int UNIX_COLORS = 0b1000;
090
091    /**
092     * Asks that the <B STYLE='color: red;'><CODE>'JOW' - Just One Word</CODE></B> types to
093     * be printed, <B STYLE='color: red;'><I>instead of</I></B> the complete
094     * type-{@code String}.
095     * 
096     * <BR /><BR />Note that there are many cases where both the complete type-{@code String} and
097     * the partial type-{@code String's} are actually identical.  This is due to a short-coming in
098     * the software that has not applied the 'linker' code yet (Java Parser Symbol-Solver).  It
099     * would add significant time-cost, and add very little to the final Tool's output.
100     * 
101     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
102
103     * <BR /> If both the flags {@code 'JOW_ALSO'} and {@code 'JOW_INSTEAD'} have been applied to a
104     * flag-mask, the {@code 'JOW_INSTEAD'} flag is the one that will be heeded, and the other
105     * ignored.
106     * 
107     * @see #JOW_ALSO
108     */
109    public static final int JOW_INSTEAD = 0b00010000;
110
111    /**
112     * Asks that the <B STYLE='color: red;'><CODE>'JOW' - Just One Word</CODE></B> types to
113     * be printed, <B STYLE='color: red;'><I>in addition to</I></B> the complete
114     * type-{@code String}.
115     * 
116     * <BR /><BR />Note that there are many cases where both the complete type-{@code String} and
117     * the partial type-{@code String's} are actually identical.  This is due to a short-coming in
118     * the software that has not applied the 'linker' code yet (Java Parser Symbol-Solver).  It
119     * would add significant time-cost, and add very little to the final Tool's output.
120     * 
121     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
122
123     * <BR /> If both the flags {@code 'JOW_ALSO'} and {@code 'JOW_INSTEAD'} have been applied to a
124     * flag-mask, the {@code 'JOW_INSTEAD'} flag is the one that will be heeded, and the other
125     * ignored.
126     * 
127     * @see #JOW_INSTEAD
128     */
129    public static final int JOW_ALSO = 0b00100000;
130
131    /**
132     * Requests that only three line-numbers be printed when writing an entity's 
133     * {@link Location} object.  The output will include:
134     * 
135     * <BR /><BR /><UL CLASS=JDUL>
136     * <LI><B>{@link Location#signatureStartLine}</B></LI>
137     * <LI><B>{@link Location#jdcStartLine}</B></LI>
138     * <LI><B>{@link Location#bodyStartLine}</B></LI>
139     * </UL>
140     */
141    public static final int BRIEF_LOCATION = 0b01000000;
142}