Package net.kyori.adventure.text

Interface JoinConfiguration

  • All Superinterfaces:
    Buildable<JoinConfiguration,​JoinConfiguration.Builder>, net.kyori.examination.Examinable
    @NonExtendable
public interface JoinConfiguration
extends Buildable<JoinConfiguration,​JoinConfiguration.Builder>, net.kyori.examination.Examinable
    A configuration for how a series of components can be joined.

    A join configuration consists of the following parts:

    • a prefix (optional)

      a component to be prepended to the resulting component

    • a separator (optional)

      a component to be placed between each component

    • a last separator (optional)

      a component to be placed between the last two components

    • a suffix (optional)

      a component to be appended to the resulting component

    • a convertor (required, defaults to ComponentLike.asComponent())

      a function to change each ComponentLike that is being joined into a Component

    • a predicate (required, defaults to true)

      a predicate that specifies if a given component should be included in the join process

    • a root style (required, defaults to Style.empty())

      the style of the parent component that contains the joined components.

    Note that the last separator only acts as an override for the normal separator. This means that if you do not specify a last separator, the normal separator will be placed between the last two components. To omit the final separator, but still include normal separators, use Component.empty() as the last separator.

    If specified, the join method can use a different last separator in the case where the amount of components being joined together is more than two. This can be used to insert a serial (or Oxford) comma if needed.

    Null elements are not allowed in the input of the join methods or as output from the convertor. If you would like to exclude elements from being joined, use the predicate.

    Since:
    4.9.0
    See Also:
    Component.join(JoinConfiguration, Iterable), Component.join(JoinConfiguration, ComponentLike...)

    • Method Detail

      • builder

        @NotNull
static @NotNull JoinConfiguration.Builder builder()
        Creates a new builder.
        Returns:
        a new builder
        Since:
        4.9.0

      • noSeparators

        @NotNull
static @NotNull JoinConfiguration noSeparators()
        Gets a join configuration with no separators, prefix or suffix.
        Returns:
        the join configuration
        Since:
        4.9.0

      • newlines

        @NotNull
static @NotNull JoinConfiguration newlines()
        Provides a join configuration with no prefix or suffix that simply joins the components together using the Component.newline() component.

        A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating the following output: 'hello\nthere'.

        Returns:
        the join configuration
        Since:
        4.10.0

      • commas

        @NotNull
static @NotNull JoinConfiguration commas​(boolean spaces)
        Provides a join configuration with no prefix or suffix that simply joins the components together using a single comma, matching a CSV like layout.

        A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating either the output 'hello,there' or 'hello, there' depending on whether the passed boolean flag was false or true respectively.

        Parameters:
        spaces - a plain boolean flag indicating whether the returned comma-based join configuration should append a single space after each comma or not
        Returns:
        the join configuration
        Since:
        4.10.0

      • arrayLike

        @NotNull
static @NotNull JoinConfiguration arrayLike()
        Provides a join configuration that joins components together in the same manner Arrays.toString(Object[]) stringifies an array. Specifically, the join configuration prefixes and suffixes the components with an open or closed square bracket respectively. Components themselves are joined together using a comma and a space.

        A purely text based example of this syntax, without introducing the concepts of components, would join the two strings 'hello' and 'there' together, creating the following output: '[hello, there]'.

        Returns:
        the join configuration
        Since:
        4.10.0

      • separator

        @NotNull
static @NotNull JoinConfiguration separator​(@Nullable
                                            @Nullable ComponentLike separator)
        Creates a join configuration with a separator and no prefix or suffix.
        Parameters:
        separator - the separator
        Returns:
        the join configuration
        Since:
        4.9.0

      • separators

        @NotNull
static @NotNull JoinConfiguration separators​(@Nullable
                                             @Nullable ComponentLike separator,
                                             @Nullable
                                             @Nullable ComponentLike lastSeparator)
        Creates a join configuration with a separator and last separator but no prefix or suffix.
        Parameters:
        separator - the separator
        lastSeparator - the last separator
        Returns:
        the join configuration
        Since:
        4.9.0

      • prefix

        @Nullable
@Nullable Component prefix()
        Gets the prefix of this join configuration.
        Returns:
        the prefix
        Since:
        4.9.0

      • suffix

        @Nullable
@Nullable Component suffix()
        Gets the suffix of this join configuration.
        Returns:
        the suffix
        Since:
        4.9.0

      • separator

        @Nullable
@Nullable Component separator()
        Gets the separator of this join configuration.
        Returns:
        the separator
        Since:
        4.9.0

      • lastSeparator

        @Nullable
@Nullable Component lastSeparator()
        Gets the last separator of this join configuration.
        Returns:
        the last separator
        Since:
        4.9.0

      • lastSeparatorIfSerial

        @Nullable
@Nullable Component lastSeparatorIfSerial()
        Gets the last separator that will be used instead of the normal last separator in the case where there are more than two components being joined. This can be used to mimic a serial (or Oxford) comma.
        Returns:
        the separator
        Since:
        4.9.0

      • convertor

        @NotNull
@NotNull java.util.function.Function<ComponentLike,​Component> convertor()
        Gets the convertor of this join configuration.

        This is used to change the components that are going to be joined. It does not touch the prefix, suffix or any of the separators.

        Returns:
        the operator
        Since:
        4.9.0

      • predicate

        @NotNull
@NotNull java.util.function.Predicate<ComponentLike> predicate()
        Gets the predicate of this join configuration.

        This is used to determine if a component is to be included in the join process. It does not touch the prefix, suffix or any of the separators.

        Returns:
        the predicate
        Since:
        4.9.0

      • parentStyle

        @NotNull
@NotNull Style parentStyle()
        Gets the style of the parent component that contains the joined components.
        Returns:
        the style
        Since:
        4.11.0