QingZhi's Blog

Persistence is not easy

0%

YAML Simple Research

Posted on Views: Valine:

Source： official specification ， w3c

Definition

YAML is the abbreviation of “YAML Ain’t Markup Language” . Different from XML(eXtensible Markup Language) , YAML is a kind of data serialization language , not Markup Language.

  • Different from Markup Language and Data Serialization Language
    • Markup Language: Force on data layout
      • eg: XML , HTML
    • Data Serialization Language: Force on data content

AML was designed from the start to be useful and friendly to people working with data.

Importion points

  • It is case sensitive
  • file extension is .yaml
  • Tabs are not allowed

Two parts of YAML

  1. structural information
    • The advantage of YAML is the structural information compressed to the minimalism;
  2. data itself
    • can’t not be compressed

自我理解：任何形式的数据标识语言，YAML,XML,HTML,JSON等，都包含有这两部分：结构化信息与数据本身。像上面提到的数据标记语言与数据序列语言，就是对这两部分侧重不同，侧重与结构就是标记语言，侧重于内容就是序列语言。各种语言标识仅仅侧重点不同，一般都具备这两项功能，这也是理解XML,YAML,JSON等语言的切入点之一。

Language Goals

  1. YAML is easily readable by humans.
  2. YAML data is portable between programming languages.
  3. YAML matches the [native data structures](https://yaml.org/spec/1.2/spec.html#native data structure//) of agile languages.
  4. YAML has a consistent model to support generic tools.
  5. YAML supports one-pass processing.
  6. YAML is expressive and extensible.
  7. YAML is easy to implement and use.

Usage

  • Configuration files
  • Internet messaging
  • Object persistence
  • Data auditing.

Relation with JSON

YAML is the superSet of JSON , that means we can transfer ALL YAML file to JSON file ,Whereas no.

Data Structure in YAML

In YAML, data structures can be adequately represented with three basic primitives (consist with python):

  • mapping: hashes、dictionaries，etc
    • Mapping use a colon and space(“: “) to mark each “key: value “pair.
  • seqences: array、list , etc
    • sequences indicate each item with a dash and space(“- “)
  • scalars: string、number , etc
    • basic element
  • comments: begin with an octothorpe(also called a “hash”, “sharp”, “pound”, or “number sign” - [“**#**”](https://yaml.org/spec/1.2/spec.html## comment//)).
    • not support multline comment

Syntax

Collections Scope

There are two ways to represent the scope of collection:

1.indent

similar with python language, that the reason way YAML is minimalist data representation.

examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#  Sequence of Scalars
- Mark McGwire
- Sammy Sosa
- Ken Griffey
#  Mapping Scalars to Scalar
hr:  65    # Home runs
avg: 0.278 # Batting average
rbi: 147   # Runs Batted In
# Mapping Scalars to Sequences
american:
  - Boston Red Sox
  - Detroit Tigers
  - New York Yankees
national:
  - New York Mets
  - Chicago Cubs
  - Atlanta Braves
# Sequence of Mappings  
-
  name: Mark McGwire
  hr:   65
  avg:  0.278
-
  name: Sammy Sosa
  hr:   63
  avg:  0.288

2. flow style

using explicit indicators rather than indentation to denote scope.

example:

1
2
3
4
5
6
7
8
9
10
# The flow sequence is written as a comma separated list within square brackets.  
- [name        , hr, avg  ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa  , 63, 0.288]
#  flow mapping uses curly braces.
Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa: {
    hr: 63,
    avg: 0.288
  }

Structure

document start and end

  1. YAML use three dashes (“—“) to separate directives from document content :

    for example : two documents in a stream , each with a leading comment

1
2
3
4
5
6
7
8
9
10
# Ranking of 1998 home runs
---
- Mark McGwire
- Sammy Sosa
- Ken Griffey

# Team ranking
---
- Chicago Cubs
- St Louis Cardinals
  1. “—“ : start signal of document , “…” : end signal of document:
1
2
3
4
5
6
7
8
9
10
---
time: 20:03:20
player: Sammy Sosa
action: strike (miss)
...
---
time: 20:03:47
player: Sammy Sosa
action: grand slam
...

ref in YAML

Repeated nodes (objects) are first identified by an anchor (marked with the ampersand - [“**&**”](https://yaml.org/spec/1.2/spec.html#& anchor//)), and are then aliased (referenced with an asterisk - [“**\***”](https://yaml.org/spec/1.2/spec.html#* alias//)) thereafter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# Single Document with Two Comments
---
hr: # 1998 hr ranking
  - Mark McGwire
  - Sammy Sosa
rbi:
  # 1998 rbi ranking
  - Sammy Sosa
  - Ken Griffey
  
#  Node for “Sammy Sosa” appears twice in this document
---
hr:
  - Mark McGwire
  # Following node labeled SS
  - &SS Sammy Sosa
rbi:
  - *SS # Subsequent occurrence
  - Ken Griffey

complex mapping key

A question mark and space ([“**? **”](https://yaml.org/spec/1.2/spec.html#? mapping key//)) indicate a complex mapping key. Within a block collection, [key: value pairs](https://yaml.org/spec/1.2/spec.html#key: value pair//) can start immediately following the [dash](https://yaml.org/spec/1.2/spec.html#- block sequence entry//), [colon](https://yaml.org/spec/1.2/spec.html#: mapping value//), or [question mark](https://yaml.org/spec/1.2/spec.html#? mapping key//).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Mapping between Sequences
---
? - Detroit Tigers
  - Chicago cubs
:
  - 2001-07-23

? [ New York Yankees,
    Atlanta Braves ]
: [ 2001-07-02, 2001-08-12,
    2001-08-14 ]
# Compact Nested Mapping    
---
# Products purchased
- item    : Super Hoop
  quantity: 1
- item    : Basketball
  quantity: 4
- item    : Big Shoes
  quantity: 1

Scalar

scalar with block notation

More Details shown in this blog.

literial Style

using denotation(“|”) , all the line breaks are significant;

1
2
3
4
# In literial style , all the newlines are preserved
--- |
  \//||\/||
  // ||  ||__
folded Style

Alternatively , they can be written with the folded style (denoted with “>”),each line break is folded to a space unless it ends an empty or a more indented line.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#  In the folded scalars,  newlines become spaces
--- >
  Mark McGwire's
  year was crippled
  by a knee injury.
# Folded newlines are preserved for "more indented" and blank lines

Example 2.14.  In the folded scalars,
newlines become spaces

--- >
  Mark McGwire's
  year was crippled
  by a knee injury.

Example 2.15.  Folded newlines are preserved
for "more indented" and blank lines

--- >
 Sammy Sosa completed another
 fine season with great stats.

   63 Home Runs
   0.288 Batting Average

 What a year!

flow scalars

There are three ways to express flow scalars:
1.Plain text 2. Double-quoted 3.Single Quoted
Features: All flow scalars can span multiple lines; [line breaks](https://yaml.org/spec/1.2/spec.html#line break//) are always [folded](https://yaml.org/spec/1.2/spec.html#line folding//).

Plain Text
1
2
3
4
5
6
7
8
9
10
11
12
# Multi-line Flow Scalars
plain:
  This unquoted scalar
  spans many lines.

quoted: "So does this
  quoted scalar.\n"
  
# Aboved is the same as , from my understanding 
plain:   This unquoted scalar spans many lines.

quoted: "So does this quoted scalar.\n"
Quoted Scalars

The double-quoted style provides [escape sequences](https://yaml.org/spec/1.2/spec.html#escaping/in double-quoted scalars/). The single-quoted style is useful when [escaping](https://yaml.org/spec/1.2/spec.html#escaping/in double-quoted scalars/) is not needed.

双引号用于强制类型转换？？

For examples:

1
2
3
4
5
6
7
8
# Quoted Scalars
unicode: "Sosa did fine.\u263A"
control: "\b1998\t1999\t2000\n"
hex esc: "\x0d\x0a is \r\n"

single: '"Howdy!" he cried.'
quoted: ' # Not a ''comment''.'
tie-fighter: '|\-*-/|'

Tags

In YAML, untagged nodes are given a type depending on the application. The examples in this specification generally use the seq, map and str types from the fail safe schema. A few examples also use the int, float, and null types from the JSON schema. The repository includes additional types such as binary, omap, set and others.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# integers
canonical: 12345
decimal: +12345
octal: 0o14
hexadecimal: 0xC

# Floating points
canonical: 1.23015e+3
exponential: 12.3015e+02
fixed: 1230.15
negative infinity: -.inf
not a number: .NaN

# Miscellaneous
null:
booleans: [ true, false ]
string: '012345'

# Timestamps
canonical: 2001-12-15T02:59:43.1Z
iso8601: 2001-12-14t21:59:43.10-05:00
spaced: 2001-12-14 21:59:43.10 -5
date: 2002-12-14

Explicit typing is denoted with a tag using the exclamation point ([“**!**”](https://yaml.org/spec/1.2/spec.html#! tag indicator//)) symbol. Global tags are URIs and may be specified in a tag shorthand notation using a handle. Application-specific local tags may also be used.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
#  Various Explicit Tags
---
not-date: !!str 2002-04-28

picture: !!binary |
 R0lGODlhDAAMAIQAAP//9/X
 17unp5WZmZgAAAOfn515eXv
 Pz7Y6OjuDg4J+fn5OTk6enp
 56enmleECcgggoBADs=

application specific tag: !something |
 The semantics of the tag
 above may be different for
 different documents.
# Glbal tags

%TAG ! tag:clarkevans.com,2002:
--- !shape
  # Use the ! handle for presenting
  # tag:clarkevans.com,2002:circle
- !circle
  center: &ORIGIN {x: 73, y: 129}
  radius: 7
- !line
  start: *ORIGIN
  finish: { x: 89, y: 102 }
- !label
  start: *ORIGIN
  color: 0xFFEEBB
  text: Pretty vector drawing.

# Unordered Sets
# Sets are represented as a
# Mapping where each key is
# associated with a null value
--- !!set
? Mark McGwire
? Sammy Sosa
? Ken Griff

# Ordered Mappings
# Ordered maps are represented as
# A sequence of mappings, with
# each mapping having one key
--- !!omap
- Mark McGwire: 65
- Sammy Sosa: 63
- Ken Griffy: 58