Package org.tomlj

Class TomlBindOptions

java.lang.Object
org.tomlj.TomlBindOptions
public final class TomlBindOptions extends Object
Options controlling how a table or array is bound to a Java type, and how a Java object is written as a table or array.

Options are immutable, and hold what they learn about each Java type bound or written with them, so reusing one set of options for many bindings avoids examining the same classes again.

See Also:

  • Method Details

    • defaults

      public static TomlBindOptions defaults()
      The default bind options: keys are the names of fields and record components, unchanged, a key with no field or component is an error, and no converters are registered.
      Returns:
      The default bind options.

    • withKeyNaming

      public TomlBindOptions withKeyNaming(TomlBindOptions.KeyNaming keyNaming)
      Create a copy of these options that turns names into keys with a different key naming.
      Parameters:
      keyNaming - The key naming.
      Returns:
      A new set of options with the given key naming.

    • withUnknownKeysIgnored

      public TomlBindOptions withUnknownKeysIgnored(boolean ignored)
      Create a copy of these options that ignores keys with no field or record component, or that reports them.

      By default, a key in a table that is bound to a record or class, and that names none of its fields or components, is an error, which catches a misspelled key in a document.

      Parameters:
      ignored - true to ignore keys with no field or record component, false to report each as an error.
      Returns:
      A new set of options.

    • withConverter

      public <T> TomlBindOptions withConverter(Class<T> type, Function<Object,? extends T> converter)
      Create a copy of these options that binds values to a type with a converter.

      The converter is given the value from the document: a String, Long, Double, Boolean, OffsetDateTime, LocalDateTime, LocalDate, LocalTime, TomlArray or TomlTable. It must return a value of the type, not null. If it throws a RuntimeException, the value is reported as a TomlBindError with the exception's message.

      A converter is used for fields, components and elements declared with exactly this type, and takes the place of the binding TomlJ would use otherwise. A converter registered earlier for the same type is replaced, and values of the type cannot be written as TOML; see withConverter(Class, Function, Function) to write them. 

      
 TomlBindOptions options =
     TomlBindOptions.defaults().withConverter(Duration.class, value -> Duration.parse((String) value));
      Type Parameters:
      T - The type the converter produces.
      Parameters:
      type - The type the converter produces.
      converter - The converter.
      Returns:
      A new set of options with the given converter.

    • withConverter

      public <T> TomlBindOptions withConverter(Class<T> type, Function<Object,? extends T> read, Function<? super T,?> write)
      Create a copy of these options that binds values to a type with a converter, and writes values of the type with another.

      read binds values as the converter given to withConverter(Class, Function) does. write is given a value of the type, never null, when an object is written as TOML, and returns the TOML value to write for it: any value MutableTomlTable.set(String, Object) accepts, such as a String, a number, a Map, a List, or a TomlValue to choose how it is written. If it throws a RuntimeException or returns null, writing throws IllegalArgumentException.

      When a document is updated from an object, a value in the document is left as it is if read converts it to a value equal to the one being written, so write does not have to return the same text as the document holds. 

      
 TomlBindOptions options = TomlBindOptions
     .defaults()
     .withConverter(Duration.class, value -> Duration.parse((String) value), Duration::toString);
      Type Parameters:
      T - The type the converters produce and write.
      Parameters:
      type - The type the converters produce and write.
      read - The converter from TOML values.
      write - The converter to TOML values.
      Returns:
      A new set of options with the given converters.

    • keyNaming

      public TomlBindOptions.KeyNaming keyNaming()
      How names of fields and record components are turned into keys.
      Returns:
      The key naming.

    • ignoresUnknownKeys

      public boolean ignoresUnknownKeys()
      Whether a key with no field or record component is ignored.
      Returns:
      true if such keys are ignored.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object