Multi-line Text Values

Multi-line text allows text values to span multiple lines, providing a convenient way to handle large blocks of text.

multi_line_text      ::= ml_text_start ml_text_line* ml_text_end

ml_text_start       ::= '"""' end_of_line
ml_text_end         ::= indentation_pattern '"""'
ml_text_line        ::= ( indentation_pattern TEXT+ )? end_of_line

Below is an example of valid multi-line text values:

[main]
text 1: """
    “Hello!” exclaimed the multi-line text,
    As it flowed across the lines;
    It pondered what might happen next,
    And hoped to fit within the rhymes.
    """
text 2:
    """
        Bracket stands alone
            Indentation now looks fine
                Code is clean again
    """

Rules for Multi-line Text

Beginning the Text: Multi-line text begins with a sequence of three double-quote characters ("""). It can be followed by spaces or comments but must be followed by a line break.

[main]
text 1: """
    "Kommer du?"
    """
text 2:         # Spurte hun håpefullt
    """         # Ventende ved døren
    "Ja, jeg skal bare hente jakken min."
    """

Content and Indentation: The content of the multi-line text starts after the line break following the opening quotes. Each line must be indented by at least one space or tab character. Refer to Spacing for details on indentation.
```
[main]
text:
    """
    Les vérités invisibles sont les plus profondes.
    """
```
Consistent Indentation: Each line of the multi-line text must follow the exact sequence of spaces and tabs used at the beginning of the text. This ensures consistent indentation. See Spacing for more information.
```
[main]
text:
    """
    La niebla cubre
    Los caminos sin huellas
    Misterio oculto
    """
```

Ending the Text: Multi-line text ends on a new line with the repeated indentation sequence, followed immediately by a sequence of three double-quote characters (""").

[main]
text:
    """
    Programmer's note: "Remember to close your loops!"""  ← this isn't the end
        """And don't forget semicolons;" she added.       ← still going
    """ # ← This is where the text ends.

Allowed Characters: Any Unicode character can be used in multi-line text, except backslashes (which introduce escape sequences) and control characters, with the exception of the tab character, which is allowed.
```
[main]
text: """
    彼は興奮した様子で言った："ダブルクオート文字はここで使える！"
    どうやら彼は、それが日本語のテキストには不適切な文字だと知らなかったようだ…
    """
```
Note

Unlike single-line text values, double quotes are allowed within multi-line text without escaping.
Escape Sequences: All escape sequences valid for single-line text are also valid in multi-line text. For detailed information about escape sequences, see Escape Sequence Rules.
```
[main]
text: """
    \u{1f604}\n\u2191 is a grinning face with smiling eyes
    """
```
Line Breaks: Each line break in the multi-line text is converted into a single newline character (\n), regardless of the original line break style used in the configuration document.
```
[main]
text: """
    Morning sun rises
    Afternoon clouds drift slowly
    Evening stars twinkle
    """
```
This will always result in: Morning sun rises↵Afternoon clouds drift slowly↵Evening stars twinkle.
Trimming Whitespace: Leading and trailing whitespace around the text is removed, as described in Spacing.
```
[main]
text: """
    Simplicity is the ultimate sophistication.
    """
```
The resulting text will be: Simplicity is the ultimate sophistication.. The leading and trailing spacing, including the final line break, is removed.
```
[main]
text:
    """
        "Simplicity is the ultimate sophistication."
    """
```
In this second example, the resulting text will be: ⎵⎵⎵⎵"Simplicity is the ultimate sophistication.". While the leading spacing is removed, only the characters after the opening sequence, including the line-break and the indentation pattern count as spacing. Every character afterwards is part of the content. See Spacing for details.

Features

Feature	Coverage
core	Escape sequences in multi-line text are part of the core language.
multi-line	Multi-line text values are a standard feature.

Errors

Error Code	Causes
Character	Raised for any illegal character or invalid escape sequence within the text.
Syntax	Raised if the closing sequence of double quotes is missing at the end of the line or document.
Indentation	No space or tab character is present before a continued text. The indentation pattern does not match the first entry for a continued text.
LimitExceeded	Raised if the text exceeds the maximum size the parser can handle.