YAML: Адамға оқуға қолайлы дерек форматы

Кіріспе

CSS framework Адам оқитын деректерді серияландыру форматы YAML (/'//j//æ//m//ə//l/; қараңыз) — адам оқитын деректерді серияландыру тілі. Ол конфигурациялық файлдар үшін және деректерді сақтау немесе жіберу үшін жиі қолданылады. YAML кеңейтілген таңбалау тілі (XML) сияқты көптеген байланыс салаларында қолданылады, бірақ оның минималды синтаксисі стандартты жалпыланған таңбалау тілінен (SGML) әдейі өзгешеленеді және көптеген жол мәндерін тырнақшаға алуды қажет етпейді (сонымен қатар JSON стилін де қолдайды және бір файлда араластырылуы мүмкін). Арнайы дерек түрлеріне рұқсат етіледі, бірақ YAML скалярларды (мысалы, жолдар, бүтін сандар және қалқымалы сандар), тізімдер мен ассоциативтік массивтерді (карталар, сөздіктер немесе хэштер деп те аталады) енгізеді. Бұл дерек түрлері Perl бағдарламалау тіліне негізделген, бірақ барлық кең таралған жоғары деңгейдегі бағдарламалау тілдері ұқсас ұғымдарды бөліседі. Кілт-мәнді жұптарды көрсету үшін қолданылатын екі нүктеге ортақталған синтаксис электрондық пошта хаттарынан (RFC 5322) шабыттандырылған, ал құжаттарды бөлу белгісі MIME-ден алынған. C тілінен қашып кету тізбектері қайта қолданылады, ал көпжолды жолдар үшін кеңістіктерді пайдалану HTML-ден алынған. Тізімдер мен хэштерде ұялатылған тізімдер мен хэштер болуы мүмкін, бұл ағаш тәрізді құрылымды құрайды; кез келген графтар YAML псевдонимдерін (SOAP-тағы XML сияқты) пайдалана отырып бейнеленуі мүмкін. Vim, Emacs және әртүрлі интеграцияланған даму орталары сияқты кейбір код редакторлары YAML-ді өңдеуді жеңілдететін мүмкіндіктерге ие, мысалы, ұялатылған құрылымдарды жинақтау немесе синтаксистік қателерді автоматты түрде көрсету. YAML файлдары үшін ресми ұсынылған файл кеңейтімі 2006 жылдан бері қолданылып келеді. 2024 жылы MIME түрі аяқталды. Оны Ингі Дот Нет және Орен Бен Кики бірге жасады, өйткені ол презентация және байланыс үшін таңбалау тілдерінің (HTML, XML, SGML және т.б.) өркендеген кезеңінде жарық көрді. Оның бастапқы атауы технологиялық кеңістікке иронизациялық сілтеме ретінде қарастырылды, оның мақсаты тағы бір құрылымдық элементі бар таңбалау тілі ретінде болды, бірақ кейіннен деректерге бағытталған екенін көрсету үшін рекурсивті аббревиатура YAML Ain't Markup Language ретінде қайта аталды, құжатты таңбалаудан ерекшеленді.

the CSS framework
Human readable data serialization format

YAML (/'//j//æ//m//ə//l/; see ) is a human readable data serialization language. It is commonly used for configuration files and in applications where data are being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML) but has a minimal syntax that intentionally differs from Standard Generalized Markup Language (SGML). and does not require quotes around most string values (it also supports JSON style and mixed in the same file). Custom data types are allowed, but YAML natively encodes scalars (such as strings, integers, and floats), lists, and associative arrays (also known as maps, dictionaries or hashes). These data types are based on the Perl programming language, though all commonly used high level programming languages share very similar concepts. The colon centered syntax, used for expressing key value pairs, is inspired by electronic mail headers as defined in , and the document separator is borrowed from MIME Escape sequences are reused from C, and whitespace wrapping for multi line strings is inspired by HTML. Lists and hashes can contain nested lists and hashes, forming a tree structure; arbitrary graphs can be represented using YAML aliases (similar to XML in SOAP). Some source code editors such as Vim, Emacs, and various integrated development environments have features that make editing YAML easier, such as folding up nested structures or automatically highlighting syntax errors. The official recommended filename extension for YAML files has been since 2006. In 2024, the MIME type has been finalized. who designed it together with Ingy döt Net and Oren Ben Kiki. because it was released in an era that saw a proliferation of markup languages for presentation and connectivity (HTML, XML, SGML, etc). Its initial name was intended as a tongue in cheek reference to the technology landscape, referencing its purpose as a markup language with the yet another construct, but it was then repurposed as YAML Ain't Markup Language, a recursive acronym, to distinguish its purpose as data oriented, rather than document markup.

Нұсқалар

Версиясы Шығарылған күні YAML 1.0 YAML 1.1 YAML 1.2.0 YAML 1.2.1 YAML 1.2.2

Синтаксисі

Шындық парағы мен толық сипаттама ресми сайтта қолжетімді. Келесіде негізгі элементтердің қысқаша мазмұны келтірілген. YAML кейбір басқару таңбаларын қоспағанда, барлық Unicode таңбалар жиынтығын қабылдайды және UTF-8, UTF-16 немесе UTF-32 кодталуы мүмкін. (UTF-32 міндетті болмаса да, JSON үйлесімділігін қамтамасыз ету үшін анализатор үшін қажет.) Құрылымды көрсету үшін бос орынмен кірігу қолданылады; алайда, табуляция таңбалары осы кірігудің бөлігі ретінде рұқсат етілмейді. Түсіндірмелер сан белгісімен (#) басталады, жолдың кез келген жерінен басталып, жолдың соңына дейін жалғасуы мүмкін. Түсіндірмелер басқа токендерден бос орынмен бөлінуі керек. Егер # таңбалары жолдың ішінде пайда болса, олар сан белгісінің әдебиеттік белгісі болып есептеледі. Тізім элементтері жолдың басында тұрған тире (-) арқылы белгіленеді, әр элемент жеке жолда орналасады. Тізімді квадрат жақшалар ([ ]) ішінде мәтінді жазып, әр элементті үтірмен бөліп көрсетуге болады. Ассоциативтік массив элементтері кілт: мән түрінде, әр элемент жеке жолда көрсетіледі. YAML кілт пен мән арасында бос орын болуын талап етеді, соның арқасында URL сияқты жолдарды тырнақшаларға алудың қажеті жоқ. Кілттің алдына сұрақ белгісі (?key: value) қою арқылы кілттің басында тире, квадрат жақшалар және т.б. болуына рұқсат етуге болады. Ассоциативтік массивті фигуралық жақшалар ({ }) ішінде де көрсетуге болады, кілттер мен мәндер екі нүкте (:) арқылы бөлінеді, ал элементтер үтірмен бөлінеді (JSON үйлесімділігін сақтау үшін бос орындар міндетті емес). Жолдар (YAML-дегі скалярдың бір түрі) әдетте тырнақшаларсыз жазылады, бірақ қос тырнақшалар (" ") немесе бір тырнақшалар (' ') ішінде көрсетілуі мүмкін. Қос тырнақшалар ішінде арнайы таңбалар C стиліндегі кері қисық сызықпен (\) басталатын қашқын тізбектерімен көрсетілуі мүмкін. Құжаттамаға сәйкес, тек сегіздік қашқын тізбегі қолдау көрсетіледі. Бір ағындағы бірнеше құжат үш тире (---) арқылы бөлінеді. Қайталамалы түйіндер бастапқыда амперсанд (&) арқылы белгіленеді, содан кейін жұлдызша (*) арқылы сілтемеленеді. Түйіндер екі нүктемен (!) басталатын тип немесе таңбамен белгіленуі мүмкін, содан кейін URI ретінде кеңейтілуі мүмкін тізбек келеді. Ағындағы YAML құжаттарының алдында пайыз белгісінен (%) басталатын «директивалар» болуы мүмкін, содан кейін атауы және кеңістікпен бөлінген параметрлері келеді. YAML 1.1 нұсқасында екі директива анықталған: %YAML директивасы берілген құжаттағы YAML нұсқасын анықтау үшін қолданылады. %TAG директивасы URI префикстерінің қысқаша жолы ретінде қолданылады. Бұл қысқартпаларды түйіннің типін белгілейтін таңбаларда пайдалануға болады.

A cheat sheet and full specification are available at the official site. The following is a synopsis of the basic elements. YAML accepts the entire Unicode character set, except for some control characters, and may be encoded in any one of UTF 8, UTF 16 or UTF 32. (Though UTF 32 is not mandatory, it is required for a parser to have JSON compatibility.) Whitespace indentation is used for denoting structure; however, tab characters are not allowed as part of that indentation. Comments begin with the number sign , can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by whitespace characters. If # characters appear inside of a string, then they are number sign literals. List members are denoted by a leading hyphen with one member per line. A list can also be specified by enclosing text in square brackets with each entry separated by a comma. An associative array entry is represented using colon space in the form key: value with one entry per line. YAML requires the colon be followed by a space so that url style strings like can be represented without needing to be enclosed in quotes. A question mark can be used in front of a key, in the form "?key: value" to allow the key to contain leading dashes, square brackets, etc., without quotes. An associative array can also be specified by text enclosed in curly braces , with keys separated from values by colon and the entries separated by commas (spaces are not required to retain compatibility with JSON). Strings (one type of scalar in YAML) are ordinarily unquoted, but may be enclosed in double quotes , or single quotes Within double quotes, special characters may be represented with C style escape sequences starting with a backslash According to the documentation the only octal escape supported is Within single quotes the only supported escape sequence is a doubled single quote denoting the single quote itself as in Block scalars are delimited with indentation with optional modifiers to preserve (|) or fold newlines. Multiple documents within a single stream are separated by three hyphens Three periods optionally end a document within a stream. Repeated nodes are initially denoted by an ampersand and thereafter referenced with an asterisk Nodes may be labeled with a type or tag using a double exclamation mark followed by a string, which can be expanded into a URI. YAML documents in a stream may be preceded by 'directives' composed of a percent sign followed by a name and space delimited parameters. Two directives are defined in YAML 1.1:
The %YAML directive is used for identifying the version of YAML in a given document. The %TAG directive is used as a shortcut for URI prefixes. These shortcuts may then be used in node type tags.

Жоғары сапалы компоненттер

YAML-ді басқа деректерді тізбектеу тілдерінен ерекшелендіретін екі негізгі қасиет – құрылымдар мен деректердің түрлері. YAML құрылымдары бір файлдың ішінде бірнеше құжатты сақтауға, қайталама түйіндерге сілтемелер жасауға және кез келген түйінді кілт ретінде пайдалануға мүмкіндік береді. YAML талдағышы осы сілтемелерді оқығанда толыққанды дерек құрылымдарына айналдырады, сондықтан деректерді пайдаланатын бағдарлама реляциялық кодтау моделін білуі қажет емес – бұл XML процессорларынан өзгеше, олар сілтемелерді кеңейтпейді. Бұл кеңейту конфигурациялық файлдарда немесе өңдеу протоколдарындағы деректерді енгізу қателіктерін азайту арқылы оқуға ыңғайлылықты арттырады, мұнда тізбектелген жазбалар сериясында көптеген параметрлер бірдей болып қалады, ал тек бірнешеуі ғана өзгереді. Мысалы, шот-фактурадағы "тапсыру адресі" және "есеп-фактура адресі" жазбалары көбінесе бірдей деректерді қамтиды.

Іс жүзіндегі ескертулер

YAML жолға бағытталғандықтан, қазіргі бағдарламалардың құрылымдалмаған нәтижесін YAML форматына аудару оңай, сонымен бірге бастапқы құжаттың көрінісін сақтап қалуға болады. Жабылу тегтері, жақшалар немесе дәйексөздерді теңестірудің қажеті болмағандықтан, күрделі емес бағдарламаларда тікелей бөлінген басып шығару операторлары арқылы жақсы құрылған YAML жасау оңай. Сондай-ақ, бос орынды белгілеуіштер grep, AWK, Perl, Ruby және Python-дағы жолға бағытталған командаларды пайдаланып YAML файлдарын жылдам сүзгілеуге мүмкіндік береді. Әсіресе, белгілеу тілдерінен айырмашылығы, бір-бірінен кейін келетін YAML жолдарының бөліктері өздері жақсы құрылған YAML құжаттары болып табылады. Бұл құжатты толығымен өңдеуге (мысалы, ашылу және жабылу тегтерін теңестіру және дәйексөздермен қоршалған және қашқан символдарды бағыттау) қажеттілігінсіз, нақты жазбаларды іздеуді бастамас бұрын талдаушыларды жасауды жеңілдетеді. Бұл мүмкіндік, әсіресе, бір реттік, күйсіз өту кезінде, жадта сақтауға тым үлкен файлдардағы жазбаларды қарау кезінде немесе бір элементті алу үшін бүкіл құрылымды қайта құрудың өте қымбат болатын жағдайларда тиімді. Керісінше, кіріктірілген шектеулері терең ұяланған иерархияларды қиындататын сияқты болса да, YAML бір ғана бос орын сияқты кішкентай кіріктірулерді қолдайды, бұл белгілеу тілдеріне қарағанда жақсы қысылуға қол жеткізе алады. Сонымен қатар, өте терең кіріктіруді толығымен болдырмауға болады: 1) кіріктірусіз "жолға орналасқан стильге" (яғни JSON сияқты форматқа) көшу; немесе 2) реляциялық сілтемелерді пайдаланып, иерархияны YAML талдаушысы толық дерек құрылымына түсінікті түрде қайта құрайтын тегіс формаға келтіру.

Қауіпсіздік

YAML – деректерді бейнелеу тілі ғана, сондықтан орындалатын командалары жоқ. Кез келген дерек тілінде тексеру және қауіпсіз талдау мүмкін болғанымен, іске асыру осыншалықты қауіпті тұзаққа толы, YAML-дің байланысты командалық тілінің болмауы салыстырмалы түрде қауіпсіздік артықшылығын бере алады. Дегенмен, YAML тілге қатысты белгілерді қолдануға мүмкіндік береді, осылайша сол белгілерді қолдайтын талдаушы кез келген жергілікті объектіні құра алады. Күрделі объектілерді құруға рұқсат беретін кез келген YAML талдаушысы инъекциялық шабуылға жағдай жасайды. Кез келген кластағы объектілерді жүктеуге мүмкіндік беретін Perl талдаушылары «белгіленген» мәндерді жасайды. Бұл мәндерді пайдалану күтпеген әрекеттерге алып келуі мүмкін, мысалы, егер класс жүктемелі операторларды қолданса. Бұл кез келген Perl кодын орындауға әкелуі мүмкін. Python немесе Ruby талдаушылары үшін жағдай да осыған ұқсас. PyYAML құжаттамасында айтылғандай:

Егер сіз Интернеттен келгендей сенімсіз көзден YAML құжатын алсаңыз, кез келген Python объектісін құру мүмкіндігі қауіпті болуы мүмкін. Функция бұл мүмкіндікті жай ғана Python нысандарымен, мысалы, бүтін сандармен немесе тізімдермен шектейді. [ ] PyYAML кез келген Python нысанын құруға мүмкіндік береді. Тіпті Python кластарының инстанцияларын да белгіні пайдалану арқылы құруға болады.

Деректерді өңдеу және бейнелеу

YAML спецификациясы инстанция құжатын "Presentation" немесе "character stream" деп анықтайды. YAML инстанциялық құжатындағы негізгі логикалық құрылымдар – скалярлар, тізімдер және сәйкестендірулер. YAML спецификациясы сондай-ақ осы негізгі логикалық құрылымдарға қатысты негізгі шектеулерді көрсетеді. Мысалы, спецификацияға сәйкес, сәйкестендіру кілттерінің реті белгіленбеген. Түйіндердің реті маңызды болатын жағдайларда міндетті түрде тізім қолданылуы керек. Сонымен қатар, YAML процессорларының сәйкестігін анықтауда YAML спецификациясы екі негізгі операцияны анықтайды: құю және жүктеу. Барлық YAML талаптарына сәйкес процессорлар осы операциялардың кем дегенде біреуін ұсынуы керек, ал екеуін де ұсынуы мүмкін. Соңында, YAML спецификациясы ақпараттық модельді немесе "өкілдік графигін" анықтайды, ол құю және жүктеу операциялары үшін өңдеу кезінде құрылуы тиіс, бірақ бұл өкілдік пайдаланушыға API арқылы қолжетімді болуы міндетті емес.

JSON-пен салыстыру

JSON синтаксисі YAML 1.2 нұсқасының негізі болып табылады, ол YAML-ді "ресми жиынтық ретінде JSON-ға сәйкестендіру" мақсатымен жарияланды. Айырмашылықтар көбінесе байқалмайды, және көптеген JSON құжаттары Syck сияқты кейбір YAML талдағыштарымен оқылуы мүмкін. Бұл JSON-ның семантикалық құрылымы YAML-ді "инлайн стильде" жазудың опциялық түрімен сәйкес келуіне байланысты. JSON сияқты инлайн стильде кеңейтілген иерархияларды жазуға болады, бірақ бұл стиль нақтылықты арттырған жағдайларды қоспағанда, YAML үшін ұсынылмайды. YAML, JSON-да жоқ көптеген қосымша мүмкіндіктерге ие, оларға түсініктемелер, кеңейтілген дерек түрлері, реляциялық сілтемелер, тырнақшасыз жолдар және кілттердің ретін сақтайтын карталау түрлері кіреді. Қысқалығының арқасында JSON деректерді сериялау және десериализациялау YAML-ге қарағанда әлдеқайда жылдам жүзеге асырылады.

TOML-мен салыстыру

TOML ini файл форматын жетілдіру мақсатында жасалған. YAML индикатор белгілерін азайту артықшылығы TOML-дың қатаң түрде басқару белгілері мен тік жақшаларды қолдану талабымен салыстырылады. YAML маңызды көшірмелерді пайдалануы TOML-дың кілттері мен кесте атауларының нүктелік нотациясымен салыстырылды, осылайша бірдей семантикалық құрылымды беруге болады. Қай конвенция конфигурациялық файлдарды оқуға ыңғайлы етеді деген мәселе бағдарламашылар арасында пікірталас тудырады.

XML-мен салыстыру

YAML-де XML-дегідей тег атрибуттарының түсінігі жоқ. Оның орнына YAML кеңейтілген типтік жариялауларға ие (оның ішінде объектілер үшін класс типтері). YAML-дің өзі XML-дің тілінде анықталған құжат схемасы сипаттамаларына ие емес, бұл мысалы, құжатты өзін-өзі тексеруге мүмкіндік берер еді. Дегенмен, YAML үшін сырттан анықталған бірнеше схема сипаттама тілдері бар (мысалы, Doctrine, Kwalify және Rx), олар осы рөлді атқарады. Сонымен қатар, YAML-дің тілде анықталған семантикасы YAML құжатының өзінде жиі қарапайым, кең таралған жағдайларда тексерушінің қажеттілігін азайтады. Бұдан өзге, YAML дерек құрылымдарын XML форматында бейнелейтін YAXML, XML схемаларын импорттауға және XSLT сияқты шығару механизмдерін YAML-ге қолдануға мүмкіндік береді. Деректерді тізбектеу форматтарын салыстыру YAML-ді басқа тізбектеу форматтарымен толық салыстыруды ұсынады.

Бағдарламалық қамтамасыз ету (эмитерлер мен талдаушылар)

Белгілі дерек құрылымдары үшін YAML файлдарын деректерді де, YAML-ге тән безендіруді де жазатын басып шығару командаларын пайдалану арқылы оңай жасауға болады. Дегенмен, өзгермелі немесе күрделі иерархиялық деректерді жіберу үшін арнайы YAML эмиттері артық. Сол сияқты, қарапайым YAML файлдары (мысалы, кілт-мәнді жұптар) реттегіш өрнектермен оңай талданады. Күрделірек немесе өзгермелі дерек құрылымдары үшін ресми YAML талдаушысы ұсынылады. YAML эмиттері мен талдаушылары көптеген танымал тілдерде бар. Олардың көпшілігі сол тілде жазылған. Кейбіреулері C кітапханасы libyaml-дың байланымдары болып табылады; олар жылдам жұмыс істеуі мүмкін. Бұрын Syck деп аталатын тағы бір C кітапханасы болған, ол жазылып, «why the lucky stiff» есімді автор тастап кеткен: ол күтілмейді, ресми бастапқы кодтар жинағы жоқ, ал веб-сайты бұзылған. Сондықтан ұсынылатын жалғыз C кітапханасы – libyaml. Оны Кирилл Симонов жасаған. 2018 жылы дамуды жаңа қолдаушылар Иан Кордаско мен Инги дөт Нет қайта бастады. C++ бағдарламашылары C кітапханасы libyaml және C++ кітапханасы libyaml cpp-нің бірін таңдай алады. Екеуінің де толыққанды тәуелсіз код базасы және мүлдем басқа API бар. libyaml cpp кітапханасының негізгі нұсқасы 0 болып табылады, бұл API кез келген уақытта өзгеруі мүмкін екенін көрсетеді, және шындығында 0.3 нұсқасынан кейін өзгерді. C# тілінде жазылған, грамматикаға бағытталған нұсқасы бар, мақсаты – ішкі элементтерге арналған кеңейтімдерді жасау. YAML-дың кейбір нұсқалары, мысалы Perl-дің YAML.pm, бүкіл файлды (ағынды) жүктеп, бірден талдайды. Ал PyYaml сияқты басқа нұсқалар жалқау және тек сұраныс бойынша келесі құжатты өңдейді. Өте үлкен файлдар үшін, құжаттарды жеке-жеке өңдеуді жоспарласа, бүкіл файлды өңдеуден бұрын инстанциялау тым қиын болуы мүмкін. Сондықтан YAML.pm-де кейде файлды құжаттарға бөліп, жеке-жеке талдау қажет болады. YAML мұны жеңілдетеді, себебі бұл құжаттың соңғы маркерін бөлуді қажет етеді, ол жолдың басында үш нүктемен және содан кейін бос орынмен (сондай-ақ мүмкін түсініктемемен) анықталады. Бұл маркер мазмұнда қолдануға тыйым салынған.

For fixed data structures, YAML files can simply be generated using print commands that write both the data and the YAML specific decoration. To dump varying, or complex, hierarchical data, however, a dedicated YAML emitter is preferable. Similarly, simple YAML files (e. g. key value pairs) are readily parsed with regular expressions. For more complex, or varying, data structures, a formal YAML parser is recommended. YAML emitters and parsers exist for many popular languages. Most of them are written in the native language itself. Some are language bindings of the C library libyaml; they may run faster. There used to be another C library, called Syck, written and orphaned by why the lucky stiff: it is unmaintained, there is no authoritative source bundle, and the web site has been hijacked. Hence the only recommendable C library is libyaml. It was originally developed by Kirill Simonov. In 2018, development was resumed by the new maintainers Ian Cordasco and Ingy döt Net. C++ programmers have the choice between the C library libyaml and the C++ library libyaml cpp. Both have completely independent code bases and completely different APIs. The library libyaml cpp still has a major version number of 0, indicating that the API may change at any moment, as happened indeed after version 0.3. There is a grammar focused implementation written in C#, with an aim on extensions for the nested elements. Some implementations of YAML, such as Perl's YAML. pm, will load an entire file (stream) and parse it en masse. Other implementations like PyYaml are lazy and iterate over the next document only upon request. For very large files in which one plans to handle the documents independently, instantiating the entire file before processing may be prohibitive. Thus in YAML. pm, occasionally one must chunk a file into documents and parse those individually. YAML makes this easy, since this simply requires splitting on the document end marker, which is defined as three periods at the start of a line followed by a whitespace (and possible a comment). This marker is forbidden in content.