Skip to content

Commit e98289f

Browse files
VampireVampire
committed
Allow to customize the alias calculation
1 parent 0f9a0bd commit e98289f

14 files changed

Lines changed: 781 additions & 29 deletions

File tree

‎config/codenarc/codenarc.groovy‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,11 @@ ruleset {
3030
BrokenOddnessCheck
3131
ClassForName
3232
ComparisonOfTwoConstants
33-
ComparisonWithSelf
33+
ComparisonWithSelf {
34+
doNotApplyToClassNames = [
35+
'net.kautler.command.api.AliasAndParameterStringTest'
36+
].join(', ')
37+
}
3438
ConstantAssertExpression
3539
ConstantIfExpression
3640
ConstantTernaryExpression
@@ -276,7 +280,11 @@ ruleset {
276280
].join(', ')
277281
}
278282
ExplicitCallToDivMethod
279-
ExplicitCallToEqualsMethod
283+
ExplicitCallToEqualsMethod {
284+
doNotApplyToClassNames = [
285+
'net.kautler.command.api.AliasAndParameterStringTest'
286+
].join(', ')
287+
}
280288
ExplicitCallToGetAtMethod
281289
ExplicitCallToLeftShiftMethod
282290
ExplicitCallToMinusMethod
@@ -391,7 +399,9 @@ ruleset {
391399

392400
// rulesets/size.xml
393401
//AbcMetric // Requires the GMetrics jar
394-
ClassSize
402+
ClassSize {
403+
maxLines = 1500
404+
}
395405
//CrapMetric // Requires the GMetrics jar and a Cobertura coverage file
396406
//CyclomaticComplexity // Requires the GMetrics jar
397407
//MethodCount

‎config/pmd/pmd.xml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,9 @@
207207
\QFound 'DU'-anomaly for variable 'result' (lines '\E.* |
208208
\QFound 'DU'-anomaly for variable 'usageTree' (lines '\E.* |
209209
\QFound 'DU'-anomaly for variable 'seen' (lines '\E.* |
210-
\QFound 'DD'-anomaly for variable 'distance' (lines '\E.*
210+
\QFound 'DD'-anomaly for variable 'distance' (lines '\E.* |
211+
\QFound 'DD'-anomaly for variable 'aliasAndParameterString' (lines '\E.* |
212+
\QFound 'DU'-anomaly for variable 'parameterString' (lines '\E.*
211213
</value>
212214
</property>
213215
</properties>

‎config/spotbugs/spotbugs-exclude.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
<Method name="setAvailableRestrictions" params="javax.enterprise.inject.Instance" returns="void"/>
5353
<Method name="setCommands" params="javax.enterprise.inject.Instance" returns="void"/>
5454
<Method name="setCustomPrefixProvider" params="javax.enterprise.inject.Instance" returns="void"/>
55+
<Method name="setAliasAndParameterStringTransformer" params="javax.enterprise.inject.Instance" returns="void"/>
5556
</Or>
5657
</And>
5758
</Or>

‎readme/README_template.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Table of Contents
3939
* [Command Usage](#command-usage)
4040
* [Parsing Parameters](#parsing-parameters)
4141
* [Customizing Command Prefix](#customizing-command-prefix)
42+
* [Customizing Alias Calculation](#customizing-alias-calculation)
4243
* [CDI Events](#cdi-events)
4344
* [Handling Missing Commands](#handling-missing-commands)
4445
* [Handling Disallowed Commands](#handling-disallowed-commands)
@@ -409,6 +410,50 @@ public class MentionPrefixProvider extends MentionPrefixProviderJavacord {
409410
}
410411
```
411412

413+
#### Customizing Alias Calculation
414+
415+
The alias calculation can be customized by providing a CDI bean that implements the
416+
[`AliasAndParameterStringTransformer`][AliasAndParameterStringTransformer JavaDoc] interface. In the implementation of
417+
the `transformAliasAndParameterString` method you can determine from the message that caused the processing what the
418+
alias and parameter string should be. The transformer is called after the alias and parameter string are determined from
419+
the message using all registered aliases and before the command is resolved from the alias. If an alias was found from
420+
the registered aliases, the `aliasAndParameterString` parameter contains the found information. If no alias was found,
421+
the parameter will be `null`. The fields in the `AliasAndParameterString` object are always non-`null`.
422+
423+
The transformer can then either accept the found alias and parameter string by returning the argument directly, or it
424+
can determine a new alias and parameter string and return these. The return value of the transformer will be used for
425+
further processing. If the alias in the returned object is not one of the registered aliases or the transformer returns
426+
`null`, there will not be any command found and the respective CDI event will be fired.
427+
428+
Example use-cases for this are:
429+
430+
- fuzzy-searching for mistyped aliases and their automatic correction (this could also be used for just a
431+
"did you mean X" response, but for that the command not found events are probably better suited)
432+
433+
- having a command that forwards to one command in one channel but to another command in another channel,
434+
like `!player` that forwards to `!mc:player` in an MC channel but to `!s4:player` in an S4 channel
435+
436+
- supporting something like `!runas @other-user foo bar baz`, where the transformer will transform that to alias
437+
`foo` and parameter string `bar baz` and then a custom `Restriction` can check whether the message author has
438+
the permissions to use `!runas` and then for example whether the `other-user` would have permissions for the
439+
`foo` command and only then allow it to proceed
440+
441+
- forwarding to a `!help` command if an unknown command was issued
442+
443+
_**Example:**_
444+
```java
445+
@ApplicationScoped
446+
public class MyAliasAndParameterStringTransformer implements AliasAndParameterStringTransformer<Message> {
447+
@Override
448+
public AliasAndParameterString transformAliasAndParameterString(
449+
Message message, AliasAndParameterString aliasAndParameterString) {
450+
return (aliasAndParameterString == null)
451+
? new AliasAndParameterString("help", "")
452+
: aliasAndParameterString;
453+
}
454+
}
455+
```
456+
412457
### CDI Events
413458

414459
#### Handling Missing Commands
@@ -557,6 +602,8 @@ limitations under the License.
557602
https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/ParameterParser.html
558603
[PrefixProvider JavaDoc]:
559604
https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/prefix/PrefixProvider.html
605+
[AliasAndParameterStringTransformer JavaDoc]:
606+
https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/AliasAndParameterStringTransformer.html
560607
[@RestrictedTo JavaDoc]:
561608
https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/annotation/RestrictedTo.html
562609
[Restriction JavaDoc]:

‎src/main/java/net/kautler/command/api/AliasAndParameterString.java‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
/*
2+
* Copyright 2019 Björn Kautler
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package net.kautler.command.api;
18+
19+
import java.util.Objects;
20+
import java.util.StringJoiner;
21+
22+
import static java.util.Objects.requireNonNull;
23+
24+
/**
25+
* The combination of an alias and its parameter string as determined from a message.
26+
*/
27+
public class AliasAndParameterString {
28+
/**
29+
* The alias.
30+
*/
31+
private final String alias;
32+
33+
/**
34+
* The parameter string.
35+
*/
36+
private final String parameterString;
37+
38+
/**
39+
* Constructs a new alias and parameter string combination.
40+
*
41+
* @param alias the alias
42+
* @param parameterString the parameter string
43+
*/
44+
public AliasAndParameterString(String alias, String parameterString) {
45+
this.alias = requireNonNull(alias);
46+
this.parameterString = requireNonNull(parameterString);
47+
}
48+
49+
/**
50+
* Returns the alias.
51+
*
52+
* @return the alias
53+
*/
54+
public String getAlias() {
55+
return alias;
56+
}
57+
58+
/**
59+
* Returns the parameter string.
60+
*
61+
* @return the parameter string
62+
*/
63+
public String getParameterString() {
64+
return parameterString;
65+
}
66+
67+
@Override
68+
public boolean equals(Object obj) {
69+
if (this == obj) {
70+
return true;
71+
}
72+
if ((obj == null) || (getClass() != obj.getClass())) {
73+
return false;
74+
}
75+
AliasAndParameterString that = (AliasAndParameterString) obj;
76+
return alias.equals(that.alias) &&
77+
parameterString.equals(that.parameterString);
78+
}
79+
80+
@Override
81+
public int hashCode() {
82+
return Objects.hash(alias, parameterString);
83+
}
84+
85+
@Override
86+
public String toString() {
87+
return new StringJoiner(", ", AliasAndParameterString.class.getSimpleName() + "[", "]")
88+
.add("alias='" + alias + "'")
89+
.add("parameterString='" + parameterString + "'")
90+
.toString();
91+
}
92+
}

‎src/main/java/net/kautler/command/api/AliasAndParameterStringTransformer.java‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
/*
2+
* Copyright 2019 Björn Kautler
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package net.kautler.command.api;
18+
19+
import net.kautler.command.api.restriction.Restriction;
20+
21+
/**
22+
* A transformer that can transform a combination of alias and parameter string to another one.
23+
* It also gets the message from which the combination was derived for determining the new values.
24+
*
25+
* <p>Possible use-cases for example include:
26+
* <ul>
27+
* <li>
28+
* fuzzy-searching for mistyped aliases and their automatic correction
29+
* (this could also be used for just a "did you mean X" response,
30+
* but for that the command not found events are probably better suited)
31+
* </li>
32+
* <li>
33+
* having a command that forwards to one command in one channel
34+
* but to another command in another channel,
35+
* like {@code !player} that forwards to {@code !mc:player} in an MC channel
36+
* but to {@code !s4:player} in an S4 channel
37+
* </li>
38+
* <li>
39+
* supporting something like {@code !runas @other-user foo bar baz},
40+
* where this transformer will transform that to alias {@code foo}
41+
* and parameter string {@code bar baz} and then a custom {@link Restriction}
42+
* can check whether the message author has the permissions to use {@code !runas}
43+
* and then for example whether the {@code other-user} would have permissions
44+
* for the {@code foo} command and only then allow it to proceed
45+
* </li>
46+
* <li>
47+
* forwarding to a {@code !help} command if an unknown command was issued
48+
* </li>
49+
* </ul>
50+
*
51+
* @param <M> the class of the messages for which this transformer can be triggered
52+
*/
53+
public interface AliasAndParameterStringTransformer<M> {
54+
/**
55+
* Transforms the given alias and parameter string to a new one, using the given message.
56+
* The given alias and parameter string can be {@code null} and will be if no alias was found.
57+
*
58+
* @param message the message from which to determine the alias and parameter string
59+
* @param aliasAndParameterString the alias and parameter string that was determined by the standard mechanism if any
60+
* @return the transformed new alias and parameter string or {@code null} if no alias could be determined
61+
*/
62+
AliasAndParameterString transformAliasAndParameterString(M message, AliasAndParameterString aliasAndParameterString);
63+
}

0 commit comments

Comments
 (0)