Package api.config

Class AddonConfig

java.lang.Object
api.config.AddonConfig
public final class AddonConfig extends Object

A map from config paths to config values. Paths are dot-separated expressions such as foo.bar.baz. Values are as in JSON (booleans, strings, numbers, lists, or objects). Values accessed through an AddonConfig are never null. If a path does not exist when called with a get____ function, a ConfigException.Missing will be thrown.

All paths must be initially registered during BTWAddon.registerConfigProperties(api.config.AddonConfig), or they will not be saved.

In addition, ALWAYS call readAndWriteConfig() when editing this config after BTWAddon.registerConfigProperties(api.config.AddonConfig), or properties WILL NOT BE SAVED. An example config would be set up during BTWAddon.registerConfigProperties(api.config.AddonConfig): 

 public void registerConfigProperties(AddonConfig config) {
 	// Register an integer with no minimum and no maximum and a default value of 6 to path foo.bar with no comment
 	config.registerInt("foo.bar", 6);
 	//Register a boolean with a default value of false to
 	config.registerBoolean("foo.buzz", false, "A boolean");
 	//Note that the previous two examples will be in the path category "foo", and you can add a comment to that category
 	config.registerCategoryComment("foo", "This is the foo category");
 	// If transferring old values to new values, such as when updating a config, you can update the old path to the new one with updatePath like so
 	config.updatePath("bar", "foo.bar");
 }

  • Constructor Details

    • AddonConfig

      public AddonConfig(String fileName)

    • AddonConfig

      public AddonConfig(String fileName, String oldFileName)

  • Method Details

    • registerCategoryComment

      public AddonConfig registerCategoryComment(String path, String... comment)
      Register a comment for a specific path. It's recommended to call this after registering values, or the comment might not be appended properly.

      Recommended for categories, for example, if you have multiple paths such as general.foo and general.bar, calling registerCategoryComment("general", "Some comment") will append the comment # Some comment in the config.

      Parameters:
      path - Path to register comment for. If the path already exists, appends old comment to the end.
      comment - Comments to add to the path. Use separate strings instead of \n.

    • registerCategoryComment

      public AddonConfig registerCategoryComment(String path, List<String> comment)
      Register a comment for a specific path. It's recommended to call this after registering values, or the comment might not be appended properly.

      Recommended for categories, for example, if you have multiple paths such as general.foo and general.bar, calling registerCategoryComment("general", "Some comment") will append the comment # Some comment in the user facing config.

      Parameters:
      path - Path to register comment for. If the path already exists, appends old comment to the end.
      comment - Comments to add to the path. Use separate strings instead of \n.

    • registerInt

      public AddonConfig registerInt(String path, int value, int min, int max, List<String> comments)
      Register an integer key value pair. Specify a min and max value to set the minimum and maximum allowed values.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Integer.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Integer.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerInt

      public AddonConfig registerInt(String path, int value, int min, int max, String... comments)
      Register an integer key value pair. Specify a min and max value to set the minimum and maximum allowed values.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Integer.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Integer.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerInt

      public AddonConfig registerInt(String path, int value, List<String> comments)
      Register an integer key value pair. Has no min or max value.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerInt

      public AddonConfig registerInt(String path, int value, String... comments)
      Register an integer key value pair. Has no min or max value.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerLong

      public AddonConfig registerLong(String path, long value, long min, long max, List<String> comments)
      Register a long key value pair. Specify a min and max value to set the minimum and maximum allowed values.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Long.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Long.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerLong

      public AddonConfig registerLong(String path, long value, long min, long max, String... comments)
      Register a long key value pair. Specify a min and max value to set the minimum and maximum allowed values.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Long.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Long.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerLong

      public AddonConfig registerLong(String path, long value, List<String> comments)
      Register a long key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerLong

      public AddonConfig registerLong(String path, long value, String... comments)
      Register a long key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerDouble

      public AddonConfig registerDouble(String path, double value, double min, double max, List<String> comments)
      Register a double key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerDouble

      public AddonConfig registerDouble(String path, double value, double min, double max, String... comments)
      Register a double key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerDouble

      public AddonConfig registerDouble(String path, double value, List<String> comments)
      Register a double key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerDouble

      public AddonConfig registerDouble(String path, double value, String... comments)
      Register a double key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerString

      public AddonConfig registerString(String path, String value, List<String> comments)
      Register a string key value pair to this config allowing any string value. Use registerEnum(String, Enum, Class, List) instead if there should only be specific strings allowed.
      Parameters:
      path - Path to register string to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerString

      public AddonConfig registerString(String path, String value, String... comments)
      Register a string key value pair to this config allowing any string value. Use registerEnum(String, Enum, Class, String...) instead if there should only be specific strings allowed.
      Parameters:
      path - Path to register string to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerBoolean

      public AddonConfig registerBoolean(String path, boolean value, List<String> comments)
      Register a boolean key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerBoolean

      public AddonConfig registerBoolean(String path, boolean value, String... comments)
      Register a boolean key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerEnum

      public <T extends Enum<T>> AddonConfig registerEnum(String path, T value, Class<T> enumClass, List<String> comments)
      Register an Enum based key value pair to this config. Will use the name of the enum constants as the valid strings.
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      path - Path to register double to.
      value - The default value for this path. Must be an element of an enum class. Users will have to match the case exactly, or an error will be thrown and the default will be used.
      enumClass - Class of the value enum, e.g. FooBarEnum.class.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerEnum

      public <T extends Enum<T>> AddonConfig registerEnum(String path, T value, Class<T> enumClass, String... comments)
      Register an Enum based key value pair to this config. Will use the name of the enum constants as the valid strings.
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      path - Path to register double to.
      value - The default value for this path. Must be an element of an enum class.
      enumClass - Class of the value enum, e.g. FooBarEnum.class.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerBooleanList

      public AddonConfig registerBooleanList(String path, List<Boolean> value, List<String> comments)
      Register a boolean list key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerBooleanList

      public AddonConfig registerBooleanList(String path, List<Boolean> value, String... comments)
      Register a boolean list key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerNumberList

      public AddonConfig registerNumberList(String path, List<Number> value, Number min, Number max, List<String> comments)
      Register a number list key value pair to this config. This non-specific type allows for users to input Integers, Doubles, and Longs. *
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerNumberList

      public AddonConfig registerNumberList(String path, List<Number> value, Number min, Number max, String... comments)
      Register a number list key value pair to this config. This non-specific type allows for users to input Integers, Doubles, and Longs.
      Parameters:
      path - Path to register a number list to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerNumberList

      public AddonConfig registerNumberList(String path, List<Number> value, List<String> comments)
      Register a number list key value pair to this config. This non-specific type allows for users to input Integers, Doubles, and Longs. Has no min or max value.
      Parameters:
      path - Path to register a number list to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerNumberList

      public AddonConfig registerNumberList(String path, List<Number> value, String... comments)
      Register a number list key value pair to this config. This non-specific type allows for users to input Integers, Doubles, and Longs. Has no min or max value.
      Parameters:
      path - Path to register a number list to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerIntList

      public AddonConfig registerIntList(String path, List<Integer> value, int min, int max, List<String> comments)
      Register an integer list key value pair to this config.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Integer.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Integer.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerIntList

      public AddonConfig registerIntList(String path, List<Integer> value, int min, int max, String... comments)
      Register an integer list key value pair to this config.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Integer.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Integer.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerIntList

      public AddonConfig registerIntList(String path, List<Integer> value, List<String> comments)
      Register an integer list key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerIntList

      public AddonConfig registerIntList(String path, List<Integer> value, String... comments)
      Register an integer list key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register integer to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerDoubleList

      public AddonConfig registerDoubleList(String path, List<Double> value, double min, double max, List<String> comments)
      Register a double list key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerDoubleList

      public AddonConfig registerDoubleList(String path, List<Double> value, double min, double max, String... comments)
      Register a double list key value pair to this config.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Double.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Double.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerDoubleList

      public AddonConfig registerDoubleList(String path, List<Double> value, List<String> comments)
      Register a double list key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerDoubleList

      public AddonConfig registerDoubleList(String path, List<Double> value, String... comments)
      Register a double list key value pair to this config. Has no min or max value.
      Parameters:
      path - Path to register double to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerLongList

      public AddonConfig registerLongList(String path, List<Long> value, long min, long max, List<String> comments)
      Register a long list key value pair to this config.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Long.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Long.MAX_VALUE to have no maximum.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerLongList

      public AddonConfig registerLongList(String path, List<Long> value, long min, long max, String... comments)
      Register a long list key value pair to this config.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      min - The minimum allowed value for this (inclusive). Use Long.MIN_VALUE to have no minimum.
      max - The maximum allowed value for this (inclusive). Use Long.MAX_VALUE to have no maximum.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerStringList

      public AddonConfig registerStringList(String path, List<String> value, List<String> comments)
      Register a string list key value pair to this config allowing any string value.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerStringList

      public AddonConfig registerStringList(String path, List<String> value, String... comments)
      Register a string list-based key value pair to this config allowing any string value.
      Parameters:
      path - Path to register long to.
      value - The default value for this path.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • registerEnumList

      public <T extends Enum<T>> void registerEnumList(String path, List<T> value, Class<T> enumClass, List<String> comments)
      Register an Enum list-based key value pair to this config. Will use the name of the enum constants as the valid strings.
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      path - Path to register double to.
      value - The default value for this path. Must be an element of an enum class. Users will have to match the case exactly, or an error will be thrown and the default will be used.
      enumClass - Class of the value enum, e.g. FooBarEnum.class.
      comments - Mutable list (ie ArrayList) of user facing comments for this value. Use separate strings instead of \n.

    • registerEnumList

      public <T extends Enum<T>> void registerEnumList(String path, List<T> value, Class<T> enumClass, String... comments)
      Register an Enum list-based key value pair to this config. Will use the name of the enum constants as the valid strings.
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      path - Path to register double to.
      value - The default value for this path. Must be an element of an enum class. Users will have to match the case exactly, or an error will be thrown and the default will be used.
      enumClass - Class of the value enum, e.g. FooBarEnum.class.
      comments - The user facing comments for this value. Use separate strings instead of \n.

    • updatePath

      public AddonConfig updatePath(@NotNull @NotNull String oldPath, @NotNull @NotNull String newPath)
      Use this to update an old path to a new one, e.g., when migrating from the old config system.

    • readAndWriteConfig

      public AddonConfig readAndWriteConfig()
      Call this method after you update the config. Saves the config file with new values to disk.

    • getInt

      public int getInt(String path)
      Gets the integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded, and only the integer part will be returned (it works like a "narrowing primitive conversion" in the Java language specification).
      Parameters:
      path - path expression
      Returns:
      the 32-bit integer value at the requested path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to an int (for example, it is out of range, or it's a boolean value)

    • getLong

      public long getLong(String path)
      Gets the long integer at the given path. If the value at the path has a fractional (floating point) component, it will be discarded, and only the integer part will be returned (it works like a "narrowing primitive conversion" in the Java language specification).
      Parameters:
      path - path expression
      Returns:
      the 64-bit long value at the requested path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a long

    • getDouble

      public double getDouble(String path)
      Parameters:
      path - path expression
      Returns:
      the floating-point value at the requested path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a double

    • getBoolean

      public boolean getBoolean(String path)
      Parameters:
      path - path expression
      Returns:
      the boolean value at the requested path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to boolean

    • getString

      public String getString(String path)
      Parameters:
      path - path expression
      Returns:
      the string value at the requested path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a string

    • getEnum

      public <T extends Enum<T>> T getEnum(Class<T> enumClass, String path)
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      enumClass - an enum class
      path - path expression
      Returns:
      the Enum value at the requested path of the requested enum class
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to an Enum

    • getIntList

      public List<Integer> getIntList(String path)
      Gets a list value with int elements. Throws if the path is unset or null or not a list or contains values not convertible to int.
      Parameters:
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of ints

    • getLongList

      public List<Long> getLongList(String path)
      Gets a list value with long elements. Throws if the path is unset or null or not a list or contains values not convertible to long.
      Parameters:
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of longs

    • getDoubleList

      public List<Double> getDoubleList(String path)
      Gets a list value with double elements. Throws if the path is unset or null or not a list or contains values not convertible to double.
      Parameters:
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of doubles

    • getBooleanList

      public List<Boolean> getBooleanList(String path)
      Gets a list value with boolean elements. Throws if the path is unset or null or not a list or contains values not convertible to boolean.
      Parameters:
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of booleans

    • getStringList

      public List<String> getStringList(String path)
      Gets a list value with string elements. Throws if the path is unset or null or not a list or contains values not convertible to string.
      Parameters:
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of strings

    • getEnumList

      public <T extends Enum<T>> List<T> getEnumList(Class<T> enumClass, String path)
      Gets a list value with Enum elements. Throws if the path is unset or null or not a list or contains values not convertible to Enum.
      Type Parameters:
      T - a generic denoting a specific type of enum
      Parameters:
      enumClass - the enum class
      path - the path to the list value.
      Returns:
      the list at the path
      Throws:
      com.typesafe.config.ConfigException.Missing - if value is absent or null
      com.typesafe.config.ConfigException.WrongType - if value is not convertible to a list of Enum

    • getExists

      public boolean getExists(String key)
      Returns:
      true if the key exists in the current config, false otherwise

    • getConfigFilePath

      public Path getConfigFilePath()

    • render

      public String render()
      Render the current config to a string. Uses ConfigUtils.CONFIG_RENDER_OPTIONS as the render options.

    • render

      public String render(com.typesafe.config.ConfigRenderOptions renderOptions)
      Render the current config to a string.
      Parameters:
      renderOptions - Config render options to modify how it renders.

    • isEmpty

      public boolean isEmpty()
      Returns:
      true if the current config has no values registered to it