Package org.tomlj

Class TomlWriteOptions

java.lang.Object
org.tomlj.TomlWriteOptions
public final class TomlWriteOptions extends Object
Options controlling how TomlTable.toToml(TomlWriteOptions) and TomlArray.toToml(TomlWriteOptions) write TOML.

keep(Keep) sets how much of the existing structure and format of a parsed document is kept. TomlWriteOptions.Keep.LAYOUT, the default, keeps the layout: a parsed document is written from the text it was parsed from, and only what the editing API changed is written anew. TomlWriteOptions.Keep.NOTATION keeps the notation - the form each key, value and table was written in, the order of lines and sections and the comments - while whitespace, indentation, blank lines and the layout of arrays and inline tables come from these options. TomlWriteOptions.Keep.NOTHING keeps nothing, and writes the whole document in the default style.

Each value falls back to the next where there is nothing to keep: a line written anew is written as TomlWriteOptions.Keep.NOTATION writes it, and a table or array with no notation to keep - one built through the editing API, or read from a document parsed with TomlParseOptions.withoutSource() - is written as TomlWriteOptions.Keep.NOTHING writes it, in the default style.

  • Field Details

  • Method Details

    • defaults

      public static TomlWriteOptions defaults()
      The default options: TomlWriteOptions.Keep.LAYOUT, no indentation, a maximum line width of 80, no line separator of their own, so that lines end with the platform's, System.lineSeparator(), and output written for TomlVersion.LATEST.
      Returns:
      The default options.

    • keep

      public TomlWriteOptions keep(TomlWriteOptions.Keep keep)
      Create a copy of these options that keeps a different amount of the existing document structure and format.
      Parameters:
      keep - How much of the existing document structure and format to keep.
      Returns:
      A new set of options with the given amount to keep.

    • withIndent

      public TomlWriteOptions withIndent(int spaces)
      Create a copy of these options that indents nested tables.

      A header whose path has n keys is indented by (n - 1) * spaces, and the entries of a table whose path has n keys by n * spaces. The entries of the root table are not indented, and the path of a table in an array of tables is the path of the array. For example, with an indent of 2: 

      
 title = "Example"

 [server]
   host = "localhost"

   [server.tls]
     enabled = true

 [[products]]
   sku = 1

      Regardless of the indent, the elements of a multi-line array are indented two spaces beyond the line the array starts on.

      Parameters:
      spaces - The number of spaces to indent per level of table nesting. Must not be negative.
      Returns:
      A new set of options with the given indent.
      Throws:
      IllegalArgumentException - If spaces is negative.

    • withLineSeparator

      public TomlWriteOptions withLineSeparator(String separator)
      Create a copy of these options that ends each line with a different line separator.

      The separator is also used for the line breaks inside a multi-line basic string, written for a string value that contains a newline.

      Parameters:
      separator - The line separator: "\n" or "\r\n", the only newlines that TOML allows.
      Returns:
      A new set of options with the given line separator.
      Throws:
      IllegalArgumentException - If separator is neither "\n" nor "\r\n".

    • withMaxLineWidth

      public TomlWriteOptions withMaxLineWidth(int columns)
      Create a copy of these options with a different maximum line width.

      An array is written on one line if that whole line fits within the maximum width, and otherwise with each element on its own line. The width of a line is counted in code points, and includes its indentation, the key before the array, and the comma after an element of an enclosing multi-line array.

      When writing TOML 1.1.0, an inline table is written the same way, with each entry on its own line. When writing TOML 1.0.0, an inline table is never split, and everything inside one stays on one line; see withVersion(TomlVersion).

      Lines can still be wider than the maximum: a long key or string is never split, nor is an inline table when writing TOML 1.0.0. With a maximum width of 0, every non-empty array and inline table is written over multiple lines, except, when writing TOML 1.0.0, an inline table and everything inside one.

      Parameters:
      columns - The widest a line may be, in code points, for an array to be written on one line. Must not be negative.
      Returns:
      A new set of options with the given maximum line width.
      Throws:
      IllegalArgumentException - If columns is negative.

    • keep

      public TomlWriteOptions.Keep keep()
      How much of the existing document structure and format is kept.
      Returns:
      How much of the existing document structure and format is kept.
      See Also:

    • withVersion

      public TomlWriteOptions withVersion(TomlVersion version)
      Create a copy of these options that writes for a different version of TOML.

      The version decides how an inline table that does not fit within the maximum line width is written. When writing TOML 1.1.0, which allows line breaks inside an inline table, such a table is written over several lines, with each entry on its own line, as an array is. When writing TOML 1.0.0, which allows no line break inside an inline table, an inline table is written on one line regardless of its width. The default is TomlVersion.LATEST.

      An inline table holding a comment can only be written over several lines, since a comment ends at a line break, so writing one for TOML 1.0.0 throws IllegalArgumentException.

      Text copied from a document (a line kept as it was read, or the literal a key or value was written as) is copied only for a version that allows it. Writing for TOML 1.0.0 throws IllegalArgumentException where it would copy a construct of TOML 1.1.0: an escape sequence \e or \xHH, a time without seconds, or a line break or trailing comma inside an inline table, whether the text comes from the document being written, from a value made with TomlValue.parse(String), or from a value copied out of another document. A value replaced or removed through the editing API is not copied, and TomlWriteOptions.Keep.NOTHING copies no text.

      Parameters:
      version - The version of TOML to write for.
      Returns:
      A new set of options with the given version.
      See Also:

    • indent

      public int indent()
      The number of spaces to indent per level of table nesting.
      Returns:
      The number of spaces to indent per level of table nesting.
      See Also:

    • lineSeparator

      public String lineSeparator()
      The line separator written at the end of each line.
      Returns:
      The line separator these options ask for, or System.lineSeparator() if they ask for none.
      See Also:

    • maxLineWidth

      public int maxLineWidth()
      The widest a line may be for an array to be written on one line.
      Returns:
      The maximum line width, in code points.
      See Also:

    • version

      public TomlVersion version()
      The version of TOML the output is written for, TomlVersion.LATEST by default.
      Returns:
      The version of TOML the output is written for.
      See Also:

    • 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