Class MagicPlaceholders

java.lang.Object
dev.ua.theroer.magicutils.placeholders.MagicPlaceholders
public final class MagicPlaceholders extends Object
Registry and helpers for MagicUtils placeholder resolution.

  • Method Details

    • registerNamespace

      public static MagicPlaceholders.NamespaceMeta registerNamespace(String namespace, @Nullable @Nullable String author, @Nullable @Nullable String version)
      Registers or updates metadata for a namespace.
      Parameters:
      namespace - namespace id
      author - namespace author
      version - namespace version
      Returns:
      metadata instance for the namespace

    • getNamespaceMeta

      public static MagicPlaceholders.NamespaceMeta getNamespaceMeta(String namespace)
      Returns metadata for the namespace, creating it if missing.
      Parameters:
      namespace - namespace id
      Returns:
      metadata instance for the namespace

    • register

      public static void register(String namespace, String key, MagicPlaceholders.PlaceholderResolver resolver)
      Registers a placeholder resolver.
      Parameters:
      namespace - namespace id
      key - placeholder key
      resolver - resolver implementation

    • registerGlobal

      public static void registerGlobal(String key, MagicPlaceholders.PlaceholderResolver resolver)
      Registers a global placeholder resolver (no namespace).
      Parameters:
      key - placeholder key
      resolver - resolver implementation

    • registerLocal

      public static void registerLocal(Object ownerKey, String key, MagicPlaceholders.PlaceholderResolver resolver)
      Registers a local placeholder resolver scoped to an owner.
      Parameters:
      ownerKey - owner scope key
      key - placeholder key
      resolver - resolver implementation

    • unregister

      public static void unregister(String namespace, String key)
      Unregisters a placeholder resolver.
      Parameters:
      namespace - namespace id
      key - placeholder key

    • unregisterGlobal

      public static void unregisterGlobal(String key)
      Unregisters a global placeholder resolver.
      Parameters:
      key - placeholder key

    • clearLocal

      public static void clearLocal(Object ownerKey)
      Removes all local placeholders for an owner.
      Parameters:
      ownerKey - owner scope key

    • get

      @Nullable public static @Nullable MagicPlaceholders.PlaceholderResolver get(String namespace, String key)
      Returns the resolver for a placeholder key.
      Parameters:
      namespace - namespace id
      key - placeholder key
      Returns:
      resolver or null if missing

    • resolveResult

      public static MagicPlaceholders.PlaceholderResult resolveResult(String namespace, String key, @Nullable @Nullable Audience audience, @Nullable @Nullable String argument)
      Resolves a placeholder value with error details.
      Parameters:
      namespace - namespace id
      key - placeholder key
      audience - optional audience
      argument - optional argument
      Returns:
      result containing value and error details

    • resolve

      public static String resolve(String namespace, String key, @Nullable @Nullable Audience audience, @Nullable @Nullable String argument)
      Resolves a placeholder value.
      Parameters:
      namespace - namespace id
      key - placeholder key
      audience - optional audience
      argument - optional argument
      Returns:
      resolved value or empty string on failure

    • render

      public static String render(PlaceholderContext context, String text)
      Resolves placeholders inside a string using the provided context.
      Parameters:
      context - placeholder context
      text - input text
      Returns:
      resolved text

    • render

      public static String render(@Nullable @Nullable Audience audience, String text)
      Resolves placeholders inside a string for an audience.
      Parameters:
      audience - audience context
      text - input text
      Returns:
      resolved text

    • render

      public static String render(@Nullable @Nullable Audience audience, String text, Map<String,String> inline)
      Resolves placeholders inside a string with inline replacements.
      Parameters:
      audience - audience context
      text - input text
      inline - inline placeholder values
      Returns:
      resolved text

    • entries

      public static Map<MagicPlaceholders.PlaceholderKey, MagicPlaceholders.PlaceholderResolver> entries()
      Returns a snapshot of registered placeholders.
      Returns:
      copy of the placeholder map

    • keysForNamespace

      public static List<MagicPlaceholders.PlaceholderKey> keysForNamespace(String namespace)
      Returns placeholder keys within a namespace.
      Parameters:
      namespace - namespace id
      Returns:
      list of placeholder keys

    • namespaces

      public static Set<String> namespaces()
      Returns all registered namespaces.
      Returns:
      set of namespace ids

    • addListener

      public static void addListener(MagicPlaceholders.PlaceholderListener listener)
      Adds a placeholder listener.
      Parameters:
      listener - listener to add

    • addWeakListener

      public static void addWeakListener(MagicPlaceholders.PlaceholderListener listener)
      Adds a placeholder listener as a weak reference.
      Parameters:
      listener - listener to add

    • removeListener

      public static void removeListener(MagicPlaceholders.PlaceholderListener listener)
      Removes a placeholder listener.
      Parameters:
      listener - listener to remove

    • clearListeners

      public static void clearListeners()
      Clears all registered listeners.

    • setDebugListener

      public static void setDebugListener(@Nullable @Nullable MagicPlaceholders.PlaceholderDebugListener listener)
      Sets a debug listener for placeholder resolution events.
      Parameters:
      listener - debug listener (null disables)

    • addDebugListener

      public static void addDebugListener(@Nullable @Nullable MagicPlaceholders.PlaceholderDebugListener listener)
      Adds a debug listener for placeholder resolution events.
      Parameters:
      listener - debug listener to add

    • removeDebugListener

      public static void removeDebugListener(@Nullable @Nullable MagicPlaceholders.PlaceholderDebugListener listener)
      Removes a debug listener.
      Parameters:
      listener - listener to remove

    • clearAll

      public static void clearAll()
      Clears all registered placeholders, namespaces, and listeners.

      Intended for test teardown or hot-reload scenarios.

    • audienceFromUuid

      @Nullable public static @Nullable Audience audienceFromUuid(@Nullable @Nullable UUID uuid)
      Creates a lightweight audience wrapper for a UUID.
      Parameters:
      uuid - audience UUID
      Returns:
      audience wrapper or null