Package picocli.codegen.annotation.processing

Class AbstractCommandSpecProcessor

  • All Implemented Interfaces:
    javax.annotation.processing.Processor
    Direct Known Subclasses:
    AbstractCompositeGeneratorProcessor
    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 Detail

      • COMMAND_DEFAULT_NAME

        private static final java.lang.String COMMAND_DEFAULT_NAME
        See Also:
        Constant Field Values

      • logger

        private static java.util.logging.Logger logger

      • processingEnv

        protected javax.annotation.processing.ProcessingEnvironment processingEnv
        The ProcessingEnvironment set by the init(ProcessingEnvironment) method.

      • COMMAND_TYPE

        private static final java.lang.String COMMAND_TYPE

      • handler

        static java.util.logging.ConsoleHandler handler

    • 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

      • stacktrace

        private static java.lang.String stacktrace​(java.lang.Exception e)

      • tryProcess

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

      • handleCommands

        protected abstract boolean handleCommands​(java.util.Map<javax.lang.model.element.Element,​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.

      • isSubcommand

        private boolean isSubcommand​(javax.lang.model.element.ExecutableElement method,
                             javax.annotation.processing.RoundEnvironment roundEnv)

      • buildTypeHierarchy

        private java.util.Stack<javax.lang.model.element.TypeElement> buildTypeHierarchy​(javax.lang.model.element.TypeElement typeElement)

      • processEnclosedElements

        private void processEnclosedElements​(AbstractCommandSpecProcessor.Context context,
                                     javax.annotation.processing.RoundEnvironment roundEnv,
                                     java.util.List<? extends javax.lang.model.element.Element> enclosedElements)

      • isValidSubcommandHasNameAttribute

        private boolean isValidSubcommandHasNameAttribute​(javax.lang.model.element.Element subcommandElement)

      • buildMixin

        private void buildMixin​(javax.lang.model.element.Element element,
                        javax.annotation.processing.RoundEnvironment roundEnv,
                        AbstractCommandSpecProcessor.Context context)

      • buildArgGroup

        private void buildArgGroup​(javax.lang.model.element.Element element,
                           AbstractCommandSpecProcessor.Context context,
                           javax.annotation.processing.RoundEnvironment roundEnv)

      • extractTypedMember

        private TypedMember extractTypedMember​(javax.lang.model.element.Element element,
                                       java.lang.String annotation)

      • superClassFor

        private static javax.lang.model.element.TypeElement superClassFor​(javax.lang.model.element.TypeElement element)
        Obtains the super type element for a given type element.
        Parameters:
        element - The type element
        Returns:
        The super type element or null if none exists

      • debugMethod

        private void debugMethod​(javax.lang.model.element.ExecutableElement method)

      • debugElement

        private void debugElement​(javax.lang.model.element.Element element,
                          java.lang.String s)

      • logElementDetails

        private void logElementDetails​(javax.lang.model.element.Element element,
                               java.lang.String s)

      • debugType

        private void debugType​(javax.lang.model.type.TypeMirror typeMirror,
                       javax.lang.model.element.Element element,
                       java.lang.String indent)

      • debugFoundAnnotations

        private void debugFoundAnnotations​(java.util.Set<? extends javax.lang.model.element.TypeElement> annotations,
                                   javax.annotation.processing.RoundEnvironment roundEnv)

      • 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