From 9b215471a1dad0311f7518e07af32ce42f32a047 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20S=C3=B6derberg?= Date: Thu, 25 Jan 2024 07:06:53 +0100 Subject: [PATCH] chore(core): add javadoc links --- docs/core/index.md | 310 +++++++++++++++++++++++++++++++-------------- 1 file changed, 214 insertions(+), 96 deletions(-) diff --git a/docs/core/index.md b/docs/core/index.md index fa24740..3d562cb 100644 --- a/docs/core/index.md +++ b/docs/core/index.md @@ -4,6 +4,15 @@ Generally you'll want to depend on a platform module which implements Cloud for your specific platform, as `cloud-core` does not have any platform-specific code. +## Links + +
+ +- [:fontawesome-brands-github: Source Code](https://github.com/Incendo/cloud) +- [:fontawesome-brands-java: JavaDoc](https://javadoc.io/doc/org.incendo/cloud-core/latest) + +
+ ## Installation Cloud is available through [Maven Central](https://central.sonatype.com/artifact/org.incendo/cloud-core). @@ -102,14 +111,20 @@ and suggestions with tooltips in ### Execution coordinators The execution coordinator is responsible for coordinating command parsing and execution. -You may create a simple execution coordinator by using `ExecutionCoordinator.simpleCoordinator()` which will not +You may create a simple execution coordinator by using +[`ExecutionCoordinator.simpleCoordinator()`]() +which will not enforce any particular executor and both parsing and suggestion generation will take place on the calling thread unless the parser or suggestion provider redirects to another executor. -You may also use `ExecutionCoordinator.asyncCoordinator()` to create an execution coordinator that will perform +You may also use +[`ExecutionCoordinator.asyncCoordinator()`]() +to create an execution coordinator that will perform parsing and suggestion generation asynchronously. You may customize the asynchronous coordinator by using -`ExecutionCoordinator.builder()` and supply different executors for different execution steps, or use -`ExecutionCoordinator.coordinatorFor(Executor)` to supply an executor which is used at every execution step. +[`ExecutionCoordinator.builder()`]() +and supply different executors for different execution steps, or use +[`ExecutionCoordinator.coordinatorFor(Executor)`]() +to supply an executor which is used at every execution step. ### Building a command @@ -117,8 +132,10 @@ parsing and suggestion generation asynchronously. You may customize the asynchro ![Example Builder](https://github.com/Incendo/cloud/blob/master/img/code/builder_java_light.png?raw=true#only-light) Commands are created using a command builder. -You may either create a new builder by calling `Command#newBuilder` or through the command manager using -`CommandManager#commandBuilder`. +You may either create a new builder by calling +[`Command#newBuilder`]() +or through the command manager using +[`CommandManager#commandBuilder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/CommandBuilderSource.html). It is recommended to use the command manager to create a new command builder, as this ties the command builder to the [parser registry](#parser-registry). @@ -126,7 +143,10 @@ The command builders are immutable, and each method returns a new command builde This allows you to store intermediate steps and reuse them to build multiple distinct commands. You must register your command to the command manager for it to be recognized. -You do this by calling `CommandManager#command(Command)` or `CommandManager#command(Command.Builder)`. +You do this by calling +[`CommandManager#command(Command)`]() +or +[`CommandManager#command(Command.Builder)`](). #### Descriptions @@ -154,9 +174,12 @@ builder.description(Description.of("The description")) ##### Command descriptions Command descriptions can be added through the command builder by calling -`Command.Builder#commandDescription(CommandDescription)`. -The `CommandDescription` instance contains two instances of `Description`, one short version -and an optional verbose version. +[`Command.Builder#commandDescription(CommandDescription)`](). +The +[`CommandDescription`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/description/CommandDescription.html) +instance contains two instances of +[`Description`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/description/Description.html), +one short version and an optional verbose version. ```java // Using the CommandDescription.commandDescription static import with strings: @@ -181,9 +204,9 @@ Depending on the platform, it might also determine who is allowed to _see_ the c The permission is ultimately evaluated by the platform integration. Though, cloud has support for some more complex permission types, such as: -- `Permission.anyOf(Permission...)`: Takes in multiple permissions and evaluates to `true` if any of the permissions evaluate to `true`. -- `Permission.allOf(Permission...)`: Takes in multiple permissions and evaluates to `true` if all the permissions evaluate to `true`. -- `PredicatePermission.of(Predicate)`: Evaluates to `true` if the predicate evaluates to `true`. +- [`Permission.anyOf(Permission...)`](): Takes in multiple permissions and evaluates to `true` if any of the permissions evaluate to `true`. +- [`Permission.allOf(Permission...)`](): Takes in multiple permissions and evaluates to `true` if all the permissions evaluate to `true`. +- [`PredicatePermission.of(Predicate)`](): Evaluates to `true` if the predicate evaluates to `true`. #### Sender types @@ -196,7 +219,9 @@ that maps between your custom type and the native command sender type. When you create a command you may override the sender type for that specific command, as long as the new sender type has `` as its supertype. -This is done by using the `Command.Builder#senderType(Class)` method. +This is done by using the +[`Command.Builder#senderType(Class)`]() +method. Cloud will make sure that the sender is of the right type when executing the command, and will fail exceptionally if it isn't. @@ -237,7 +262,9 @@ Command literals are fixed strings, and represent what you might think of as a " They may have secondary aliases, depending on the platform you're targeting. Literals may be placed after required variable components, but never after optional variable components. -The literals are created by using the various different `Command.Builder#literal` methods, for example: +The literals are created by using the various different +[`Command.Builder#literal`]() +methods, for example: ```java title="Example of literals" builder @@ -254,35 +281,55 @@ Literals are always required. #### Variable Variable components are parsed using parsers. -You can create a variable component either by using a `CommandComponent.Builder` that you create using -`CommandComponent.builder`, or by using one of the many different `Command.Builder` overloads. - -The component wraps a [parser](#parsers), but in many cases you will want to work with a `ParserDescriptor` instead. -A `ParserDescriptor` is a structure containing an `ArgumentParser` as well as a `TypeToken` that describes the object +You can create a variable component either by using a +[`CommandComponent.Builder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/component/CommandComponent.Builder.html) +that you create using +[`CommandComponent.builder`](), +or by using one of the many different +[`Command.Builder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/Command.Builder.html) +overloads. + +The component wraps a [parser](#parsers), but in many cases you will want to work with a +[`ParserDescriptor`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ParserDescriptor.html) +instead. +A +[`ParserDescriptor`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ParserDescriptor.html) +is a structure containing an +[`ArgumentParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ArgumentParser.html) +as well as a `TypeToken` that describes the object produced by the parser. If you do not provide a parser descriptor, then you will have to manually specify the value type. All variable components have a name. When you want to extract the parsed values in a [command handler](#handler) you do so using the component name. -You may use a `CloudKey` instead of the name, which then allows you to retrieve the parsed values +You may use a +[`CloudKey`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/key/CloudKey.html) +instead of the name, which then allows you to retrieve the parsed values in a type-safe manner. ##### Required -You can create a required variable component either by using `CommandComponent.Builder.#equired()` or any -of the many different overloaded `required` factory methods in `Command.Builder`. +You can create a required variable component either by using +[`CommandComponent.Builder#required()`]() +or any +of the many different overloaded `required` factory methods in +[`Command.Builder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/Command.Builder.html). ##### Optional -You can create a required variable component either by using `CommandComponent.Builder#optional()` or any -of the many different overloaded `optional` factory methods in `Command.Builder`. +You can create a required variable component either by using +[`CommandComponent.Builder#optional()`]() +or any +of the many different overloaded `optional` factory methods in +[`Command.Builder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/Command.Builder.html) +. When creating an optional variable component you may supply a default value. The default value will be used in the case that the user has not supplied any input for the component. There are three different types of default values: -- **DefaultValue.constant(Value)**: A constant default value. -- **DefaultValue.dynamic(Function)**: A dynamic value that is evaluated when the command is parsed. -- **DynamicValue.parsed(String)**: A string that is parsed by the component parser when the command is parsed. +- [`DefaultValue.constant(Value)`](): A constant default value. +- [`DefaultValue.dynamic(Function)`](): A dynamic value that is evaluated when the command is parsed. +- [`DynamicValue.parsed(String)`](): A string that is parsed by the component parser when the command is parsed. ##### Component pre-processing @@ -296,10 +343,12 @@ You can find it here: #### Command context -The command context is used to store values throughout the parsing process, such as parsed component values, +The [`CommandContext`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/context/CommandContext.html) +is used to store values throughout the parsing process, such as parsed component values, values from preprocessors, parsed flags, etc. -You can fetch values from the command context using both strings and `CloudKey`s. It is recommended to use +You can fetch values from the command context using both strings and +[`CloudKey`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/key/CloudKey.html). It is recommended to use keys to access values from the context as they are type-safe. ```java title="Example context usage" @@ -319,8 +368,9 @@ final List cats = commandContext.inject(new TypeToken>() {}); #### Handler -The command handler is an instance of `CommandExecutionHandler` and is invoked when a command has been parsed -successfully. +The command handler is an instance of +[`CommandExecutionHandler`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/execution/CommandExecutionHandler.html) +and is invoked when a command has been parsed successfully. Depending on the command execution coordinator the handler might be invoked asynchronously. The handler is passed an instance of the [command context](#command-context). @@ -330,20 +380,29 @@ builder.handler(ctx -> { }); ``` -You may implement `CommandExecutionHandler.FutureCommandExecutionHandler` to have the handler be a future-returning +You may implement +[`CommandExecutionHandler.FutureCommandExecutionHandler`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/execution/CommandExecutionHandler.FutureCommandExecutionHandler.html) +to have the handler be a future-returning function. Cloud will wait for the future to complete and will handle any completion exceptions gracefully. -You may delegate to other handlers using `CommandExecutionHandler.delegatingExecutionHandler`. +You may delegate to other handlers using +[`CommandExecutionHandler.delegatingExecutionHandler`](). The command builder also has some utility functions for creating handlers that delegate to the existing handler, like -`Command.Builder#prependHandler` and `Command.Builder#appendHandler`. +[`Command.Builder#prependHandler`]() +and +[`Command.Builder#appendHandler`](). ### Registering commands -The command may be registered to the command manager by using `CommandManager#register(Command)`. -You may also register a command builder using `CommandManager#register(Command.Builder)` +The command may be registered to the command manager by using +[`CommandManager#command(Command)`](). +You may also register a command builder using +[`CommandManager#command(Command.Builder)`]() in which case the command will be built by the manager. -Commands may also be registered by passing a `CommandFactory` to the command manager. +Commands may also be registered by passing a +[`CommandFactory`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/CommandFactory.html) +to the command manager. The command factory is an interface which outputs a list of commands. ### Customizing the command manager @@ -352,21 +411,23 @@ The command factory is an interface which outputs a list of commands. When a command is entered by a command sender, it goes through the following stages: -1. It is converted into a `CommandInput` instance. +1. It is converted into a [`CommandInput`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/context/CommandInput.html) instance. 2. A command context is created for the input. 3. The context is passed to the preprocessors, which may alter the command input or write to the context. - - If a command processor causes an interrupt using `ConsumerService.interrupt()` the context will be filtered out + - If a command processor causes an interrupt using [`ConsumerService.interrupt()`]() the context will be filtered out and the command will not be parsed. 4. The input is parsed into a command chain, and the parsed values are written to the context. - If the input cannot be parsed into a command that the sender is allowed to execute, the sender is notified and the parsing is canceled. 5. The command postprocessors get to act on the command, and may alter the command context. They may also postpone command execution, which can be used to require confirmations, etc. - - If a postprocessor causes an interrupt using `ConsumerService.interrupt()` the command will not be executed. + - If a postprocessor causes an interrupt using [`ConsumerService.interrupt()`]() the command will not be executed. 6. The command is executed using the command executor. -The pre- and post-processors can be registered to the command manager using `CommandManager#registerCommandPreProcessor` -and `CommandManager#registerCommandPostProcessor`. +The pre- and post-processors can be registered to the command manager using +[`CommandManager#registerCommandPreProcessor`]() +and +[`CommandManager#registerCommandPostProcessor`](). Incendo maintains some processors that you may depend on in your projects: @@ -377,8 +438,10 @@ Incendo maintains some processors that you may depend on in your projects: #### Exception handling Cloud v2 introduced a new exception handling system. -You may register exception handlers through the exception controller, which can be retrieved using -`CommandManager#exceptionController`. +You may register exception handlers through the +[`ExceptionController`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/handling/ExceptionController.html), +which can be retrieved using +[`CommandManager#exceptionController`](). Cloud will attempt to match a thrown exception to any of the registered exception handlers, giving preference to the most specific exception type and to the last registered handler. @@ -388,34 +451,44 @@ You may register multiple exception handlers for the same exception type. Cloud will iterate over the exception handlers (giving preference to the last registered handler) until a handler consumes the exception, which allows for the registration of default handlers. -Some exception types, such as `ArgumentParseException` and `CommandExecutionException` wrap the actual exceptions +Some exception types, such as +[`ArgumentParseException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/ArgumentParseException.html) +and +[`CommandExecutionException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/CommandExecutionException.html) +wrap the actual exceptions thrown by the parser or command handler. By default, Cloud will forward the wrapper exceptions. If you instead want to be able to register exception handlers for the causes, then you may use the -`ExceptionHandler.unwrappingHandler()` methods to unwrap these exceptions. +[`ExceptionHandler.unwrappingHandler()`]() +methods to unwrap these exceptions. You can choose to unwrap all instances of a given exception type, all instances with a given cause type or all instances that pass a given predicate. Command exceptions are thrown whenever a command cannot be parsed or executed normally. This can be for several reasons, such as: -- The command sender does not have the required permission (NoPermissionException) -- The command sender is of the wrong type (InvalidCommandSenderException) -- The requested command does not exist (NoSuchCommandException) -- The provided command input is invalid (InvalidSyntaxException) -- The parser cannot parse the input provided (ArgumentParseException) +- The command sender does not have the required permission ([`NoPermissionException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/NoPermissionException.html)) +- The command sender is of the wrong type ([`InvalidCommandSenderException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/InvalidCommandSenderException.html)) +- The requested command does not exist ([`NoSuchCommandException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/NoSuchCommandException.html)) +- The provided command input is invalid ([`InvalidSyntaxException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/InvalidSyntaxException.html)) +- The parser cannot parse the input provided ([`ArgumentParseException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/ArgumentParseException.html)) ##### Captions -`ParserException` makes use of Cloud's caption system. -(Nearly) all argument parsers in Cloud will throw `ParserException` on invalid input, in which case you're able -to override the exception message by configuring the manager's [CaptionRegistry](TODO). +[`ParserException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/parsing/ParserException.html) +makes use of Cloud's caption system. +(Nearly) all argument parsers in Cloud will throw +[`ParserException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/parsing/ParserException.html) on invalid input, in which case you're able +to override the exception message by configuring the manager's [`CaptionRegistry`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/CaptionRegistry.html). The caption registry allows you to register caption providers that provide values for caption keys. You may register multiple caption providers and the registry will iterate over them until one responds with a non-`null` value. -There are some static factory methods in `CaptionProvider` that help generating providers for constant values. -All standard caption keys can be found in [StandardCaptionKeys](TODO). +There are some static factory methods in +[`CaptionProvider`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/CaptionProvider.html) +that help generating providers for constant values. +All standard caption keys can be found in +[StandardCaptionKeys](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/caption/StandardCaptionKeys.html). Some platform adapters have their own caption key classes as well. The JavaDoc for the caption keys list their replacement variables. @@ -436,7 +509,10 @@ to be thrown. You may create a custom caption formatter that generates more complex output types than strings. This is particularly useful if you want to route the captions through some external system to generate platform-native message types (i.e. `Component` for Minecraft). You may format captions using this custom -type by invoking `ParserException#formatCaption` or `CommandContext#formatCaption`. +type by invoking +[`ParserException#formatCaption`]() +or +[`CommandContext#formatCaption`](). ## Parsers @@ -448,12 +524,12 @@ The parser registry is primarily used in two different places: - When only a value type has been supplied to a command component to look up the relevant parser. - When using annotated command methods. -If you are creating a library or using `cloud-annotations`, it is recommended to register your parser -in the parser registry. -You can access the parser registry via `CommandManager#parserRegistry`. +If you are creating a library or using [cloud-annotations](../annotations/index.md), it is recommended to register your parser +in the parser registry. You can access the parser registry via +[`CommandManager#parserRegistry`](). The parser suppliers get access to a structure containing parser parameters. These parameters are most often mapped to annotations, and allow for the customization of the parsers -when using `cloud-annotations`. +when using [cloud-annotations](../annotations/index.md). !!! example "Example parser registration" @@ -481,7 +557,8 @@ Cloud has four different string "modes": The string parsers do not produce suggestions by default. -The string parsers can be created using the static factory methods found in [StringParser](TODO). +The string parsers can be created using the static factory methods found in +[`StringParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/StringParser.html). #### String Array @@ -491,30 +568,32 @@ it encounters a [flag](#flags). The string array parser does not produce suggestions by default. -The string array parser can be created using the static factory methods found in [StringArrayParser](TODO). +The string array parser can be created using the static factory methods found in +[`StringArrayParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/StringArrayParser.html). #### Character This parses a single space-delimited character. The character parser does not produce suggestions by default. -The character parser can be created using the static factory methods found in [CharacterParser](TODO). +The character parser can be created using the static factory methods found in +[`CharacterParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/CharacterParser.html). #### Numbers Cloud has parsers for bytes, shorts, integers, longs, doubles and floats. The numerical values may have min- and max-values set. -All numerical parsers except for `FloatParser` and `DoubleParser` will produce suggestions. +Cloud will generate suggestions for all numerical types, except for `float` and `double`. The numerical parsers can be created using the static factory methods found in: -- [ByteParser](TODO) -- [ShortParser](TODO) -- [IntegerParser](TODO) -- [LongParser](TODO) -- [DoubleParser](TODO) -- [FloatParser](TODO) +- [`ByteParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/ByteParser.html) +- [`ShortParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/ShortParser.html) +- [`IntegerParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/IntegerParser.html) +- [`LongParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/LongParser.html) +- [`DoubleParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/DoubleParser.html) +- [`FloatParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/FloatParser.html) #### Boolean @@ -522,20 +601,23 @@ The boolean parser can either be strict or liberal. A strict boolean parser only accepts (independent of the case) `true` and `false`. A liberal boolean parser also accepts `yes`, `no`, `on` and `off`. -The boolean parser can be created using the static factory methods found in [BooleanParser](TODO). +The boolean parser can be created using the static factory methods found in +[`BooleanParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/BooleanParser.html). #### Enum The enum parser matches the input (independent of the case) to the names of an enum. The parser will return the enum values as suggestions. -The enum parser can be created using the static factory methods found in [EnumParser](TODO). +The enum parser can be created using the static factory methods found in +[`EnumParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/EnumParser.html). #### UUID The UUID parser parses dash-separated UUIDs. -The UUID parser can be created using the static factory methods found in [UUIDParser](TODO). +The UUID parser can be created using the static factory methods found in +[`UUIDParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/standard/UUIDParser.html). ### Flags @@ -551,7 +633,10 @@ Flags can have aliases alongside their full names. When referring to the full name of a flag, you use `--name` whereas an alias uses the syntax `-a`. You can chain the aliases of multiple presence flags together, such that `-a -b -c` is equivalent to `-abc`. -The flag values are contained in `FlagContext` which can be retrieved using `CommandContext#flags()`. +The flag values are contained in +[`FlagContext`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/flag/FlagContext.html) +which can be retrieved using +[`CommandContext#flags()`](). !!! example "Example of a command with a presence flag" @@ -569,8 +654,11 @@ Aggregate parsers are a new concept as of Cloud v2, and they supersede the old c An aggregate parser is a combination of multiple parsers that maps the intermediate results into an output type using a mapper. -You may either implement the `AggregateParser` interface, or using construct the parser by using a builder -that you create by calling `AggregateParser.builder()`. +You may either implement the +[`AggregateParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/aggregate/AggregateParser.html) +interface, or using construct the parser by using a builder +that you create by calling +[`AggregateParser.builder()`](). !!! example "Example Aggregate Parser" @@ -591,7 +679,10 @@ that you create by calling `AggregateParser.builder()`. ### Either -You may use `ArgumentParser.firstOf(ParserDescriptor, ParserDescriptor)` to create a parser for the type `Either`. +You may use +[`ArgumentParser.firstOf(ParserDescriptor, ParserDescriptor)`]() +to create a parser for the type +[`Either`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/type/Either.html). The parser will first attempt to parse the primary type `A`, and if this fails it will fall back on the fallback type `B`. The suggestions of both the primary and fallback parsers will be joined when using the parser as the suggestion provider. @@ -637,7 +728,9 @@ The recommended way of parsing an argument is to: and an error message is sent to the command sender. The parser has two different choices when it comes to which method to implement. -If the parser implements `ArgumentParser` then the signature looks like +If the parser implements +[`ArgumentParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ArgumentParser.html) +then the signature looks like ```java public ArgumentParseResult parse( @@ -645,10 +738,16 @@ public ArgumentParseResult parse( CommandInput input) { ... } ``` -where the `ArgumentParseResult` can either be a `ArgumentParseResult.success(OutputType)` or -`ArgumentParseResult.failure(Exception)`. +where the +[`ArgumentParseResult`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ArgumentParseResult.html) +can either be a +[`ArgumentParseResult.success(OutputType)`]() +or +[`ArgumentParseResult.failure(Exception)`](). -The parser may also implement `ArgumentParser.FutureParser` in which case the signature looks like +The parser may also implement +[`ArgumentParser.FutureArgumentParser`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/parser/ArgumentParser.FutureArgumentParser.html) +in which case the signature looks like ```java public CompletableFuture parseFuture( @@ -686,21 +785,31 @@ Returning a future is useful when the parsing needs to take place on a specific #### Exceptions -It is recommended to make use of `ParserException` when returning a failed result. -This allows for integration with the caption system, see [exception handling](#exception-handling) for more information. +It is recommended to make use of +[`ParserException`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/exception/parsing/ParserException.html) +when returning a failed result. This allows for integration with the caption system, +see [exception handling](#exception-handling) for more information. #### Suggestions -The parser may implement the `suggestions` method to produce suggestions. +The parser may return suggestions for command input. These suggestions will be used to provide suggestions for the component using the parser, unless the component is created using a custom suggestion provider. -Parsers implement `SuggestionProviderHolder` which means that they can return a suggestion provider by overriding -the `suggestionProvider` method. +Parsers implement +[`SuggestionProviderHolder`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/suggestion/SuggestionProviderHolder.html) +which means that they can return a suggestion provider by overriding +the +[`suggestionProvider`]() +method. However, the recommended way of providing suggestions is by implementing one of the suggestion provider -interfaces (`SuggestionProvider`, `SuggestionProvider.Strings`, -`BlockingSuggestionProvider` or `BlockingSuggestionProvider.Strings`). -If the parser implements a suggestion provider interface it does not need to override the `suggestionProvider` +interfaces ([`SuggestionProvider`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/suggestion/SuggestionProvider.html), +[`BlockingSuggestionProvider`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/suggestion/BlockingSuggestionProvider.html), +or +[`BlockingSuggestionProvider.Strings`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/suggestion/BlockingSuggestionProvider.Strings.html)). + +If the parser implements a suggestion provider interface it does not need to override the +[`suggestionProvider`]() method, as it'll return `this` by default. ## Extra @@ -708,9 +817,16 @@ method, as it'll return `this` by default. ### Help generation Cloud has a system that assists in querying for command information. -This is accessible through the `HelpHandler` that can be accessed using `CommandManager#createHelpHandler`. -This invokes a `HelpHandlerFactory`. -You may replace the default `HelpHandlerFactory` using `CommandManager#helpHandlerFactory(HelpHandlerFactory)` +This is accessible through the +[`HelpHandler`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/help/HelpHandler.html) +that can be accessed using +[`CommandManager#createHelpHandler`](). +This invokes a +[`HelpHandlerFactory`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/help/HelpHandlerFactory.html). +You may replace the default +[`HelpHandlerFactory`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/help/HelpHandlerFactory.html) +using +[`CommandManager#helpHandlerFactory(HelpHandlerFactory)`]() to change how the information is generated. The help handler will try to output as much information as it can, depending on how precise the query is. @@ -720,8 +836,10 @@ There are three types of query results: - **Multiple**: Returns a list of partial results. - **Verbose**: Returns verbose information about a specific command. -You may query for results by using `HelpHandler#query(HelpQuery)`. -The help handler does not display any information, this is instead done by a `HelpRenderer`. +You may query for results by using +[`HelpHandler#query(HelpQuery)`](). +The help handler does not display any information, this is instead done by a +[`HelpRenderer`](https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/help/HelpRenderer.html). `cloud-core` does not contain any implementations of the help renderer as this is highly platform-specific, but [cloud-minecraft-extras](../minecraft/minecraft-extras.md#minecraft-help) contains an opinionated implementation of the help system for Minecraft.