com.github.aliteralmind.codelet

Enum CodeletType

java.lang.Object

java.lang.Enum<CodeletType>

com.github.aliteralmind.codelet.CodeletType

All Implemented Interfaces:

Serializable, Comparable<CodeletType>

public enum CodeletType
extends Enum<CodeletType>

The type of a single JavaDoc codelet instance.

Author:

Copyright (C) 2014, Jeff Epstein, released under the LPGL 2.1. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Enum Constant Summary

Enum Constants

Enum Constant and Description
CONSOLE_OUT {@.codelet.out}: A taglet that displays the example code's console output (via java.lang.System.out).
FILE_TEXT {@.file.textlet}: A taglet that displays the contents of a plain text file.
SOURCE_AND_OUT {@.codelet.and.out}: A taglet that displays the example code's source code and console output.
SOURCE_CODE {@.codelet}: A taglet that displays the example code's source code.

Method Summary

Methods

Modifier and Type	Method and Description
void	crashIfForbiddenValue(CodeletType e_rqd, String s_thisEnumsVarNm, Object o_xtraInfo) If an CodeletType is a forbidden value, crash.
void	crashIfNotRequiredValue(CodeletType e_rqd, String s_thisEnumsVarNm, Object o_xtraInfo) If an CodeletType is not a required value, crash.
String	getDefaultLineProcNamePrefix() The default prefix for Customizers of this type.
String	getName() The name of this taglet, as used in JavaDoc.
boolean	isConsoleOut() Is this CodeletType equal to CONSOLE_OUT?.
boolean	isFileText() Is this CodeletType equal to FILE_TEXT?.
boolean	isNameEqualTo(String name) Is a string equal to this taglet type's name?.
boolean	isSourceAndOut() Is this CodeletType equal to SOURCE_AND_OUT?.
boolean	isSourceCode() Is this CodeletType equal to SOURCE_CODE?.
static CodeletType	newTypeForTagletName(String name, String name_varName) Get a new CodeletType whose name is equal to a string value.
static CodeletType	valueOf(String name) Returns the enum constant of this type with the specified name.
static CodeletType[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

SOURCE_CODE

public static final CodeletType SOURCE_CODE

{@.codelet}: A taglet that displays the example code's source code.

This sets

1. getName() to ".codelet"
2. getDefaultLineProcNamePrefix() to "getSourceConfig_"

{@.codelet}: Format

{@.codelet fully.qualified.ClassName[:customizerFunction()]}

The customizer portion is optional, but when provided, must be preceded by a percent sign ('%').

Examples:

{@.codelet fully.qualified.examples.ExampleClassName}

Prints out all lines in (assuming Windows)
fully\qualified\examples\ExampleClassName.java
Where "fully" is in the example-code base directory as configured.

{@.codelet fully.qualified.examples.ExampleClassName:lineRange(1, false, "text in start line", 1, false, "text in end line")}

Same as above, but only displays a portion of the lines, starting and ending with lines that contain specific text (inclusive).

See Also:

CONSOLE_OUT, SOURCE_AND_OUT, FILE_TEXT, isSourceCode(), SourceCodeProcessor, SourceCodeTemplate, CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH

CONSOLE_OUT

public static final CodeletType CONSOLE_OUT

{@.codelet.out}: A taglet that displays the example code's console output (via java.lang.System.out).

This sets

1. getName() to ".codelet.out"
2. getDefaultLineProcNamePrefix() to "getConsoleOutConfig_"

{@.codelet.out}: Format

{@.codelet.out fully.qualified.ClassName[("Command line params", false, -1)][:customizerFunction()]}

• The command-line parameters are optional. When not provided, an empty string array is passed to the example-code's main function. When provided, it must be formatted as specified by
  com.github.xbn.util.SimpleMethodSignature.newFromStringAndDefaults
• The customizer portion is optional.

Examples:

{@.codelet.out fully.qualified.examples.ExampleClassName}

ReplacedInEachInput the taglet with the entire console output.

{@.codelet fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params")}

Same as above, but passes a five-element string array to the main function.

See Also:

SOURCE_CODE, isConsoleOut(), ConsoleOutProcessor, ConsoleOutTemplate, CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH

SOURCE_AND_OUT

public static final CodeletType SOURCE_AND_OUT

{@.codelet.and.out}: A taglet that displays the example code's source code and console output.

This sets

1. getName() to ".codelet.and.out"
2. getDefaultLineProcNamePrefix() to "getSourceConfig_"

{@.codelet.and.out}: Format

{@.codelet.and.out fully.qualified.ClassName[("Command line params", false, -1)][:customizerFunction()]}

See the format requirements for both {@.codelet} and {@.codelet.out} for examples.

{@.codelet.and.out fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params"):customizerFunction()}

is essentially equal to

{@.codelet fully.qualified.examples.ExampleClassName:customizerFunction()}{@.codelet.out fully.qualified.examples.ExampleClassName("command", -1, "line", true, "params")}

A customizer in a {@.codelet.and.out} taglet is only applied to the source code. To also customize the output, use

{@.codelet com.github.aliteralmind.codelet.examples.adder.AdderDemo%customizerForSourceCode()}
{@.codelet.out com.github.aliteralmind.codelet.examples.adder.AdderDemo%customizerForOutput()}

See Also:

SOURCE_CODE, isSourceAndOut(), SourceAndOutProcessor, SourceAndOutTemplate, CodeletBaseConfig#DEFAULT_SRC_CODE_TMPL_PATH

FILE_TEXT

public static final CodeletType FILE_TEXT

{@.file.textlet}: A taglet that displays the contents of a plain text file.

This sets

1. getName() to ".file.textlet"
2. getDefaultLineProcNamePrefix() to "getFileTextConfig_"

{@.file.textlet}: Format

{@.file.textlet path\to\file.txt[:customizerFunction()]}

Replaced with all lines in a plain-text file, such as for displaying an example code's input. The customizer function is optional. The path may be

• absolute,
• relative to the directory in which javadoc.exe was invoked, or,
• relative to the directory of the taglet's enclosing file.

This list also represents the order in which the search occurs.

(New for version 0.1.3): Absolute paths must contain the file separators exactly as required by your system (such as "C:\directory\subdir\file.txt"). Otherwise all single url-slashes ('/') used as file separators are changed to

System.getProperty("file.separator", "\\")

For example, on Microsoft Windows, "java_code/input.txt" is changed to "java_code\input.txt".

A single environment variable may be used to prefix the path. For example:

$<base_directory>/filelets/input.txt

When used, it is required that the first two characters in the path are "$<", followed by the environment variable name, followed by a close sharp ('>'). This environment variable, as returned by either

System.getProperty("base_directory")

or

System.getenv("base_directory")

must be a non-null, non-empty value, and be either a system property or environment variable--not both. (New for version 0.1.3, the idea from Stack Overflow user Unihedron.)

See Also:

SOURCE_CODE, isFileText(), FileTextProcessor, FileTextTemplate, CodeletBaseConfig#DEFAULT_FILE_TEXT_TMPL_PATH

Method Detail

values

public static CodeletType[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (CodeletType c : CodeletType.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static CodeletType valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

getName

public String getName()

The name of this taglet, as used in JavaDoc.

Returns:

For example, if the taglet is
{@.codelet.out my.package.examples.AnExample}
this returns ".codelet.out"

See Also:

newTypeForTagletName(s,s)

getDefaultLineProcNamePrefix

public String getDefaultLineProcNamePrefix()

The default prefix for Customizers of this type.

This is intended to be followed by either the example classes simple name, or the explicitely-provided function-name-postfix for the plain-text file being displayed.

isSourceCode

public final boolean isSourceCode()

Is this CodeletType equal to SOURCE_CODE?.

Returns:

this == SOURCE_CODE

See Also:

isConsoleOut(), isFileText(), isSourceAndOut()

isConsoleOut

public final boolean isConsoleOut()

Is this CodeletType equal to CONSOLE_OUT?.

Returns:

this == CONSOLE_OUT

See Also:

isSourceCode()

isFileText

public final boolean isFileText()

Is this CodeletType equal to FILE_TEXT?.

Returns:

this == FILE_TEXT

See Also:

isSourceCode()

isSourceAndOut

public final boolean isSourceAndOut()

Is this CodeletType equal to SOURCE_AND_OUT?.

Returns:

this == SOURCE_AND_OUT

See Also:

isSourceCode()

crashIfNotRequiredValue

public void crashIfNotRequiredValue(CodeletType e_rqd,
                           String s_thisEnumsVarNm,
                           Object o_xtraInfo)

If an CodeletType is not a required value, crash.

Equal to
EnumUtil.crashIfNotRequiredValue(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo)

See Also:

crashIfForbiddenValue(ert,s,o)

crashIfForbiddenValue

public void crashIfForbiddenValue(CodeletType e_rqd,
                         String s_thisEnumsVarNm,
                         Object o_xtraInfo)

If an CodeletType is a forbidden value, crash.

Equal to
EnumUtil.crashIfForbiddenValue(this, e_rqd, s_thisEnumsVarNm, o_xtraInfo)

See Also:

crashIfNotRequiredValue(ert,s,o)

isNameEqualTo

public boolean isNameEqualTo(String name)

Is a string equal to this taglet type's name?.

Parameters:

name - May not be null.

Returns:

name.equals(getName())

newTypeForTagletName

public static final CodeletType newTypeForTagletName(String name,
                               String name_varName)

Get a new CodeletType whose name is equal to a string value.

Parameters:

name - The name, which must be non-null, and equal to a type's getName().

name_varName - Descriptive name of the name parameter, for the potential error message. Should not be null or empty.

Throws:

IllegalArgumentException - If name is not equal to a known codelet type.