= Cloud documentation Alexander Söderberg v0.1.0, 2020-12-30 :sectnums: :cloud-version: 1.3.0 :toc: left :toclevels: 3 :icons: font :hide-uri-scheme: == Introduction to Cloud CAUTION: The Cloud documentation is still a work in progress. Cloud is a command manager and dispatcher for the JVM. Cloud allows you to define commands in several ways, most notably using command builders, or annotations. Cloud has platform implementations for many platforms, including Minecraft server software such as Bukkit or Discord bot frameworks such as JDA. Cloud allows you to customize the command execution pipeline by injecting custom behaviour along the entire execution path. All of this will be covered in this document. This document will first introduce different Cloud concepts using the builder pattern API. Section 4 will expand upon this by introducing the annotation (declarative) API, which offers another way of declaring commands. == Getting Started Cloud is available through https://search.maven.org/search?q=cloud.commandframework[Maven Central]. [source,xml,subs="attributes,verbatim"] ---- cloud.commandframework cloud-core {cloud-version} ---- If you want to use snapshot builds, then they are available via the Sonatype OSS Snapshot repository: [source,xml] ---- sonatype-snapshots https://oss.sonatype.org/content/repositories/snapshots ---- === Modules cloud-core:: Core Cloud API module. cloud-annotations:: Cloud annotation API. cloud-services:: Cloud service API. Included in Core. cloud-tasks:: Cloud scheduling API. cloud-kotlin-extensions:: Cloud extensions for Kotlin. cloud-bukkit:: Cloud implementation for the Bukkit API. cloud-paper:: Extension of cloud-bukkit for the Paper API. cloud-velocity:: Cloud implementation for the Velocity (1.1.0+) API. cloud-brigadier:: Cloud utilities for Mojang's Brigadier API. cloud-bungee:: Cloud implementation for the BungeeCord API. cloud-jda:: Cloud implementation for the JDA API. cloud-javacord:: Cloud implementation for the Javacord API. cloud-pircbotx:: Cloud implementation for the PircBotX framework. == Core The core module contains the majority of the API that you will be interacting with when using Cloud. === Command Manager The first step to any Cloud project is to create a command manager. Each supported platform has its own command manager, but for the most part they look and behave very similarly. It is possible to support multiple platforms in the same project. All command managers have a generic type argument for the command sender type. Most platforms have their own "native" command sender type, but Cloud allows you to use whatever sender you want, by supplying a mapping function to the command manager. This sender type will be included in the command context, which you will be interacting with a lot when using Cloud. [title="Creating a command manager instance using Bukkit"] ==== This particular example uses `cloud-bukkit`, though most concepts transfer over to the other command mangers. [source,java] ---- CommandManager manager = new BukkitCommandManager<>( /* Owning plugin */ this, AsynchronousCommandExecutionCoordinator.newBuilder().build(), <1> Function.identity(), <2> Function.identity(), <3> ); ---- <1> The execution coordinator handles the coordination of command parsing and execution. You can read more about this in section 3.6. <2> Function that maps the platform command sender to your command sender. <3> Function that maps your command sender to the platform command sender. ==== The command manager is used to register commands, create builders, change command settings, etc. More information can be found in the CommandManager https://javadoc.commandframework.cloud/cloud/commandframework/CommandManager.html[JavaDoc]. === Commands Commands consist of chains of arguments that are parsed from user input. These arguments can be either static literals or variables. Variable arguments are parsed into different types using argument parsers. Variable arguments may be either required, or they can be optional. Optional arguments may have default values. [title=Example command structure] ==== [source] ---- /foo bar one /foo bar two /foo <1> ---- <1> When a variable argument is present next to literals, it will be allowed to catch any input that isn't caught by the literals. Only one variable may exist at any level, but there may be many literals. This example contains three unique commands. ==== === Argument Types ==== Literals Literals are fixed strings and can be used to create "subcommands". You may use however many command literals you want at any level of a command. Command literals may have additional aliases that correspond to the same argument. A literal can be created directly in the command builder: [source,java] ---- builder = builder.literal( "main", <1> "alias1", "alias2", "alias3" <2> ); ---- <1> Any literal must have a main "alias". <2> You may also specify additional aliases. These are optional. You can also attach a description to your node, which is used in the command help system: [source,java] ---- builder = builder.literal( "main", Description.of("Your Description") ); ---- Literals may also be created using the https://javadoc.commandframework.cloud/cloud/commandframework/arguments/StaticArgument.html[StaticArgument] class. ==== Standard Cloud has built in support for all primitive types, as well as some other commonly used argument types. ===== string There are three different types of string arguments: single:: A single string without any blank spaces. greedy:: Consumes all remaining input. quoted:: Consumes either a single string, or a string surrounded by `"` or `'`. String arguments can be constructed using: * `StringArgument.of(name)`: Required single string argument * `StringArgument.of(name, mode)`: Required string argument of specified type * `StringArgument.optional(name)`: Optional single string argument * `StringArgument.optional(name, mode)`: Optional string argument of specified type Furthermore, a string argument builder can be constructed using `StringArgument.newBuilder(name)`. This allows you to provide a custom suggestion generator, using `StringArgument.Builder#withSuggestionsProvider(BiFunction, List>)`. ===== byte/short/int/long There are four different integer argument types: - byte - short - int - long All integer types are created the same way, the only difference is the class. These examples will use `IntegerArgument`, but the same methods are available in `ByteArgument`, `ShortArgument`, and `LongArgument`. Integer arguments can be constructed using: * `IntegerArgument.of(name)`: Required integer argument without a range * `IntegerArgument.optional(name)`: Optional integer argument without a range * `IntegerArgument.optional(name, default)`: Optional integer argument without a range, with a default value Furthermore, an integer argument builder can be constructed using `IntegerArgument.newBuilder(name)`. This allows you to provide a custom suggestion generator, using `IntegerArgument.Builder#withSuggestionsProvider(BiFunction, List>)`, and set minimum and maximum values. ===== float/double There are two different floating point argument types: - float - double All floating point types are created the same way, the only difference is the class. These examples will use `FloatArgument`, but the same methods are available in `DoubleArgument`. Floating point arguments can be constructed using: * `FloatArgument.of(name)`: Required float argument without a range * `FloatArgument.optional(name)`: Optional float argument without a range * `FloatArgument.optional(name, default)`: Optional float argument without a range, with a default value Furthermore, a floating point argument builder can be constructed using `FloatArgument.newBuilder(name)`. This allows you to provide a custom suggestion generator, using `FloatArgument.Builder#withSuggestionsProvider(BiFunction, List>)`, and set minimum and maximum values. ===== enums The enum argument type allows you to create a command argument using any enum type. They can be created using `EnumArgument.of` and `EnumArgument.optional`. The parser accepts case independent values and suggestions will be created for you. ===== boolean The boolean argument type is very simple. It parses boolean-like values from the input. There are two different modes: liberal:: Accepts truthy values ("true", "yes", "on") and falsy values ("false", "no", off") non-liberal:: Accepts only "true" and "false" ===== compound arguments ==== Custom ==== Flags === Suggestions === Injection Points ==== Preprocessing ==== Postprocessing === Execution Coordinators === Command Proxies === Permissions === Exception Handling === Command Context === Command Handler === Extra ==== Translations ==== Confirmations ==== Help Generation == Annotations == Kotlin DSL == Platforms === Minecraft ==== Bukkit ===== Paper ===== Brigadier ==== Sponge The Sponge implementation is still a work in progress. ==== Fabric The Fabric implementation is still a work in progress. === Discord ==== JDA ==== Javacord === IRC [glossary] == Glossary [glossary] sender:: A thing that is able to produce input that gets parsed into commands. argument:: An argument is something that can be parsed from a string. required argument:: A required argument is an argument that must be supplied by the sender. optional argument:: An optional argument is an argument that can be omitted by the sender. It may have a default value. literal:: A fixed string. command:: A command is a chain of arguments combined with a handler that acts on the parsed arguments. command tree:: A structure that contains all recognized commands, and that is used when parsing command sender input.