Parser TOML

TOML (Tom's Obvious Minimal Language) to minimalny format plikow konfiguracyjnych zaprojektowany tak, aby byl latwy do czytania i pisania. Jest standardowym formatem konfiguracji dla Rust (Cargo.toml), pakietowania Python (pyproject.toml) i wielu innych nowoczesnych narzedzi programistycznych.

Specyfikacje

• TOML v1.0.0 Specification
• TOML.io

Typowe zastosowania

• Parsowanie Cargo.toml w celu uzyskania zaleznosci i metadanych projektow Rust
• Odczyt pyproject.toml dla konfiguracji budowania Python (PEP 518/621)
• Przetwarzanie konfiguracji Hugo, Zola lub innych generatorow stron statycznych
• Edycja plikow konfiguracyjnych Deno (deno.toml)
• Walidacja konfiguracji przed wdrozeniem

Funkcje

• Pelna obsluga specyfikacji TOML v1.0.0
• Parsowanie tabel, tablic tabel i zagniezdzonych struktur
• Obsluga tabel i tablic inline
• Obsluga wartosci daty/czasu
• Konwersja do JSON, YAML lub XML
• Walidacja skladni z komunikatami bledow

Przyklady

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
dependencies = ["requests>=2.28"]

Wskazowki

• TOML uzywa = dla par klucz-wartosc, w odroznieniu od dwukropkow w YAML.
• Lancuchy znakow musza byc w cudzyslowach. Uzyj """ dla lancuchow wieloliniowych.
• Tabele ([table]) tworza zagniezdzone struktury.
• Tablice tabel uzywaja skladni [[array]].

Zrozumienie Parser TOML

TOML (Tom's Obvious Minimal Language) to format plikow konfiguracyjnych zaprojektowany tak, aby byl jednoznaczny i latwy do odczytu. Stworzony przez Toma Preston-Wernera (wspolzalozyciela GitHub), TOML czysto odwzorowuje sie na tablice hashujaca i jest celowo prostszy od YAML, bedac jednoczesnie bardziej ekspresyjny niz pliki INI. Wersja 1.0.0 zostala sfinalizowana w 2021 roku.

Projekt TOML koncentruje sie na jasnosci. Klucze i wartosci uzywaja prostej skladni "key = value". Tabele (sekcje) sa oznaczane [nawiasami kwadratowymi], tworzac zagniezdzone struktury bez wrazliwosci na wciecia. Tablice tabel uzywaja [[podwojnych nawiasow kwadratowych]] do definiowania powtarzajacych sie sekcji. TOML natywnie obsluguje lancuchy znakow, liczby calkowite, zmiennoprzecinkowe, wartosci logiczne, daty, czasy i daty-czasy jako typy pierwszoklasowe, eliminujac niejednoznacznosci parsowania czeste w JSON i YAML.

Ekosystem Rust wczesnie przyjal TOML z Cargo.toml jako formatem manifestu pakietu. Python podazyl z pyproject.toml (PEP 518 i PEP 621), czyniąc go nowoczesnym zamiennikiem dla setup.py i setup.cfg. TOML pojawia sie takze w narzedziach Go, Deno (deno.toml), Hugo i wielu innych narzedziach programistycznych ceniących wyraźna, czytelna konfiguracje.

TOML zamienia elastycznosc na przewidywalnosc. W odroznieniu od YAML istnieje tylko jeden sposob reprezentowania kazdej struktury danych. Nie ma kotwic, aliasow, niespodzianek z niejawna koercja typow ani znaczacych bialych znakow. Kompromisem jest to, ze gleboko zagniezdzone struktury staja sie rozwlekle, poniewaz kazdy poziom wymaga wlasnego naglowka tabeli.

TOML wyroznia sie w plaskich lub umiarkowanie zagniezdzonych plikach konfiguracyjnych, ktore ludzie czesto edytuja. Jego jednoznaczna skladnia unika pulapek YAML, takich jak koercja wartosci logicznych i bledy wciec, bedac jednoczesnie bardziej czytelny niz JSON do celow konfiguracyjnych. TOML to naturalny wybor dla manifestow projektow (Cargo.toml, pyproject.toml) i konfiguracji narzedzi. YAML pozostaje lepiej dopasowany do gleboko zagniezdzonych struktur, takich jak manifesty Kubernetes, a JSON jest standardem wymiany danych miedzy systemami.

Skladnia [[podwojnych nawiasow kwadratowych]] tworzy tablice tabel, gdzie kazde wystapienie naglowka dodaje nowy element do tablicy. Na przyklad [[products]] pojawiajace sie trzy razy tworzy tablice trzech obiektow produktow, kazdy z wlasnymi parami klucz-wartosc zebranymi w kolejnosci. TOML obsluguje rowniez jednoliniowe komentarze za pomoca symbolu hash (#), ktore moga pojawiac sie w osobnej linii lub po wartosci. Nie ma skladni komentarzy wieloliniowych, ale wariant jednoliniowy jest nadal znaczacą przewagą nad JSON, ktory nie ma zadnej obslugi komentarzy.

Tabele i tabele inline sluza roznym celom. Tabele uzywaja skladni [header] i rozciagaja sie na wiele linii, co czyni je czytelnymi dla sekcji z wieloma kluczami. Tabele inline uzywaja nawiasow klamerowych w jednej linii (key = { a = 1, b = 2 }) i musza byc zdefiniowane w calosci w tej jednej linii — nie moga byc rozszerzane po definicji. Jako ogolna zasada, uzywaj standardowych tabel dla czytelnosci, gdy sekcja ma wiecej niz dwa lub trzy klucze.