Text processing

Text processors are a core component of the API. They are responsible for parsing and transforming chat messages using registered parsers, placeholders, keywords, and formatters.

The API provides a default GlobalTextProcessor, which can be accessed through:

Social.get().getTextProcessor();

The global text processor manages all registered text parsers and provides utility methods for parsing messages.

Processing a message

Messages can be processed using the parsers registered in the global text processor through the GlobalTextProcessor::parse method. To do this, you must provide a SocialParserContext.

Note

This section assumes that you already know how to obtain a SocialUser instance.

// Build the parser context
var context = SocialParserContext.builder(user, Component.text("Hello, $(nickname)! :smile:"))
    .build();

// Parse the message
Component message = Social.get().getTextProcessor().parse(context);

Convenience methods

The global text processor provides convenience methods that avoid manually creating a SocialParserContext. These are particularly useful when parsing multiple messages:

• parse(user, channel, message): parses a message and returns the resulting Component.
  • user - instance of SocialUser
  • channel - instance of ChatChannel
  • message - either a Component or a String
• parseAndSend(user, channel, message): parses a message and immediately sends it to the specified user
  • user - instance of SocialUser
  • channel - instance of ChatChannel
  • message - either a Component or a String

Registering custom placeholders

Placeholders can be registered in the global text processor by extending SocialContextualPlaceholder or by providing a lambda function.

The following example demonstrates the lambda-based approach:

String identifier = "example_placeholder"; // Our placeholder will be $(example_placeholder)

Social.get().getTextProcessor().registerContextualPlaceholder(identifier, context -> { 
    return Component.text(context.user().displayName().color(NamedTextColor.GOLD));
});

This placeholder returns the player's display name formatted in gold.

Registering custom keywords

Keywords are registered in the same way as placeholders, but using GlobalTextProcessor::registerContextualKeyword:

String keyword = "example_keyword"; // [example_keyword]

Social.get().getTextProcessor().registerContextualKeyword(keyword, context -> {
    return Component.text("Click me!")
        .clickEvent(ClickEvent.runCommand("/me hello world!"));
});

Tip

Keywords are intended for player use. Prefer short, intuitive, and memorable names.

Registering custom parsers

Custom parsers provide the most flexibility and allow deeper integration with the message processing pipeline.

To create a parser, implement the SocialContextualParser interface:

ExampleParser.java

public class ExampleParser implements SocialContextualParser {

    @Override
    public Component parse(SocialParserContext context) {
        return context.message().replaceText(
                TextReplacementConfig.builder()
                        .matchLiteral("try the ketchup")
                        .replacement(Component.text("try the ketchup")
                                .color(NamedTextColor.RED))
                        .build()
        );
    }

}

Customizing parser behavior

Parser behavior can be modified by implementing additional interfaces.

By default, parsers operate only on non-player input. To support player input as well, implement SocialUserInputParser. If the parser should operate only on player input, implement SocialFilterLike.

Supporting offline players

Version 0.4 introduces an experimental mechanism that allows parsers to operate when the user is offline, or when the parser does not require access to the context's user.

To enable this behavior, override:

@Override
public boolean supportsOfflinePlayers() {
    return true;
}

Parser execution order

The global text processor provides two additional parser groups: - Early parsers: executed before registered parsers - Late parsers: executed after registered parsers

Although the standard registration methods are recommended, these groups allow greater control over the parsing pipeline. For example:

Social.get().getTextProcessor().LATE_PARSERS.add(new ExampleParser());