Allow to customize the alias calculation

Author: Vampire

config/codenarc/codenarc.groovy

@@ -30,7 +30,11 @@ ruleset {
     BrokenOddnessCheck
     ClassForName
     ComparisonOfTwoConstants
-    ComparisonWithSelf
+    ComparisonWithSelf {
+        doNotApplyToClassNames = [
+                'net.kautler.command.api.AliasAndParameterStringTest'
+        ].join(', ')
+    }
     ConstantAssertExpression
     ConstantIfExpression
     ConstantTernaryExpression
@@ -276,7 +280,11 @@ ruleset {
         ].join(', ')
     }
     ExplicitCallToDivMethod
-    ExplicitCallToEqualsMethod
+    ExplicitCallToEqualsMethod {
+        doNotApplyToClassNames = [
+                'net.kautler.command.api.AliasAndParameterStringTest'
+        ].join(', ')
+    }
     ExplicitCallToGetAtMethod
     ExplicitCallToLeftShiftMethod
     ExplicitCallToMinusMethod
@@ -391,7 +399,9 @@ ruleset {
 
     // rulesets/size.xml
     //AbcMetric   // Requires the GMetrics jar
-    ClassSize
+    ClassSize {
+        maxLines = 1500
+    }
     //CrapMetric   // Requires the GMetrics jar and a Cobertura coverage file
     //CyclomaticComplexity   // Requires the GMetrics jar
     //MethodCount

config/pmd/pmd.xml

@@ -207,7 +207,9 @@
                     \QFound 'DU'-anomaly for variable 'result' (lines '\E.* |
                     \QFound 'DU'-anomaly for variable 'usageTree' (lines '\E.* |
                     \QFound 'DU'-anomaly for variable 'seen' (lines '\E.* |
-                    \QFound 'DD'-anomaly for variable 'distance' (lines '\E.*
+                    \QFound 'DD'-anomaly for variable 'distance' (lines '\E.* |
+                    \QFound 'DD'-anomaly for variable 'aliasAndParameterString' (lines '\E.* |
+                    \QFound 'DU'-anomaly for variable 'parameterString' (lines '\E.*
                 </value>
             </property>
         </properties>

config/spotbugs/spotbugs-exclude.xml

@@ -52,6 +52,7 @@
                     <Method name="setAvailableRestrictions" params="javax.enterprise.inject.Instance" returns="void"/>
                     <Method name="setCommands" params="javax.enterprise.inject.Instance" returns="void"/>
                     <Method name="setCustomPrefixProvider" params="javax.enterprise.inject.Instance" returns="void"/>
+                    <Method name="setAliasAndParameterStringTransformer" params="javax.enterprise.inject.Instance" returns="void"/>
                 </Or>
             </And>
         </Or>

readme/README_template.md

@@ -39,6 +39,7 @@ Table of Contents
     * [Command Usage](#command-usage)
     * [Parsing Parameters](#parsing-parameters)
     * [Customizing Command Prefix](#customizing-command-prefix)
+    * [Customizing Alias Calculation](#customizing-alias-calculation)
   * [CDI Events](#cdi-events)
     * [Handling Missing Commands](#handling-missing-commands)
     * [Handling Disallowed Commands](#handling-disallowed-commands)
@@ -409,6 +410,50 @@ public class MentionPrefixProvider extends MentionPrefixProviderJavacord {
 }
 ```
 
+#### Customizing Alias Calculation
+
+The alias calculation can be customized by providing a CDI bean that implements the
+[`AliasAndParameterStringTransformer`][AliasAndParameterStringTransformer JavaDoc] interface. In the implementation of
+the `transformAliasAndParameterString` method you can determine from the message that caused the processing what the
+alias and parameter string should be. The transformer is called after the alias and parameter string are determined from
+the message using all registered aliases and before the command is resolved from the alias. If an alias was found from
+the registered aliases, the `aliasAndParameterString` parameter contains the found information. If no alias was found,
+the parameter will be `null`. The fields in the `AliasAndParameterString` object are always non-`null`.
+
+The transformer can then either accept the found alias and parameter string by returning the argument directly, or it
+can determine a new alias and parameter string and return these. The return value of the transformer will be used for
+further processing. If the alias in the returned object is not one of the registered aliases or the transformer returns
+`null`, there will not be any command found and the respective CDI event will be fired.
+
+Example use-cases for this are:
+
+- fuzzy-searching for mistyped aliases and their automatic correction (this could also be used for just a
+  "did you mean X" response, but for that the command not found events are probably better suited)
+
+- having a command that forwards to one command in one channel but to another command in another channel,
+  like `!player` that forwards to `!mc:player` in an MC channel but to `!s4:player` in an S4 channel
+
+- supporting something like `!runas @other-user foo bar baz`, where the transformer will transform that to alias
+  `foo` and parameter string `bar baz` and then a custom `Restriction` can check whether the message author has
+  the permissions to use `!runas` and then for example whether the `other-user` would have permissions for the
+  `foo` command and only then allow it to proceed
+
+- forwarding to a `!help` command if an unknown command was issued
+
+_**Example:**_
+```java
+@ApplicationScoped
+public class MyAliasAndParameterStringTransformer implements AliasAndParameterStringTransformer<Message> {
+    @Override
+    public AliasAndParameterString transformAliasAndParameterString(
+            Message message, AliasAndParameterString aliasAndParameterString) {
+        return (aliasAndParameterString == null)
+                ? new AliasAndParameterString("help", "")
+                : aliasAndParameterString;
+    }
+}
+```
+
 ### CDI Events
 
 #### Handling Missing Commands
@@ -557,6 +602,8 @@ limitations under the License.
     https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/ParameterParser.html
 [PrefixProvider JavaDoc]:
     https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/prefix/PrefixProvider.html
+[AliasAndParameterStringTransformer JavaDoc]:
+    https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/AliasAndParameterStringTransformer.html
 [@RestrictedTo JavaDoc]:
     https://www.javadoc.io/page/net.kautler/command-framework/latest/net/kautler/command/api/annotation/RestrictedTo.html
 [Restriction JavaDoc]:

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

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2019 Björn Kautler
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.kautler.command.api;
+
+import java.util.Objects;
+import java.util.StringJoiner;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * The combination of an alias and its parameter string as determined from a message.
+ */
+public class AliasAndParameterString {
+    /**
+     * The alias.
+     */
+    private final String alias;
+
+    /**
+     * The parameter string.
+     */
+    private final String parameterString;
+
+    /**
+     * Constructs a new alias and parameter string combination.
+     *
+     * @param alias           the alias
+     * @param parameterString the parameter string
+     */
+    public AliasAndParameterString(String alias, String parameterString) {
+        this.alias = requireNonNull(alias);
+        this.parameterString = requireNonNull(parameterString);
+    }
+
+    /**
+     * Returns the alias.
+     *
+     * @return the alias
+     */
+    public String getAlias() {
+        return alias;
+    }
+
+    /**
+     * Returns the parameter string.
+     *
+     * @return the parameter string
+     */
+    public String getParameterString() {
+        return parameterString;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj) {
+            return true;
+        }
+        if ((obj == null) || (getClass() != obj.getClass())) {
+            return false;
+        }
+        AliasAndParameterString that = (AliasAndParameterString) obj;
+        return alias.equals(that.alias) &&
+                parameterString.equals(that.parameterString);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(alias, parameterString);
+    }
+
+    @Override
+    public String toString() {
+        return new StringJoiner(", ", AliasAndParameterString.class.getSimpleName() + "[", "]")
+                .add("alias='" + alias + "'")
+                .add("parameterString='" + parameterString + "'")
+                .toString();
+    }
+}

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

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2019 Björn Kautler
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.kautler.command.api;
+
+import net.kautler.command.api.restriction.Restriction;
+
+/**
+ * A transformer that can transform a combination of alias and parameter string to another one.
+ * It also gets the message from which the combination was derived for determining the new values.
+ *
+ * <p>Possible use-cases for example include:
+ * <ul>
+ *     <li>
+ *         fuzzy-searching for mistyped aliases and their automatic correction
+ *         (this could also be used for just a "did you mean X" response,
+ *         but for that the command not found events are probably better suited)
+ *     </li>
+ *     <li>
+ *         having a command that forwards to one command in one channel
+ *         but to another command in another channel,
+ *         like {@code !player} that forwards to {@code !mc:player} in an MC channel
+ *         but to {@code !s4:player} in an S4 channel
+ *     </li>
+ *     <li>
+ *         supporting something like {@code !runas @other-user foo bar baz},
+ *         where this transformer will transform that to alias {@code foo}
+ *         and parameter string {@code bar baz} and then a custom {@link Restriction}
+ *         can check whether the message author has the permissions to use {@code !runas}
+ *         and then for example whether the {@code other-user} would have permissions
+ *         for the {@code foo} command and only then allow it to proceed
+ *     </li>
+ *     <li>
+ *         forwarding to a {@code !help} command if an unknown command was issued
+ *     </li>
+ * </ul>
+ *
+ * @param <M> the class of the messages for which this transformer can be triggered
+ */
+public interface AliasAndParameterStringTransformer<M> {
+    /**
+     * Transforms the given alias and parameter string to a new one, using the given message.
+     * The given alias and parameter string can be {@code null} and will be if no alias was found.
+     *
+     * @param message                 the message from which to determine the alias and parameter string
+     * @param aliasAndParameterString the alias and parameter string that was determined by the standard mechanism if any
+     * @return the transformed new alias and parameter string or {@code null} if no alias could be determined
+     */
+    AliasAndParameterString transformAliasAndParameterString(M message, AliasAndParameterString aliasAndParameterString);
+}