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