Package org.tomlj

Class Toml

java.lang.Object
org.tomlj.Toml
public final class Toml extends Object
Methods for parsing data stored in Tom's Obvious, Minimal Language (TOML), for binding it to Java objects, and for writing Java objects as TOML.

By default, documents may nest tables and arrays at most 128 levels deep, not counting the root table, and a value, table or array nested deeper than that is reported as a parse error. The limit bounds the stack depth needed to parse and serialize a document; change it with TomlParseOptions.withMaxNestingDepth(int).

  • Method Details

    • parse

      public static TomlParseResult parse(String input)
      Parse a TOML string.
      Parameters:
      input - The input to parse.
      Returns:
      The parse result.

    • parse

      public static TomlParseResult parse(String input, TomlVersion version)
      Parse a TOML string.
      Parameters:
      input - The input to parse.
      version - The version level to parse at.
      Returns:
      The parse result.

    • parse

      public static TomlParseResult parse(String input, TomlParseOptions options)
      Parse a TOML string.
      Parameters:
      input - The input to parse.
      options - The options to parse with.
      Returns:
      The parse result.

    • parse

      public static TomlParseResult parse(Path file) throws IOException
      Parse a TOML file.
      Parameters:
      file - The input file to parse.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(Path file, TomlVersion version) throws IOException
      Parse a TOML file.
      Parameters:
      file - The input file to parse.
      version - The version level to parse at.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(Path file, TomlParseOptions options) throws IOException
      Parse a TOML file.
      Parameters:
      file - The input file to parse.
      options - The options to parse with.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(InputStream is) throws IOException
      Parse a TOML input stream.
      Parameters:
      is - The UTF-8 encoded input stream to read the TOML document from.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(InputStream is, TomlVersion version) throws IOException
      Parse a TOML input stream.
      Parameters:
      is - The UTF-8 encoded input stream to read the TOML document from.
      version - The version level to parse at.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(InputStream is, TomlParseOptions options) throws IOException
      Parse a TOML input stream.
      Parameters:
      is - The UTF-8 encoded input stream to read the TOML document from.
      options - The options to parse with.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(Reader reader) throws IOException
      Parse a TOML reader.
      Parameters:
      reader - The reader to obtain the TOML document from.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(Reader reader, TomlVersion version) throws IOException
      Parse a TOML input stream.
      Parameters:
      reader - The reader to obtain the TOML document from.
      version - The version level to parse at.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(Reader reader, TomlParseOptions options) throws IOException
      Parse a TOML input stream.
      Parameters:
      reader - The reader to obtain the TOML document from.
      options - The options to parse with.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(ReadableByteChannel channel) throws IOException
      Parse a TOML reader.
      Parameters:
      channel - The channel to read the TOML document from.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(ReadableByteChannel channel, TomlVersion version) throws IOException
      Parse a TOML input stream.
      Parameters:
      channel - The UTF-8 encoded channel to read the TOML document from.
      version - The version level to parse at.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parse

      public static TomlParseResult parse(ReadableByteChannel channel, TomlParseOptions options) throws IOException
      Parse a TOML input stream.
      Parameters:
      channel - The UTF-8 encoded channel to read the TOML document from.
      options - The options to parse with.
      Returns:
      The parse result.
      Throws:
      IOException - If an IO error occurs.

    • parseAs

      public static <T> T parseAs(String input, Class<T> type)
      Parse a TOML string and bind it to a Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      input - The input to parse.
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • parseAs

      public static <T> T parseAs(String input, Class<T> type, TomlBindOptions options)
      Parse a TOML string and bind it to a Java type. 
      
 record Server(String host, int port) {}

 record Config(String name, List<Server> servers) {}

 Config config = Toml.parseAs(input, Config.class, TomlBindOptions.defaults());

      The document is parsed at the latest version of TOML, with the default nesting limit and without keeping its source text (see TomlParseOptions.withoutSource()). A table or array bound to TomlTable, TomlArray or Object therefore keeps no source text either, and toToml() writes it in the default style. If the document has any parse error, nothing is bound and a TomlParseException holding every parse error is thrown. Otherwise the document is bound as TomlTable.as(Class, TomlBindOptions) binds a table.

      To parse with other options, or to bind a document more than once or in parts, parse it with parse(String, TomlParseOptions) and call as on the result or on any table or array of it.

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

    • parseAs

      public static <T> T parseAs(String input, GenericType<T> type)
      Parse a TOML string and bind it to a generic Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      input - The input to parse.
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • parseAs

      public static <T> T parseAs(String input, GenericType<T> type, TomlBindOptions options)
      Parse a TOML string and bind it to a generic Java type.

      This parses and binds as parseAs(String, Class, TomlBindOptions) does, to a type such as Map<String, Server> that a Class cannot name.

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

    • parseAs

      public static <T> T parseAs(Path file, Class<T> type) throws IOException
      Parse a TOML file and bind it to a Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      file - The input file to parse.
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      IOException - If an IO error occurs.
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • parseAs

      public static <T> T parseAs(Path file, Class<T> type, TomlBindOptions options) throws IOException
      Parse a TOML file and bind it to a Java type.

      This parses and binds as parseAs(String, Class, TomlBindOptions) does.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      file - The input file to parse.
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      IOException - If an IO error occurs.
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.

    • parseAs

      public static <T> T parseAs(Path file, GenericType<T> type) throws IOException
      Parse a TOML file and bind it to a generic Java type, with the default options.
      Type Parameters:
      T - The type to bind to.
      Parameters:
      file - The input file to parse.
      type - The type to bind to.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      IOException - If an IO error occurs.
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.
      See Also:

    • parseAs

      public static <T> T parseAs(Path file, GenericType<T> type, TomlBindOptions options) throws IOException
      Parse a TOML file and bind it to a generic Java type.

      This parses and binds as parseAs(String, Class, TomlBindOptions) does, to a type such as Map<String, Server> that a Class cannot name.

      Type Parameters:
      T - The type to bind to.
      Parameters:
      file - The input file to parse.
      type - The type to bind to.
      options - The options to bind with.
      Returns:
      A new instance of the type, holding the values of the document.
      Throws:
      IOException - If an IO error occurs.
      TomlParseException - If the document has any parse error.
      TomlBindException - If any value of the document cannot be bound.
      IllegalArgumentException - If the type, or a type it holds, cannot be bound to.

    • toToml

      public static String toToml(Object value)
      Write a record, class or map as a TOML document, with the default options.
      Parameters:
      value - The record, class or map.
      Returns:
      The TOML document.
      Throws:
      IllegalArgumentException - If value is not written as a table, a type it holds cannot be written, or a value it holds cannot be written as TOML.
      See Also:

    • toToml

      public static String toToml(Object value, TomlBindOptions options)
      Write a record, class or map as a TOML document, with the default write options.
      Parameters:
      value - The record, class or map.
      options - The options to write the object with.
      Returns:
      The TOML document.
      Throws:
      IllegalArgumentException - If value is not written as a table, a type it holds cannot be written, or a value it holds cannot be written as TOML.
      See Also:

    • toToml

      public static String toToml(Object value, TomlBindOptions options, TomlWriteOptions writeOptions)
      Write a record, class or map as a TOML document. 
      
 record Server(String host, int port) {}

 record Config(String name, List<Server> servers) {}

 String toml = Toml.toToml(config, TomlBindOptions.defaults(), TomlWriteOptions.defaults());

      This writes the same document as MutableTomlTable.from(value, options).toToml(writeOptions): see MutableTomlTable.from(Object, TomlBindOptions) for how each value is written.

      Parameters:
      value - The record, class or map.
      options - The options to write the object with.
      writeOptions - The options to write the document with.
      Returns:
      The TOML document.
      Throws:
      IllegalArgumentException - If value is not written as a table, a type it holds cannot be written, or a value it holds cannot be written as TOML, or the document cannot be written at the version of the write options.

    • parseDottedKey

      public static List<String> parseDottedKey(String dottedKey)
      Parse a dotted key into individual parts.
      Parameters:
      dottedKey - A dotted key (e.g. server.address.port).
      Returns:
      A list of individual keys in the path.
      Throws:
      IllegalArgumentException - If the dotted key cannot be parsed.

    • joinKeyPath

      public static String joinKeyPath(List<String> path)
      Join a list of keys into a single dotted key string.
      Parameters:
      path - The list of keys that form the path.
      Returns:
      The path string.

    • canonicalDottedKey

      public static String canonicalDottedKey(String dottedKey)
      Get the canonical form of the dotted key.
      Parameters:
      dottedKey - A dotted key (e.g. server.address.port).
      Returns:
      The canonical form of the dotted key.
      Throws:
      IllegalArgumentException - If the dotted key cannot be parsed.

    • tomlEscape

      public static StringBuilder tomlEscape(String text)
      Escape a text string using the TOML escape sequences.
      Parameters:
      text - The text string to escape.
      Returns:
      A StringBuilder holding the results of escaping the text.

    • equals

      public static boolean equals(TomlArray array1, TomlArray array2)
      Performs a deep comparison between two arrays to determine if they are equivalent.
      Parameters:
      array1 - First array
      array2 - Second array
      Returns:
      Returns true if the arrays are equivalent, else false.

    • equals

      public static boolean equals(TomlTable table1, TomlTable table2)
      Performs a deep comparison between two tables to determine if they are equivalent.
      Parameters:
      table1 - First table
      table2 - Second table
      Returns:
      Returns true if the tables are equivalent, else false.