yaml_notes.md

YAML Notes ( 1.2 )

Links and resources

• Spec 1.2 @ http://yaml.org/spec/1.2/spec.html

Overview

• Human readable
• Machine processable
• Minimum structural elements

Basic Primitives

• Scalars (Strings/Numbers)
• Sequences (Arrays/Lists)
• Mappings (hashes/dicts)

Typing System

• Simple system
• Based on primitives
• Aliasing System

Use cases

• Config files
• Log files
• Interprocess messaging
• Cross language data sharing
• Object Persistence
• Debugging

YAML vs JSON

• JSON easier to parse / generate ; difficult to read
• YAML easier to read ; not so easy as json for parsing/generating

General Notes

• Complies to JSON Spec
• YAML is primarily a data serialization language
• Mappings use : for key value separation
• Block collections use indentation for scoping
• '---' is used as directives
• Document separator directive is ( multiple docs in same stream ) is '---'
• '...' end of document without starting new one
• '---' start of document
• Anchor is created using '&' and refered using '*'

YAML Schema and Tags

• tags are used to denote application specific type processing
• yaml schema is a combination of set of tags and a mechanism for resolving non specific tags
• Failsafe schema
  • guaranteed to work in any yaml document

Examples using yamerl

Sequence of scalars

application:start(yamerl). 
f().
String = "
- Mark Angel\n
- Emmauela\n
- Denilson\n
\n
- Apple\n
- Orange\n
- Grapes\n
". 
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

Mapping : Scalars to sequence

application:start(yamerl). 
f().
String = "
fruits:\n
  - Orange\n
  - Apple\n
vegs:\n
  - carrot\n
  - brinjal\n
" .
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

Sequence of mappings

application:start(yamerl). 
f().

String = "
-\n
  name: Mark McGwire \n
  hr:   65 \n
  avg:  0.278 \n
-\n
  name: Sammy Sosa \n
  hr:   63 \n
  avg:  0.288 \n 
".
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

Sequence of sequence using explicit indicators

• Here indentation is not used; instead explicit indicators are used

application:start(yamerl). 
f().

String = "
- [name        , hr, avg  ] \n
- [Mark McGwire, 65, 0.278] \n
- [Sammy Sosa  , 63, 0.288] \n
".
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

Mapping of mappings using explicit indicator

application:start(yamerl). 
f().

String = "
Mark McGwire: {hr: 65, avg: 0.278}\n
Sammy Sosa: {\n
    hr: 63,\n
    avg: 0.288\n
  }\n
".
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

Two docs in a stream

# Ranking of 1998 home runs
---
- Mark McGwire
- Sammy Sosa
- Ken Griffey

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

Two docs in a stream example 2

---
time: 20:03:20
player: Sammy Sosa
action: strike (miss)
...
---
time: 20:03:47
player: Sammy Sosa
action: grand slam
...

Documents with comments

---
hr: # 1998 hr ranking
  - Mark McGwire
  - Sammy Sosa
rbi:
  # 1998 rbi ranking
  - Sammy Sosa
  - Ken Griffey

Anchor and Alias

---
hr:
  - Mark McGwire
  # Following node labeled SS
  - &SS Sammy Sosa
rbi:
  - *SS # Subsequent occurrence
  - Ken Griffey

Complex value as key / 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

application:start(yamerl). 
f().

String = "
---\n
# Products purchased\n
- item    : Super Hoop\n
  quantity: 1\n
- item    : Basketball\n
  quantity: 4\n
- item    : Big Shoes\n
  quantity: 1\n
".
io:format("~n~s~n",[String]).
yamerl_constr:string(String). 

• Output

[ % documents
 [ % document 
  [{"item","Super Hoop"},{"quantity",1}], % seq 1 
  [{"item","Basketball"},{"quantity",4}],
  [{"item","Big Shoes"},{"quantity",1}]
 ]
]

Scalars in literal style block notation

• using '|'
• line breaks are preserved

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

Scalars in folded style block notation

• using '>'
• line breaks are converted to space except if starting in more indeted form

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

Folded newlines being preserved due to indentation

>
 Sammy Sosa completed another
 fine season with great stats.

   63 Home Runs
   0.288 Batting Average

 What a year!

Indentation determines scope

name: Mark McGwire
accomplishment: >
  Mark set a major league
  home run record in 1998.
stats: |
  65 Home Runs
  0.278 Batting Average

Single and Double Quotes

• Double quotes allow escapes
• Single quote allow only ' as escape for escaping single quote

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: '|\-*-/|'

Multiline flow scalars

plain:
  This unquoted scalar
  spans many lines.

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

Integers

canonical: 12345
decimal: +12345
octal: 0o14
hexadecimal: 0xC

Floating Point

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

Boolean, Null, Strings

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 Tagging

---
not-date: !!str 2002-04-28

picture: !!binary |
 R0lGODlhDAAMAIQAAP//9/X
 17unp5WZmZgAAAOfn515eXv
 Pz7Y6OjuDg4J+fn5OTk6enp---
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.
 56enmleECcgggoBADs=

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

Global 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 repr as mapping
• key is mapped to null

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

Code for following examples

f(). 
Docs = yamerl_constr:file("priv/sample.yml").
[ Doc |_ ] = Docs.
Doc. 

Example / Primitive-Scalar

tasks 

• Output

"tasks" 

Example / Prmitive-List or seqeunce

- task1

["task1"]

Example / Primitive-Map

task1 : val1

[{"task1","val1"}]

Example / map having value as list of maps

exp_mp : 
   - 
    pat : a
    
   -
    pat : b 

[{"exp_mp",[ [{"pat","a"}], [{"pat","b"}] ] }]

Example

task1
task2
task3

"task1 task2 task3" 

Example / Prmitive-List or seqeunce

- task1

["task1"]

Example

-task1

"-task1" 

Example

- task1
- task2
- task3

["task1", "task2", "task3"]

Example

task1 : val1

[{"task1","val1"}]

Example

- task1 : val1

[[{"task1","val1"}]]

Example

- task1 : val1
- task2 : val2
- task3 : val3

[[{"task1","val1"}],[{"task2","val2"}],[{"task3","val3"}]]

Example

tasks :
 - one 
 - two 

[{"tasks",["one","two"]}]

Example

tasks :
 - one : o
 - two : t

[{"tasks",[[{"one","o"}],[{"two","t"}]]}]