Multi-line Strings in YAML

Chapter 4: Multi-Line Strings¶

YAML allows you to define multi-line strings in a way that preserves or folds the lines depending on your needs. This is useful for writing long descriptions, commands, or configuration blocks where a single line would be too cumbersome. In this chapter, we'll explore how to handle multi-line strings using two different block styles: literal and folded.

4.1 Block Styles: Literal (|) vs. Folded (>)¶

YAML provides two block styles for handling multi-line strings:

Literal Block Style (|): Preserves line breaks, making each line in the YAML file a separate line in the final value.
Folded Block Style (>): Folds newlines into spaces, combining multiple lines into a single paragraph unless there’s a blank line.

4.2 Literal Block Style (|)¶

The literal block style is used when you want to preserve the exact formatting of the string, including all line breaks. Each new line in the YAML file will result in a new line in the output.

Example: Using Literal Block Style (|)¶

# Multi-line string with literal block style
description: |
  This is a multi-line string.
  Each line is preserved exactly as written.
  This can be useful for writing long text blocks
  or configuration snippets.

Output:¶

This is a multi-line string.
Each line is preserved exactly as written.
This can be useful for writing long text blocks
or configuration snippets.

This style is ideal for preserving formatting, such as when writing configuration scripts, log outputs, or large text blocks.

4.3 Folded Block Style (>)¶

The folded block style combines lines into a single string, replacing newlines with spaces. This is useful when you want a clean, continuous text without line breaks.

Example: Using Folded Block Style (>)¶

# Multi-line string with folded block style
summary: >
  This is a multi-line string
  that will be folded into
  a single line in the final output.
  Blank lines are preserved as line breaks.

Output:¶

This is a multi-line string that will be folded into a single line in the final output. Blank lines are preserved as line breaks.

Folded block style is often used for documentation, messages, or text that doesn't need strict line breaks.

4.4 Preserving Blank Lines¶

In both block styles, YAML allows you to preserve blank lines by inserting an extra line between blocks of text. This is useful when you need paragraphs or separation within the content.

Example: Preserving Blank Lines¶

# Using literal block style with blank lines
long_text: |
  This is the first paragraph.

  This is the second paragraph with a blank line between them.
  This paragraph will preserve the line break.

Output:¶

This is the first paragraph.

This is the second paragraph with a blank line between them.
This paragraph will preserve the line break.

4.5 Indentation in Multi-Line Strings¶

YAML respects the indentation level of multi-line strings. You can control how much indentation is applied to the lines inside the block.

Example: Indentation in Multi-Line Strings¶

# YAML respects indentation inside multi-line blocks
config_script: |
    echo "Starting service..."
    systemctl start nginx
    echo "Service started successfully."

4.6 Special Characters in Multi-Line Strings¶

When working with multi-line strings, you might encounter special characters (such as : or #). To prevent YAML from interpreting these characters as syntax, you can enclose the string in quotes or use the literal block style.

Example: Multi-Line String with Special Characters¶

# Handling special characters inside a multi-line string
command: |
  echo "Hello, world!"
  # This is a comment inside a multi-line string
  echo "End of script."

Because we’re using the literal block style (|), special characters like # are treated as part of the string rather than YAML syntax.

4.7 Multi-Line Strings in DevOps¶

Multi-line strings are frequently used in DevOps for handling large configurations, command sequences, or log outputs.

Kubernetes Configurations¶

Multi-line strings can be useful when specifying environment variables, commands, or configuration files in Kubernetes Pods or Deployments.

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  app-config: |
    DB_HOST=localhost
    DB_PORT=5432
    DB_USER=admin
    DB_PASSWORD=secret

Here, the app-config field contains a multi-line string representing environment variables for an application. The literal block style ensures that each line is treated separately.

Ansible Playbooks¶

When writing tasks in Ansible, multi-line strings are often used for complex command sequences or scripts.

- name: Run nginx setup script
  shell: |
    echo "Installing Nginx"
    yum install -y nginx
    systemctl start nginx
    echo "Nginx started"

In this example, the shell module runs a multi-line command sequence to install and start Nginx.

4.8 Best Practices for Multi-Line Strings¶

Choose the Right Block Style: Use literal block style (|) when you need to preserve exact formatting and line breaks. Use folded block style (>) when you want a continuous paragraph with no line breaks.
Comment Long Blocks: When using multi-line strings for configurations or commands, add comments to explain the purpose of each block. This makes your YAML more readable and maintainable.
Avoid Over-Nesting: While YAML allows indentation for multi-line strings, avoid over-nesting as it can make your file harder to read. Stick to consistent and manageable indentation levels.

4.9 Practice Exercise: Writing a Multi-Line String¶

Try writing a YAML file that defines a log output and a shell script using multi-line strings.

# Multi-line string for log output
log_output: |
  Starting the application...
  Loading configuration...
  Application started successfully.

# Multi-line shell script
setup_script: |
  echo "Installing dependencies"
  apt-get update
  apt-get install -y nginx
  systemctl start nginx

This concludes Chapter 4 on Multi-Line Strings. You now understand how to use literal and folded block styles to manage long text, commands, or configuration snippets in YAML. Multi-line strings are essential for writing readable, manageable YAML files in DevOps.