001/*license*\ 002 Codelet: Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com) 003 004 This software is dual-licensed under the: 005 - Lesser General Public License (LGPL) version 3.0 or, at your option, any later version; 006 - Apache Software License (ASL) version 2.0. 007 008 Either license may be applied at your discretion. More information may be found at 009 - http://en.wikipedia.org/wiki/Multi-licensing. 010 011 The text of both licenses is available in the root directory of this project, under the names "LICENSE_lgpl-3.0.txt" and "LICENSE_asl-2.0.txt". The latest copies may be downloaded at: 012 - LGPL 3.0: https://www.gnu.org/licenses/lgpl-3.0.txt 013 - ASL 2.0: http://www.apache.org/licenses/LICENSE-2.0.txt 014\*license*/ 015package com.github.aliteralmind.codelet; 016 import com.github.xbn.lang.CrashIfObject; 017 import com.github.xbn.util.EnumUtil; 018/** 019 <P>The type of a single JavaDoc codelet instance.</P> 020 021 @author Copyright (C) 2014, Jeff Epstein, released under the LPGL 2.1. <A HREF="http://codelet.aliteralmind.com">{@code http://codelet.aliteralmind.com}</A>, <A HREF="https://github.com/aliteralmind/codelet">{@code https://github.com/aliteralmind/codelet}</A> 022 **/ 023public enum CodeletType { 024 /** 025 <P>{@code {@.codelet}}: A taglet that displays the example code's source code.</P> 026 027 <P>This sets<OL> 028 <LI>{@link #getName() getName}{@code ()} to {@code ".codelet"}</LI> 029 <LI>{@link #getDefaultLineProcNamePrefix() getDefaultLineProcNamePrefix}{@code ()} to {@code "getSourceConfig_"}</LI> 030 </OL></P> 031 032 <H3>{@code {@.codelet}}: Format</H3> 033 034 <P><CODE>{@.codelet <I>fully.qualified.ClassName</I>[:<A HREF="CustomizationInstructions.html#overview">lineProcessorFunction</A>()]}</CODE></P> 035 036 <P>The customizer portion is optional, but when provided, must be preceded by a {@linkplain CodeletInstance#CUSTOMIZER_PREFIX_CHAR percent sign} ({@code '%'}).</P> 037 038 <P><B>Examples:</B></P> 039 040<BLOCKQUOTE>{@code {@.codelet fully.qualified.examples.ExampleClassName}}</BLOCKQUOTE> 041 042 <P>Prints out all lines in (assuming Windows) 043 <BR> {@code fully\qualified\examples\ExampleClassName.java} 044 <BR>Where {@code "fully"} is in the {@linkplain CodeletBaseConfig#EXAMPLE_CLASS_SRC_BASE_DIR example-code base directory} as configured.</P> 045 046<BLOCKQUOTE><CODE>{@.codelet fully.qualified.examples.ExampleClassName:{@link com.github.aliteralmind.codelet.BasicCustomizers#lineRange(CodeletInstance, CodeletType, Integer, Boolean, String, Integer, Boolean, String, String) lineRange}(1, false, "text in start line", 1, false, "text in end line")}</CODE></BLOCKQUOTE> 047 048 <P>Same as above, but only displays a <A HREF="{@docRoot}/overview-summary.html#xmpl_snippet">portion</A> of the lines, starting and ending with lines that contain specific text (inclusive).</P> 049 050 @see #CONSOLE_OUT 051 @see #SOURCE_AND_OUT 052 @see #FILE_TEXT 053 @see #isSourceCode() 054 @see com.github.aliteralmind.codelet.type.SourceCodeProcessor 055 @see com.github.aliteralmind.codelet.type.SourceCodeTemplate 056 @see com.github.aliteralmind.codelet.CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH 057 **/ 058 SOURCE_CODE(".codelet", "getSourceConfig_"), 059 //The value of the second parameter ("getSourceConfig_") must be the 060 //same for both SOURCE_CODE and SOURCE_AND_OUT 061 /** 062 <P>{@code {@.codelet.out}}: A taglet that displays the example code's console output (via <CODE>java.lang.{@link java.lang.System System}.{@link java.lang.System#out out}</CODE>).</P> 063 064 <P>This sets<OL> 065 <LI>{@link #getName() getName}{@code ()} to {@code ".codelet.out"}</LI> 066 <LI>{@link #getDefaultLineProcNamePrefix() getDefaultLineProcNamePrefix}{@code ()} to {@code "getConsoleOutConfig_"}</LI> 067 </OL></P> 068 069 <H3>{@code {@.codelet.out}}: Format</H3> 070 071 <P><CODE>{@.codelet.out <I>fully.qualified.ClassName</I>[("Command line params", false, -1)][:<A HREF="CustomizationInstructions.html#overview">lineProcessorFunction</A>()]}</CODE></P> 072 073 <P><UL> 074 <LI>The command-line parameters are optional. When not provided, an empty string array is passed to the example-code's <A HREF="http://docs.oracle.com/javase/tutorial/getStarted/application/index.html#MAIN">{@code main} function</A>. When provided, it must be formatted as specified by 075 <BR> <CODE>com.github.xbn.util.{@link com.github.aliteralmind.codelet.simplesig.SimpleMethodSignature SimpleMethodSignature}.{@link com.github.aliteralmind.codelet.simplesig.SimpleMethodSignature#newFromStringAndDefaults(Class, Object, String, Class[], Appendable) newFromStringAndDefaults}</CODE> 076 <LI>The customizer portion is optional.</LI> 077 </UL></P> 078 079 <P><B>Examples:</B></P> 080 081<BLOCKQUOTE>{@code {@.codelet.out fully.qualified.examples.ExampleClassName}}</BLOCKQUOTE> 082 083 <P>ReplacedInEachInput the taglet with the entire console output.</P> 084 085<BLOCKQUOTE>{@code {@.codelet fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params")}}</BLOCKQUOTE> 086 087 <P>Same as above, but passes a five-element string array to the main function.</P> 088 089 @see #SOURCE_CODE 090 @see #isConsoleOut() 091 @see com.github.aliteralmind.codelet.type.ConsoleOutProcessor 092 @see com.github.aliteralmind.codelet.type.ConsoleOutTemplate 093 @see com.github.aliteralmind.codelet.CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH 094 **/ 095 CONSOLE_OUT(".codelet.out", "getConsoleOutConfig_"), 096 /** 097 <P>{@code {@.codelet.and.out}}: A taglet that displays the example code's source code and console output.</P> 098 099 <P>This sets<OL> 100 <LI>{@link #getName() getName}{@code ()} to {@code ".codelet.and.out"}</LI> 101 <LI>{@link #getDefaultLineProcNamePrefix() getDefaultLineProcNamePrefix}{@code ()} to {@code "getSourceConfig_"}</LI> 102 </OL></P> 103 104 <H3>{@code {@.codelet.and.out}}: Format</H3> 105 106 <P><CODE>{@.codelet.and.out <I>fully.qualified.ClassName</I>[("Command line params", false, -1)][:customizerFunction()]}</CODE></P> 107 108 <P>See the format requirements for both {@link #SOURCE_CODE {@.codelet}} and {@link #CONSOLE_OUT {@.codelet.out}} for examples.</P> 109 110<BLOCKQUOTE>{@code {@.codelet.and.out fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params"):customizerFunction()}}</BLOCKQUOTE></P> 111 112 <P>is essentially equal to</P> 113 114<BLOCKQUOTE>{@code {@.codelet fully.qualified.examples.ExampleClassName:customizerFunction()}{@.codelet.out fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params")}}</BLOCKQUOTE></P> 115 116 <P>A customizer in a {@code {@.codelet.and.out}} taglet is only applied to the source code. To also customize the output, use</P> 117 118 <P style="font-size: 125%;"><B><CODE>{@.codelet com.github.aliteralmind.codelet.examples.adder.AdderDemo%customizerForSourceCode()} 119 <BR>{@.codelet.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%customizerForOutput()}</CODE></B></P> 120 121 @see #SOURCE_CODE 122 @see #isSourceAndOut() 123 @see com.github.aliteralmind.codelet.type.SourceAndOutProcessor 124 @see com.github.aliteralmind.codelet.type.SourceAndOutTemplate 125 @see com.github.aliteralmind.codelet.CodeletBaseConfig#DEFAULT_AND_OUT_TMPL_PATH CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH 126 **/ 127 SOURCE_AND_OUT(".codelet.and.out", "getSourceConfig_"), 128 //The value of the second parameter ("getSourceConfig_") must be the 129 //same for both SOURCE_CODE and SOURCE_AND_OUT 130 /** 131 <P>{@code {@.file.textlet}}: A taglet that displays the contents of a plain text file.</P> 132 133 <P>This sets<OL> 134 <LI>{@link #getName() getName}{@code ()} to {@code ".file.textlet"}</LI> 135 <LI>{@link #getDefaultLineProcNamePrefix() getDefaultLineProcNamePrefix}{@code ()} to {@code "getFileTextConfig_"}</LI> 136 </OL></P> 137 138 <H3>{@code {@.file.textlet}}: Format</H3> 139 140 <P><CODE>{@.file.textlet <I>path\to\file.txt</I>[:<A HREF="CustomizationInstructions.html#overview">lineProcessorFunction</A>()]}</CODE></P> 141 142 <P>Replaced with all lines in a plain-text file, such as for displaying an example code's input. The path may be<UL> 143 <LI><A HREF="http://docs.oracle.com/javase/tutorial/essential/io/path.html#relative">absolute</A>,</LI> 144 <LI>relative to the directory in which {@code javadoc.exe} was invoked, or,</LI> 145 <LI>relative to the directory of the taglet's {@linkplain CodeletInstance#getEnclosingFile() enclosing file}.</LI> 146 </UL>This list also represents the order in which the search occurs.</P> 147 148 <P>The customizer portion is optional.</P> 149 150 @see #SOURCE_CODE 151 @see #isFileText() 152 @see com.github.aliteralmind.codelet.type.FileTextProcessor 153 @see com.github.aliteralmind.codelet.type.FileTextTemplate 154 @see com.github.aliteralmind.codelet.CodeletBaseConfig#DEFAULT_FILE_TEXT_TMPL_PATH CodeletBaseConfig#DEFAULT_FILE_TEXT_TMPL_PATH 155 **/ 156 FILE_TEXT(".file.textlet", "getFileTextConfig_"); 157 158 private final String tagName; 159 private final String defaultLineProcNamePrefix; 160 /** 161 <P>Construct an {@code CodeletType}.</P> 162 163 @param tag_name The name of the codelet. <I>Should</I> not be {@code null} or empty. Get with {@link #getName() getName}{@code ()} 164 @param default_lineProcNamePrefix The default prefix for Customizers of this type. <I>Should</I> not be {@code null} or empty, and should end with an underscore ({@code '_'}). Get with {@link #getDefaultLineProcNamePrefix() getDefaultLineProcNamePrefix}{@code ()}. 165 @see #SOURCE_CODE 166 **/ 167 CodeletType(String tag_name, String default_lineProcNamePrefix) { 168 tagName = tag_name; 169 defaultLineProcNamePrefix = default_lineProcNamePrefix; 170 } 171 /** 172 <P>The {@linkplain com.sun.javadoc.Tag#name() name} of this taglet, as used in JavaDoc.</P> 173 174 @return For example, if the taglet is 175 <BR> {@code {@.codelet.out my.package.examples.AnExample}} 176 <BR>this returns {@code ".codelet.out"}</P> 177 @see #CodeletType(String, String) CodeletType(s,s) 178 @see #newTypeForTagletName(String, String) newTypeForTagletName(s,s) 179 **/ 180 public String getName() { 181 return tagName; 182 } 183 /** 184 <P>The default prefix for Customizers of this type.</P> 185 186 <P>This is intended to be followed by either the example classes {@linkplain java.lang.Class#getSimpleName() simple name}, or the <I>explicitely-provided</I> function-name-postfix for the plain-text file being displayed.</P> 187 @see #CodeletType(String, String) 188 **/ 189 public String getDefaultLineProcNamePrefix() { 190 return defaultLineProcNamePrefix; 191 } 192 /** 193 <P>Is this {@code CodeletType} equal to {@code SOURCE_CODE}?.</P> 194 195 @return <CODE>this == {@link #SOURCE_CODE}</CODE> 196 197 @see #isConsoleOut() 198 @see #isFileText() 199 @see #isSourceAndOut() 200 **/ 201 public final boolean isSourceCode() { 202 return this == SOURCE_CODE; 203 } 204 /** 205 <P>Is this {@code CodeletType} equal to {@code CONSOLE_OUT}?.</P> 206 207 @return <CODE>this == {@link #CONSOLE_OUT}</CODE> 208 @see #isSourceCode() 209 **/ 210 public final boolean isConsoleOut() { 211 return this == CONSOLE_OUT; 212 } 213 /** 214 <P>Is this {@code CodeletType} equal to {@code FILE_TEXT}?.</P> 215 216 @return <CODE>this == {@link #FILE_TEXT}</CODE> 217 @see #isSourceCode() 218 **/ 219 public final boolean isFileText() { 220 return this == FILE_TEXT; 221 } 222 /** 223 <P>Is this {@code CodeletType} equal to {@code SOURCE_AND_OUT}?.</P> 224 225 @return <CODE>this == {@link #SOURCE_AND_OUT}</CODE> 226 @see #isSourceCode() 227 **/ 228 public final boolean isSourceAndOut() { 229 return this == SOURCE_AND_OUT; 230 } 231 232 /** 233 <P>If an <CODE>CodeletType</CODE> is not a required value, crash.</P> 234 235 <P>Equal to 236 <BR> <CODE>{@link com.github.xbn.util.EnumUtil EnumUtil}.{@link com.github.xbn.util.EnumUtil#crashIfNotRequiredValue(Enum, Enum, String, Object) crashIfNotRequiredValue}(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo)</CODE></P> 237 @see #crashIfForbiddenValue(CodeletType, String, Object) crashIfForbiddenValue(ert,s,o) 238 **/ 239 public void crashIfNotRequiredValue(CodeletType e_rqd, String s_thisEnumsVarNm, Object o_xtraInfo) { 240 EnumUtil.crashIfNotRequiredValue(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo); 241 } 242 /** 243 <P>If an <CODE>CodeletType</CODE> is a forbidden value, crash.</P> 244 245 <P>Equal to 246 <BR> <CODE>{@link com.github.xbn.util.EnumUtil EnumUtil}.{@link com.github.xbn.util.EnumUtil#crashIfForbiddenValue(Enum, Enum, String, Object) crashIfForbiddenValue}(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo)</CODE></P> 247 @see #crashIfNotRequiredValue(CodeletType, String, Object) crashIfNotRequiredValue(ert,s,o) 248 **/ 249 public void crashIfForbiddenValue(CodeletType e_rqd, String s_thisEnumsVarNm, Object o_xtraInfo) { 250 EnumUtil.crashIfForbiddenValue(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo); 251 } 252 /** 253 <P>Is a string equal to <I>this</I> taglet type's name?.</P> 254 255 @param name May not be {@code null}. 256 @return <CODE>name.equals({@link #getName() getName}())</CODE> 257 **/ 258 public boolean isNameEqualTo(String name) { 259 return isNameEqualTo(name, "name"); 260 } 261 private boolean isNameEqualTo(String name, String name_varName) { 262 try { 263 return name.equals(getName()); 264 } catch(RuntimeException rx) { 265 throw CrashIfObject.nullOrReturnCause(name, name_varName, null, rx); 266 } 267 } 268 /** 269 <P>Get a new {@code CodeletType} whose name is equal to a string value.</P> 270 271 @param name The name, which must be non-{@code null}, and equal to a type's {@link #getName() getName}{@code ()}. 272 @param name_varName Descriptive name of the {@code name} parameter, for the potential error message. <I>Should</I> not be {@code null} or empty. 273 @exception IllegalArgumentException If {@code name} is not equal to a known codelet type. 274 **/ 275 public static final CodeletType newTypeForTagletName(String name, String name_varName) { 276 if(CodeletType.SOURCE_CODE.isNameEqualTo(name, name_varName)) { 277 return CodeletType.SOURCE_CODE; 278 } 279 if(CodeletType.CONSOLE_OUT.isNameEqualTo(name, name_varName)) { 280 return CodeletType.CONSOLE_OUT; 281 } 282 if(CodeletType.FILE_TEXT.isNameEqualTo(name, name_varName)) { 283 return CodeletType.FILE_TEXT; 284 } 285 if(CodeletType.SOURCE_AND_OUT.isNameEqualTo(name, name_varName)) { 286 return CodeletType.SOURCE_AND_OUT; 287 } 288 289 throw new IllegalArgumentException(name_varName + " (\"" + name + "\") is not CodeletType.SOURCE_CODE.getName() (\"" + CodeletType.SOURCE_CODE.getName() + "\"), CodeletType.CONSOLE_OUT.getName() (\"" + CodeletType.CONSOLE_OUT.getName() + "\"), CodeletType.FILE_TEXT.getName() (\"" + CodeletType.FILE_TEXT.getName() + "\"), or CodeletType.SOURCE_AND_OUT.getName() (\"" + CodeletType.SOURCE_AND_OUT.getName() + "\")"); 290 } 291};