Package net.kautler.command.api

Class ParameterParser

  • @ApplicationScoped
public class ParameterParser
extends Object
    A parser that can semantically parse and validate a command parameter string according to a defined usage string syntax and return the parsed parameters.

    The usage string has to follow this pre-defined format:

    • Placeholders for free text without whitespaces (in the value) look like <my placeholder>
    • One placeholder for free text with whitespaces (in the value) is allowed as effectively last parameter and looks like <my placeholder...>
    • Literal parameters look like 'literal'
    • Optional parts are enclosed in square brackets like [<optional placeholder>]
    • Alternatives are enclosed in parentheses and are separated by pipe characters like ('all' | 'some' | 'none')
    • Whitespace characters between the defined tokens are optional and ignored
    Examples:
    • @Usage("<coin type> <amount>")
    • @Usage("['all'] ['exact']")
    • @Usage("[<text...>]")
    • @Usage("(<targetLanguage> '|' | <sourceLanguage> <targetLanguage>) <text...>")

    Warning: If you have an optional literal parameter following an optional placeholder parameter like for example [<user mention>] ['exact'] and a user invokes the command with only the parameter exact, it could fit in both parameter slots. You have to decide yourself in which slot it belongs. For cases where the literal parameter can never be meant for the placeholder, you can use fixupParsedParameter(Map, String, String) to correct the parameters map for the two given parameters.

    • Method Detail

      • getParsedParameters

        public Map<String,​String> getParsedParameters​(Command<?> command,
                                                    String prefix,
                                                    String usedAlias,
                                                    String parameterString)
        Returns the parsed parameters for the usage of the given command that was triggered using the given prefix, alias and parameter string. The resulting map will have the placeholder names and literal parameters as keys and the actual supplied arguments as values. If multiple placeholders with the same name have a value, the values are returned as comma-separated values for that placeholder.

        Warning: If you have an optional literal parameter following an optional placeholder parameter like for example [<user mention>] ['exact'] and a user invokes the command with only the parameter exact, it could fit in both parameter slots. You have to decide yourself in which slot it belongs. For cases where the literal parameter can never be meant for the placeholder, you can use fixupParsedParameter(Map, String, String) to correct the parameters map for the two given parameters.

        Parameters:
        command - the command of which the usage should be used to parse the parameters
        prefix - the command prefix that was used to invoke the command
        usedAlias - the alias that was used to invoke the command
        parameterString - the parameter string to parse
        Returns:
        the parsed parameters as map
        Throws:
        IllegalArgumentException - if the parameter string does not adhere to the usage pattern of the given command, which includes that there are arguments given when none were expected; the message is suitable to be directly forwarded to end users
        See Also:
        fixupParsedParameter(Map, String, String)

      • fixupParsedParameter

        public void fixupParsedParameter​(Map<String,​String> parameters,
                                 String placeholderName,
                                 String literalName)
        If you have an optional literal parameter following an optional placeholder parameter like for example [<user mention>] ['exact'] and a user invokes the command with only the parameter exact, it could fit in both parameter slots. You have to decide yourself in which slot it belongs. For cases where the literal parameter can never be meant for the placeholder, you can use this method to correct the parameters map for the two given parameters.

        This method checks whether the literal parameter is absent and the placeholder parameter has the literal parameter as value. If this is the case, the placeholder parameter is removed and the literal parameter added instead.

        Parameters:
        parameters - the parameters map to fix potentially
        placeholderName - the name of the placeholder parameter
        literalName - the name of the literal parameter