Skip to content

Commit

Permalink
docs: update README
Browse files Browse the repository at this point in the history
  • Loading branch information
Citymonstret committed Jan 22, 2024
1 parent a7c5d1d commit 5ae109b
Showing 1 changed file with 14 additions and 94 deletions.
108 changes: 14 additions & 94 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,13 @@
# cloud-spring
<div align="center">
<img src="https://github.com/Incendo/cloud/raw/master/img/CloudNew.png" width="300px"/>
<br/>
<h1>cloud-spring</h1>

![license](https://img.shields.io/github/license/incendo/cloud.svg)
[![central](https://img.shields.io/maven-central/v/org.incendo/cloud-spring)](https://search.maven.org/search?q=org.incendo)
![build](https://img.shields.io/github/actions/workflow/status/incendo/cloud-spring/build.yml?logo=github)
[![docs](https://img.shields.io/readthedocs/incendocloud?logo=readthedocs)](https://cloud.incendo.org)
</div>

This is an opinionated implementation of [Cloud](https://github.com/incendo/cloud) for
[Spring Shell](https://spring.io/projects/spring-shell).
Expand Down Expand Up @@ -36,96 +45,7 @@ The example module contains a Spring Boot application with a couple of commands.

- no intermediate executors (you can do `/cat add` and `/cat remove` but not `/cat`)

## usage

**cloud-spring is not yet available on Maven Central!**
```xml
<dependencies>
<dependency>
<groupId>cloud.commandframework</groupId>
<artifactId>cloud-spring</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
```

You should first familiarize yourself with the [Cloud Docs](https://cloud.incendo.org).
The easiest way to use the `SpringCommandManager` is by using `SpringCommandSender` as the command sender type,
because there are default bindings set up for this.
If you want to use a custom command sender type then you'll want to create a binding for `CommandSenderSupplier`:
```java
@Bean
@NonNull CommandSenderSupplier<YourSenderType> commandSenderMapper() {
return () -> yourSender;
}
```
Cloud will create an instance of `SpringCommandManager` which automatically register commands to Spring Shell.

The recommended way of creating commands is by extending `CommandBean`.
Command beans are automatically registered to the command manager.
Examples can be found
[here](https://github.com/Incendo/cloud-spring/tree/main/example/src/main/java/org/incendo/cloud/spring/example/commands).

You may also autowire the `SpringCommandManager` and manually register commands.

### command execution coordinator

The command execution coordinator can be customized by creating a binding for `SpringCommandExecutionCoordinatorResolver`.
By default, `CommandExecutionCoordinator.simpleCoordinator` will be used.

### annotated commands

If you want to use annotated commands, then you must create a binding for `AnnotationParser`.
When doing so, you also have the option of creating a builder modifier that targets the `@CommandGroup` annotation:
```java
@Bean
@NonNull AnnotationParser<YourSenderType> annotationParser(
final @NonNull SpringCommandManager<YourSenderType> commandManager
) {
final AnnotationParser<YourSenderType> annotationParser = new AnnotationParser<>(
commandManager,
YourSenderType.class
);
// Optional: Binding for `@CommandGroup`
annotationParser.registerBuilderModifier(CommandGroup.class,
(annotation, builder) -> builder.meta(SpringCommandManager.COMMAND_GROUP_KEY, annotation.value()));
return annotationParser;
}
```

Cloud will then automatically detect all beans annotated with `@ScanCommands` and register them to `AnnotationParser`:
```java
@ScanCommands
@Component
public class SomeCommand {

@CommandGroup("A group")
@CommandDescription("A description")
@CommandMethod("A command")
public void yourCommand() {
// ...
}
}
```

Spring beans can be injected into command methods. You may annotated the injected members with `@Qualifier`:
```java
@CommandMethod("command <argument>")
public void yourCommand(
@Argument String argument,
@Qualifier("bean") SomeBean someBean
) {
// ...
}
```

### completions

Cloud suggestions will be invoked to provide suggestions for your commands.
You can use normal suggestions, but we also offer `CloudCompletionProposal` which
allows you to use rich completions:
```java
CloudCompletionProposal.of("proposal")
.displayName("with a display name")
.category("and a category");
```
## links

- Docs: https://cloud.incendo.org/spring/
- Incendo Discord: https://discord.gg/aykZu32

0 comments on commit 5ae109b

Please sign in to comment.