io.github.nucleuspowered.nucleus.api.service

Interface NucleusMessageTokenService

public interface NucleusMessageTokenService

Allows plugins to register their own tokens for use in templated messages, and to obtain NucleusTextTemplate instances.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	NucleusMessageTokenService.TokenParser A parser for tokens directed at a plugin.

Method Summary

Modifier and Type	Method and Description
default Optional<org.spongepowered.api.text.Text>	applyPrimaryToken(String primaryToken, org.spongepowered.api.command.CommandSource source) Gets the result of a primary token's registered NucleusMessageTokenService.TokenParser on a CommandSource
default Optional<org.spongepowered.api.text.Text>	applyPrimaryToken(String primaryToken, org.spongepowered.api.command.CommandSource source, Map<String,Object> variables) Gets the result of a primary token's registered NucleusMessageTokenService.TokenParser on a CommandSource
default Optional<org.spongepowered.api.text.Text>	applyToken(String plugin, String token, org.spongepowered.api.command.CommandSource source) Gets the result of a token's registered NucleusMessageTokenService.TokenParser on a CommandSource
default Optional<org.spongepowered.api.text.Text>	applyToken(String plugin, String token, org.spongepowered.api.command.CommandSource source, Map<String,Object> variables) Gets the result of a token's registered NucleusMessageTokenService.TokenParser on a CommandSource
NucleusTextTemplate	createFromString(String string) Creates a NucleusTextTemplate from a string, which could be either Json or Ampersand formatted.
Optional<org.spongepowered.api.util.Tuple<NucleusMessageTokenService.TokenParser,String>>	getPrimaryTokenParserAndIdentifier(String primaryToken) Gets the NucleusMessageTokenService.TokenParser and specific token identifier for a primary token.
List<String>	getPrimaryTokens() Gets the currently registered primary tokens.
default Optional<NucleusMessageTokenService.TokenParser>	getTokenParser(org.spongepowered.api.plugin.PluginContainer pluginContainer) Gets the NucleusMessageTokenService.TokenParser for the specified PluginContainer, if it exists.
Optional<NucleusMessageTokenService.TokenParser>	getTokenParser(String plugin) Gets the NucleusMessageTokenService.TokenParser for the specified plugin id, if it exists.
default Optional<org.spongepowered.api.text.Text>	parseToken(String token, org.spongepowered.api.command.CommandSource source) Parses a token that might be either a primary token or a standard token.
Optional<org.spongepowered.api.text.Text>	parseToken(String token, org.spongepowered.api.command.CommandSource source, Map<String,Object> variables) Parses a token that might be either a primary token or a standard token.
void	register(org.spongepowered.api.plugin.PluginContainer pluginContainer, NucleusMessageTokenService.TokenParser parser) Registers a NucleusMessageTokenService.TokenParser for the specified PluginContainer.
boolean	registerPrimaryToken(String primaryIdentifier, org.spongepowered.api.plugin.PluginContainer registeringPlugin, String identiferToMapTo) A primary token is a token that does not have a plugin identifier - such as {{prefix}}.
boolean	registerTokenFormat(String tokenStart, String tokenEnd, String replacement) Allows users to register additional token delimiter formats.
boolean	unregister(org.spongepowered.api.plugin.PluginContainer pluginContainer) Unregisters the NucleusMessageTokenService.TokenParser for a plugin.

Method Detail

register

void register(org.spongepowered.api.plugin.PluginContainer pluginContainer,
              NucleusMessageTokenService.TokenParser parser)
       throws PluginAlreadyRegisteredException

Registers a NucleusMessageTokenService.TokenParser for the specified PluginContainer. Plugins may only register ONE NucleusMessageTokenService.TokenParser.

Parameters:

pluginContainer - The PluginContainer of the plugin.

parser - The NucleusMessageTokenService.TokenParser that recieves the identifier from the token, along with any contextual variables and the target MessageReceiver of the message.

Throws:

PluginAlreadyRegisteredException - Thrown if the token has been registered previously.

unregister

boolean unregister(org.spongepowered.api.plugin.PluginContainer pluginContainer)

Unregisters the NucleusMessageTokenService.TokenParser for a plugin.

Parameters:

pluginContainer - The PluginContainer of the plugin.

Returns:

true if successful.

registerPrimaryToken

boolean registerPrimaryToken(String primaryIdentifier,
                             org.spongepowered.api.plugin.PluginContainer registeringPlugin,
                             String identiferToMapTo)

A primary token is a token that does not have a plugin identifier - such as {{prefix}}. Plugins can register their own tokens on a first come first served basis. There are some notes:

• If the token you wish to register has already been registered, then you cannot register over it.
• Tokens are case insensitive.
• Tokens cannot have space, colon, pipe or brace characters in them.
• The token is simply an alias for {{pl:plugin:identifier}}. The primary identifier does NOT have to be the same as the token's identifier.

Primary tokens can have extra data, but extra data must appear after a pipe character ("|"). So, a token "bacon" that has the extra data "eggs" would be {{bacon|eggs}}. You only need to register the "bacon" part.

Parameters:

primaryIdentifier - The identifier that you wish to be able to use, without {} marks. So, if you want to register {{clan}}, the input should be "clan".

registeringPlugin - The PluginContainer of the plugin that will control this token.

identiferToMapTo - The identifier that this token will map to - so if {{clan}} should map to {{pl:clans:clanname}}, this should be clanname.

Returns:

true if the mapping was registered.

getTokenParser

default Optional<NucleusMessageTokenService.TokenParser> getTokenParser(org.spongepowered.api.plugin.PluginContainer pluginContainer)

Gets the NucleusMessageTokenService.TokenParser for the specified PluginContainer, if it exists.

Parameters:

pluginContainer - The PluginContainer of the pluginContainer that registered the token.

Returns:

The NucleusMessageTokenService.TokenParser that is run for the token, if it exists.

getTokenParser

Optional<NucleusMessageTokenService.TokenParser> getTokenParser(String plugin)

Gets the NucleusMessageTokenService.TokenParser for the specified plugin id, if it exists.

Parameters:

plugin - The ID of the plugin that registered the token.

Returns:

The NucleusMessageTokenService.TokenParser that is run for the token, if it exists.

applyToken

default Optional<org.spongepowered.api.text.Text> applyToken(String plugin,
                                                             String token,
                                                             org.spongepowered.api.command.CommandSource source)

Gets the result of a token's registered NucleusMessageTokenService.TokenParser on a CommandSource

Parameters:

plugin - The ID of the plugin that registered the token.

token - The identifier that is passed to the NucleusMessageTokenService.TokenParser.

source - The CommandSource to perform the operation with.

Returns:

The Text, if any.

getPrimaryTokenParserAndIdentifier

Optional<org.spongepowered.api.util.Tuple<NucleusMessageTokenService.TokenParser,String>> getPrimaryTokenParserAndIdentifier(String primaryToken)

Gets the NucleusMessageTokenService.TokenParser and specific token identifier for a primary token.

Parameters:

primaryToken - The primary token, without { and } characters.

Returns:

A Tuple with the NucleusMessageTokenService.TokenParser and specific identifier to pass to the parser.

getPrimaryTokens

List<String> getPrimaryTokens()

Gets the currently registered primary tokens.

Returns:

The primary tokens.

applyToken

default Optional<org.spongepowered.api.text.Text> applyToken(String plugin,
                                                             String token,
                                                             org.spongepowered.api.command.CommandSource source,
                                                             Map<String,Object> variables)

Gets the result of a token's registered NucleusMessageTokenService.TokenParser on a CommandSource

Parameters:

plugin - The ID of the plugin that registered the token.

token - The identifier that is passed to the NucleusMessageTokenService.TokenParser.

source - The CommandSource to perform the operation with.

variables - The variables that could be used in the token.

Returns:

The Text, if any.

applyPrimaryToken

default Optional<org.spongepowered.api.text.Text> applyPrimaryToken(String primaryToken,
                                                                    org.spongepowered.api.command.CommandSource source)

Gets the result of a primary token's registered NucleusMessageTokenService.TokenParser on a CommandSource

Parameters:

primaryToken - The primary identifier that parsed.

source - The CommandSource to perform the operation with.

Returns:

The Text, if any.

applyPrimaryToken

default Optional<org.spongepowered.api.text.Text> applyPrimaryToken(String primaryToken,
                                                                    org.spongepowered.api.command.CommandSource source,
                                                                    Map<String,Object> variables)

Gets the result of a primary token's registered NucleusMessageTokenService.TokenParser on a CommandSource

Parameters:

primaryToken - The primary identifier that parsed.

source - The CommandSource to perform the operation with.

variables - The variables that could be used in the token.

Returns:

The Text, if any.

parseToken

default Optional<org.spongepowered.api.text.Text> parseToken(String token,
                                                             org.spongepowered.api.command.CommandSource source)

Parses a token that might be either a primary token or a standard token.

Parameters:

token - The token, without the delimiters.

source - The source to apply the tokens with.

Returns:

The token result, if it exists.

parseToken

Optional<org.spongepowered.api.text.Text> parseToken(String token,
                                                     org.spongepowered.api.command.CommandSource source,
                                                     @Nullable
                                                     Map<String,Object> variables)

Parses a token that might be either a primary token or a standard token.

Parameters:

token - The token, without the delimiters.

source - The source to apply the tokens with.

variables - The variables to pass to the parser.

Returns:

The token result, if it exists.

registerTokenFormat

boolean registerTokenFormat(String tokenStart,
                            String tokenEnd,
                            String replacement)
                     throws IllegalArgumentException

Allows users to register additional token delimiter formats. For example, if a token wanted to register {%id%} to run {{pl:blah:id}}, then they would need to run:

     registerTokenFormat("{%", "%}", "pl:blah:$1")
 

Note that the third argument contains $1. This method will replace $1 with the ID.

This will only apply to Ampersand formatted strings.

Parameters:

tokenStart - The start delimiter of a token to register.

tokenEnd - The end delimiter of a token to register.

replacement - The form of the token identifier to use (without the {{,}} delimiters).

Returns:

true if successful.

Throws:

IllegalArgumentException - thrown if the delimiters are illegal.

createFromString

NucleusTextTemplate createFromString(String string)
                              throws NucleusException

Creates a NucleusTextTemplate from a string, which could be either Json or Ampersand formatted.

Parameters:

string - The string to register.

Returns:

The NucleusTextTemplate that can be parsed.

Throws:

NucleusException - thrown if the string could not be parsed.