TOML

2 nástrojů

TOML to JSONPřevod formátu TOML do JSON TOML FormatterFormátujte a validujte konfigurační soubory TOML

TOML nástroje na ToolDecku vám umožňují formátovat, validovat a převádět TOML konfigurační soubory přímo v prohlížeči — bez instalace, bez účtu, bez nahrávání dat na jakýkoliv server. TOML Formatter parsuje váš TOML vstup a znovu ho serializuje s konzistentním odsazením, normalizovaným pořadím klíčů a inline chybami validace, které přesně určí syntaktické problémy. Konvertor TOML na JSON převádí TOML dokumenty na jejich JSON ekvivalenty a zachovává datové typy včetně datetime hodnot, inline tabulek a polí tabulek. Oba nástroje běží zcela na straně klienta, takže vaše konfigurační soubory — které často obsahují přihlašovací údaje k databázi, API endpointy a nasazovací tajné klíče — zůstávají na vašem počítači. Pokud potřebujete opačný směr převodu, konvertor JSON na TOML v kategorii JSON tuto konverzi zajistí.

Co jsou TOML nástroje?

TOML (Tom's Obvious, Minimal Language) je formát konfiguračních souborů postavený na explicitní a jednoznačné syntaxi. Vytvořil ho Tom Preston-Werner, spoluzakladatel GitHubu. TOML byl poprvé vydán v roce 2013 a specifikace verze 1.0 vyšla v lednu 2021. Formát se jednoznačně mapuje na hashovací tabulku: každý TOML soubor definuje strom párů klíč-hodnota organizovaných do tabulek (sekcí označených [závorkami]). Na rozdíl od YAML se TOML nespoléhá na odsazení pro určení struktury, čímž eliminuje celou třídu chyb parsování způsobených bílými znaky. Na rozdíl od JSON TOML podporuje komentáře, nativní typy datum/čas a víceřádkové řetězce — funkce, které konfigurační soubory potřebují, ale JSON nebyl navržen k jejich poskytování.

TOML nástroje automatizují mechanickou práci s čtením, validací a převodem TOML souborů. Formátovací nástroje normalizují odsazení a pořadí klíčů, aby konfigurační soubory zůstaly čitelné napříč týmem, i když stejný soubor upravuje více přispěvatelů. Konverzní nástroje překládají mezi TOML a JSON, což je užitečné, když knihovna nebo API očekává JSON vstup, ale zdrojem pravdy je TOML konfigurace. Validace zachytí syntaktické chyby — chybějící uzavírací závorka, duplicitní klíč nebo neplatný datetime literál — dříve, než způsobí selhání při spuštění aplikace.

Tyto úlohy se vyskytují často v Rust projektech (kde Cargo.toml je manifestem balíčku), při Python packaging (pyproject.toml nahradil setup.py jako standardní konfiguraci sestavení v PEP 518 a PEP 621), u Hugo statických webů (které používají TOML pro konfiguraci webu ve výchozím nastavení) a v jakékoli infrastrukturní konfiguraci ukládané v TOML souborech. Specifikace TOML je spravována na toml.io a parsery existují pro všechny hlavní programovací jazyky.

Proč používat TOML nástroje na ToolDecku?

TOML nástroje na ToolDecku parsují a zpracovávají vše uvnitř záložky prohlížeče pomocí JavaScriptu. Žádná konfigurační data nejsou přenášena na server, není vyžadován žádný účet a nástroje fungují offline po počátečním načtení stránky.

🔒

Soukromí jako výchozí stav

Konfigurační soubory často obsahují citlivé hodnoty — URL databáze, API klíče, cíle nasazení. ToolDeck zpracovává TOML zcela na straně klienta, takže nic neopustí váš prohlížeč. Bezpečné pro proprietární projekty a interní konfiguraci infrastruktury.

⚡

Okamžitá zpětná vazba

Vložte TOML a okamžitě uvidíte formátovaný výstup nebo JSON. Syntaktické chyby jsou hlášeny s čísly řádků a popisem. Není třeba čekat na instalaci CLI nástroje ani na dokončení kroku sestavení.

🔄

Přesná konverze typů

Konvertor TOML na JSON zachovává TOML specifické typy, jako jsou offset datetime, lokální datum a lokální čas, jako řetězce ISO 8601. Přesnost celých čísel a desetinných čísel je zachována. Pole tabulek se správně mapují na JSON pole objektů.

🌐

Není nutná instalace

Funguje na jakémkoli zařízení s moderním prohlížečem. Užitečné, když kontrolujete pull request na počítači bez obvyklého vývojového prostředí nebo když potřebujete rychle validovat TOML soubor kolegy.

Případy použití TOML nástrojů

Formátování, validace a konverze TOML se vyskytují napříč různými rolemi a typy projektů. Rust vývojáři pracují s Cargo.toml denně. Python vývojáři konfigurují sestavení a nástroje prostřednictvím pyproject.toml. DevOps inženýři spravují konfiguraci aplikací, která se dodává jako TOML. Níže uvedené úlohy ukazují, kde prohlížečové TOML nástroje šetří čas ve srovnání s psaním jednorázového skriptu nebo instalací CLI nástroje.

Vyčištění Cargo.toml

Po sloučení několika přidání závislostí má Cargo.toml Rust projektu nekonzistentní formátování. Spusťte ho přes TOML Formatter, abyste normalizovali odsazení a pořadí klíčů před odevzdáním.

pyproject.toml na JSON

CI pipeline potřebuje metadata sestavení ve formátu JSON, ale zdrojem pravdy je pyproject.toml. Použijte konvertor TOML na JSON k vygenerování JSON reprezentace a ověřte mapování před zautomatizováním konverze v pipeline.

Migrace konfigurace

Přesouváte aplikaci z konfigurace založené na JSON na TOML (nebo naopak). Konvertor TOML na JSON vám umožní porovnat obě reprezentace vedle sebe a potvrdit, že datové typy, vnořené struktury a sémantika polí jsou zachovány.

Ladění syntaxe

Konfigurační soubor TOML se při spuštění aplikace nepodaří parsovat s nepřehlednou chybovou zprávou. Vložte ho do TOML Formatter, abyste získali konkrétní čísla řádků a sloupců pro syntaktickou chybu spolu s popisem, co parser očekával.

Generování dokumentace

Píšete dokumentaci, která obsahuje příklady konfigurace ve formátech TOML i JSON. Převeďte kanonický TOML příklad přes konvertor TOML na JSON, aby obě verze zůstaly synchronizované bez ručního přepisu.

Výuka syntaxe TOML

Vývojáři, kteří jsou v TOML noví, mohou experimentovat s formátem zápisem TOML v TOML Formatter, sledovat chyby validace v reálném čase a porovnávat strukturu s formátovaným výstupem. To je rychlejší než samotné čtení specifikace.

Reference datových typů TOML

TOML v1.0 definuje následující datové typy. Každý typ se mapuje na konkrétní reprezentaci při převodu do JSON. Tabulka níže pokrývá syntaxi, příklady a chování konverze pro každý typ TOML.

Typ	Syntaxe	Příklad	Mapování JSON
Řetězec	"..." nebo '...'	name = "TOML"	JSON string. Základní řetězce podporují escape sekvence (\n, \t, \u). Literální řetězce ('...') zacházejí se zpětnými lomítky jako s literálními znaky.
Celé číslo	číslice, 0x, 0o, 0b	port = 8080	JSON number. Podporuje hexadecimální (0xDEAD), oktalové (0o755), binární (0b1010) a oddělovače podtržítkem (1_000).
Desetinné číslo	číslice s . nebo e	pi = 3.14159	JSON number. Podporuje inf, -inf a nan (mapováno na null nebo řetězec v JSON, protože JSON nemá NaN).
Logická hodnota	true / false	enabled = true	JSON boolean. Platné jsou pouze malá písmena true a false.
Datum a čas s posunem	RFC 3339	2024-01-15T09:30:00Z	JSON string (ISO 8601). Obsahuje posun časového pásma. JSON nemá nativní typ datetime.
Lokální datum a čas	datum T čas	2024-01-15T09:30:00	JSON string. Bez informace o časovém pásmu. Vhodné pro časy podle nástěnných hodin.
Lokální datum	YYYY-MM-DD	2024-01-15	JSON string. Datum bez časové složky.
Lokální čas	HH:MM:SS	09:30:00	JSON string. Čas bez data nebo časového pásma.
Pole	[hodnota, ...]	ports = [8080, 8443]	JSON array. TOML pole mohou být heterogenní v TOML v1.0, ale musí být homogenní ve v0.5.
Tabulka	tomlCategoryContent.r10Syntax	[database]	JSON object. Standardní tabulky používají [závorky]. Inline tabulky používají složené závorky na jednom řádku.

Specifikace TOML v1.0.0 (toml.io) je aktuální stabilní verze. Pole tabulek používají [[dvojité závorky]] pro definici opakovaných záznamů tabulky, které se mapují na JSON pole objektů.

Jak vybrat správný TOML nástroj

ToolDeck má tři nástroje pro práci s TOML soubory. Dva jsou v kategorii TOML a jeden je v kategorii JSON pro opačný směr konverze. Vyberte nástroj, který odpovídá vaší úloze.

1
Pokud potřebujete znovu odsadit TOML soubor, normalizovat pořadí klíčů nebo validovat syntaxi TOML s hlášením chyb na úrovni řádků → TOML Formatter
2
Pokud potřebujete převést konfigurační soubor TOML na JSON pro použití v API, skriptech nebo nástrojích, které očekávají JSON vstup → TOML to JSON Converter
3
Pokud potřebujete převést JSON dokument do formátu TOML pro projekty, které používají TOML jako svůj konfigurační standard → JSON to TOML Converter

Pro každodenní práci s TOML zvládne TOML Formatter formátování i validaci v jednom kroku — vložte TOML a buď dostanete čistý výstup, nebo se dozvíte přesně, kde je syntaktická chyba. Když potřebujete propojit TOML a JSON, konvertor TOML na JSON zachovává všechny datové typy TOML včetně datetime hodnot a vnořených tabulek. Pro opačný směr (JSON na TOML) použijte konvertor JSON na TOML v kategorii JSON. Pokud ladíte konfiguraci, která se nepodaří parsovat, začněte s TOML Formatter: jeho chybové zprávy obsahují čísla řádků a popisy očekávaných tokenů, které jsou konkrétnější než to, co hlásí většina TOML parserů na úrovni aplikace.

Nejčastější dotazy

Jaký je rozdíl mezi TOML a YAML?

TOML používá explicitní syntaxi se závorkami pro tabulky a nespoléhá na odsazení pro určení struktury. YAML používá odsazení k definici hierarchie, což ho činí citlivým na chyby způsobené bílými znaky — jediný špatně umístěný mezera může zcela změnit parsovanou strukturu. TOML má také nativní typy datum/čas a zakazuje duplicitní klíče, zatímco YAML tiše použije poslední hodnotu, pokud se klíč objeví dvakrát. TOML je obecně preferován pro konfiguraci aplikací, zatímco YAML je běžnější v Kubernetes manifestech a definicích CI/CD pipeline, kde je užitečná podpora více dokumentů a kotvy/aliasy.

Jaký je rozdíl mezi TOML a JSON?

JSON je formát výměny dat navržený pro komunikaci mezi stroji. TOML je konfigurační formát navržený pro čtení a úpravy lidmi. TOML podporuje komentáře (řádky začínající #), nativní typy datetime, víceřádkové řetězce a tabulky, které snižují hloubku vnoření. JSON nepodporuje komentáře, nemá typ datum a vyžaduje explicitní vnoření pomocí složených závorek. JSON je správnou volbou pro API payloady a ukládání dat; TOML je správnou volbou pro konfigurační soubory, které lidé upravují ručně.

Může TOML reprezentovat všechny datové struktury JSON?

TOML může reprezentovat většinu JSON struktur, ale existují okrajové případy. TOML nepodporuje hodnoty null — neexistuje žádný TOML ekvivalent JSON null. Klíče TOML musí být řetězce, což odpovídá klíčům JSON objektů. Pole TOML byla v v0.5 omezena na homogenní typy, ale TOML v1.0 umožňuje pole se smíšenými typy. Hluboce vnořené JSON objekty mohou být v TOML rozvláčné, protože každá úroveň vnoření vyžaduje samostatnou hlavičku tabulky.

Které projekty používají TOML pro konfiguraci?

Rustův sestavovací systém Cargo používá Cargo.toml jako manifest balíčku. Python přijal pyproject.toml jako standardní konfigurační soubor sestavení prostřednictvím PEP 518 (2016) a PEP 621 (2020). Hugo, generátor statických webů, používá TOML pro konfiguraci webu ve výchozím nastavení. InfluxDB používá TOML pro konfiguraci serveru. Systém Go modulů TOML zvažoval, ale zvolil vlastní formát; mnoho Go projektů však stále používá TOML pro konfiguraci na úrovni aplikace prostřednictvím knihoven jako BurntSushi/toml a pelletier/go-toml.

Jak TOML zpracovává komentáře?

TOML podporuje komentáře na celém řádku i na konci řádku pomocí znaku #. Vše od # do konce řádku je parserem ignorováno. Komentáře nemohou být uvnitř víceřádkových základních řetězců ani víceřádkových literálních řetězců. Při převodu TOML na JSON jsou komentáře zahozeny, protože JSON syntaxi komentářů nemá. To znamená, že zpětná konverze z TOML na JSON a zpět na TOML ztratí všechny komentáře z původního souboru.

Co jsou pole tabulek v TOML?

Pole tabulek používají syntaxi [[dvojitých závorek]] k definici opakovaných záznamů stejné struktury tabulky. Například [[servers]] appearing twice vytvoří pole se dvěma objekty serveru. V JSON se toto mapuje na pole objektů. Pole tabulek se běžně používají pro seznamy závislostí, definice serverů nebo konfigurace pluginů, kde má každý záznam stejnou sadu klíčů.

Je TOML citlivý na bílé znaky?

TOML není citlivý na odsazení. Odsazení je čistě estetické a neovlivňuje parsování. TOML však vyžaduje nové řádky k oddělení párů klíč-hodnota — na jeden řádek nelze umístit dva páry klíč-hodnota (s výjimkou inline tabulek). Inline tabulky musí se vejít na jeden řádek a nemohou obsahovat nové řádky. Tento návrh se vyhýbá chybám způsobeným odsazením, které jsou běžné v YAML souborech.

Co se stane s datetime hodnotami TOML při převodu na JSON?

JSON nemá nativní typ datetime, takže TOML datetime hodnoty jsou převedeny na řetězce ISO 8601. Offset datetime hodnoty (jako 2024-01-15T09:30:00Z) si zachovají posun časového pásma v řetězcové reprezentaci. Lokální datum a čas, lokální datum a lokální čas jsou serializovány jako řetězce bez informace o časovém pásmu. Konverze je bezeztrátová v tom smyslu, že původní hodnotu lze z řetězce zpětně parsovat, ale konzument JSON musí vědět, že má s těmito řetězci zacházet jako s daty, nikoli jako s libovolným textem.