Package org.tomlj

Interface TomlTable

All Known Subinterfaces:
MutableTomlTable, TomlParseResult
public interface TomlTable
An interface for accessing data stored in Tom's Obvious, Minimal Language (TOML).

Values can be addressed in two ways. Methods that take a String interpret it as a dotted key using TOML key syntax, exactly as it would appear in a document: "server.port" names the port entry within the server table, and any key containing characters other than A-Z, a-z, 0-9, _ and - must be quoted, e.g. "\"@key\".value". Methods that take a List<String> interpret each element as a literal key, with no quoting or escaping required.

Consequently, the raw key names returned by keySet() and entrySet() can be used with the List<String> methods (e.g. get(Collections.singletonList(key))), but not directly with the String methods unless the key is a bare key. The keys returned by dottedKeySet() and dottedEntrySet() are already quoted where necessary and can be passed to the String methods. Toml.joinKeyPath(List) converts a key path into a dotted key.

The key sets, the entry sets and toMap() list the keys in the order elements() lists their entries. The dotted and path sets list the paths within a table where the table's key is, after the table's own path when tables are included.

The comments of a document are kept, and are read from the table or array they were written in; see TomlComment.

A table that can be edited is a MutableTomlTable; a parse result is one.

  • Method Details

    • size

      int size()
      Return the number of entries in tis table.
      Returns:
      The number of entries in tis table.

    • isEmpty

      boolean isEmpty()
      true if there are no entries in this table.
      Returns:
      true if there are no entries in this table.

    • contains

      default boolean contains(String dottedKey)
      Check if a key was set in the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.port").
      Returns:
      true if the key was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • contains

      default boolean contains(List<String> path)
      Check if a key was set in the TOML document.
      Parameters:
      path - The key path.
      Returns:
      true if the key was set in the TOML document.

    • keySet

      Set<String> keySet()
      Get the keys of this table.

      The returned set contains only immediate keys to this table, and not dotted keys or key paths. For a complete view of keys available in the TOML document, use dottedKeySet() or keyPathSet().

      The keys are returned as raw names, without quoting. To look up a value by one of these keys, use a List<String> method such as get(List), or quote it with Toml.joinKeyPath(List) before passing it to a String method such as get(String).

      Returns:
      A set containing the keys of this table.

    • dottedKeySet

      default Set<String> dottedKeySet()
      Get all the dotted keys of this table.

      Paths to intermediary and empty tables are not returned. To include these, use dottedKeySet(boolean).

      Returns:
      A set containing all the dotted keys of this table.

    • dottedKeySet

      default Set<String> dottedKeySet(boolean includeTables)
      Get all the dotted keys of this table.
      Parameters:
      includeTables - If true, also include paths to intermediary and empty tables.
      Returns:
      A set containing all the dotted keys of this table.

    • keyPathSet

      default Set<List<String>> keyPathSet()
      Get all the paths in this table.

      Paths to intermediary and empty tables are not returned. To include these, use keyPathSet(boolean).

      Returns:
      A set containing all the key paths of this table.

    • keyPathSet

      Set<List<String>> keyPathSet(boolean includeTables)
      Get all the paths in this table.
      Parameters:
      includeTables - If true, also include paths to intermediary and empty tables.
      Returns:
      A set containing all the key paths of this table.

    • entrySet

      Set<Map.Entry<String,Object>> entrySet()
      Get the entries of this table.

      The returned set contains only immediate entries of this table, and not entries with dotted keys or key paths. For a complete view of all entries available in the TOML document, use dottedEntrySet() or entryPathSet().

      The entry keys are raw names, without quoting. See keySet() for how to use them in lookups.

      Returns:
      A set containing the immediate entries of this table.

    • dottedEntrySet

      default Set<Map.Entry<String,Object>> dottedEntrySet()
      Get all the dotted entries of this table.

      Paths to intermediary and empty tables are not returned. To include these, use dottedEntrySet(boolean).

      Returns:
      A set containing all the entries of this table.

    • dottedEntrySet

      default Set<Map.Entry<String,Object>> dottedEntrySet(boolean includeTables)
      Get all the dotted entries of this table.
      Parameters:
      includeTables - If true, also include paths to intermediary and empty tables.
      Returns:
      A set containing all the entries of this table.

    • entryPathSet

      default Set<Map.Entry<List<String>,Object>> entryPathSet()
      Get all the entries in this table.

      Paths to intermediary and empty tables are not returned. To include these, use entryPathSet(boolean).

      Returns:
      A set containing all the entries of this table.

    • entryPathSet

      Set<Map.Entry<List<String>,Object>> entryPathSet(boolean includeTables)
      Get all the entries in this table.
      Parameters:
      includeTables - If true, also include entries in intermediary and empty tables.
      Returns:
      A set containing all the entries of this table.

    • get

      default @Nullable Object get(String dottedKey)
      Get a value from the TOML document.

      The key is parsed using TOML key syntax, so keys containing characters other than A-Z, a-z, 0-9, _ and - must be quoted (e.g. "\"@key\""). To look up a raw key name without quoting, such as one returned by keySet(), use get(List) instead.

      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • get

      default @Nullable Object get(List<String> path)
      Get a value from the TOML document.

      This is a shortcut for entry(List), returning its value.

      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • isString

      default boolean isString(String dottedKey)
      Check if a value in the TOML document is a string.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.hostname").
      Returns:
      true if the value can be obtained as a string.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isString

      default boolean isString(List<String> path)
      Check if a value in the TOML document is a string.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a string.

    • getString

      default @Nullable String getString(String dottedKey)
      Get a string from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.hostname").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a string, or any element of the path preceding the final key is not a table.

    • getString

      default @Nullable String getString(List<String> path)
      Get a string from the TOML document.
      Parameters:
      path - A dotted key (e.g. "server.address.hostname").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a string, or any element of the path preceding the final key is not a table.

    • getString

      default String getString(String dottedKey, Supplier<String> defaultValue)
      Get a string from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.hostname").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a string, or any element of the path preceding the final key is not a table.

    • getString

      default String getString(List<String> path, Supplier<String> defaultValue)
      Get a string from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a string, or any element of the path preceding the final key is not a table.

    • isLong

      default boolean isLong(String dottedKey)
      Check if a value in the TOML document is a long.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a long.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isLong

      default boolean isLong(List<String> path)
      Check if a value in the TOML document is a long.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a long.

    • getLong

      default @Nullable Long getLong(String dottedKey)
      Get a long from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a long, or any element of the path preceding the final key is not a table.

    • getLong

      default @Nullable Long getLong(List<String> path)
      Get a long from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a long, or any element of the path preceding the final key is not a table.

    • getLong

      default long getLong(String dottedKey, LongSupplier defaultValue)
      Get a long from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a long, or any element of the path preceding the final key is not a table.

    • getLong

      default long getLong(List<String> path, LongSupplier defaultValue)
      Get a long from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a long, or any element of the path preceding the final key is not a table.

    • isDouble

      default boolean isDouble(String dottedKey)
      Check if a value in the TOML document is a double.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a double.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isDouble

      default boolean isDouble(List<String> path)
      Check if a value in the TOML document is a double.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a double.

    • getDouble

      default @Nullable Double getDouble(String dottedKey)
      Get a double from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a double, or any element of the path preceding the final key is not a table.

    • getDouble

      default @Nullable Double getDouble(List<String> path)
      Get a double from the TOML document.
      Parameters:
      path - A dotted key.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a double, or any element of the path preceding the final key is not a table.

    • getDouble

      default double getDouble(String dottedKey, DoubleSupplier defaultValue)
      Get a double from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a double, or any element of the path preceding the final key is not a table.

    • getDouble

      default double getDouble(List<String> path, DoubleSupplier defaultValue)
      Get a double from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a double, or any element of the path preceding the final key is not a table.

    • isBoolean

      default boolean isBoolean(String dottedKey)
      Check if a value in the TOML document is a boolean.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a boolean.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isBoolean

      default boolean isBoolean(List<String> path)
      Check if a value in the TOML document is a boolean.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a boolean.

    • getBoolean

      default @Nullable Boolean getBoolean(String dottedKey)
      Get a boolean from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a boolean, or any element of the path preceding the final key is not a table.

    • getBoolean

      default @Nullable Boolean getBoolean(List<String> path)
      Get a boolean from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a boolean, or any element of the path preceding the final key is not a table.

    • getBoolean

      default boolean getBoolean(String dottedKey, BooleanSupplier defaultValue)
      Get a boolean from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a boolean, or any element of the path preceding the final key is not a table.

    • getBoolean

      default boolean getBoolean(List<String> path, BooleanSupplier defaultValue)
      Get a boolean from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a boolean, or any element of the path preceding the final key is not a table.

    • isOffsetDateTime

      default boolean isOffsetDateTime(String dottedKey)
      Check if a value in the TOML document is an OffsetDateTime.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as an OffsetDateTime.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isOffsetDateTime

      default boolean isOffsetDateTime(List<String> path)
      Check if a value in the TOML document is an OffsetDateTime.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as an OffsetDateTime.

    • getOffsetDateTime

      default @Nullable OffsetDateTime getOffsetDateTime(String dottedKey)
      Get an offset date time from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not an OffsetDateTime, or any element of the path preceding the final key is not a table.

    • getOffsetDateTime

      default @Nullable OffsetDateTime getOffsetDateTime(List<String> path)
      Get an offset date time from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not an OffsetDateTime, or any element of the path preceding the final key is not a table.

    • getOffsetDateTime

      default OffsetDateTime getOffsetDateTime(String dottedKey, Supplier<OffsetDateTime> defaultValue)
      Get an offset date time from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not an OffsetDateTime, or any element of the path preceding the final key is not a table.

    • getOffsetDateTime

      default OffsetDateTime getOffsetDateTime(List<String> path, Supplier<OffsetDateTime> defaultValue)
      Get an offset date time from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not an OffsetDateTime, or any element of the path preceding the final key is not a table.

    • isLocalDateTime

      default boolean isLocalDateTime(String dottedKey)
      Check if a value in the TOML document is a LocalDateTime.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a LocalDateTime.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isLocalDateTime

      default boolean isLocalDateTime(List<String> path)
      Check if a value in the TOML document is a LocalDateTime.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a LocalDateTime.

    • getLocalDateTime

      default @Nullable LocalDateTime getLocalDateTime(String dottedKey)
      Get a local date time from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalDateTime, or any element of the path preceding the final key is not a table.

    • getLocalDateTime

      default @Nullable LocalDateTime getLocalDateTime(List<String> path)
      Get a local date time from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalDateTime, or any element of the path preceding the final key is not a table.

    • getLocalDateTime

      default LocalDateTime getLocalDateTime(String dottedKey, Supplier<LocalDateTime> defaultValue)
      Get a local date time from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalDateTime, or any element of the path preceding the final key is not a table.

    • getLocalDateTime

      default LocalDateTime getLocalDateTime(List<String> path, Supplier<LocalDateTime> defaultValue)
      Get a local date time from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalDateTime, or any element of the path preceding the final key is not a table.

    • isLocalDate

      default boolean isLocalDate(String dottedKey)
      Check if a value in the TOML document is a LocalDate.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a LocalDate.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isLocalDate

      default boolean isLocalDate(List<String> path)
      Check if a value in the TOML document is a LocalDate.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a LocalDate.

    • getLocalDate

      default @Nullable LocalDate getLocalDate(String dottedKey)
      Get a local date from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalDate, or any element of the path preceding the final key is not a table.

    • getLocalDate

      default @Nullable LocalDate getLocalDate(List<String> path)
      Get a local date from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalDate, or any element of the path preceding the final key is not a table.

    • getLocalDate

      default LocalDate getLocalDate(String dottedKey, Supplier<LocalDate> defaultValue)
      Get a local date from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalDate, or any element of the path preceding the final key is not a table.

    • getLocalDate

      default LocalDate getLocalDate(List<String> path, Supplier<LocalDate> defaultValue)
      Get a local date from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalDate, or any element of the path preceding the final key is not a table.

    • isLocalTime

      default boolean isLocalTime(String dottedKey)
      Check if a value in the TOML document is a LocalTime.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      true if the value can be obtained as a LocalTime.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isLocalTime

      default boolean isLocalTime(List<String> path)
      Check if a value in the TOML document is a LocalTime.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a LocalTime.

    • getLocalTime

      default @Nullable LocalTime getLocalTime(String dottedKey)
      Get a local time from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalTime, or any element of the path preceding the final key is not a table.

    • getLocalTime

      default @Nullable LocalTime getLocalTime(List<String> path)
      Get a local time from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalTime, or any element of the path preceding the final key is not a table.

    • getLocalTime

      default LocalTime getLocalTime(String dottedKey, Supplier<LocalTime> defaultValue)
      Get a local time from the TOML document, or return a default.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a LocalTime, or any element of the path preceding the final key is not a table.

    • getLocalTime

      default LocalTime getLocalTime(List<String> path, Supplier<LocalTime> defaultValue)
      Get a local time from the TOML document, or return a default.
      Parameters:
      path - The key path.
      defaultValue - A supplier for the default value.
      Returns:
      The value, or the default.
      Throws:
      TomlInvalidTypeException - If the value is present but not a LocalTime, or any element of the path preceding the final key is not a table.

    • isArray

      default boolean isArray(String dottedKey)
      Check if a value in the TOML document is an array.
      Parameters:
      dottedKey - A dotted key (e.g. "server.addresses").
      Returns:
      true if the value can be obtained as an array.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isArray

      default boolean isArray(List<String> path)
      Check if a value in the TOML document is an array.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as an array.

    • getArray

      default @Nullable TomlArray getArray(String dottedKey)
      Get an array from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.addresses").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not an array, or any element of the path preceding the final key is not a table.

    • getArray

      default @Nullable TomlArray getArray(List<String> path)
      Get an array from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not an array, or any element of the path preceding the final key is not a table.

    • getArrayOrEmpty

      default TomlArray getArrayOrEmpty(String dottedKey)
      Get an array from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.addresses").
      Returns:
      The value, or an empty array if no array was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not an array, or any element of the path preceding the final key is not a table.

    • getArrayOrEmpty

      default TomlArray getArrayOrEmpty(List<String> path)
      Get an array from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or an empty array if no array was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not an array, or any element of the path preceding the final key is not a table.

    • isTable

      default boolean isTable(String dottedKey)
      Check if a value in the TOML document is a table.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address").
      Returns:
      true if the value can be obtained as a table.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.

    • isTable

      default boolean isTable(List<String> path)
      Check if a value in the TOML document is a table.
      Parameters:
      path - The key path.
      Returns:
      true if the value can be obtained as a table.

    • getTable

      default @Nullable TomlTable getTable(String dottedKey)
      Get a table from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address").
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a table, or any element of the path preceding the final key is not a table.

    • getTable

      default @Nullable TomlTable getTable(List<String> path)
      Get a table from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or null if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a table, or any element of the path preceding the final key is not a table.

    • getTableOrEmpty

      default TomlTable getTableOrEmpty(String dottedKey)
      Get a table from the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The value, or an empty table if no value was set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If the value is present but not a table, or any element of the path preceding the final key is not a table.

    • getTableOrEmpty

      default TomlTable getTableOrEmpty(List<String> path)
      Get a table from the TOML document.
      Parameters:
      path - The key path.
      Returns:
      The value, or an empty table if no value was set in the TOML document.
      Throws:
      TomlInvalidTypeException - If the value is present but not a table, or any element of the path preceding the final key is not a table.

    • inputPositionOf

      default @Nullable TomlPosition inputPositionOf(String dottedKey)
      Get the position where a key is defined in the TOML document.
      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The input position, or null if the key was not set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • inputPositionOf

      @Nullable TomlPosition inputPositionOf(List<String> path)
      Get the position where a key is defined in the TOML document.

      For a non-empty path, this is the position of entry(List).

      Parameters:
      path - The key path.
      Returns:
      The input position, or null if the key was not set in the TOML document.
      Throws:
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • comments

      default List<TomlComment> comments(String dottedKey)
      Get the comments attached to a key.

      Returns the comments in document order: the run directly above the key, if any, then the comment on its line, if any, so at most two, each with its TomlComment.placement().

      Returns an empty list if the key was not set in the document or has no comments; use contains(String) to tell those apart.

      The comments on a [[x]] header are attached to the table it opens, so comments("x") is empty and they are read with getArray("x").comments(0) and so on.

      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The attached comments, in document order. Unmodifiable.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • comments

      default List<TomlComment> comments(List<String> path)
      Get the comments attached to a key.

      Returns the comments in document order: the run directly above the key, if any, then the comment on its line, if any, so at most two, each with its TomlComment.placement().

      Returns an empty list if the key was not set in the document or has no comments; use contains(List) to tell those apart.

      The comments on a [[x]] header are attached to the table it opens, so comments("x") is empty and they are read with getArray("x").comments(0) and so on.

      This is a shortcut for entry(List), returning its comments.

      Parameters:
      path - The key path.
      Returns:
      The attached comments, in document order. Unmodifiable.
      Throws:
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • comment

      default @Nullable TomlComment comment(String dottedKey, TomlComment.Placement placement)
      Get the comment attached to a key at a placement.

      Returns null if the key was not set in the document or has no comment at that placement; use contains(String) to tell those apart.

      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      placement - TomlComment.Placement.ABOVE for the run directly above the key, or TomlComment.Placement.AFTER for the comment on its line.
      Returns:
      The comment at that placement, or null if there is none.
      Throws:
      NullPointerException - If dottedKey or placement is null.
      IllegalArgumentException - If the key cannot be parsed, or placement is TomlComment.Placement.UNATTACHED.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • comment

      default @Nullable TomlComment comment(List<String> path, TomlComment.Placement placement)
      Get the comment attached to a key at a placement.

      Returns null if the key was not set in the document or has no comment at that placement; use contains(List) to tell those apart.

      This is a shortcut for entry(List), returning TomlEntry.comment(TomlComment.Placement).

      Parameters:
      path - The key path.
      placement - TomlComment.Placement.ABOVE for the run directly above the key, or TomlComment.Placement.AFTER for the comment on its line.
      Returns:
      The comment at that placement, or null if there is none.
      Throws:
      NullPointerException - If placement is null.
      IllegalArgumentException - If placement is TomlComment.Placement.UNATTACHED.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • entry

      default @Nullable TomlKeyValue entry(String dottedKey)
      Get the entry for a key.

      The key is parsed using TOML key syntax, so keys containing characters other than A-Z, a-z, 0-9, _ and - must be quoted (e.g. "\"@key\""). To look up a raw key name without quoting, such as one returned by keySet(), use entry(List) instead.

      Parameters:
      dottedKey - A dotted key (e.g. "server.address.port").
      Returns:
      The entry, or null if the key was not set in the TOML document.
      Throws:
      IllegalArgumentException - If the key cannot be parsed.
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • entry

      @Nullable TomlKeyValue entry(List<String> path)
      Get the entry for a key.

      The entry is the TomlKeyValue that elements() holds for the key, in the table the path leads to. get(List), inputPositionOf(List) and comments(List) are shortcuts that read the value, position and comments of this entry. An empty path names this table itself, which is not an entry, so it returns null.

      Parameters:
      path - The key path.
      Returns:
      The entry, or null if the key was not set in the TOML document.
      Throws:
      TomlInvalidTypeException - If any element of the path preceding the final key is not a table.

    • elements

      List<TomlElement> elements()
      Get the elements written in this table, in document order.

      Each element is a TomlKeyValue, an entry of this table, or an unattached TomlComment. The entries are those entrySet() holds. A comment is unattached when it is neither directly above an entry nor on its line: a run separated by a blank line from the entry below it, a run at the end of a section or of the document, or, in an inline table, a comment on a line with no entry.

      Returns:
      The elements, in document order. Unmodifiable.

    • toMap

      Map<String,Object> toMap()
      Get the entries of this table as a Map.

      Note that this does not do a deep conversion. If this table contains tables or arrays, they will be of type TomlTable or TomlArray respectively.

      Returns:
      The entries of this table as a Map.

    • toJson

      default String toJson(JsonOptions... options)
      Return a representation of this table using JSON.
      Parameters:
      options - Options for the JSON encoder.
      Returns:
      A JSON representation of this table.

    • toJson

      default String toJson(EnumSet<JsonOptions> options)
      Return a representation of this table using JSON.
      Parameters:
      options - Options for the JSON encoder.
      Returns:
      A JSON representation of this table.

    • toJson

      default void toJson(Appendable appendable, JsonOptions... options) throws IOException
      Append a JSON representation of this table to the appendable output.
      Parameters:
      appendable - The appendable output.
      options - Options for the JSON encoder.
      Throws:
      IOException - If an IO error occurs.

    • toJson

      default void toJson(Appendable appendable, EnumSet<JsonOptions> options) throws IOException
      Append a JSON representation of this table to the appendable output.
      Parameters:
      appendable - The appendable output.
      options - Options for the JSON encoder.
      Throws:
      IOException - If an IO error occurs.

    • toToml

      default String toToml()
      Return a representation of this table using TOML, written with the default options.

      A TomlParseResult is written keeping its layout: the text it was parsed from is written back, with only what the editing API changed written anew; any other table, including a table of a parse result rather than the result itself, is written in the default style, keeping the literal form each of its values was parsed with.

      Returns:
      A TOML representation of this table.
      See Also:

    • toToml

      default String toToml(TomlWriteOptions options)
      Return a representation of this table using TOML.

      A TomlParseResult keeps as much of its existing structure and format as options ask for; see TomlWriteOptions.Keep. Any other table is written in the default style, keeping the literal form of each value unless the options ask for TomlWriteOptions.Keep.NOTHING. See toToml().

      Parameters:
      options - The options to write with.
      Returns:
      A TOML representation of this table.
      Throws:
      IllegalArgumentException - If the version the options write for cannot write this table: TOML 1.0.0 and an inline table holding a comment, or text copied from a document that only TOML 1.1.0 allows; see TomlWriteOptions.withVersion(TomlVersion).
      See Also:

    • toToml

      default void toToml(Appendable appendable) throws IOException
      Append a TOML representation of this table to the appendable output, written with the default options.

      Written as toToml() writes it.

      Parameters:
      appendable - The appendable output.
      Throws:
      IOException - If an IO error occurs.
      See Also:

    • toToml

      default void toToml(Appendable appendable, TomlWriteOptions options) throws IOException
      Append a TOML representation of this table to the appendable output.

      Written as toToml(TomlWriteOptions) writes it.

      Parameters:
      appendable - The appendable output.
      options - The options to write with.
      Throws:
      IOException - If an IO error occurs.
      IllegalArgumentException - If the version the options write for cannot write this table: TOML 1.0.0 and an inline table holding a comment, or text copied from a document that only TOML 1.1.0 allows; see TomlWriteOptions.withVersion(TomlVersion).
      See Also:

    • as

      default <T> T as(Class<T> type)
      Bind this table to a Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of this table.
      Throws:
      TomlBindException - If any value of this table cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • as

      default <T> T as(Class<T> type, TomlBindOptions options)
      Bind this table to a Java type. 
      
 record Server(String host, int port) {}
 
 record Config(String name, List<Server> servers) {}

 Config config = Toml.parse(path).as(Config.class, TomlBindOptions.defaults());

      The value of each key or element is bound to the type declared for it, as follows:

      • A string to String, an enum constant, or char for a string of one character. An enum constant is matched by its name, or else by its name ignoring case and with - and space read as _; a constant with a TomlName annotation is matched by the annotation's value only.
      • An integer to long, int, short, byte, BigInteger, or to a floating point type if it can be represented exactly. A value out of range for the type is an error.
      • A float to double, float or BigDecimal.
      • A boolean to boolean.
      • An offset date-time to OffsetDateTime, ZonedDateTime or Instant, and a local date-time, date or time to LocalDateTime, LocalDate or LocalTime.
      • An array to a List, Set, Collection, Iterable, a concrete collection class, or a Java array.
      • A table to a record, a class, or a Map with String keys.
      • Any value to Object, unchanged, and a table or array to TomlTable or TomlArray, or to a copy of it for MutableTomlTable or MutableTomlArray.
      • Any value to Optional<T>, by binding it to T.
      • Any value to a type that has a converter in the options, by that converter.

      A table is bound to a record through its canonical constructor, with a key for each component. It is bound to a class by creating an instance with its constructor without parameters, then setting a field for each key. Every field of the class and its superclasses is bound except static, transient and final fields. The key of a field or component is its name, converted by the options' key naming, or the value of its TomlName annotation.

      A key the table does not have is bound as follows:

      • An Optional is empty.
      • A field of a class keeps the value it was given when the instance was created.
      • A record component, or a field of a class that is null once the instance is created, is null if it is nullable, and an error if it is never null. A primitive is never null; otherwise, an annotation named NonNull, NotNull or Nonnull marks a field or component as never null, and one named Nullable marks it as nullable, from any package, as long as the annotation is kept at runtime. Without either, it is never null if its class, an enclosing class, its package or its module is annotated as JSpecify's NullMarked, and nullable otherwise.
      A key in the table that names no field or component is an error, unless the options ignore unknown keys.

      Binding does not stop at the first error. Every value is bound, and the errors, each with the path and position of the value, are thrown together in a TomlBindException. An exception thrown by a record's constructor or a converter is reported as an error at the position of the value being bound.

      TomlJ binds to private fields and classes by reflection. In a named module, the package holding them must be opened to the module org.tomlj.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of this table.
      Throws:
      TomlBindException - If any value of this table cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.

    • as

      default <T> T as(GenericType<T> type)
      Bind this table to a generic Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of this table.
      Throws:
      TomlBindException - If any value of this table cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • as

      default <T> T as(GenericType<T> type, TomlBindOptions options)
      Bind this table to a generic Java type.

      This binds as as(Class, TomlBindOptions) does, to a type such as List<Server> that a Class cannot name.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of this table.
      Throws:
      TomlBindException - If any value of this table cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.