001/*
002 * PlotSquared, a land and world management plugin for Minecraft.
003 * Copyright (C) IntellectualSites <https://intellectualsites.com>
004 * Copyright (C) IntellectualSites team and contributors
005 *
006 * This program is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * This program is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
018 */
019package com.plotsquared.core.configuration.caption.load;
020
021import org.checkerframework.checker.nullness.qual.NonNull;
022import org.checkerframework.checker.nullness.qual.Nullable;
023
024import java.util.Locale;
025import java.util.Map;
026import java.util.function.Function;
027
028public interface DefaultCaptionProvider {
029
030    /**
031     * Returns a DefaultCaptionProvider that loads captions from a {@link ClassLoader}'s resources.
032     * The resource urls are determined by applying the given function to a locale.
033     *
034     * @param classLoader the class loader to load caption resources from.
035     * @param urlProvider the function to get an url from a locale.
036     * @return a caption provider using a function to determine resource urls.
037     */
038    static @NonNull DefaultCaptionProvider forClassLoader(
039            final @NonNull ClassLoader classLoader,
040            final @NonNull Function<@NonNull Locale, @NonNull String> urlProvider
041    ) {
042        return new ClassLoaderCaptionProvider(classLoader, urlProvider);
043    }
044
045    /**
046     * Returns a DefaultCaptionProvider that loads captions from a {@link ClassLoader}'s resources.
047     * The resource urls are determined by replacing the first occurrence of {@code %s} in the string with
048     * {@link Locale#toString()}.
049     *
050     * @param classLoader the class loader to load caption resources from.
051     * @param toFormat    a string that can be formatted to result in a valid resource url when calling
052     *                    {@code String.format(toFormat, Locale#toString)}
053     * @return a caption provider using string formatting to determine resource urls.
054     */
055    static @NonNull DefaultCaptionProvider forClassLoaderFormatString(
056            final @NonNull ClassLoader classLoader,
057            final @NonNull String toFormat
058    ) {
059        return forClassLoader(classLoader, locale -> String.format(toFormat, locale));
060    }
061
062    /**
063     * Loads default translation values for a specific language and returns it as a map.
064     * If no default translation exists, {@code null} is returned. A returned map might be empty.
065     *
066     * @param locale the locale to load the values for.
067     * @return a map of default values for the given locale.
068     */
069    @Nullable Map<@NonNull String, @NonNull String> loadDefaults(final @NonNull Locale locale);
070
071}