Dart Multi-line Strings

1. When to use this skill

Use this skill when:

• Refactoring consecutive print() or stdout.writeln() statements into a single, cohesive output block.
• Simplifying string literals that span multiple lines, contain embedded newlines (\n), or use nested indentations.
• Formatting large user-facing text output (like CLI help menus, reports, or templated messages) to be readable, maintainable, and performant.

When NOT to use (Abstention Guardrails)

Do NOT refactor to multiline strings when:

• Short, Single-Line Outputs: Strings that comfortably fit on a single line (<80 chars) without embedded newlines.
• Localized String Catalogs: Strings that are looked up from localization bundles (e.g. intl, ARB files), where line breaks or formatting must conform to external translation tooling.
• Raw Query Strings with Strict Whitespace Semantics: Protocol strings, strict CSV rows, or queries where indentation whitespace inside triple quotes would alter payload semantics or introduce unintended leading spaces.
• Streaming or Incremental I/O: Progress bars, spinners, or interactive console streams where individual writes occur with delays or flushing between lines.

Discovery

To find candidate code blocks for multi-line string refactoring:

• Look for multiple back-to-back print() or stdout.writeln() calls inside a function, especially inside loops, console views, or CLI controllers.
• Look for single-line strings heavily loaded with \n escape sequences.
• Look for multiple string concatenations using the + operator or adjacent string literal splits that are meant to represent multi-line outputs.

2. Guidelines

Combine Consecutive Outputs

Instead of calling print() repeatedly for a multi-line output, group the contents into a single triple-quoted string literal: print('''...''').

Explicit and Clean Alignment

In a triple-quoted literal, the exact spacing and formatting inside the quotes are preserved. Use this to specify indentation levels visually instead of using manually padded space prefixes (e.g., ' ').

Remove Empty Print Calls

If there are empty print() or print('') statements serving as vertical separators between output segments, replace them by letting the trailing newline of a multi-line string block handle the separation naturally.

Handling the First Newline

If the opening triple-quote is immediately followed by a newline, the compiler discards it.

• If you do not want a leading blank line, start the string content on a fresh line in the source code for clean layout.
• If you do want a leading blank line in the output, leave an extra empty line inside the triple-quoted block, or use \n explicitly at the beginning:

  print('''
  
  This starts with one blank line above it.''');

Handling the Trailing Newline & print()

print() automatically appends a trailing newline to the printed output.

• If you place the closing ''' on a new line (\n''');), an extra trailing blank line will be printed.
• To avoid unintended trailing blank lines, place the closing triple-quotes immediately after the final character:

  // ✅ Emits standard output with no extra trailing empty line:
  print('''
  Header
  Content''');

Avoiding Ghost Blank Lines in Conditional Interpolations

When injecting optional content via interpolation (${condition ? '...' : ''}), placing the ${...} on its own line leaves behind its enclosing newline when the condition evaluates to '', producing an empty blank line in the output.

• Include the leading newline inside the conditional string literal so the newline only renders when the content is present:

  // ✅ Clean conditional rendering without ghost blank lines:
  print('''
  Branch Details:
      Name: $branch${hasWarning ? '\n    WARNING: $warningMessage' : ''}''');

80-Character Line Limit Exemption

The lines_longer_than_80_chars lint rule automatically ignores lines inside multiline string literals. You can write long lines inside triple-quotes without triggering linter warnings or being forced to break them up.

Dynamic Switch Expressions inside Interpolation

Leverage Dart 3 switch expressions directly inside string interpolations to dynamically select and inject optional lines, conditional labels, or helper instructions. This avoids cluttering the surrounding code with imperatively constructed strings or multiple if statements:

print('''
Status: ${status.isSuccess ? 'PASS' : 'FAIL'}${switch (status) {
  Status.failed => '\nError details: $errorMessage',
  _ => '',
}}''');

3. Examples

Refactoring Consecutive Prints with Indentation

Avoid:

void printGerritView(String branch, String desc, bool hasConflicts) {
  print('Branch Details:');
  print('    Name:        ' + branch);
  print('    Description: ' + desc);
  print('');
  if (hasConflicts) {
    print('    WARNING: This branch has conflicts.');
    print('    Run `git merge origin/main` to resolve.');
  }
}

Prefer:

void printGerritView(String branch, String desc, bool hasConflicts) {
  print('''
Branch Details:
    Name:        $branch
    Description: $desc${hasConflicts ? '''

    WARNING: This branch has conflicts.
    Run `git merge origin/main` to resolve.''' : ''}''');
}