# Riferimento Rapido YAML

*Scalari, sequenze, mapping, ancore, multi-riga*

> Source: YAML Specification (yaml.org) · MIT

## Sintassi

### Regole di Base

| Command | Description |
|---------|-------------|
| `Indentation` | Solo spazi (nessun tab), profondità consistente |
| `#` | Commento (fino a fine riga) |
| `---` | Marcatore di inizio documento |
| `...` | Marcatore di fine documento |
| `Case sensitive` | Chiavi e valori distinguono le maiuscole |

### Esempio Minimale

```
---
name: Alice
age: 30
active: true
```

## Scalari

### Tipi Scalari

| Command | Description |
|---------|-------------|
| `hello` | Stringa (senza virgolette) |
| `"hello"` | Stringa (doppi apici, permette escape) |
| `'hello'` | Stringa (apice singolo, letterale) |
| `42 / 3.14` | Numero (intero / virgola mobile) |
| `true / false` | Booleano |
| `null / ~` | Valore null |
| `2026-03-26` | Data (ISO 8601) |

### Regole di Virgolettatura

```
plain: nessuna virgoletta necessaria
special: "il colon: e il cancelletto # richiedono virgolette"
escape: "line\nnewline"
literal: 'nessun escape \n qui'
```

## Sequenze

### Sequenza a Blocchi

```
fruits:
  - apple
  - banana
  - cherry
```

### Sequenza Flow (Inline)

```
colors: [red, green, blue]
matrix: [[1, 2], [3, 4]]
```

### Sequenza di Oggetti

```
users:
  - name: Alice
    role: admin
  - name: Bob
    role: user
```

## Mapping

### Mapping a Blocchi

```
server:
  host: localhost
  port: 8080
  debug: false
```

### Mapping Flow (Inline)

```
point: {x: 10, y: 20}
```

### Chiavi Complesse

```
? [first, second]
: "valore chiave composta"
```

## Ancore e Alias

### Definizione e Riutilizzo

```
defaults: &defaults
  timeout: 30
  retries: 3
production:
  <<: *defaults
  timeout: 60
```

### Riferimento

| Command | Description |
|---------|-------------|
| `&name` | Definisce un'ancora |
| `*name` | Riferimento (alias) a un'ancora |
| `<<` | Chiave merge — fonde il mapping nel corrente |

## Stringhe Multi-riga

### Scalari a Blocchi

| Command | Description |
|---------|-------------|
| `\| (letterale)` | Preserva i newline esattamente |
| `> (ripiegato)` | Ripiega i newline in spazi |
| `\|+ (conserva)` | Letterale, conserva newline finali |
| `\|- (elimina)` | Letterale, elimina newline finali |
| `>- (piega+elimina)` | Ripiegato, elimina newline finali |

### Blocco Letterale

```
script: |
  echo "line one"
  echo "line two"
```

### Blocco Ripiegato

```
description: >
  Questo lungo testo verrà
  ripiegato in una singola riga
  con spazi.
```

## Tag

### Tag di Tipo

| Command | Description |
|---------|-------------|
| `!!str 42` | Forza il valore a stringa "42" |
| `!!int "42"` | Forza il valore a intero 42 |
| `!!float 1` | Forza il valore a float 1.0 |
| `!!bool "true"` | Forza il valore a booleano |
| `!!null ""` | Forza il valore a null |
| `!!binary` | Dati binari codificati in base64 |

### Esempio di Tag

```
port: !!str 8080
enabled: !!bool "yes"
version: !!float 3
```

## Pattern Comuni

### Docker Compose

```
services:
  web:
    image: nginx:alpine
    ports: ["80:80"]
    environment:
      NODE_ENV: production
```

### GitHub Actions

```
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
```

### Suggerimenti

| Command | Description |
|---------|-------------|
| `yamllint` | Linta YAML per sintassi e stile |
| `yq` | Processore YAML da riga di comando (come jq) |
| `Avoid Norway` | NO è booleano false — metti tra virgolette i codici paese |
| `Avoid !!python` | Non caricare mai YAML non attendibile con loader non sicuri |