YAML 快速指南

---

---

YAML – 簡介

YAML Ain't Markup Language 是一種資料序列化語言，符合使用者對資料的期望。它旨在易於人類理解，並與其他程式語言完美配合。它可用於管理資料，幷包含 Unicode 可列印字元。本章將為您介紹 YAML 並讓您瞭解其功能。

格式

考慮以下文字：

Quick brown fox jumped over the lazy dog.

此文字的 YAML 表示形式如下：

yaml.load(Quick brown fox jumped over the lazy dog.)
>>'Quick brown fox jumped over the lazy dog.'

請注意，YAML 將值作為字串格式處理，並如上所述表示輸出。

示例

讓我們藉助以下示例瞭解 YAML 中的格式：

考慮以下圓周率“pi”的值為 3.1415926。在 YAML 中，它表示為如下所示的浮點數：

>>> yaml.load('3.1415926536')
3.1415926536

假設要將多個值載入到如下所示的特定資料結構中：

eggs
ham
spam
French basil salmon terrine

當您將其載入到 YAML 中時，這些值將以陣列資料結構（一種列表形式）的形式處理。輸出如下所示：

>>> yaml.load('''
   - eggs
   - ham
   - spam
   - French basil salmon terrine
   ''')
['eggs', 'ham', 'spam', 'French basil salmon terrine']

功能

YAML 包含一種標記語言，具有重要的結構，用於區分面向資料語言和文件標記。YAML 的設計目標和功能如下：

• 匹配敏捷方法及其語言（如 Perl、Python、PHP、Ruby 和 JavaScript）的原生資料結構

• YAML 資料可在程式語言之間移植

• 包含一致的資料模型

• 易於人工閱讀

• 支援單向處理

• 易於實現和使用

YAML – 基礎

現在您已經瞭解了 YAML 及其功能，讓我們學習其語法和其他操作的基礎知識。請記住，YAML 包含一種易於閱讀的結構化格式。

建立 YAML 檔案的規則

建立 YAML 檔案時，應記住以下基本規則：

• YAML 區分大小寫

• 檔案應以 .yaml 為副檔名

• 建立 YAML 檔案時，YAML 不允許使用製表符；允許使用空格

YAML 檔案的基本元件

YAML 的基本元件如下所述：

常規塊格式

此塊格式使用 連字元+空格 在指定的列表中開始新專案。請觀察以下示例：

--- # Favorite movies
 - Casablanca
 - North by Northwest
 - The Man Who Wasn't There

內聯格式

內聯格式用 逗號和空格 分隔，專案用 JSON 括起來。請觀察以下示例：

--- # Shopping list
   [milk, groceries, eggs, juice, fruits]

摺疊文字

摺疊文字將換行符轉換為空格，並刪除前導空格。請觀察以下示例：

- {name: John Smith, age: 33}
- name: Mary Smith
  age: 27

遵循 YAML 所有基本約定的結構如下所示：

men: [John Smith, Bill Jones]
women:
  - Mary Smith
  - Susan Williams

YAML 基本元素概要

• YAML 基本元素的概要如下：YAML 中的註釋以 (#) 字元開頭。

• 註釋必須用空格與其他標記分隔。

• 空格縮排用於表示結構。

• 製表符不包含在 YAML 檔案的縮排中。

• 列表成員以一個前導連字元 (-) 表示。

• 列表成員用方括號括起來，並用逗號分隔。

• 關聯陣列使用冒號 ( : ) 以鍵值對的形式表示。它們用花括號 {} 括起來。

• 具有單個流的多個文件用 3 個連字元 (---) 分隔。

• 每個檔案中重複的節點最初用一個與號 (&) 表示，以後用星號 (*) 標記。

• YAML 始終需要冒號和逗號作為列表分隔符，後跟空格和標量值。

• 節點應使用感嘆號 (!) 或雙感嘆號 (!!) 標記，後跟可以擴充套件為 URI 或 URL 的字串。

YAML – 縮排和分隔

學習任何程式語言時，縮排和分隔是兩個主要概念。本章將詳細介紹與 YAML 相關的這兩個概念。

YAML 的縮排

YAML 不包含任何強制空格。此外，無需保持一致。有效的 YAML 縮排如下所示：

a:
   b:
      - c
      -  d
      - e
f:
      "ghi"

• 使用 YAML 中的縮排時，應記住以下規則：流塊必須至少使用一些空格與周圍的當前塊級別縮排。

• YAML 的流內容跨越多行。流內容的開頭以 { 或 [ 開頭。

• 塊列表項與周圍的塊級別具有相同的縮排，因為 - 被視為縮排的一部分。

縮排塊的示例

觀察以下顯示帶示例的縮排的程式碼：

--- !clarkevans.com/^invoice
invoice: 34843
date   : 2001-01-23
bill-to: &id001
   given  : Chris
   family : Dumars
   address:
      lines: |
            458 Walkman Dr.
            Suite #292
      city    : Royal Oak
      state   : MI
      postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
   - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments: >
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

字串分隔

使用雙引號字串分隔字串。如果轉義給定字串中的換行符，則將其完全刪除並轉換為空格值。

示例

在此示例中，我們重點介紹了作為陣列結構列出的動物列表，其資料型別為字串。每個新元素都以連字元作為字首列出。

-
 - Cat
 - Dog
 - Goldfish
-
 - Python
 - Lion
 - Tiger

另一個解釋 YAML 中字串表示的示例如下所示。

 errors:
      messages:
         already_confirmed: "was already confirmed, please try signing in"
         confirmation_period_expired: "needs to be confirmed within %{period}, please request a new one"
         expired: "has expired, please request a new one"
         not_found: "not found"
         not_locked: "was not locked"
         not_saved:
            one: "1 error prohibited this %{resource} from being saved:"
            other: "%{count} errors prohibited this %{resource} from being saved:"

此示例指的是使用者只需提及關鍵方面即可使用的錯誤訊息集，並相應地獲取值。此 YAML 模式遵循 JSON 的結構，對於 YAML 新手來說很容易理解。

YAML – 註釋

既然您已經熟悉了 YAML 的語法和基礎知識，讓我們進一步深入瞭解其細節。在本章中，我們將瞭解如何在 YAML 中使用註釋。

YAML 支援單行註釋。其結構將透過以下示例進行解釋：

# this is single line comment.

YAML 不支援多行註釋。如果要為多行提供註釋，您可以按照以下示例所示進行操作：

# this
# is a multiple
# line comment

註釋的功能

YAML 中註釋的功能如下：

• 在執行過程中會跳過註釋塊。

• 註釋有助於為指定的程式碼塊新增說明。

• 註釋不能出現在標量內。

• YAML 沒有辦法轉義井號 (#)，因此在多行字串中，無法將註釋與原始字串值分開。

集合中的註釋如下所示：

key: #comment 1
   - value line 1
   #comment 2
   - value line 2
   #comment 3
   - value line 3

YAML 塊註釋的快捷鍵組合是 Ctrl+Q。

如果您使用的是 Sublime Text 編輯器，則註釋塊的步驟如下：

選擇塊。在 Linux 和 Windows 上使用“CTRL + /”，在 Mac 作業系統上使用“CMD+/”。執行塊。

請注意，如果您使用的是 Visual Studio Code 編輯器，則相同的步驟也適用。始終建議使用 Sublime Text 編輯器 建立 YAML 檔案，因為它受大多數作業系統支援，幷包含對開發人員友好的快捷鍵。

YAML – 集合和結構

YAML 包含使用縮排表示作用域的塊集合。在此，每個條目都以新行開頭。集合中的塊序列用 連字元和空格 (-) 表示每個條目。在 YAML 中，塊集合樣式不用任何特定指示符表示。YAML 中的塊集合可以透過識別其中包含的鍵值對將其與其他標量量區分開來。

對映表示 JSON 結構中包含的鍵值。它經常用於多語言支援系統和移動應用程式中 API 的建立。對映使用鍵值對錶示法，使用 冒號和空格 (:)。

示例

考慮一個標量序列的示例，例如如下所示的棒球運動員列表：

- Mark Joseph
- James Stephen
- Ken Griffey

以下示例顯示將標量對映到標量：

hr: 87
avg: 0.298
rbi: 149

以下示例顯示將標量對映到序列：

European:
- Boston Red Sox
- Detroit Tigers
- New York Yankees

national:
- New York Mets
- Chicago Cubs
- Atlanta Braves

集合可用於序列對映，如下所示：

-
   name: Mark Joseph
   hr: 87
   avg: 0.278
-
   name: James Stephen
   hr: 63
   avg: 0.288

對於集合，YAML 包含使用顯式指示符而不是使用縮排來表示空間的流樣式。集合中的流序列被寫成用方括號括起來的逗號分隔列表。最適合在 PHP 框架（如 symphony）中包含的集合的說明。

[PHP, Perl, Python]

這些集合儲存在文件中。YAML 中文件的分隔用三個連字元或短劃線 (---) 表示。文件的結尾用三個點 (...) 標記。

YAML 中文件的分隔用三個短劃線 (---) 表示。文件的結尾用三個點 (...) 表示。

文件表示稱為結構格式，如下所示：

# Ranking of 1998 home runs
---
- Mark Joseph
- James Stephen
- Ken Griffey 

# Team ranking
---
- Chicago Cubs
- St Louis Cardinals

問號與空格的組合表示結構中的複雜對映。在一個塊集合中，使用者可以使用連字元、冒號和問號包含結構。以下示例顯示序列之間的對映：

- 2001-07-23
? [ New York Yankees,Atlanta Braves ]
: [ 2001-07-02, 2001-08-12, 2001-08-14]

YAML – 標量和標籤

YAML 中的標量使用文字型別（表示為 (|)）的塊格式編寫。它表示換行符計數。在 YAML 中，標量以摺疊樣式 (>) 編寫，其中每一行都表示一個摺疊空格，該空格以空行或縮排更多的行結尾。

文字中保留換行符，如下所示：

ASCII Art
--- |
\//||\/||
// || ||__

對於縮排更多的行和空行，摺疊的換行符將保留，如下所示：

>
Sammy Sosa completed another
fine season with great stats.
63 Home Runs
0.288 Batting Average
What a year!

YAML 流標量包括純樣式和引號樣式。雙引號樣式包含各種轉義序列。流標量可以包含多行；換行符在此結構中始終被摺疊。

plain:
This unquoted scalar
spans many lines.
quoted: "So does this
quoted scalar.\n"

在 YAML 中，未標記的節點使用特定型別的應用程式指定。標籤規範的示例通常使用seq、map和str型別表示 YAML 標籤儲存庫。標籤表示為如下所示的示例：

整數標籤

這些標籤包含整數數值。它們也稱為數字標籤。

canonical: 12345
decimal: +12,345
sexagecimal: 3:25:45
octal: 014
hexadecimal: 0xC

浮點數

這些標籤包含十進位制和指數值。它們也稱為指數標籤。

canonical: 1.23015e+3
exponential: 12.3015e+02
sexagecimal: 20:30.15
fixed: 1,230.15
negative infinity: -.inf
not a number: .NaN

其他標籤

它包含各種嵌入其中的整數、浮點數和字串值。因此，它被稱為其他標籤。

null: ~
true: y
false: n
string: '12345'

YAML –完整示例

下面的完整示例指定了YAML的結構，其中包括符號和各種表示形式，這在將YAML轉換為JSON格式或處理JSON格式時將非常有用。這些屬性在JSON文件中也稱為鍵名。這些表示法是為了安全目的而建立的。

上述YAML格式表示defaults、adapter和host的各種屬性以及其他屬性。YAML還會記錄生成的每個檔案，跟蹤生成的錯誤訊息。將指定的YAML檔案轉換為JSON格式後，我們將得到如下所示的所需輸出：

defaults: &defaults
   adapter:  postgres
   host:     localhost

development:
   database: myapp_development
   <<: *defaults

test:
   database: myapp_test
   <<: *defaults

讓我們將YAML轉換為JSON格式並檢查輸出。

{
   "defaults": {
      "adapter": "postgres",
      "host": "localhost"
   },
   "development": {
      "database": "myapp_development",
      "adapter": "postgres",
      "host": "localhost"
   },
   "test": {
      "database": "myapp_test",
      "adapter": "postgres",
      "host": "localhost"
   }
}

帶有“<<: *”字首的defaults鍵根據需要包含，無需重複編寫相同的程式碼片段。

YAML - 處理過程

YAML遵循標準的流程處理程式。YAML中的原生資料結構包括簡單的表示形式，例如節點。它也稱為表示節點圖。

它包括對映、序列和標量量，這些量被序列化以建立一個序列化樹。透過序列化，物件將轉換為位元組流。

序列化事件樹有助於建立字元流的表示，如下圖所示。

反向過程將位元組流解析為序列化事件樹。之後，節點將轉換為節點圖。這些值隨後轉換為YAML原生資料結構。下圖對此進行了說明：

YAML中的資訊以兩種方式使用：**機器處理**和**人工閱讀**。YAML中的處理器用作在上面所示圖表中轉換互補檢視之間資訊的工具。本章描述了YAML處理器必須在給定應用程式中提供的信​​息結構。

YAML包含一個序列化過程，用於以序列格式表示資料物件。YAML資訊的處理包括三個階段：**表示、序列化、呈現和解析**。讓我們詳細討論每個階段。

表示

YAML使用三種節點來表示資料結構：**序列、對映**和**標量**。

序列

序列指的是有序的條目數，它對映鍵值對的無序關聯。它對應於Perl或Python的陣列列表。

下面顯示的程式碼是序列表示的示例：

product:
   - sku         : BL394D
     quantity    : 4
     description : Football
     price       : 450.00
   - sku         : BL4438H
     quantity    : 1
     description : Super Hoop
     price       : 2392.00

對映

另一方面，對映表示字典資料結構或雜湊表。下面提到了一個相同的例子：

batchLimit: 1000
threadCountLimit: 2
key: value
keyMapping: <What goes here?>

標量

標量表示字串、整數、日期和原子資料型別的標準值。請注意，YAML還包含指定資料型別結構的節點。有關標量的更多資訊，請參閱本教程的第6章。

序列化

YAML需要序列化過程，這簡化了對人友好的鍵順序和錨點名稱。序列化的結果是YAML序列化樹。可以遍歷它以產生一系列YAML資料的事件呼叫。

下面給出了一個序列化示例：

consumer:
   class: 'AppBundle\Entity\consumer'
   attributes:
      filters: ['customer.search', 'customer.order', 'customer.boolean']
   collectionOperations:
      get:
         method: 'GET'
         normalization_context:
       groups: ['customer_list']
   itemOperations:
      get:
         method: 'GET'
         normalization_context:
            groups: ['customer_get']

呈現

YAML序列化的最終輸出稱為呈現。它以對人友好的方式表示字元流。YAML處理器包含各種呈現細節，用於建立流、處理縮排和格式化內容。這個完整的過程由使用者的偏好引導。

YAML呈現過程的一個示例是建立的JSON值的輸出結果。觀察下面給出的程式碼以更好地理解：

{
   "consumer": {
      "class": "AppBundle\\Entity\\consumer",
      "attributes": {
         "filters": [
            "customer.search",
            "customer.order",
            "customer.boolean"
         ]
      },
      "collectionOperations": {
         "get": {
            "method": "GET",
            "normalization_context": {
               "groups": [
                  "customer_list"
               ]
            }
         }
      },
      "itemOperations": {
         "get": {
            "method": "GET",
            "normalization_context": {
               "groups": [
                  "customer_get"
               ]
            }
         }
      }
   }
}

解析

解析是呈現的逆過程；它包含一系列字元並建立一系列事件。它丟棄了呈現過程中引入的細節，這些細節導致序列化事件。由於輸入格式錯誤，解析過程可能會失敗。它基本上是一個檢查YAML是否格式良好的過程。

考慮下面提到的YAML示例：

---
   environment: production
   classes:
      nfs::server:
         exports:
            - /srv/share1
            - /srv/share3
   parameters:
      paramter1

三個連字元表示文件的開始，後面定義了各種屬性。

YAML lint是YAML的線上解析器，有助於解析YAML結構以檢查其是否有效。YAML lint的官方連結如下：http://www.yamllint.com/

您可以看到如下所示的解析輸出：

YAML - 資訊模型

本章將詳細解釋我們在上一章中討論的過程和步驟。YAML中的資訊模型將使用特定的圖表以系統化的格式指定序列化和呈現過程的特性。

對於資訊模型，重要的是要表示可以在程式設計環境之間移植的應用程式資訊。

上圖表示以圖形格式表示的普通訊息模型。在YAML中，原生資料的表示是根植的、連線的，並且是標記節點的有向圖。如果我們提到有向圖，它包括一組具有有向圖的節點。如資訊模型中提到的，YAML支援三種類型的節點，即：

• 序列
• 標量
• 對映

這些表示節點的基本定義已在上一章中討論過。在本章中，我們將重點關注這些術語的示意圖。下面的序列圖表示帶有各種型別標籤和對映節點的圖例的工作流程。

共有三種類型的節點：**序列節點、標量節點**和**對映節點**。

序列

序列節點遵循順序架構，幷包含零個或多個節點的有序序列。YAML序列可以重複包含相同的節點或單個節點。

標量

YAML中標量的內容包括Unicode字元，可以用一系列零的格式表示。一般來說，標量節點包含標量量。

對映

對映節點包括鍵值對錶示。對映節點的內容包括鍵值對的組合，其中必須維護鍵名唯一。序列和對映共同構成一個集合。

請注意，如上圖所示，標量、序列和對映以系統化的格式表示。

YAML - 語法字元

各種型別的字元用於各種功能。本章詳細介紹了YAML中使用的語法，並重點介紹字元操作。

指示符字元

指示符字元包括用於描述YAML文件內容的特殊語義。下表對此進行了詳細說明。

下面的示例顯示了語法中使用的字元：

%YAML 1.1
---
!!map {
   ? !!str "sequence"
   : !!seq [
      !!str "one", !!str "two"
   ],
   ? !!str "mapping"
   : !!map {
      ? !!str "sky" : !!str "blue",
      ? !!str "sea" : !!str "green",
   }
}

# This represents
# only comments.
---
!!map1 {
   ? !!str "anchored"
   : !local &A1 "value",
   ? !!str "alias"
   : *A1,
}
!!str "text"

YAML - 語法基元

在本章中，您將學習YAML中語法基元的以下方面：

• 生產引數
• 縮排空格
• 分隔空格
• 忽略的行字首
• 折行

讓我們詳細瞭解每個方面。

生產引數

生產引數包括一組引數和允許值的範圍，這些值用於特定生產。YAML中使用以下生產引數列表：

縮排

它由字元**n**或**m**表示。字元流取決於其中包含的塊的縮排級別。許多產品都對這些特性進行了引數化。

上下文

它由**c**表示。YAML支援兩組上下文：**塊樣式**和**流樣式**。

樣式

它由s表示。標量內容可以以五種樣式之一呈現：**普通、帶雙引號和帶單引號的流、文字和摺疊塊。**

截斷

它由**t**表示。塊標量提供許多機制，有助於修剪塊：**去除、剪輯**和**保留**。截斷有助於格式化換行符字串。它用於塊樣式表示。截斷過程藉助指示符進行。指示符控制應使用字串的換行符產生什麼輸出。換行符使用**(-)**運算子刪除，並使用**(+)**運算子新增換行符。

下面顯示了一個截斷過程的示例：

strip: |-
   text↓
clip: |
   text↓
keep: |+
   text↓

解析指定的YAML示例後的輸出如下：

縮排空格

在YAML字元流中，縮排定義為由零個或多個字元組成的換行符。最重要的是要注意，縮排不能包含任何製表符。縮排中的字元絕不能被視為節點內容資訊的一部分。觀察以下程式碼以更好地理解：

%YAML 1.1
---
!!map {
   ? !!str "Not indented"
   : !!map {
      ? !!str "By one space"
      : !!str "By four\n spaces\n",
      ? !!str "Flow style"
      : !!seq [
         !!str "By two",
         !!str "Still by two",
         !!str "Again by two",
      ]
   }
}

縮排後可以看到的輸出如下：

{
   "Not indented": {
      "By one space": "By four\n spaces\n", 
      "Flow style": [
         "By two", 
         "Still by two", 
         "Again by two"
      ]
   }
}

分隔空格

YAML使用空格字元分隔標記。最重要的是要注意，YAML中的分隔符不應包含製表符。

以下程式碼行顯示了分隔空格的使用：

{ · first: · Sammy, · last: · Sosa · }

上面顯示的語法會給出以下輸出

{
   "\u00b7 last": "\u00b7 Sosa \u00b7", 
   "\u00b7 first": "\u00b7 Sammy"
}

忽略的行字首

空字首始終包含取決於標量型別的縮排，其中還包括前導空格。普通標量不應包含任何製表符。另一方面，帶引號的標量可能包含製表符。塊標量完全取決於縮排。

以下示例以系統化的方式顯示了忽略行字首的工作原理：

%YAML 1.1
---
!!map {
   ? !!str "plain"
   : !!str "text lines",
   ? !!str "quoted"
   : !!str "text lines",
   ? !!str "block"
   : !!str "text·®lines\n"
}

塊流實現的輸出如下：

{
   "plain": "text lines", 
   "quoted": "text lines", 
   "block": "text\u00b7\u00aelines\n"
}

折行

折行允許換行長行以提高可讀性。較多的短行意味著更好的可讀性。透過注意長行的原始語義來實現折行。以下示例演示了折行：

%YAML 1.1
--- !!str
"specific\L\
trimmed\n\n\n\
as space"

您可以看到以JSON格式進行折行的輸出如下：

"specific\u2028trimmed\n\n\nas space"

YAML - 字元流

在YAML中，您會遇到以下各種字元流：

• 指令
• 文件邊界標記
• 文件
• 完整流

在本章中，我們將詳細討論它們。

指令

指令是在YAML處理器中使用的基本指令。指令是表示細節（如註釋），這些細節不會反映在序列化樹中。在YAML中，無法定義私有指令。本節討論各種型別的指令以及相關的示例：

保留指令

保留指令以三個連字元（---）開頭，如下面的示例所示。保留指令將轉換為JSON的特定值。

%YAML 1.1
--- !!str
"foo"

YAML指令

YAML指令是預設指令。如果轉換為JSON，則獲取的值在其前導字元和終止字元中包含正斜槓字元。

%YAML 1.1
---
!!str "foo"

文件邊界標記

YAML 使用這些標記允許在一個流中包含多個文件。這些標記特別用於傳達 YAML 文件的結構。請注意，以“---”開頭的行用於開始一個新的文件。

以下程式碼透過示例對此進行了說明：

%YAML 1.1
---
!!str "foo"
%YAML 1.1
---
!!str "bar"
%YAML 1.1
---
!!str "baz"

文件

YAML 文件被認為是呈現為單個根節點的單個原生資料結構。YAML 文件中的表示細節，例如指令、註釋、縮排和樣式，不被視為其中包含的內容。

YAML 中使用兩種型別的文件。本節將對它們進行解釋：

顯式文件

它以文件開始標記開頭，然後是根節點的表示。YAML 顯式宣告的示例如下所示：

---

some: yaml

...

它包含顯式的開始和結束標記，在本例中為“---”和“...” 。將指定的 YAML 轉換為 JSON 格式後，我們將得到如下所示的輸出：

{
   "some": "yaml"
}

隱式文件

這些文件不以文件開始標記開頭。請觀察以下程式碼：

fruits:
   - Apple
   - Orange
   - Pineapple
   - Mango

將這些值轉換為 JSON 格式，我們將得到如下所示的簡單 JSON 物件：

{
   "fruits": [
      "Apple",
      "Orange",
      "Pineapple",
      "Mango"
   ]
}

完整流

YAML 包含一個稱為字元流的位元組序列。流以包含位元組順序的 (表示字元編碼) 字首開頭。完整的流以包含字元編碼的字首開頭，後跟註釋。

完整流 (字元流) 的示例如下所示：

%YAML 1.1
---
!!str "Text content\n"

YAML - 節點屬性

每個表示節點包含兩個主要特徵，稱為錨點和標籤。節點屬性可以與節點內容一起指定，也可以從字元流中省略。

節點表示的基本示例如下：

%YAML 1.1
---
!!map {
   ? &A1 !!str "foo"
   : !!str "bar",
   ? !!str &A2 "baz"
   : *a1
}

節點錨點

錨點屬性表示一個節點以供將來參考。YAML 表示中節點的字元流用＆號 (&)指示符表示。YAML 處理器不需要保留與其中組合的表示細節一起的錨點名稱。以下程式碼對此進行了說明：

%YAML 1.1
---
!!map {
   ? !!str "First occurence"
   : &A !!str "Value",
   ? !!str "Second occurence"
   : *A
}

使用錨點節點生成的 YAML 輸出如下所示：

---
!!map {
   ? !!str "First occurence"
   : !!str "Value",
   ? !!str "Second occurence"
   : !!str "Value",
}

節點標籤

標籤屬性表示原生資料結構的型別，該型別完整地定義了一個節點。標籤用 (!) 指示符表示。標籤被認為是表示圖的固有部分。以下示例詳細解釋了節點標籤：

%YAML 1.1
---
!!map {
   ? !<tag:yaml.org,2002:str> "foo"
   : !<!bar> "baz"
}

節點內容

節點內容可以用流內容或塊格式表示。塊內容擴充套件到行尾，並使用縮排表示結構。每種集合型別都可以以特定的單流集合樣式表示，或者可以視為單個塊。以下程式碼詳細解釋了這一點：

%YAML 1.1
---
!!map {
   ? !!str "foo"
   : !!str "bar baz"
}

%YAML 1.1
---
!!str "foo bar"

%YAML 1.1
---
!!str "foo bar"

%YAML 1.1
---
!!str "foo bar\n"

YAML - 塊標量頭

在本章中，我們將重點介紹用於表示內容的各種標量型別。在 YAML 中，註釋可以位於標量內容之前或之後。重要的是要注意，註釋不應包含在標量內容中。

請注意，所有流標量樣式都可以包含多行，但不能在多個鍵中使用。

標量的表示如下所示：

%YAML 1.1
---
!!map {
   ? !!str "simple key"
   : !!map {
      ? !!str "also simple"
      : !!str "value",
      ? !!str "not a simple key"
      : !!str "any value"
   }
}

塊標量頭的生成輸出如下所示：

{
   "simple key": {
      "not a simple key": "any value", 
      "also simple": "value"
   }
}

文件標記標量內容

本例中的所有字元都被視為內容，包括內部空格字元。

%YAML 1.1
---
!!map {
   ? !!str "---"
   : !!str "foo",
   ? !!str "...",
   : !!str "bar"
}

%YAML 1.1
---
!!seq [
   !!str "---",
   !!str "...",
   !!map {
      ? !!str "---"
      : !!str "..."
   }
]

普通換行符用以下示例表示：

%YAML 1.1
---
!!str "as space \
trimmed\n\
specific\L\n\
none"

相同的 JSON 輸出如下所示：

"as space trimmed\nspecific\u2028\nnone"

YAML - 流樣式

YAML 中的流樣式可以被認為是 JSON 的自然擴充套件，用於涵蓋摺疊內容行以獲得更好的可讀性功能，該功能使用錨點和別名來建立物件例項。在本章中，我們將重點介紹以下概念的流表示：

• 別名節點
• 空節點
• 流標量樣式
• 流集合樣式
• 流節點

別名節點的示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "First occurrence"
   : &A !!str "Foo",
   ? !!str "Override anchor"
   : &B !!str "Bar",
   ? !!str "Second occurrence"
   : *A,
   ? !!str "Reuse anchor"
   : *B,
}

上面程式碼的 JSON 輸出如下所示：

{
   "First occurrence": "Foo", 
   "Second occurrence": "Foo", 
   "Override anchor": "Bar", 
   "Reuse anchor": "Bar"
}

內容為空的節點被認為是空節點。以下示例顯示了這一點：

%YAML 1.2
---
!!map {
   ? !!str "foo" : !!str "",
   ? !!str "" : !!str "bar",
}

JSON 中空節點的輸出表示如下：

{
   "": "bar", 
   "foo": ""
}

流標量樣式包括雙引號、單引號和平面型別。相同的基本示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "implicit block key"
   : !!seq [
      !!map {
         ? !!str "implicit flow key"
         : !!str "value",
      }
   ]  
}

上面示例的 JSON 格式輸出如下所示：

{
   "implicit block key": [
      {
         "implicit flow key": "value"
      }
   ] 
}

YAML 中的流集合在一個流集合中嵌套了一個塊集合。流集合條目以逗號 (,) 指示符結尾。以下示例詳細解釋了流集合塊：

%YAML 1.2
---
!!seq [
   !!seq [
      !!str "one",
      !!str "two",
   ],
   
   !!seq [
      !!str "three",
      !!str "four",
   ],
]

JSON 中流集合的輸出如下所示：

[
   [
      "one", 
      "two"
   ], 
   [
      "three", 
      "four"
   ]
]

像 JSON 這樣的流樣式包含開始和結束指示符。唯一沒有任何屬性的流樣式是純標量。

%YAML 1.2
---
!!seq [
!!seq [ !!str "a", !!str "b" ],
!!map { ? !!str "a" : !!str "b" },
!!str "a",
!!str "b",
!!str "c",]

以上程式碼的 JSON 格式輸出如下所示：

[
   [
      "a", 
      "b"
   ], 
   
   {
      "a": "b"
   }, 
   
   "a", 
   "b", 
   "c"
]

YAML - 塊樣式

YAML 包含兩種塊標量樣式：文字和摺疊。塊標量由一些指示符控制，這些指示符在內容本身之前有一個標題。塊標量頭的示例如下所示：

%YAML 1.2
---
!!seq [
   !!str "literal\n",
   !!str "·folded\n",
   !!str "keep\n\n",
   !!str "·strip",
]

具有預設行為的 JSON 格式輸出如下所示：

[
   "literal\n", 
   "\u00b7folded\n", 
   "keep\n\n", 
   "\u00b7strip"
]

塊樣式的型別

有四種類型的塊樣式：文字、摺疊、保留和去除樣式。這些塊樣式是在塊切除場景的幫助下定義的。塊切除場景的示例如下所示：

%YAML 1.2
---
!!map {
   ? !!str "strip"
   : !!str "# text",
   ? !!str "clip"
   : !!str "# text\n",
   ? !!str "keep"
   : !!str "# text\n",
}

您可以看到使用三種格式生成的 JSON 輸出，如下所示：

{
   "strip": "# text", 
   "clip": "# text\n", 
   "keep": "# text\n"
}

YAML 中的切除控制最終換行符和尾隨空行，這些換行符和空行以各種形式解釋。

去除

在這種情況下，最終換行符和空行將從標量內容中排除。它由切除指示符“-”指定。

裁剪

如果沒有指定顯式切除指示符，則裁剪被認為是預設行為。最終換行符將保留在標量的內容中。上面示例中演示了裁剪的最佳示例。它以換行符“\n”字元結尾。

保留

保留是指新增“+”切除指示符的表示。建立的附加行不受摺疊的影響。附加行不受摺疊的影響。

YAML - 序列樣式

要理解序列樣式，重要的是要理解集合。集合和序列樣式的概念並行工作。YAML 中的集合用正確的序列樣式表示。如果要引用標籤的正確順序，請始終參考集合。YAML 中的集合由從零開始的連續整數索引，如陣列中所示。序列樣式的重點從集合開始。

示例

讓我們考慮宇宙中行星的數量作為一個序列，可以將其建立為一個集合。以下程式碼顯示瞭如何表示宇宙中行星的序列樣式：

# Ordered sequence of nodes in YAML STRUCTURE
Block style: !!seq
- Mercury   # Rotates - no light/dark sides.
- Venus     # Deadliest. Aptly named.
- Earth     # Mostly dirt.
- Mars      # Seems empty.
- Jupiter   # The king.
- Saturn    # Pretty.
- Uranus    # Where the sun hardly shines.
- Neptune   # Boring. No rings.
- Pluto     # You call this a planet?
Flow style: !!seq [ Mercury, Venus, Earth, Mars,      # Rocks
                    Jupiter, Saturn, Uranus, Neptune, # Gas
                    Pluto ]                           # Overrated

然後，您可以看到 JSON 格式的有序序列的以下輸出：

{
   "Flow style": [
      "Mercury", 
      "Venus", 
      "Earth", 
      "Mars", 
      "Jupiter", 
      "Saturn", 
      "Uranus", 
      "Neptune", 
      "Pluto"
   ], 
   
   "Block style": [
      "Mercury", 
      "Venus", 
      "Earth", 
      "Mars", 
      "Jupiter", 
      "Saturn", 
      "Uranus", 
      "Neptune", 
      "Pluto"
   ]
}

YAML - 流對映

YAML 中的流對映表示鍵值對的無序集合。它們也稱為對映節點。請注意，應保持鍵的唯一性。如果流對映結構中鍵重複，則會生成錯誤。鍵順序在序列化樹中生成。

示例

流對映結構的示例如下所示：

%YAML 1.1
paper:
   uuid: 8a8cbf60-e067-11e3-8b68-0800200c9a66
   name: On formally undecidable propositions of  Principia Mathematica and related systems I.
   author: Kurt Gödel.
tags:
   - tag:
      uuid: 98fb0d90-e067-11e3-8b68-0800200c9a66
      name: Mathematics
   - tag:
      uuid: 3f25f680-e068-11e3-8b68-0800200c9a66
      name: Logic

JSON 格式中對映序列（無序列表）的輸出如下所示：

{
   "paper": {
      "uuid": "8a8cbf60-e067-11e3-8b68-0800200c9a66",
      "name": "On formally undecidable propositions of Principia Mathematica and related systems I.",
      "author": "Kurt Gödel."
   },
   "tags": [
      {
         "tag": {
            "uuid": "98fb0d90-e067-11e3-8b68-0800200c9a66",
            "name": "Mathematics"
         }
      },
      {
         "tag": {
            "uuid": "3f25f680-e068-11e3-8b68-0800200c9a66",
            "name": "Logic"
         }
      }
   ]
}

如果您觀察到如上所示的輸出，您會發現鍵名在 YAML 對映結構中保持唯一。

YAML - 塊序列

YAML 的塊序列表示一系列節點。每個專案都用前導“-”指示符表示。請注意，YAML 中的“-”指示符應與節點用空格分隔。

塊序列的基本表示如下所示：

block sequence:
··- one↓
  - two : three↓

示例

觀察以下示例，以便更好地理解塊序列。

示例 1

port: &ports
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  <<: *ports

塊序列的 JSON 格式輸出如下所示：

{
   "port": {
      "adapter": "postgres",
      "host": "localhost"
   },
   "development": {
      "database": "myapp_development",
      "adapter": "postgres",
      "host": "localhost"
   }
}

YAML - 安全模式模式

YAML 模式定義為一組標籤的組合，幷包含一種解析非特定標籤的機制。YAML 中的安全模式模式以這樣一種方式建立，即它可以與任何 YAML 文件一起使用。它也被認為是通用 YAML 文件的推薦模式。

型別

安全模式模式有兩種型別：通用對映和通用序列

通用對映

它表示一個關聯容器。在這裡，每個鍵在關聯中都是唯一的，並且恰好對映到一個值。YAML 對鍵定義沒有任何限制。

表示通用對映的示例如下所示：

Clark : Evans
Ingy : döt Net
Oren : Ben-Kiki
Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

JSON 格式中通用對映結構的輸出如下所示：

{
   "Oren": "Ben-Kiki", 
   "Ingy": "d\u00f6t Net", 
   "Clark": "Evans", 
   "Flow style": {
      "Oren": "Ben-Kiki", 
      "Ingy": "d\u00f6t Net", 
      "Clark": "Evans"
   }
}

通用序列

它表示一種序列型別。它包含一個由從零開始的連續整數索引的集合。它用!!seq標籤表示。

Clark : Evans
Ingy : döt Net
Oren : Ben-Kiki
Flow style: !!seq { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

安全模式模式此通用序列的輸出

schema is shown below:
{
   "Oren": "Ben-Kiki", 
   "Ingy": "d\u00f6t Net", 
   "Clark": "Evans", 
   "Flow style": {
      "Oren": "Ben-Kiki", 
      "Ingy": "d\u00f6t Net", 
      "Clark": "Evans"
   }
}

YAML - JSON 模式

YAML 中的 JSON 模式被認為是大多數現代計算機語言的共同點。它允許解析 JSON 檔案。YAML 強烈建議在 JSON 模式上考慮其他模式。其主要原因是它包含使用者友好的鍵值組合。訊息可以編碼為鍵，並可以在需要時使用。

JSON 模式是標量，缺少值。JSON 模式中的對映條目以某種鍵值對的格式表示，其中 null 被視為有效。

示例

空 JSON 模式表示如下所示：

!!null null: value for null key
key with null value: !!null null

JSON 表示的輸出如下所示：

{
   "null": "value for null key", 
   "key with null value": null
}

示例

以下示例表示布林 JSON 模式：

YAML is a superset of JSON: !!bool true
Pluto is a planet: !!bool false

以下是 JSON 格式的相同輸出：

{
   "YAML is a superset of JSON": true, 
   "Pluto is a planet": false
}

示例

以下示例表示整數 JSON 模式：

negative: !!int -12
zero: !!int 0
positive: !!int 34

生成的整數 JSON 模式的輸出如下所示

{
   "positive": 34, 
   "zero": 0, 
   "negative": -12
}

示例

JSON 模式中的標籤用以下示例表示：

A null: null
Booleans: [ true, false ]
Integers: [ 0, -0, 3, -19 ]
Floats: [ 0., -0.0, 12e03, -2E+05 ]
Invalid: [ True, Null, 0o7, 0x3A, +12.3 ]

您可以找到如下所示的 JSON 輸出：

{
   "Integers": [
      0, 
      0, 
      3, 
      -19
   ], 
   
   "Booleans": [
      true, 
      false
   ], 
   "A null": null, 

   "Invalid": [
         true, 
         null, 
         "0o7", 
         58, 
         12.300000000000001
   ], 
   
   "Floats": [
      0.0, 
      -0.0, 
      "12e03", 
      "-2E+05"
   ]
}