YAML – Scalars and Tags

YAML - Scalars and Tags

Scalars are the fundamental building blocks of YAML, representing individual pieces of data like strings, numbers, and booleans. Tags are used to explicitly define the type of a scalar or any other YAML node.

Scalars

YAML offers several styles for writing scalar content, broadly categorized into block scalars (for multi-line content) and flow scalars (often inline).

Block Scalars

Block scalars are ideal for multi-line strings. They begin with a literal (|) or folded (>) style indicator.

1. Literal Style (|): Preserves all newlines within the string. Each line in the block is part of the string’s content exactly as it appears.

ascii_art: |
  \_/
 (o.o)
 > ^ <

# Chomping indicators control trailing newlines:
# | : Clip (single newline at end if content ends with newline, else no newline)
# |- : Strip (no newlines at end)
# |+ : Keep (all newlines at end)

clipped_script: |
  #!/bin/bash
  echo "Hello"

stripped_script: |-
  #!/bin/bash
  echo "Hello"

kept_script: |+
  #!/bin/bash
  echo "Hello"

2. Folded Style (>): Folds newlines within a paragraph into spaces. A blank line signifies a paragraph break (preserved as a newline). Lines indented more than the block itself are also preserved as newlines.

description: >
  This is a long description
  that will be folded into a
  single line, with newlines
  replaced by spaces.

  However, this new paragraph
  will start on a new line.
    And this line, being more indented,
    will also start on a new line.

# Chomping indicators (>, >-, >+) work similarly to literal style.

Flow Scalars (Inline Scalars)

Flow scalars are typically used for shorter, single-line values but can span multiple lines with specific rules.

• Plain (Unquoted): Strings written without quotes. They cannot start with certain characters (e.g., {}[]&*#?!|->%@,, grave accent) and must be careful with colons followed by spaces (: ). Example: name: John Doe`
• Single-Quoted ('): Enclosed in single quotes. Allows most characters literally. A single quote inside is escaped by doubling it (''). Fewer escape sequences are processed. Example: message: 'It''s a beautiful day!'
• Double-Quoted ("): Enclosed in double quotes. Supports C-style escape sequences like \n (newline), \t (tab), \\ (backslash), \" (double quote). Example: path: "C:\\Program Files\\My App"

plain_scalar: This is a simple string.
quoted_scalar: "This string can contain \"escaped quotes\" and newlines\nlike this."
single_quoted_scalar: 'This string handles most characters literally, like : { } [ ] - * & #.'
multiline_flow_plain: This unquoted scalar
  spans multiple lines;
  newlines are folded.
multiline_flow_quoted: "So does this\n  quoted scalar, with explicit \\n for newlines."

Tags

Tags in YAML explicitly specify the data type of a node. While YAML parsers often infer types automatically (e.g., 123 as an integer, true as a boolean), tags provide clarity or override default behavior. Tags are denoted by ! or !!.

• Specific tags: !!int (integer), !!float (float), !!str (string), !!bool (boolean), !!null (null), !!map (mapping), !!seq (sequence).
• Application-defined tags: Custom tags like !mytype can be used for application-specific data structures.

YAML’s Core Schema automatically resolves common types:

Common Implicitly Typed Scalars

The following demonstrate various representations that YAML typically parses into standard types without explicit tags.

# Integers
canonical_int: 12345
decimal_positive: +12345
hexadecimal: 0xC_A_F_E # Underscores for readability, parsed as 0xCAFE
octal: 0o14 # Parses as 12 decimal

# Floating-Point Numbers
canonical_float: 1.23015e+3
exponential_float: 12.3015e+02
fixed_float: 1230.15
negative_infinity: -.inf # Represents negative infinity
not_a_number: .nan # Represents NaN (Not a Number)

# Booleans
is_active: true
is_enabled: false

# Null
no_value: null
alternate_null: ~

# Strings (explicitly tagged if ambiguity needs resolving)
# For example, if '12345' should always be a string:
zip_code: !!str '12345'
version_number: !!str '2.0'

# Dates and Timestamps (YAML Core schema includes ISO 8601 support)
date: 2023-10-26
timestamp: 2023-10-26T10:20:30.5Z

The sexagesimal format (e.g., 3:25:45 for time or angles) is also part of YAML’s extended tag set, though not always enabled by default in all parsers without specific schema configuration. It’s often used for time durations or geographic coordinates.

Understanding scalars and tags is crucial for accurately representing data and ensuring it’s interpreted correctly by YAML processors and applications.