YAML
![](http://upload.wikimedia.org/wikipedia/commons/9/92/Yaml_logo.png)
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.[1]
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[2] 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í
- 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
Reference
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/