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

      withEntriesAlignedWithHeaders(boolean) indents the entries of a table like its header instead.

      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.

    • withEntriesAlignedWithHeaders

      public TomlWriteOptions withEntriesAlignedWithHeaders(boolean aligned)
      Create a copy of these options that indents the entries of a table like its header, or one level beyond it.

      With entries aligned, the entries of a table whose path has n keys are indented by (n - 1) * spaces, the same as its header, rather than by n * spaces. For example, with an indent of 2: 

      
 title = "Example"

 [server]
 host = "localhost"

   [server.tls]
   enabled = true

 [[products]]
 sku = 1

      The default is false, which indents entries one level beyond their header; see withIndent(int).

      Parameters:
      aligned - Whether the entries of a table are indented like its header.
      Returns:
      A new set of options with the given alignment.

    • 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.

    • withSpaceInsideArrays

      public TomlWriteOptions withSpaceInsideArrays(boolean spaced)
      Create a copy of these options that writes an array on one line with a space inside each bracket, [ 1, 2 ], or without, [1, 2].

      The spaces count towards the width of the line, see withMaxLineWidth(int). An empty array is written [] either way, and an array written over several lines is not affected. The default is false.

      Parameters:
      spaced - Whether an array written on one line has a space inside each bracket.
      Returns:
      A new set of options with the given array spacing.

    • withBlankLineBetweenNestedHeaders

      public TomlWriteOptions withBlankLineBetweenNestedHeaders(boolean blankLine)
      Create a copy of these options that does or does not write a blank line between a table header and the header of a table within it that directly follows it.

      A header is written with a blank line above it. Without that blank line between nested headers, a header that directly follows the header of a table containing it, with no entry or unattached comment between them, is written on the next line: 

      
 [servers]
 [servers.alpha]
 ip = "10.0.0.1"

 [servers.beta]
 ip = "10.0.0.2"

      The blank line is left out only where these options lay out the header: in TomlWriteOptions.Keep.LAYOUT, a header the document wrote keeps the blank lines it had. The default is true.

      Parameters:
      blankLine - Whether a blank line separates a header from the header of a table within it that directly follows it.
      Returns:
      A new set of options with the given blank line setting.

    • 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:

    • entriesAlignedWithHeaders

      public boolean entriesAlignedWithHeaders()
      Whether the entries of a table are indented like its header.
      Returns:
      true if the entries of a table are indented like its header, false if one level beyond it.
      See Also:

    • spaceInsideArrays

      public boolean spaceInsideArrays()
      Whether an array written on one line has a space inside each bracket.
      Returns:
      true if an array written on one line has a space inside each bracket.
      See Also:

    • blankLineBetweenNestedHeaders

      public boolean blankLineBetweenNestedHeaders()
      Whether a blank line separates a header from the header of a table within it that directly follows it.
      Returns:
      true if a blank line separates the two headers.
      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