8000 Add the option to retrieve raw arguments by DerEchtePilz · Pull Request #459 · CommandAPI/CommandAPI · GitHub
[go: up one dir, main page]

Skip to content

Add the option to retrieve raw arguments #459

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 32 commits into from
Jul 12, 2023
Merged
Changes from 1 commit
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
3c7aa7f
Add the option to retrieve raw arguments
DerEchtePilz Jun 8, 2023
4baa0a4
Fix SuggestionsBranch.java. Change String[]::new to new String[0]
DerEchtePilz Jun 8, 2023
b186494
Fix CommandArgument.java
DerEchtePilz Jun 8, 2023
b50afe8
Merge dev/dev into dev/raw-argument-input
DerEchtePilz Jun 15, 2023
8981a2a
Add tests for retrieving raw arguments
DerEchtePilz Jun 15, 2023
6cf237d
Move raw argument creation into CommandAPIHandler
DerEchtePilz Jun 15, 2023
c24d084
Fix raw argument tests failing when using the ChatComponentArgument o…
JorelAli Jun 15, 2023
46deb77
Add empty documentation page
DerEchtePilz Jun 17, 2023
bafaacf
Add documentation (1)
DerEchtePilz Jun 23, 2023
ff7fcc1
Add documentation (2)
DerEchtePilz Jun 27, 2023
a0cfc2d
Modify CommandArguments to remove deprecations and add getOrDefault m…
DerEchtePilz Jun 28, 2023
eb431b0
Address some code review
DerEchtePilz Jun 30, 2023
9fe5879
Fix markdownlint issues
DerEchtePilz Jun 30, 2023
d0b59d3
Make sure commandarguments.md lists every method
DerEchtePilz Jun 30, 2023
3af41ab
Link CommandArguments references to commandarguments.md
DerEchtePilz Jun 30, 2023
f67a012
Merge branch 'dev/dev' into dev/raw-argument-input
DerEchtePilz Jun 30, 2023
5643f0d
Update intro.md, optional_arguments.md and upgrading.md
DerEchtePilz Jul 1, 2023
6ebf8e1
Remove 'What terms are used' section, refactor 'Access the inner stru…
DerEchtePilz Jul 3, 2023
e2fd959
Improve explanation for unsafe arguments
DerEchtePilz Jul 4, 2023
a3db5ea
Add an explanation of raw arguments to the JavaDocs for methods deali…
DerEchtePilz Jul 4, 2023
c8c1de6
Remove unnecessary sentence from commandarguments.md
DerEchtePilz Jul 4, 2023
7ff5cf6
Convert CommandArguments.java into a record
DerEchtePilz Jul 4, 2023
c5916bb
Replace usage of CommandArguments#getFullInput in CommandAPIExecutor …
DerEchtePilz Jul 4, 2023
b1104a3
Make Java examples use the node name to access arguments
DerEchtePilz Jul 5, 2023
3f096b8
Make Kotlin examples use the node name to access arguments
DerEchtePilz Jul 5, 2023
cae4298
Make Kotlin DSL examples use the node name to access arguments
DerEchtePilz Jul 5, 2023
ec80dc5
Fix Bukkit Core dependencies
DerEchtePilz Jul 5, 2023
d05c9eb
Add documentation examples
DerEchtePilz Jul 5, 2023
0641607
Update global changelog
DerEchtePilz Jul 5, 2023
4753950
Merge branch 'dev/dev' into dev/raw-argument-input
DerEchtePilz Jul 5, 2023
897739d
Add JavaDocs to record parameters
DerEchtePilz Jul 12, 2023
ad1621d
Merge branch 'dev/raw-argument-input' of https://github.com/JorelAli/…
DerEchtePilz Jul 12, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Fix markdownlint issues
  • Loading branch information
DerEchtePilz committed Jun 30, 2023
commit 9fe5879d991dbc1f9b8cd5c2bc79f7f36fa8a5b2
16 changes: 15 additions & 1 deletion docssrc/src/commandarguments.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,13 +19,14 @@ While the argument array just gives the possibility to access the arguments via
- [Access arguments by node name](#access-arguments-by-node-name-1)
- [Access arguments by index](#access-arguments-by-index-1)


ATTENTION!!!!! Every executable and generated documentation has to be deleted before committing anything!

-----

## Access the inner structure directly

To provide arguments, the `CommandArguments` class stores:

- a `Object[]` of parsed arguments
- a `Map<String, Object>` of parsed arguments mapped to their node names
- a `String[]` of raw arguments
Expand Down Expand Up @@ -53,9 +54,11 @@ While these methods can be used to access arguments, it may be safer to use the
-----

## What terms are used?

Throughout this page, multiple terms are used that may need an explanation.

### `nodeName`

The `nodeName` is set when initializing an argument. For example:

```java
Expand All @@ -65,6 +68,7 @@ new StringArgument("string")
The `nodeName` here would be `string`.

### `raw argument`

A "raw argument" is the `String` form of an argument as written in a command. For example:

A user defines a command `/mycommand` that accepts a `double` as the first argument and an entity selector as the second argument. It could be executed with the values `15.3` as the `double` value and `@e` as the entity selector:
Expand All @@ -78,18 +82,21 @@ When [accessing the raw arguments](#access-raw-arguments) of this command there
However, when [accessing the arguments](#access-arguments) of this command there is `15.3` available as `double` and `@e` available as `Collection<Entity>`.

### `unsafe argument`

When [accessing arguments](#access-arguments) you need to cast the `Object` returned by these methods to the type the argument returns. More about casting arguments [here](./arguments.md#argument-casting).

However, the `CommandArguments` class provides a way to remove the need to cast the arguments which is referred to as `unsafe arguments` in this page.

-----

## Access arguments

The `CommandArguments` class provides its arguments in a way similar to how a `List` or `Map` let you access their contents. When using these methods, you need to cast the arguments to their respective type. The `CommandArguments` class also provides a way to [access unsafe arguments](#access-unsafe-arguments).

You can choose to access arguments by their node name or by their index.

### Access arguments by node name

Accessing arguments by their node name is the recommended way of accessing arguments.

There are two methods you can use to access arguments by their node name:
Expand All @@ -102,6 +109,7 @@ Optional<Object> getOptional(String nodeName);
There is no downside of using one method over the other but the `CommandArguments#getOptional(String)` method is especially great when you have optional arguments in your command.

### Access arguments by index

Accessing arguments by their index is the original way of accessing arguments. However, we recommend to [access arguments by node name](#access-arguments-by-node-name).

Similar to the two methods of accessing arguments by their node name, there also are two methods you can use to access arguments by their index:
Expand All @@ -120,9 +128,11 @@ Optional<Object> getOptional(int index);
-----

## Access raw arguments

Raw arguments are accessed basically the same way you would [access arguments](#access-arguments). You can access them by their node name and their index in the argument array.

### Access raw arguments by node name

Accessing raw arguments by their node name is the recommended way of doing it.

To access raw arguments by their node name, you can use these methods:
Expand All @@ -133,6 +143,7 @@ Optional<String> getRawOptional(String nodeName);
```

### Access raw arguments by index

Of course, if you don't want to access raw arguments by their node name, we also provide the option to access them by index with these methods:

```java
Expand All @@ -149,6 +160,7 @@ Optional<String> getRawOptional(int index);
-----

## Access unsafe arguments

Accessing unsafe arguments is a nice way to shorten your code as you do not need to cast the argument to its corresponding type.

Here, you might notice the usage of several `getOrDefaultUnchecked` methods and not the `getOptionalUnchecked` methods you might have expected.
Expand All @@ -158,6 +170,7 @@ That is not a problem when [accessing arguments](#access-arguments) because here
Unsafe arguments can also be accessed by their node names and their indices.

### Access arguments by node name

Unsafe arguments can also be accessed by node name which, again, is the recommended way of doing it.

In the case of unsafe arguments, the CommandAPI doesn't provide two but instead three methods to access them:
Expand All @@ -169,6 +182,7 @@ T getOrDefaultUnchecked(String nodeName, Supplier<T> defaultValue);
```

### Access arguments by index

If you want to access unsafe arguments by index, you can do that by using these methods:

```java
Expand Down
0