Package studio.mevera.imperat

Class ConfigBuilder<S extends Source,I extends Imperat<S>,B extends ConfigBuilder<S,I,B>>

java.lang.Object
studio.mevera.imperat.ConfigBuilder<S,I,B>
Type Parameters:
S - the source type representing the entity or origin of the command (e.g., a user or a system)
I - the implementation type that extends Imperat
public abstract class ConfigBuilder<S extends Source,I extends Imperat<S>,B extends ConfigBuilder<S,I,B>> extends Object
A generic abstract builder class for configuring instances of ImperatConfig and creating implementations of the Imperat interface. The builder pattern is utilized to allow fine-grained configuration of various components needed within the command processing system.

  • Field Details

  • Constructor Details

    • ConfigBuilder

      protected ConfigBuilder()

  • Method Details

    • commandPrefix

      public B commandPrefix(String cmdPrefix)
      Sets the command prefix for the command processing chain.
      Parameters:
      cmdPrefix - the prefix string to be used before commands
      Returns:
      the updated instance of the ConfigBuilder to allow for method chaining

    • permissionChecker

      public B permissionChecker(PermissionChecker<S> permissionChecker)
      Sets a custom PermissionChecker to determine and resolve permissions for the command sender/source within the platform's configuration.
      Parameters:
      permissionChecker - the PermissionChecker implementation used to handle permission checks for commands
      Returns:
      the current ConfigBuilder instance for method chaining and further configuration

    • autoPermissionAssignMode

      public B autoPermissionAssignMode(boolean modeToggle)
      Toggles the APA (Auto Permission Assign) mode, When enabled, it will automatically compute, set permissions automatically for every CommandParameter in every CommandUsage you make without the need to explicitly set the permissions , the same goes on ROOT commands and even subcommands (since they are also treated as CommandParameter)
      Parameters:
      modeToggle - toggles the auto permission assign mode
      Returns:
      the current ConfigBuilder instance for method chaining and further configuration

    • permissionLoader

      @Experimental public B permissionLoader(PermissionLoader<S> permissionLoader)
      Sets the permission loader for automatic permission assignment.

      This method configures the PermissionLoader that will be used to load and resolve permissions for command parameters when Auto Permission Assign (APA) mode is active. The permission loader is responsible for determining what permissions should be applied to individual command nodes based on the command structure and configuration.

      Prerequisite: This method can only be called when APA mode is enabled via the configuration. APA mode must be activated before setting up permission loading components to ensure proper initialization order and prevent configuration conflicts.

      The permission loader works in conjunction with the NodePermissionAssigner to provide a complete automatic permission assignment system. The loader determines which permissions to assign, while the assigner handles how those permissions are applied to the parameter nodes.

      Parameters:
      permissionLoader - the permission loader to use for loading permissions, must not be null
      Returns:
      this builder instance for method chaining, never null
      Throws:
      IllegalStateException - if Auto Permission Assign (APA) mode is not enabled
      NullPointerException - if permissionLoader is null
      Since:
      1.0
      See Also:

    • permissionAssigner

      @Experimental public B permissionAssigner(NodePermissionAssigner<S> permissionAssigner)
      Sets the permission assigner for automatic permission assignment.

      This method configures the NodePermissionAssigner that will be used to assign permissions to command parameter nodes when Auto Permission Assign (APA) mode is active. The permission assigner defines the strategy for how permissions loaded by the PermissionLoader are actually applied to individual ParameterNode instances.

      Prerequisite: This method can only be called when APA mode is enabled via the configuration. APA mode must be activated before setting up permission assignment components to ensure proper initialization order and prevent configuration conflicts.

      The permission assigner works in conjunction with the PermissionLoader to provide a complete automatic permission assignment system. The loader determines which permissions to assign, while the assigner handles how those permissions are applied to the parameter nodes.

      If no custom assigner is provided, the system will use the default assigner available via NodePermissionAssigner.defaultAssigner().

      Parameters:
      permissionAssigner - the permission assigner to use for assigning permissions to parameter nodes, must not be null
      Returns:
      this builder instance for method chaining, never null
      Throws:
      IllegalStateException - if Auto Permission Assign (APA) mode is not enabled
      NullPointerException - if permissionAssigner is null
      See Also:

    • helpCoordinator

      public B helpCoordinator(HelpCoordinator<S> coordinator)
      Sets the HelpCoordinator that coordinates all the core-components of the new help API, to create a coordinator call HelpCoordinator.create()
      Parameters:
      coordinator - the coordinator
      Returns:
      the current instance of ConfigBuilder for method chaining
      Since:
      2.0.0

    • contextFactory

      public B contextFactory(ContextFactory<S> contextFactory)
      Sets the context factory for creating contexts used in command execution.
      Parameters:
      contextFactory - the context factory to be used for generating contexts
      Returns:
      the current instance of ConfigBuilder for method chaining

    • usageVerifier

      public B usageVerifier(UsageVerifier<S> usageVerifier)
      Sets the usage verifier for the configuration.
      Parameters:
      usageVerifier - the UsageVerifier instance to validate command usages
      Returns:
      the current ConfigBuilder instance for fluent chaining

    • returnResolver

      public B returnResolver(Type type, ReturnResolver<S,?> returnResolver)
      Registers a ReturnResolver
      Parameters:
      type - the type of value to return using the return resolver
      returnResolver - the return resolving instance.
      Returns:
      the current ConfigBuilder instance for fluent chaining

    • dependencyResolver

      public B dependencyResolver(Type type, DependencySupplier resolver)
      Registers a dependency resolver for a specific type and returns the current ConfigBuilder instance.
      Parameters:
      type - the target type for which the dependency resolver is being registered
      resolver - the dependency resolver to associate with the specified type
      Returns:
      the current instance of ConfigBuilder for method chaining

    • annotationReplacer

      public <A extends Annotation> B annotationReplacer(Class<A> annotationType, AnnotationReplacer<A> replacer)
      Registers a custom annotation replacer for the specified annotation type. This allows for dynamic transformation or substitution of annotations during command processing, enabling advanced annotation-based command customization.

      Annotation replacers are particularly useful for:

      • Converting legacy annotation formats to newer ones
      • Applying conditional annotation logic based on runtime context
      • Implementing annotation inheritance or composition patterns
      • Providing backwards compatibility for deprecated annotations

      Example usage: 

      
 builder.annotationReplacer(LegacyCommand.class, (annotation, context) -> {
     return Command.builder()
         .name(annotation.value())
         .permission(annotation.permission())
         .build();
 });
      Type Parameters:
      A - the type of annotation to be replaced by the AnnotationReplacer
      Parameters:
      annotationType - the class object representing the annotation type to register a replacer for, must not be null
      replacer - the annotation replacer implementation that will handle transformations for the specified annotation type, must not be null
      Returns:
      this builder instance for method chaining
      Throws:
      IllegalArgumentException - if annotationType or replacer is null
      See Also:

    • overlapOptionalParameterSuggestions

      public B overlapOptionalParameterSuggestions(boolean overlap)
      Configures whether multiple optional parameters can be suggested simultaneously during tab completion at the same command depth level. This is a builder method that provides a fluent interface for the underlying configuration setting.

      This setting affects the behavior of tab completion suggestions without modifying the underlying command structure. The command tree and parameter validation remain unchanged regardless of this setting.

      Examples: 

      
 // Command structure: /command [count] [extra]
 //                              \[extra]

 // When enabled (true):
 /command <TAB> → shows: [count], [extra]

 // When disabled (false):
 /command <TAB> → shows: [count] (first optional only)

      Default behavior: The default value depends on the framework configuration, but typically defaults to false for simpler user experience.

      Parameters:
      overlap - true to allow multiple optional parameter suggestions, false to limit to one optional parameter suggestion at a time
      Returns:
      this builder instance for method chaining
      See Also:

    • setDefaultSuggestionResolver

      public B setDefaultSuggestionResolver(SuggestionResolver<S> resolver)
      Sets the default suggestion resolver to be used when no specific resolver is defined for a parameter or command context. This resolver acts as a fallback mechanism for tab completion suggestions.

      The default suggestion resolver is invoked when:

      • A parameter has no specific SuggestionResolver defined
      • A command argument requires suggestions but no custom logic exists
      • Fallback suggestions are needed during error recovery

      Example usage: 

      
 builder.setDefaultSuggestionResolver((source, context, input) -> {
     // Provide generic suggestions like player names, common values, etc.
     return Arrays.asList("player1", "player2", "default_value");
 });

      Note: Setting this to null will disable default suggestions, potentially leaving some parameters without tab completion support.

      Parameters:
      resolver - the default suggestion resolver implementation, or null to disable default suggestions
      Returns:
      this builder instance for method chaining
      See Also:

    • throwableResolver

      public <T extends Throwable> B throwableResolver(Class<T> exception, ThrowableResolver<T,S> handler)
      Registers a throwable resolver for a specific exception type. This method allows customizing the handling behavior for specific types of exceptions during application execution.
      Type Parameters:
      T - The type of the throwable.
      Parameters:
      exception - The class object representing the type of the throwable for which the resolver will be configured.
      handler - The ThrowableResolver implementation responsible for handling the specified throwable type.
      Returns:
      The current instance of ConfigBuilder, allowing method chaining for further configuration.

    • preProcessor

      public B preProcessor(CommandPreProcessor<S> preProcessor)
      Adds a command pre-processor to the configuration. A command pre-processor is executed before resolving command arguments into values.
      Parameters:
      preProcessor - the CommandPreProcessor to be added to the chain of execution
      Returns:
      the current ConfigBuilder instance for method chaining

    • postProcessor

      public B postProcessor(CommandPostProcessor<S> postProcessor)
      Adds a CommandPostProcessor to the chain of execution that processes the command context after the resolving of arguments into values.
      Parameters:
      postProcessor - the post-processor to be added to the execution chain; it processes the command context after argument resolution
      Returns:
      the current ConfigBuilder instance for chaining additional configurations

    • preProcessingChain

      public B preProcessingChain(CommandProcessingChain<S,CommandPreProcessor<S>> chain)
      Configures the pre-processing chain for command processing. This chain defines a series of CommandPreProcessor instances that will execute before resolving the arguments into values.
      Parameters:
      chain - the pre-processing chain to set, which consists of multiple CommandPreProcessor handlers
      Returns:
      the current ConfigBuilder instance for method chaining

    • postProcessingChain

      public B postProcessingChain(CommandProcessingChain<S,CommandPostProcessor<S>> chain)
      Sets the post-processing chain for the configuration.
      Parameters:
      chain - the CommandProcessingChain of CommandPostProcessor instances to be set as the post-processing chain
      Returns:
      the ConfigBuilder instance for method chaining

    • contextResolverFactory

      public <T> B contextResolverFactory(Type type, ContextResolverFactory<S,T> factory)
      Registers a context resolver factory for the specified type. This method allows configuring a factory responsible for creating a context resolver for the given type during the command processing.
      Type Parameters:
      T - the type the resolver factory handles
      Parameters:
      type - the specific type for which the resolver factory is being set
      factory - the context resolver factory to be registered
      Returns:
      this ConfigBuilder instance for method chaining

    • contextResolver

      public <T> B contextResolver(Type type, ContextResolver<S,T> resolver)
      Registers a context resolver for a specified type, allowing you to resolve a default value from the context for that type.
      Type Parameters:
      T - the type of value being resolved from the context
      Parameters:
      type - the class type of the value to be resolved
      resolver - the context resolver responsible for providing the default value when required
      Returns:
      the updated instance of ConfigBuilder, enabling fluent configuration

    • parameterType

      public <T> B parameterType(Type type, ParameterType<S,T> resolver)
      Registers a parameter type and its associated resolver for parsing command arguments.
      Type Parameters:
      T - The type of the parameter being registered.
      Parameters:
      type - The class representing the type of the parameter being resolved.
      resolver - The resolver to handle parsing for the specified parameter type.
      Returns:
      The current instance of ConfigBuilder, allowing method chaining.

    • applyOnConfig

      public B applyOnConfig(@NotNull @NotNull Consumer<ImperatConfig<S>> configConsumer)
      Applies a consumer function to the current configuration, allowing modifications to be performed directly on the ImperatConfig instance.
      Parameters:
      configConsumer - a Consumer that takes the ImperatConfig<S> to apply changes. The provided consumer may modify the configuration as needed.
      Returns:
      the current B instance for fluent method chaining.

    • namedSuggestionResolver

      public B namedSuggestionResolver(String name, SuggestionResolver<S> suggestionResolver)
      Registers a named suggestion resolver for providing autocomplete suggestions for command arguments or parameters.
      Parameters:
      name - the unique name to identify the suggestion resolver
      suggestionResolver - the suggestion resolver to be registered
      Returns:
      the current instance of ConfigBuilder for method chaining

    • defaultSuggestionResolver

      public B defaultSuggestionResolver(@NotNull @NotNull SuggestionResolver<S> suggestionResolver)
      Sets the default suggestion resolver for providing autocomplete suggestions for command arguments or parameters in the configuration.
      Parameters:
      suggestionResolver - the SuggestionResolver implementation to be used as the default resolver for suggestions
      Returns:
      the current ConfigBuilder instance for method chaining

    • sourceResolver

      public <R> B sourceResolver(Type type, SourceResolver<S,R> sourceResolver)
      Registers a SourceResolver for a specific type to resolve command sources.
      Type Parameters:
      R - the resulting type resolved by the source resolver
      Parameters:
      type - the type of the source to be resolved
      sourceResolver - the source resolver instance that converts the source
      Returns:
      the current ConfigBuilder instance for method chaining

    • placeholder

      public B placeholder(Placeholder<S> placeholder)
      Registers a placeholder with the configuration.
      Parameters:
      placeholder - the placeholder to be registered, containing the unique identifier and the dynamic resolver logic that defines how it behaves.
      Returns:
      the current ConfigBuilder instance for chaining further configuration.

    • globalDefaultUsageBuilder

      public B globalDefaultUsageBuilder(CommandUsage.Builder<S> usage)
      Sets the global default usage builder that will be used for all commands that do not have their own specific usage builder configured.

      The usage builder is responsible for constructing the usage/syntax data structure that defines how a command should be used, including its arguments, parameters, and expected format. This global default will be applied to all commands registered through this builder unless they explicitly override it with their own usage configuration.

      This method follows the builder pattern and returns the current builder instance to allow for method chaining.

      Parameters:
      usage - the CommandUsage.Builder to use as the global default for building command usage/syntax data. Must not be null.
      Returns:
      this builder instance for method chaining
      Throws:
      NullPointerException - if usage is null
      Since:
      1.0.0
      See Also:

    • handleMiddleOptionalArgSkipping

      public B handleMiddleOptionalArgSkipping(boolean toggle)
      Refer to ImperatConfig.setHandleExecutionConsecutiveOptionalArgumentsSkip(boolean)
      Parameters:
      toggle - the toggle for this option
      Returns:
      whether this option is enabled or not.

    • defaultAttachmentMode

      public B defaultAttachmentMode(AttachmentMode attachmentMode)
      The default attachment mode.
      Parameters:
      attachmentMode - the default attachment mode
      Returns:
      the default value.

    • instanceFactory

      public B instanceFactory(InstanceFactory<S> instanceFactory)
      Sets the instance factory used for creating instances of classes during command processing and dependency resolution.
      Parameters:
      instanceFactory - the InstanceFactory implementation to be used for instantiating classes. Must not be null.
      Returns:
      this builder instance for method chaining
      Throws:
      NullPointerException - if instanceFactory is null
      See Also:

    • build

      @NotNull public abstract I build()
      Builds and returns the final configuration object based on the provided settings and definitions within the builder. This method finalizes the configuration and ensures all dependencies are properly resolved before returning the result.
      Returns:
      the fully constructed and finalized instance of type I