Skip to content

Configuration Options

Jump to bottom
GroundbreakingMC edited this page Oct 3, 2025 · 1 revision

Configuration Options

TOMLy provides two sets of options: PreserveOptions for parsing and WriterOptions for serialization.

PreserveOptions (Parsing)

Control what elements are preserved during parsing.

Default Options

By default, nothing is preserved for maximum performance:

PreserveOptions options = PreserveOptions.defaultOptions();
// Equivalent to:
// preserveBlankLines = false
// preserveHeaderComments = false
// preserveInlineComments = false

Builder API

Use the builder for custom configuration:

PreserveOptions options = PreserveOptions.builder()
    .preserveBlankLines(true)
    .preserveHeaderComments(true)
    .preserveInlineComments(true)
    .build();

Blank Lines Preservation

Empty lines between sections:

name = "MyApp"

[server]
host = "localhost"
PreserveOptions options = PreserveOptions.builder()
    .preserveBlankLines(true)
    .build();

TomlDocument doc = Tomly.parse(toml, false, options);
Node nameNode = doc.get("name");
List<String> comments = nameNode.headerComments(); // May contain empty strings for blank lines

Use cases:

  • Maintaining visual structure in round-trip serialization
  • Preserving document formatting conventions

Performance impact: Minimal

Header Comments Preservation

Comments appearing before key-value pairs:

# This is a header comment
# It can span multiple lines
name = "MyApp"
PreserveOptions options = PreserveOptions.builder()
    .preserveHeaderComments(true)
    .build();

TomlDocument doc = Tomly.parse(toml, false, options);
Node nameNode = doc.get("name");
List<String> headers = nameNode.headerComments();
// ["# This is a header comment", "# It can span multiple lines"]

Use cases:

  • Generating documented configuration files
  • Preserving documentation during config updates
  • Configuration management tools

Performance impact: Small (requires comment tracking)

Inline Comments Preservation

Comments at the end of value lines:

name = "MyApp"  # The application name
port = 8080     # Default port
PreserveOptions options = PreserveOptions.builder()
    .preserveInlineComments(true)
    .build();

TomlDocument doc = Tomly.parse(toml, false, options);
Node nameNode = doc.get("name");
String inline = nameNode.inlineComment(); // "The application name"

Use cases:

  • Preserving field-level documentation
  • Maintaining hints for configuration values

Performance impact: Small (requires comment parsing)

Combining Options

Enable all preservation features:

PreserveOptions fullPreservation = PreserveOptions.builder()
    .preserveBlankLines(true)
    .preserveHeaderComments(true)
    .preserveInlineComments(true)
    .build();

Preserve only comments:

PreserveOptions commentsOnly = PreserveOptions.builder()
    .preserveHeaderComments(true)
    .preserveInlineComments(true)
    .build();

WriterOptions (Serialization)

Control formatting when writing TOML.

Default Options

WriterOptions options = WriterOptions.defaultOptions();
// writeBlankLines = false
// writeHeaderComments = false
// writeInlineComments = false
// maxLineLength = 100

Builder API

WriterOptions options = WriterOptions.builder()
    .writeBlankLines(true)
    .writeHeaderComments(true)
    .writeInlineComments(true)
    .maxLineLength(80)
    .build();

Write Blank Lines

Preserve blank lines in output:

WriterOptions options = WriterOptions.builder()
    .writeBlankLines(true)
    .build();

doc.save(Path.of("output.toml"), options);

Output:

name = "MyApp"

[server]
host = "localhost"

Write Header Comments

Include header comments in output:

WriterOptions options = WriterOptions.builder()
    .writeHeaderComments(true)
    .build();

doc.save(Path.of("output.toml"), options);

Output:

# Application name
name = "MyApp"

Write Inline Comments

Include inline comments:

WriterOptions options = WriterOptions.builder()
    .writeInlineComments(true)
    .build();

doc.save(Path.of("output.toml"), options);

Output:

name = "MyApp" # The application name
port = 8080 # Default port

Max Line Length

Control when to break long values:

// Default: 100 characters
WriterOptions standard = WriterOptions.builder()
    .maxLineLength(100)
    .build();

// Compact: no line breaks
WriterOptions compact = WriterOptions.builder()
    .maxLineLength(Integer.MAX_VALUE)
    .build();

// Narrow: 80 characters
WriterOptions narrow = WriterOptions.builder()
    .maxLineLength(80)
    .build();

Effect on arrays:

// With maxLineLength = 10
[1, 2, 3, 4, 5]

// Becomes:
[
  1,
  2,
  3,
  4,
  5
]

Element Options Preset

For serializing individual values without line breaks:

WriterOptions options = WriterOptions.elementOptions();
// Equivalent to maxLineLength = Integer.MAX_VALUE

Use case:

Node arrayNode = doc.get("servers");
String oneLine = arrayNode.saveToString(WriterOptions.elementOptions());
// Always single line regardless of content

Common Scenarios

Production Configuration

Fast parsing, no preservation:

PreserveOptions parseOpts = PreserveOptions.defaultOptions();
WriterOptions writeOpts = WriterOptions.defaultOptions();

TomlDocument doc = Tomly.parse(configPath, false, parseOpts);
doc.save(outputPath, writeOpts);

Documentation Generation

Preserve and write all comments:

PreserveOptions parseOpts = PreserveOptions.builder()
    .preserveHeaderComments(true)
    .preserveInlineComments(true)
    .preserveBlankLines(true)
    .build();

WriterOptions writeOpts = WriterOptions.builder()
    .writeHeaderComments(true)
    .writeInlineComments(true)
    .writeBlankLines(true)
    .maxLineLength(80)
    .build();

TomlDocument doc = Tomly.parse(templatePath, false, parseOpts);
// Modify values...
doc.save(outputPath, writeOpts);

Configuration Updates

Preserve structure, update values:

PreserveOptions parseOpts = PreserveOptions.builder()
    .preserveHeaderComments(true)
    .preserveBlankLines(true)
    .build();

WriterOptions writeOpts = WriterOptions.builder()
    .writeHeaderComments(true)
    .writeBlankLines(true)
    .build();

TomlDocument doc = Tomly.parse(configPath, false, parseOpts);
doc.set("version", new StringNode("2.0.0", List.of(), null));
doc.save(configPath, writeOpts);

Compact Output

Minimize file size(amount of lines):

WriterOptions compact = WriterOptions.builder()
    .maxLineLength(Integer.MAX_VALUE)
    .build();

doc.save(Path.of("compact.toml"), compact);

Next Steps

Clone this wiki locally