Support Automatic Multiline String Encoding for Strings Containing \n in Arrays

[IsQiao]

Feature Request: Support Automatic Multiline String Encoding for Strings Containing \n in Arrays

Description

When encoding a Go struct with an array of strings containing \n (newline characters) into TOML using go-toml/v2, the \n is preserved as a literal escape sequence in the output rather than being rendered as an actual newline within a multiline string ("""). Even with SetArraysMultiline(true) enabled, which splits array elements across multiple lines, the strings within the array do not use TOML's multiline string syntax (""") automatically. This results in less readable output where newlines are escaped rather than naturally formatted, which is unexpected given TOML's focus on human-friendly configuration.

Currently, there is no straightforward way to automatically render these strings as multiline strings without significant manual intervention or custom preprocessing, making it challenging to handle arrays with dynamic or user-provided data containing newlines. I propose adding an option to automatically encode strings containing \n within arrays as TOML multiline strings (""") to improve usability and readability.

Steps to Reproduce

Here’s an example demonstrating the current behavior:

package main

import (
	"bytes"
	"fmt"
	"github.com/pelletier/go-toml/v2"
)

func main() {
	type Config struct {
		Name string   `toml:"name"`
		Tags []string `toml:"tags,multiline"`
	}

	config := Config{
		Name: "example",
		Tags: []string{
			"line1\nline2\nline3",
			"go\ntoml",
			"single line",
		},
	}

	var buf bytes.Buffer
	enc := toml.NewEncoder(&buf)
	enc.SetArraysMultiline(true)

	err := enc.Encode(config)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	fmt.Println(buf.String())
}

Current Output

The output I get with the above code is:

name = 'example'
tags = [
  "line1\nline2\nline3",
  "go\ntoml",
  'single line'
]

Expected Behavior

I’d expect strings containing \n within arrays to be automatically encoded as TOML multiline strings when SetArraysMultiline is enabled, like this:

name = 'example'
tags = [
  """
  line1
  line2
  line3
  """,
  """
  go
  toml
  """,
  'single line'
]

This would make array outputs more readable and align with TOML’s human-friendly design goals, without requiring complex workarounds or manual tagging.

Lack of Workaround

Currently, there is no simple or direct workaround to achieve this behavior:

• Using the toml:"multiline" tag on the array field works in some cases but requires explicit annotation for every affected field, which is impractical for dynamic data or reusable structs.
• Preprocessing strings to manually wrap them in """ or post-processing the TOML output is possible but cumbersome and error-prone, defeating the purpose of using an automated encoding library.
• Without a built-in option, developers are left with either accepting the less readable output or implementing custom logic, which adds unnecessary complexity.

[pelletier]

Thanks! This seems worthy of a new Encoder flag to control this behavior.

Looks like it needs to cover:

• The current, default behavior.
• Always emit multi-line basic strings (""").
• Only emit multi-line basic strings when the string contains new-line characters.

I don't have time for new feature development on go-toml at the moment but I'm happy to merge a patch from anyone who does.