YAML

Z Wikipedie, otevřené encyklopedie
Skočit na navigaci Skočit na vyhledávání

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 indentací (předsazením)
  • předsazení o jednu úroveň sestává ze 2 nebo 4 mezer; tabulátory nejsou povoleny.
  • neomezené úrovně vnořování

3. edice specifikace formátu, verze 1.2, vyšla 1. října 2009.[1]

Primitiva[editovat | editovat zdroj]

Literály[editovat | editovat zdroj]

Ř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 kontrolní 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" na začátku uvádí zadání v okálním tvaru (osmičkové soustavě)
  • "0x" uvádí hexadecimální zadání
  • je povolený semilogaritmický (vědecký) zápis s mantisou a exponentem
  • na rozdíl od JSONu je možné uvést (kladné i záporné) nekonečno 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é otisky (timestamps) se zadávají ve tvaru RRRR-MM-DD, následovaný 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ě uveden časový posun 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[editovat | editovat zdroj]

 # 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
 # víceřádkové poznámky nejsou podporovány

Sekvence[editovat | editovat zdroj]

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[editovat | editovat zdroj]

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[2] nedojde k chybě a zůstane hodnota u prvního výskytu.

Dokument[editovat | editovat zdroj]

 --- # 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[editovat | editovat zdroj]

Se zachováním nových řá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.
  • S uvedením "|-" bude oříznuto poslední odřádkování.
S vynecháním nových řá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.
  • S uvedením ">+" bude za řetězec přidáno odřádkování.

Složená data[editovat | editovat zdroj]

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ě[editovat | editovat zdroj]

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[editovat | editovat zdroj]

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 se v jednom řádku zadávají ve složených závorkách. Řetězcové literály .

[John Smith, Bill Jones]

to samé jako:

{0: John Smith, 1: Bill Jones}

Další možnosti[editovat | editovat zdroj]

Odkazování[editovat | editovat zdroj]

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í[editovat | editovat zdroj]

---
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[editovat | editovat zdroj]

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

%YAML 1.2

Ostatní[editovat | editovat zdroj]

Bílé místo
  • 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[editovat | editovat zdroj]

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[editovat | editovat zdroj]

Reference[editovat | editovat zdroj]

  1. https://yaml.org/spec/1.2/spec.html
  2. https://codebeautify.org/yaml-to-json-xml-csv

Související odkazy[editovat | editovat zdroj]

konkurenční formáty

Externí odkazy[editovat | editovat zdroj]