picocli.codegen.annotation.processing

Class AbstractCommandSpecProcessor

java.lang.Object

javax.annotation.processing.AbstractProcessor

picocli.codegen.annotation.processing.AbstractCommandSpecProcessor

All Implemented Interfaces:

javax.annotation.processing.Processor

Direct Known Subclasses:

NativeImageConfigGeneratorProcessor

public abstract class AbstractCommandSpecProcessor
extends javax.annotation.processing.AbstractProcessor

Abstract annotation processor for @picocli.* annotations that produces a set of CommandLine.Model.CommandSpec objects built from the annotated source code.

Subclasses should override the handleCommands(Map, Set, RoundEnvironment) method to do something useful with these CommandSpec objects, like generating source code, documentation or configuration files.

Note that due to the limitations of annotation processing and the compiler API, annotation attributes of type Class are not available as Class values at compile time, but only as TypeMirror values. Picocli 4.0 introduces a new CommandLine.Model.ITypeInfo interface that provides ArgSpec type metadata that can be used both at compile time and at runtime.

Similarly, ArgSpec objects constructed by the annotation processor will have a CommandLine.Model.IGetter and CommandLine.Model.ISetter implementation that is different from the one used at runtime and cannot be invoked directly: the annotation processor will assign an AnnotatedElementHolder implementation that gives subclass annotation processors access to the annotated element.

CommandSpec objects constructed by the annotation processor will have an VersionProviderMetaData version provider and a DefaultValueProviderMetaData default value provider, which gives subclass annotation processors access to the TypeMirror of the version provider and default value provider specified in the annotation.

Since:

4.0

Field Summary

Fields

Modifier and Type	Field and Description
protected javax.annotation.processing.ProcessingEnvironment	processingEnv The ProcessingEnvironment set by the init(ProcessingEnvironment) method.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractCommandSpecProcessor()

Method Summary

Modifier and Type	Method and Description
protected void	error(javax.lang.model.element.Element element, java.lang.String msg, java.lang.Object... args) Prints a compile-time error message for the specified element.
protected void	fatalError(java.lang.String msg) Prints a compile-time error message prefixed with "FATAL ERROR".
java.util.Set<java.lang.String>	getSupportedAnnotationTypes() Returns the annotation types supported by the super class, and adds "picocli.*" if necessary.
javax.lang.model.SourceVersion	getSupportedSourceVersion() Returns the max supported source version.
protected abstract boolean	handleCommands(java.util.Map<javax.lang.model.element.Element,picocli.CommandLine.Model.CommandSpec> commands, java.util.Set<? extends javax.lang.model.element.TypeElement> annotations, javax.annotation.processing.RoundEnvironment roundEnv) Subclasses must implement this method and do something with the CommandSpec command model objects that were found during compilation.
void	init(javax.annotation.processing.ProcessingEnvironment processingEnv)
protected void	logInfo(java.lang.String msg) Prints a compile-time NOTE message.
boolean	process(java.util.Set<? extends javax.lang.model.element.TypeElement> annotations, javax.annotation.processing.RoundEnvironment roundEnv)
static void	setLoadResourceBundles(boolean loadBundles) During annotation processing, resource bundles may not be available on the classpath and thereby cause failures.
protected void	warn(javax.lang.model.element.Element element, java.lang.String msg, java.lang.Object... args) Prints a compile-time warning message for the specified element.

Methods inherited from class javax.annotation.processing.AbstractProcessor

getCompletions, getSupportedOptions, isInitialized

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

processingEnv

protected javax.annotation.processing.ProcessingEnvironment processingEnv

The ProcessingEnvironment set by the init(ProcessingEnvironment) method.

Constructor Detail

AbstractCommandSpecProcessor

protected AbstractCommandSpecProcessor()

Method Detail

getSupportedAnnotationTypes

public java.util.Set<java.lang.String> getSupportedAnnotationTypes()

Returns the annotation types supported by the super class, and adds "picocli.*" if necessary. Subclasses can omit the @SupportedAnnotationTypes("picocli.*") annotation, but add other annotations if desired.

Specified by:

getSupportedAnnotationTypes in interface javax.annotation.processing.Processor

Overrides:

getSupportedAnnotationTypes in class javax.annotation.processing.AbstractProcessor

Returns:

the set of supported annotation types, with at least "picocli.*"

getSupportedSourceVersion

public javax.lang.model.SourceVersion getSupportedSourceVersion()

Returns the max supported source version. Returns SourceVersion.latest() by default, subclasses may override or may use the SupportedSourceVersion annotation.

Specified by:

getSupportedSourceVersion in interface javax.annotation.processing.Processor

Overrides:

getSupportedSourceVersion in class javax.annotation.processing.AbstractProcessor

Returns:

the max supported source version

init

public void init(javax.annotation.processing.ProcessingEnvironment processingEnv)

Specified by:

init in interface javax.annotation.processing.Processor

Overrides:

init in class javax.annotation.processing.AbstractProcessor

process

public boolean process(java.util.Set<? extends javax.lang.model.element.TypeElement> annotations,
                       javax.annotation.processing.RoundEnvironment roundEnv)

Specified by:

process in interface javax.annotation.processing.Processor

Specified by:

process in class javax.annotation.processing.AbstractProcessor

setLoadResourceBundles

public static final void setLoadResourceBundles(boolean loadBundles)

During annotation processing, resource bundles may not be available on the classpath and thereby cause failures. For that reason, by default, resource bundles are not loaded during annotation processing. This method allows for enabling loading of resource bundles during annotation processing.

Parameters:

loadBundles - true if bundles should be loaded, false (default) if bundles should not be loaded

Since:

4.8.0

handleCommands

protected abstract boolean handleCommands(java.util.Map<javax.lang.model.element.Element,picocli.CommandLine.Model.CommandSpec> commands,
                                          java.util.Set<? extends javax.lang.model.element.TypeElement> annotations,
                                          javax.annotation.processing.RoundEnvironment roundEnv)

Subclasses must implement this method and do something with the CommandSpec command model objects that were found during compilation.

Parameters:

commands - a map of annotated elements to their associated CommandSpec. Note that the key set may contain classes that do not have a @Command annotation but were added to the map because the class has fields annotated with Option or @Parameters.

annotations - the annotation types requested to be processed

roundEnv - environment for information about the current and prior round

Returns:

whether or not the set of annotation types are claimed by this processor. If true is returned, the annotation types are claimed and subsequent processors will not be asked to process them; if false is returned, the annotation types are unclaimed and subsequent processors may be asked to process them. A processor may always return the same boolean value or may vary the result based on chosen criteria.

logInfo

protected void logInfo(java.lang.String msg)

Prints a compile-time NOTE message.

Parameters:

msg - the info message

error

protected void error(javax.lang.model.element.Element element,
                     java.lang.String msg,
                     java.lang.Object... args)

Prints a compile-time error message for the specified element.

Parameters:

element - the problematic element

msg - the error message with optional format specifiers

args - the arguments to use to call String.format on the error message

warn

protected void warn(javax.lang.model.element.Element element,
                    java.lang.String msg,
                    java.lang.Object... args)

Prints a compile-time warning message for the specified element.

Parameters:

element - the problematic element, may be null

msg - the warning message with optional format specifiers

args - the arguments to use to call String.format on the warning message

fatalError

protected void fatalError(java.lang.String msg)

Prints a compile-time error message prefixed with "FATAL ERROR".

Parameters:

msg - the error message with optional format specifiers