Skip to content

Commit 2f0dd21

Browse files
MqznMqzn
committed
Finished new help section
1 parent 1d196aa commit 2f0dd21

File tree

2 files changed

+82
-126
lines changed

2 files changed

+82
-126
lines changed

‎docs/Imperat/Command Help.md

+79-124
Original file line numberDiff line numberDiff line change
@@ -48,157 +48,112 @@ public final class GroupCommand {
4848
}
4949
}
5050
```
51-
### Help template
52-
53-
A help template is an interface that allows you to customize how the help-menu is displayed to the command-sender, there's already a `DefaultHelpTemplate` that looks like this when you execute `/group <group> help`:
54-
55-
![default-help-command.png](./assets/default-help-command.png)
56-
57-
:::note
58-
the `N/A` represents an unknown description, if it is annoying you, you can set a description per subcommand/usage whether using the classic way or the annotations or just make your own template which doesn't include the description in the `UsageFormatter`
59-
60-
:::
61-
62-
Any help template has 4 main components:
63-
- Header -> the header of the menu at the top
64-
- Footer -> the footer of the menu at the bottom
65-
- **UsageFormatter** -> controls the formatting of each single `CommandUsage`
66-
- **UsageDisplayer** -> controls how the **formatted usages** are displayed together
67-
68-
#### Example Help Template
69-
Here we will be building and creating our custom help-template that will define how the help-menu is displayed, let's call it `ExampleHelpTemplate` as below :-
51+
### Help provider
52+
A help provider is an interface whose only responsibility is to provide help-menu per command
53+
and it needs `ExecutionContext` as a parameter to do so.
54+
Help provider is cached in `Imperat`(the dispatcher) acting as a global help providing service.
7055

56+
You can implement your own help-provider and register it, to define how the help message is displayed as below:
7157
```java
72-
public class ExampleHelpTemplate implements HelpTemplate {
73-
74-
private UsageDisplayer displayer = UsageDisplayer.plain();
75-
private UsageFormatter formatter = new DefaultFormatter();
76-
77-
@Override
78-
public String getHeader(Command<?> command) {
79-
return
80-
"&8&l&m===================&r &6"
81-
+ command.name() + "'s help&r &8&l&m===================";
82-
}
83-
84-
85-
@Override
86-
public String getFooter(Command<?> command) {
87-
return "&8&l&m=================================";
88-
}
89-
58+
public final class ExampleHelpProvider implements HelpProvider<YourPlatformSource> {
9059
@Override
91-
public UsageFormatter getUsageFormatter() {
92-
return formatter;
60+
public void provide(ExecutionContext<YourPlatformSource> context) throws ImperatException {
61+
var src = context.source();
62+
var cmd = context.command();
63+
64+
if(cmd.usages().isEmpty()) {
65+
throw new NoHelpException();
66+
}
67+
68+
src.reply("sending the help for command '" + cmd.name() + "'");
69+
for(var usage : cmd.usages()) {
70+
src.reply("[+] /" + CommandUsage.format(cmd, usage) + " - " + usage.description());
71+
}
9372
}
94-
95-
@Override
96-
public void setUsageFormatter(UsageFormatter formatter) {
97-
this.formatter = formatter;
98-
}
99-
100-
@Override
101-
public UsageDisplayer getUsagesDisplayer() {
102-
return displayer;
103-
}
104-
105-
@Override
106-
public void setUsageDisplayer(UsageDisplayer displayer) {
107-
this.displayer = displayer;
108-
}
109-
11073
}
111-
```
11274

113-
You can use the default `UsageFormatter` as you can see above, but it's okay to make your own
114-
`UsageFormatter` instead of the `DefaultFormatter`, here's an example of
115-
implementing your own `UsageFormatter`:-
75+
```
11676

77+
and then registering your help provider
11778
```java
118-
public class ExampleUsageFormatter implements UsageFormatter {
119-
120-
121-
@Override
122-
public <S extends Source> String formatUsageLine(Command<S> command, CommandUsage<S> usage, boolean isLast) {
123-
String format = "/" + CommandUsage.format(command, usage);
124-
return "&a" + format + " &r&l-&r &e<yellow>" + usage.description();
125-
}
126-
127-
}
79+
imperat.setHelpProvider(new ExampleHelpProvider());
12880
```
12981

130-
Then inside of your custom help-template, you should just replace `new DefaultFormatter()` with `new ExampleUsageFormatter` *(or whatever the name of your class that implements the `UsageFormatter`)*.
82+
### Templates
83+
Some people would prefer to have their help displayed in the old format
84+
Any help template has 3 main components:
85+
- **Two Hyphens** (header and footer)
86+
- **UsageFormatter** -> defines the formatting of each single `CommandUsage`
13187

132-
:::info
133-
UsageDisplayer has already a premade implementation that you should be using (unless you want to make your own implementation) `PlainDisplayer`,
134-
We recommend fetching the instance of `PlainDisplayer` through the method `UsageDisplayer.plain()`.
135-
:::
88+
In imperat, there's an abstract class called `HelpTemplate`, it implements `HelpProvider` which contains these components,
89+
and another abstract class called `PaginatedHelpTemplate` (the name describes it's purpose) which extends `HelpTemplate` adding
90+
the ability to display command usages in the form of pages.
91+
Both classes are sealed, meaning that you can't extend them to make your own templates.
92+
You are forced to use our built-in builders for creation of templates as below
13693

137-
### Paginated Help Template
94+
```java
95+
imperat.setHelpProvider(
96+
HelpProvider.<YourPlatformSource>template()
97+
.header(content -> "------- " + content.command().name() + "'s help --------")
98+
.footer(content -> "-----------------")
99+
.formatter(yourOwnFormatter)
100+
.displayer((context, usages)-> {
101+
//define how usages are displayed here
102+
})
103+
.build()
104+
);
105+
```
138106

139-
It's exactly the same as a normal `HelpTemplate` but with two extra methods :
140-
- `int syntaxesPerPage()` -> defines how many syntax should displayed per one page
141-
- `String pagesHeaderComponent(int page, int maxPages)` -> controls how the pages header will be displayed as a singular part of the full header.
107+
As you can see above, you can define header, footer, `UsageFormatter` and displayer consumer to override the default display algorithm.
142108

109+
:::note[Notice]
110+
You are not required to create your displayer; By default, it's a simple for-loop showing the usages linearly
111+
along with their description on the right.
143112

144-
:::note
145-
In `PaginatedHelpTemplate` , there's a default method that combines 2 methods to form the total header of the help-menu that will be displayed, which are:-
146-
- `getHeader` (from the normal `HelpTemplate` interface)
147-
- `pagesHeaderComponent()` (from the `PaginatedHelpTemplate`) which for example shows how the `%currentPage%/%max_pages%` are displayed for a `PaginatedHelpTemplate`
148113
:::
149114

150-
#### Example Paginated Help Template
115+
the header and footer are hyphens for help (`HelpHyphen`) which has some data/content cached with it (`HyphenContent`) which contains:
116+
- Command owning the usages
117+
- current page and max-pages (they are `1` by default if the template isn't paginated)
151118

152-
We will be creating our own paginated help template by creating
153-
a class and calling it for example `ExamplePaginatedHelpTemplate` :-
119+
Here's a quick example below on creating and registering a paginated template
120+
```java
121+
imperat.setHelpProvider(
122+
HelpProvider.<YourPlatformSource>paginated(10)
123+
.header(
124+
content -> "--------" + content.command().name() + "'s help ("
125+
+ content.currentPage() + "/" + content.maxPages() + ") ------"
126+
)
127+
.footer((content) -> "------------")
128+
.build()
129+
);
130+
```
131+
132+
You can use the default `UsageFormatter`, but it's okay to make your own
133+
`UsageFormatter` instead of the default built-in formatter`, here's an example of
134+
implementing your own `UsageFormatter`:-
154135

155136
```java
156-
public final class ExamplePaginatedHelpTemplate
157-
extends ExampleHelpTemplate implements PaginatedHelpTemplate {
158-
159-
@Override
160-
public int syntaxesPerPage() {
161-
return 5;
162-
}
137+
public class ExampleUsageFormatter implements UsageFormatter {
138+
163139

164140
@Override
165-
public String fullHeader(Command<?> command, int page, int maxPages) {
166-
return "&8&l&m===================&r &2"
167-
+ command.name() + "'s help " + pagesHeaderComponent(page, maxPages) + "&r &8&l&m===================";
168-
}
169-
170-
171-
private String pagesHeaderComponent(int page, int maxPages) {
172-
return "&8( &a" + page + "&7/" + maxPages + " &8)";
141+
public <S extends Source> String formatUsageLine(Command<S> command, CommandUsage<S> usage, int index) {
142+
String format = "/" + CommandUsage.format(command, usage);
143+
return format + " - " + usage.description();
173144
}
174145

175146
}
176147
```
177148

178-
### Registering your help-template
179-
180-
We should register our help template so that it can be applied
181-
on any help usage(s) as the example below :
182-
183-
```java
184-
dispatcher.setHelpTemplate(new ExampleHelpTemplate());
185-
```
186-
187-
188-
:::tip
189-
You can do exactly the same for your Paginated help template
190-
(in this case: `ExamplePaginatedHelpTemplate`) , so for example :
191-
`dispatcher.setHelpTemplate(new ExamplePaginatedHelpTemplate())`
192-
149+
:::info[Notice]
150+
paginated help templates forces you to specify the number of usages to be displayed per one page.
151+
which is `10` usages per page as specified in the example above.
152+
Moreover, the paginated template builder has the same methods as that of the normal template builder.
193153
:::
194-
### Results
195154

196-
**Here i will show you the results of your patience and hard work for learning**
197-
**how to create your own help displaying and customize it:-**
198-
##### For normal help-template
155+
:::tip[Tip]
156+
If no usage description is supplied during command creation it will return `N/A` by default.
157+
The `N/A` represents an unknown description, if it is annoying you, you can set a description per subcommand/usage whether using the classic way or the annotations.
199158

200-
![Default Help Template Result](./assets/example-help-command.png)
201-
202-
##### For paginated help-template
203-
204-
![Paginated Help Template Result](./assets/example-paginated-help-command.png)
159+
:::

‎docs/Imperat/Supported-Platforms.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ Platforms are classified into:
4747

4848
## Minecraft platforms
4949
Imperat currently has implementations for the current minecraft-related platforms:
50-
- Bukkit/Spigot/Paper
50+
- Bukkit
5151
- Bungeecord
5252

5353
:::tip[Pro Tip]
@@ -72,5 +72,6 @@ SAME AS BUKKIT but the prefix is `Bungee`
7272

7373

7474
## Other platforms
75-
Coming soon...
75+
- **CLI** for command-line applications
76+
More coming soon...
7677

0 commit comments

Comments
 (0)