CustomizationInstructions (Codelet)

java.lang.Object
- com.github.xbn.util.lock.AbstractLockable
- - com.github.xbn.util.lock.AbstractOneWayLockable
  - - com.github.aliteralmind.codelet.CustomizationInstructions<T>

All Implemented Interfaces:

Lockable, OneWayLockable
```
public class CustomizationInstructions<T extends CodeletTemplateBase>
extends AbstractOneWayLockable
```
The instructions returned by a Codelet Customizer, which is used by the taglet-processor to modify its output.

Codelet: Customizer: Three parts

A CustomizationInstructions is the object returned by all Codelet Customizers. A CustomizationInstructions is composed of three items: A line filter, alterer, and template.

Codelet: Customizer: Three parts: Part 1: Line filter

A line filter is used to keeping only wanted lines, such as a code snippet, or eliminating lines you define as unwanted. An example is to eliminate the package declaration line and all JavaDoc multi-line comments.
- Raw object: com.github.xbn.linefilter.FilteredLineIterator (set with filter)
- Convenience creators: NewLineFilterFor, NewFilteredLineIteratorFor
Codelet: Customizer: Three parts: 2: Alterer

The all-line alterer modifies each line returned (kept) by the filter. A filter may be applied so it does not start until needed, and expires when complete.
- Raw objects: com.github.xbn.linefilter.AllTextLineAlterer (set with alterer), which is an array of TextLineAlterers (set with orderedAlterers)
- Convenience creators: NewLineAltererFor, NewJDLinkForWordOccuranceNum, NewTextLineAltererFor
Codelet: Customizer: Three parts: 3: Template

The context into which final output text is placed, and whose rendered output is what actually replaces the taglet. Templates may be overridden for an individual taglet (by setting one into template, in a custom customizer), or for all taglets in a JavaDoc file or an entire package (with TemplateOverrides).
- Raw objects: template (set with template) which, at its heart, is a com.github.aliteralmind.templatefeather.FeatherTemplate
Codelet: Customizer: Overview

A "Codelet Customizer" is a function that returns the instructions for tailoring an example code's output. As stated in the overview, common customizations include
- Displaying only a portion of an example's source code: A code snippet.
- Eliminating unwanted lines, such as the package declaration line and all multi-line comments.
- Making the first appearance of a class, function, or object names into a clickable JavaDoc link.
Contents:
- Taglet syntax: A customizer function is "called" by one or more codelet-taglets. Examples:
  - Default function name and class location
  - Defaults with a custom postfix
  - Specifying the class in which the processor function exists
  - Specifying extra parameters for the customizer function
- The customizer function:
  - Examples: A customizer function that
    - Does nothing.
    - Changes a function, constructor, class, or field name to a clickable JavaDoc link.
  - Specifications and
  - Pre-made customizers: BasicCustomizers
  - CustomizationInstructions: The object returned by the customizer function. Made up of three parts: A line filter, alterer, and template
Codelet: Customizer function: Example: A customizer that does nothing

A customizer function that makes (almost) no changes:
```
private static final CustomizationInstructions<SourceCodeTemplate> aCustomizerThatDoesNothing(CodeletInstance instance, CodeletType needed_defaultAlterType)  {
   return  new CustomizationInstructions<SourceCodeTemplate>(instance,
         needed_defaultAlterType).
      defaults(null, null, null, null).build();
}
```
Here is the same function, with documentation on the available debugging parameters:
```
private static final CustomizationInstructions<SourceCodeTemplate> aCustomizerThatDoesNothing(CodeletInstance instance, CodeletType needed_defaultAlterType)  {
   return  new CustomizationInstructions<SourceCodeTemplate>(instance,
         needed_defaultAlterType).
      defaults(
         null, null, //dbgEveryLine and its range
         null,       //dbgAllAltr: on=System.out, off=null
         null).      //dbgTemplate
      build();
}
```
This do-nothing customizer uses all defaults. It
1. Filters no lines,
2. Default alterers as configured.
3. Uses the Default template,
Codelet: Customizer: Requirements

The customizer function has the following requirements:
- Its location (containing class) must be explicitely specified in the taglet, or must exist in one of the following default classes, which are searched in order:
  1. BasicCustomizers,
  2. The enclosing class, if it is a class,
  3. And a class named "zCodeletCustomizers", if one exists in the enclosing package.
- It must be static and
- accessible (it is obtained with Class.getDeclaredMethod and made accessible with theLineProcMethod.setAccessible(true)).
- Its first parameter must be a CodeletInstance and second must be a CodeletType. Both of these parameters are ommitted from all taglets.
- It may contain zero-or-more extra parameters, whose types are either primitives or non-null strings (null is not possible), as specified by
  com.github.xbn.util.SimpleMethodSignature.getObjectFromString
  If there are any extra types in the customizer function signature, they must be provided in the customizer portion of every taglet using it. The types, amount, and order of extra parameters, in both the taglet and the customizer function signature, must exactly match.
When taglets are used in a class (as opposed to package-info.java or your project's overview summary), it is encouraged that its customizer functions be in the class, and that these functions are private. (In the Codelet and XBN-Java projects, this is not possible, as doing so would create circular-dependency nightmare--this is the primary reason for the zCodeletCustomizers default class.)

Codelet: Customizer: Taglet syntax: Example: Default function name and class location

{@.codelet fully.qualified.examples.ExampleClassName%()}

This ":()" shortcut indicates a customizer function with the standard name and class location should be used. In particular:
- Its name is "getSourceCode_ExampleClassName",
- It has no extra parameters, and it
- Must exist in one of the default classes
{@.codelet fully.qualified.examples.ExampleClassName%()}

is equivalent to both

{@.codelet fully.qualified.examples.ExampleClassName:getSourceCode_ExampleClassName()}

and

{@.codelet fully.qualified.examples.ExampleClassName:package.of.EnclosingClass#getSourceCode_ExampleClassName()}

with one exception: When the processor's function name is explicitely specified, but its class is not (which is true in the first two of the three above), the customizer must exist in one of the default classes

Codelet: Customizer: Taglet syntax: Example: Defaults with custom postfix

{@.codelet fully.qualified.examples.ExampleClassName%_ExtraStuff()}

Same as the default example, except the underscore-first-character indicates that this is not the customizer's entire function name, rather its postfix.

This is useful when there are multiple codelets of the same type, for the same example class (or text file).

Codelet: Customizer: Taglet syntax: Example: Specifying the class in which the processor function exists

The customizer function can be in any class, which may explicitely specified:

{@.codelet fully.qualified.examples.ExampleClassName:fully.qualified.package.MyCodeletCustomizers#getSource_ExampleClass(true, "See line 12")}

If using the default function name, it may be omitted, although the hash ('#') is required:

{@.codelet fully.qualified.examples.ExampleClassName:fully.qualified.package.MyCodeletCustomizers#(true, "See line 12")}

Signature formatting is as specified by
SimpleMethodSignature.newFromStringAndDefaults
(Before being provided to newFromStringAndDefaults, the omitted function name is given its default value ["getSource_ExampleClass"], as described in this and the previous example. In all cases, SimpleMethodSignature requires a function name.)

Codelet: Customizer: Taglet syntax: Example: Specifying extra processor parameters

The default customizer has a single CodeletInstance parameter. This is specified in the taglet with either empty parentheses, or no parens at all, as demonstrated in the default example.

Extra parameters may be optionally specified, and must be provided both in the function and in any taglet that uses (calls) it. For example, this taglet

{@.codelet fully.qualified.examples.ExampleClassName:(true, "See line 12")}

refers to this function:

getSourceCode_ExampleClassName(CodeletInstance taglet, CodeletType needed_defaultAlterType, boolean do_displayLineNums, String annotation)

which, since there is no fully-qualified class specified after the percent sign, must be in one of the default class-locations.

Parameter formatting is specified by
SimpleMethodSignature.newFromStringAndDefaults

This is a "simple" signature. Only primitives and strings are allowed. null is not possible.

Extra parameters can also be specified with the ":()" shortcut:
{@.codelet fully.qualified.examples.ExampleClassName:((byte)3, false)}
Since:

0.1.0

Author:

Copyright (C) 2014, Jeff Epstein (aliteralmind __DASH__ github __AT__ yahoo __DOT__ com), dual-licensed under the LGPL (version 3.0 or later) or the ASL (version 2.0). See source code for details. http://codelet.aliteralmind.com, https://github.com/aliteralmind/codelet

Constructor Summary

Constructors
Constructor and Description
`CustomizationInstructions(CodeletInstance instance, CodeletType needed_defaultAlterType)` Create a new instance.

Method Summary

Methods
Modifier and Type	Method and Description
`CustomizationInstructions<T>`	`alterer(AllTextLineAlterer all_lineAlterer)` Set the line-alterer.
`CustomizationInstructions<T>`	`build()` Declare that this object is ready for use and should be locked.
`CustomizationInstructions<T>`	`classNameOrFilePathRestricter(String whitelist_searchTerm)` Wildcard search-term to restrict the classes or files that may utilize this customizer.
`CustomizationInstructions<T>`	`defaultOrOverrideTemplate(Appendable dbgDest_ifNonNull)` Use the default (or override) template.
`CustomizationInstructions<T>`	`defaults(Appendable dbgEveryLine_ifNonNull, LengthInRange rangeForEveryLineDebug_ifNonNull, Appendable dbgAllAltr_ifNonNull, Appendable dbgTemplate_ifNonNull)` Make no customizations.
`CustomizationInstructions<T>`	`filter(FilteredLineIterator filter)` Keep or eliminate lines that meet some conditions.
`AllTextLineAlterer`	`getAlterer()` Get the line-alterer.
`String`	`getClassNameOrFilePathRestricter()` Wildcard search-term to restrict the classes that may utilize this customizer.
`String`	`getCustomizedBody(CodeletInstance instance, Iterator<String> raw_lineItr)` Given all configured customization instructions, transform the raw output (source-code, console-output, or file-text) into its fully-processed form, ready for insertion into the template.
`Appendable`	`getDefaultTemplateDebug()` When using the default template only, this is its debug destination.
`FilteredLineIterator`	`getFilter()` Get the line-filter.
`CodeletInstance`	`getInstance()`
`CodeletType`	`getNeededAlterArrayType()`
`T`	`getTemplate()` Get the template.
`CustomizationInstructions<T>`	`orderedAlterers(Appendable dbgDest_ifNonNull, NullElement null_element, ExpirableElements xprbl_elements, MultiAlterType multi_type, TextLineAlterer... alterers)` Set an ordered series of line-alterers.
`CustomizationInstructions<T>`	`template(T template)` Override the template for this codelet-taglet only.
`CustomizationInstructions<T>`	`unfiltered(Appendable dbgEveryLine_ifNonNull, LengthInRange rangeForEveryLineDebug_ifNonNull)` Display all lines.
`boolean`	`wasTemplateSet()` Was the template set?.

Methods inherited from class com.github.xbn.util.lock.AbstractOneWayLockable
lock

Methods inherited from class com.github.xbn.util.lock.AbstractLockable
ciLocked, ciNotLocked, forceUnlock, isLocked, isUnlockable, lock, toString

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.github.xbn.util.lock.OneWayLockable
isUnlockable

Methods inherited from interface com.github.xbn.util.lock.Lockable
isLocked, lock

- Constructor Detail
  - CustomizationInstructions
```
public CustomizationInstructions(CodeletInstance instance,
                         CodeletType needed_defaultAlterType)
```
    Create a new instance.
    
    Equal to
    this(instance, instance.getType())
    
    Parameters:
    instance - May not be null.
    needed_defaultAlterType - The type of default alterers needed when using the default template. May not be null. If instance.getType.SOURCE_AND_OUT, then this must be either SOURCE_CODE or CONSOLE_OUT. If instance.getType is any other type, then needed_defaultAlterType must be equal to it.
- Method Detail
  - defaults
```
public CustomizationInstructions<T> defaults(Appendable dbgEveryLine_ifNonNull,
                                    LengthInRange rangeForEveryLineDebug_ifNonNull,
                                    Appendable dbgAllAltr_ifNonNull,
                                    Appendable dbgTemplate_ifNonNull)
```
    Make no customizations.
    
    This calls
    1. unfiltered(dbgDest_ifNonNull)
    2. orderedAlterers(dbgAllAltr_ifNonNull, NullElement.BAD ExpirableElements.OPTIONAL, MultiAlterType.CUMULATIVE DefaultAlterGetterUtil.getDefaultAlterArray(getNeededAlterArrayType()))
    3. defaultOrOverrideTemplate(dbgTemplate_ifNonNull)
    Returns:
    this
  - getNeededAlterArrayType
```
public CodeletType getNeededAlterArrayType()
```
  - getFilter
```
public FilteredLineIterator getFilter()
```
    Get the line-filter.
    
    See Also:
    filter(FilteredLineIterator)
  - getAlterer
```
public AllTextLineAlterer getAlterer()
```
    Get the line-alterer.
    
    See Also:
    alterer(AllTextLineAlterer)
  - getTemplate
```
public T getTemplate()
```
    Get the template.
    Returns:
    A non-null template: When this taglet only should use a non-default (and non-override) template.
    
    null: If wasTemplateSet() is
    
    true: No template was set.
    
    false: The default (or override) template should be used.
    See Also:
    template(T), defaultOrOverrideTemplate(Appendable)
  - getInstance
```
public CodeletInstance getInstance()
```
  - defaultOrOverrideTemplate
```
public CustomizationInstructions<T> defaultOrOverrideTemplate(Appendable dbgDest_ifNonNull)
```
    Use the default (or override) template.
    
    This sets
    1. getTemplate() to null
    2. wasTemplateSet() to true
    This leaves the template object as null to avoid having to know about the CodeletInstance, which is required to determine if the default or override template should be used. A null template value triggers the taglet processor to get the appropriate template.
    Parameters:
    dbgDest_ifNonNull - When non-null, this is the debugging destination for all gap-fills. Get with getDefaultTemplateDebug()
    
    Returns:
    this
    
    Throws:
    
    LockException - If build() was already called.
    
    IllegalStateException - If wasTemplateSet() is true.
    See Also:
    template(T)
  - template
```
public CustomizationInstructions<T> template(T template)
```
    Override the template for this codelet-taglet only.
    
    This sets wasTemplateSet() to true.
    
    Parameters:
    template - May not be null. Get with getTemplate(). Note that JavaDoc is multi-threaded, and therefore this template-object must be a new object (not shared among multiple taglets). Use the copy constructor or getObjectCopy() to duplicate it.
    
    Returns:
    this
    
    Throws:
    
    LockException - If build() was already called.
    
    IllegalStateException - If wasTemplateSet() is true.
    See Also:
    defaultOrOverrideTemplate(Appendable)
  - unfiltered
```
public CustomizationInstructions<T> unfiltered(Appendable dbgEveryLine_ifNonNull,
                                      LengthInRange rangeForEveryLineDebug_ifNonNull)
```
    Display all lines.
    
    Returns:
    filter(NewFilteredLineIteratorFor.keepAllLinesUnchanged(null, dbgEveryLine_ifNonNull, rangeForEveryLineDebug_ifNonNull))
  - filter
```
public CustomizationInstructions<T> filter(FilteredLineIterator filter)
```
    Keep or eliminate lines that meet some conditions. Kept lines may be altered.
    
    Two examples of filtering lines:
    - Displaying only a range of lines--a code snippet.
    - Eliminating the package declaration line and all JavaDoc multi-line comments
    Parameters:
    filter - May not be null. Get with getFilter().
    
    Returns:
    this
    
    Throws:
    
    LockException - If build() was already called.
    See Also:
    unfiltered(Appendable, LengthInRange)
  - orderedAlterers
```
public CustomizationInstructions<T> orderedAlterers(Appendable dbgDest_ifNonNull,
                                           NullElement null_element,
                                           ExpirableElements xprbl_elements,
                                           MultiAlterType multi_type,
                                           TextLineAlterer... alterers)
```
    Set an ordered series of line-alterers.
    
    Parameters:
    alterers - May not be null or empty and, if null_element.isBad() is true, no elements may be null. Elements should not be duplicate.
    
    Returns:
    alterer(new AllTextLineAlterer(alterers, xprbl_elements, multi_type, dbgDest_ifNonNull))
  - alterer
```
public CustomizationInstructions<T> alterer(AllTextLineAlterer all_lineAlterer)
```
    Set the line-alterer.
    
    Parameters:
    all_lineAlterer - May not be null. Get with getAlterer().
    
    Returns:
    this
    
    Throws:
    
    LockException - If build() was already called.
    See Also:
    orderedAlterers(Appendable, NullElement, ExpirableElements, MultiAlterType, TextLineAlterer...)
  - classNameOrFilePathRestricter
```
public CustomizationInstructions<T> classNameOrFilePathRestricter(String whitelist_searchTerm)
```
    Wildcard search-term to restrict the classes or files that may utilize this customizer.
    Parameters:
    whitelist_searchTerm - Wildcard search term to match the fully-qualified class name of the example code, or path of the text file that is allowed to use this customizer. Class name examples:
    
    "com.github.mylibrary.examples.AGoodExample"
    
    "com.github.mylibrary.examples.A*Example"
    
    "*.examples.A*Example"
    
    Text file examples:
    
    "com/github/mylibrary/examples/doc-files/AGoodExample_input.txt"
    
    "com/github/mylibrary/examples/doc-files/*_input.txt"
    
    "*_input.txt"
    
    May not be null or empty, and should be a valid wildcard term. Get with getClassNameOrFilePathRestricter().
    Returns:
    this
    See Also:
    FilenameUtils#wildcardMatch, TagletOfTypeProcessor#crashIfClassOrFileCannotUseCustomizer
  - getClassNameOrFilePathRestricter
```
public String getClassNameOrFilePathRestricter()
```
    Wildcard search-term to restrict the classes that may utilize this customizer.
    
    See Also:
    classNameOrFilePathRestricter(String)
  - wasTemplateSet
```
public boolean wasTemplateSet()
```
    Was the template set?.
    
    See Also:
    getTemplate(), template(T), defaultOrOverrideTemplate(Appendable)
  - getDefaultTemplateDebug
```
public Appendable getDefaultTemplateDebug()
```
    When using the default template only, this is its debug destination.
    
    See Also:
    getTemplate(), defaultOrOverrideTemplate(Appendable)
  - getCustomizedBody
```
public String getCustomizedBody(CodeletInstance instance,
                       Iterator<String> raw_lineItr)
```
    Given all configured customization instructions, transform the raw output (source-code, console-output, or file-text) into its fully-processed form, ready for insertion into the template.
    
    This logs all alterers that do not make an alteration.
    
    Throws:
    
    AlterationNotMadeException - If at least one alteration is not made, and it is configured that a crash should occur (in addition to the warning).
  - build
```
public CustomizationInstructions<T> build()
```
    Declare that this object is ready for use and should be locked.
    
    Returns:
    this
    
    Throws:
    
    IllegalStateException - If the filter or alterer are null, or wasTemplateSet() is false.

Class CustomizationInstructions<T extends CodeletTemplateBase>

Codelet: Customizer: Three parts

Codelet: Customizer: Three parts: Part 1: Line filter

Codelet: Customizer: Three parts: 2: Alterer

Codelet: Customizer: Three parts: 3: Template

Codelet: Customizer: Overview

Codelet: Customizer function: Example: A customizer that does nothing

Codelet: Customizer: Requirements

Codelet: Customizer: Taglet syntax: Example: Default function name and class location

Codelet: Customizer: Taglet syntax: Example: Defaults with custom postfix

Codelet: Customizer: Taglet syntax: Example: Specifying the class in which the processor function exists

Codelet: Customizer: Taglet syntax: Example: Specifying extra processor parameters

Constructor Summary

Method Summary

Methods inherited from class com.github.xbn.util.lock.AbstractOneWayLockable

Methods inherited from class com.github.xbn.util.lock.AbstractLockable

Methods inherited from class java.lang.Object

Methods inherited from interface com.github.xbn.util.lock.OneWayLockable

Methods inherited from interface com.github.xbn.util.lock.Lockable

Constructor Detail

CustomizationInstructions

Method Detail

defaults

getNeededAlterArrayType

getFilter

getAlterer

getTemplate

getInstance

defaultOrOverrideTemplate

template

unfiltered

filter

orderedAlterers

alterer

classNameOrFilePathRestricter

getClassNameOrFilePathRestricter

wasTemplateSet

getDefaultTemplateDebug

getCustomizedBody

build