# YAML 簡介

YAML 格式中，含有一個到多個 **節點 (node)**，每個節點必定是 **純量 (Scalar)**、**序列 (Sequence)**、**映射(Mapping)資料** 其中一種。

- 純量 (scalar)
    
    運用零個或多個 Unicode 字元，以表示 **自定義資料 (opaque datum)**。說白一點，就是將**最基本的、不可再分的值**，全部使用文字來描述。
- 序列 (sequence)
    
    有順序的節點清單。清單內容，不限制節點的類型。以破折號( “**`-`** ”)，表示該行資料為序列。

```YAML
- 20
- 'Two'
- 34.3
```

- 映射 (mapping)

使用 Key: Value 的配對方式，以便快速找到所要的資料。 Key 是索引值，所以 Key 必需是 **唯一值**。  
以 冒號加空格("`:`") 的方式，來標註 key: value 的組合。

```YAML
language: csharp
```

## YAML 語法

在 YAML 的區塊集(Block collection) 中，以 **空格** **縮行** 的方式，表示資料的階層。  
**左側對齊的節點，視為同一階層的資料**。  
因為 `Tab` 可能在不同語言，表示方式不同，所以 **YAML 不建議使用 `Tab` 作為縮行的方式**。

YAML 的語法中，支援 **註解** 的標註，在 `#` 後方的文字，都會視為註解內容。

```YAML
# 註解
```

##### 序列: scalars

```
- John
- Roy
```

##### 序列: mapping

```
-
  name: John
  age: 20
  
-
  name: Roy
  age: 32
```

##### 映射: Scalars to Scalars

```
name: John
age: 20
```

##### 映射: Scalars to Sequence

```
person: 
  - John
  - Roy
```

### 02. 區塊的結構

有時，可能需要針對 YAML 內的資料，進行區塊的劃分。

YAML 運用三個破折號( “`---`“) ，表示 `---` 下方的，是一個新的資料區塊。並以三個點號("'`...`")，表示該區塊的結束。

```YAML
---	# begin

... # end
```

### 03. 多行資料的表示方式

有時，當 Scalars 內的文字太長或是需要分段落時，會以 `|` 或 `>` 表示。

- `|` 表示後面的文字，**每一行資料都視為獨立的資料**。

```YAML
node: |
    This is a book.
    it is a pen.
```

取回的 node 資料結果，如下

```
This is a book.
it is a pen.
```

- `>` 表示後面的文字，只有在 **縮行改變** 或 **空行** 時，YAML 才會視為新的資料。

```YAML
node: >
   This is a book.
   it is a pen.
      I want to supermark.
```

取回的 node 資料結果，如下

```
This is a book. it is a pen.
 I want to supermark.
```

### 04. 重複的節點資料

有時，我們希望某個節點被 **重複引用**。這時，就可以將 **`&`**、**`*`** 兩個符號會搭配在一起使用。

`&` 錨點，也是希望被重複引用的節點位置。

```
bill-to: &id001
  given: Chris
  family: Dumars
```

`*` 要引用其他節點的位置

```
ship-to: *id001
```

在上面的範例，取出來的 `bill-to` 與 `ship-to` 的內容是相同的。

### 05. 映射的複合鍵

前面使用 mapping 時，通常都是單一鍵。若需要以多個 Scalars 組成一個 key ，就要用 `?` 來組成 mapping key。

```
? - Detroit Tigers
  - Chicago cubs
:
  - 2001-07-23
```

出處 [14. 延伸補充 - YAML - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天 (ithome.com.tw)](https://ithelp.ithome.com.tw/articles/10206454)