YAML

YAML Ain't Markup Language (zkráceně YAML /jæml/) je formát pro serializaci strukturovaných dat.

Mezi rysy tohoto formátu patří:

• čitelnost nejen strojem, ale i člověkem
• struktura a hierarchie dat je řešena odsazením
• odsazení o jednu úroveň sestává ze 2 nebo 4 mezer; tabulátory nejsou povoleny.
• neomezené úrovně vnořování

3. vydání specifikace formátu, verze 1.2, vyšla 1. října 2009.

Primitiva

Literály

Řetězce

• mohou být uvedeny znakem dvojitých i jednoduchých uvozovek (na rozdíl od JSONu), s tím, že musejí končit stejným znakem
• uvozovka v uvozovce se eskapuje zdvojením
• kontrolní znaky se escapují zpětným lomítkem
• jsou povoleny některé diakritické znaky
• znaky mimo základní ASCII lze zapsat pomocí hexadecimálního kódu znaku, uvedeného za \x (8bitového), \u (16bitového) nebo \U (32bitového)
• uvozovky musejí být nezbytně uvedeny například v těchto případech:
  • končí-li mezerou nebo jiným bílým znakem (a ten má být zahrnut)
  • obsahují-li řídicí znaky
  • obsahují-li čárku v poli v in-line notaci (viz dále)
  • začínají-li speciálním znakem (!, #, &, *, ", ', [, {, |, >, \)
  • víceřádkový text

string: 'Wendy''s'
unicode: "Sosa did fine.\u263A"
control: "\b1998\t1999\t2000\n"
hex esc: "\x0d\x0a is \r\n"

Víceřádkový řetězec:

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

Čísla

• v základním (kanonickém) tvaru je možné volitelné unární znaménko (záporné i kladné)
• „0o“ uvádí oktální zadání (osmičkové soustavě)
• „0x“ uvádí hexadecimální zadání (šestnáctkové soustavě)
• je povolený semilogaritmický (vědecký) zápis s mantisou a exponentem
• na rozdíl od JSONu je možné uvést nekonečno (kladné i záporné) a NaN
• číslo, za kterým následuje text, který není poznámka, bude (na rozdíl od některých jazyků) převeden na řetězec

canonical: 12345
decimal: +12345
octal: 0o14 
hexadecimal: 0xC
exponential: 12.3015e+02
fixed: 1230.15
negative infinity: -.inf 
not a number: .NaN
fraction: .5

Časové hodnoty

Tzv. časové značky (timestamps) se zadávají ve tvaru RRRR-MM-DD, následovaném volitelným uvedením času, které odděluje buď mezera nebo (velké či malé) písmeno T a čas ve tvaru HH:MM:SS. Za časem může být volitelně uvedeno časové pásmo buď jako celé číslo nebo ve formátu [+/-]HH:MM.

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

Logické hodnoty

YAML podporuje booleovské hodnoty false a true

 - false
 - False
 - true
 - TRUE

NULL

YAML podporuje hodnotu NULL, která může být zadána explicitně (null) nebo s použitím tildy ~ nebo může (na místech, kde se očekává hodnota, jako např. prvek sekvence, viz dále) být vynechána.

 - Null
 - null
 -
 - NULL
 - ~

Poznámky

 # toto je poznámka
 # vše až do konce řádky je ignorováno
 # poznámky mohou začínat na libovolném místě
- 1 # poznámky mohou být vkládány i do řádků s hodnotami,
 # ... pak však musí být před # mezera
- CSharp se označuje jako C#

Víceřádkové poznámky (blokové komentáře) nejsou podporovány.

Sekvence

Odpovídá neasociativnímu poli.

 - Banány
 - Pomeranče
 - Mandarinky

• převede se jako pole s číselnými indexy číslovanými od nuly
• začne-li definice sekvence, nelze jako další prvek zadat dvojici klíč:hodnota

Mapa

Odpovídá asociativnímu poli (ukládá dvojic klíč:hodnota, běžně se označuje termínem hash).

Božena Němcová: Babička
Ernest Hemingway: Stařec a moře
Douglas Addams: Stopařův průvodce po Galaxii
1984: 1984

• u posledního prvku bude index uložený jako řetězec a hodnota prvku bude uložena jako číslo.
• chování při uvedení stejného indexu pole podruhé se liší podle konkrétní implementace; např. podle on-line konvertoru do JSONu nedojde k chybě a zůstane hodnota u prvního výskytu.

Dokument

--- # Seznam knih
Autor: Božena Němcová
Kniha: Babička
---
Autor: Ernest Hemingway
Kniha: Stařec a moře
...

Sekvence „---“ značí začátek dokumentu, „...“ konec dokumentu nebo datového proudu.

Víceřádkový text

Se zalomením řádků

data: |
   There once was a short man from Ealing
   Who got on a bus to Darjeeling
       It said on the door
       "Please don't spit on the floor"
   So he carefully spat on the ceiling

• Úvodní mezery (dané odsazením) budou vynechány.
• Uvedením "|-" bude oříznuto poslední odřádkování.

Bez zalomení řádků

specialDelivery: >
    Follow the Yellow Brick
    Road to the Emerald City.
    Pay no attention to the
    man behind the curtain.

• Nové řádky budou zaměněny za mezery, úvodní mezery budou vynechány.
• Uvedením ">+" bude za řetězec přidáno odřádkování.

Složená data

Data je možné libovolně vnořovat. Úroveň zanoření je určena a označena odsazením textu od levého okraje:

Zadaná strukturovaně

adresa:
    ulice: U mlýna
    "č. p.": 15         # ve verzi 1.2 nemusí být v uvozovkách
    město: Bílé Bělidlo

knihy:
    - autor: Božena Němcová 
      název: Babička
    - autor: Ernest Hemingway
      název: Stařec a moře

Odkazování dovnitř struktur v YAMLu může být (v závislosti na cílovém jazyku) např.: adresa.ulice nebo adresa["č. p."].

Zadaná in-line

YAML podporuje také zadání více dat v jednom řádku (in-line). Jako např. v JavaScriptu, jsou asociativní pole uvedena ve složených závorkách. Jako znak, oddělující klíč a hodnotou, je dvojtečka, samotné dvojice se oddělují čárkou.

Asociované pole

- {name: John Smith, age: 33}

to samé jako:

- name: John Smith
  age: 33

Neasociované pole

Neasociativní pole (seznamy) se v jednom řádku uvádějí v hranatých závorkách.

[John Smith, Bill Jones]

Další možnosti

Odkazování

bill-to: &id001 # definuje identifikátor id001
    street: |
            123 Tornado Alley
            Suite 16
    city:   East Centerville
    state:  KS

ship-to: *id001 # reference na id001
    state: Kansas   # pozměňuje položku
    country: USA    # doplňuje novou položku

Přetypování

---
a: 123 # celé číslo
b: "123" # řetězec, vynuceno uvozovkami
c: 123.0 # číslo s plovoucí desetinnou čárkou
d: !!float 123 # ditto, přetypování vynuceno klíčovým slovem
e: !!str 123 # přetypování pro řetězec, jako b)
g: Yes # boolean
f: No # boolean
h: !!str Yes # řetězec, přetypování vynuceno klíčovým slovem
i: Yes we have No bananas # řetězec
j: !!bool No # boolean
--- # binární data (base64)
picture: !!binary |
  R0lGODlhDAAMAIQAAP//9/X
  17unp5WZmZgAAAOfn515eXv
  Pz7Y6OjuDg4J+fn5OTk6enp
  56enmleECcgggoBADs=mZmE

Hlavička

Níže uvedený řádek (direktiva) dovoluje uvést verzi formátu obsahu, který za ním následuje.

%YAML 1.2

Ostatní

Bílé znaky

• tabulátory nejsou povoleny pro odsazování
• mezery před hodnotami (resp. jejich dvojnásobek nebo čtyřnásobek) určuje úroveň zanoření
• mezery za hodnotami (včetně řetězců) jsou ignorovány
• řádek s bílým místem, na němž není uvedena žádná hodnota, je ignorován (neplatí pro neuvedené prvky pole, které se převedou na NULL)

Překlady

Některé skriptovací jazyky nebo frameworky (např. Symfony) využívají soubory YAML mj. jako tabulku překladů. Do nich pak mohou vkládat „placeholdery“, které slouží jako místa pro doplnění proměnných. Příklad:

messages:
    forFree: Nic neplatíš!
    payPrice: Zaplatíš %price% Kč.

Použití těchto textů ve Twigu:

{% trans %}messages.pay{% trans %}<br>
{% trans with({'%price%': 99}) %}messages.payPrice{% trans %}

Odkazy

Související články

konkurenční formáty

• JSON
• XML
• Extensible Data Notation
• NEON

Externí odkazy

• https://www.yamlonline.com/
• http://www.yaml.org/
• https://yamlonline.com/
• http://zdrojak.root.cz/clanky/yaml-serializacni-format-pro-ukladani-dat/