Konwerter JSON na TOML

Konwerter JSON → TOML

TOML to czytelny dla człowieka format konfiguracji, używany m.in. w Rust (Cargo.toml) i Pythonie (pyproject.toml). Ten konwerter zamienia strukturę JSON na poprawny TOML.

Na co mapują się typy?

Zalety TOML

• Jest czytelniejszy niż JSON, bo nie wymaga cudzysłowów przy każdej wartości.
• Obsługuje komentarze (w JSON nie ma).
• Dobrze odwzorowuje hierarchię konfiguracji.
• Jest typowany — liczby, daty i wartości logiczne mają jawne typy.

Przykład

{
  "name": "app",
  "server": { "port": 8080 }
}

staje się:

name = "app"

[server]
port = 8080

Jak działa konwerter JSON na TOML

Narzędzie najpierw parsuje tekst JSON do drzewa obiektów. Każdy klucz i wartość trafiają do struktury, którą można przechodzić rekurencyjnie. Na tym etapie sprawdzana jest składnia JSON — jeśli tekst jest niepoprawny, konwersja się zatrzymuje.

Drugi etap to serializacja. Algorytm przechodzi drzewo i dla każdego klucza decyduje, czy zapisać go jako wartość prostą, czy jako tabelę. Klucze proste są wypisywane przed tabelami, bo TOML wymaga, aby pary klucz = wartość nie występowały po nagłówku sekcji, do której należą. Zagnieżdżone obiekty zamieniają się na nagłówki w postaci [ścieżka.do.tabeli].

Tablice są rozdzielane na dwa przypadki: tablica wartości prostych trafia do jednej linii w nawiasach kwadratowych, a tablica obiektów staje się serią nagłówków [[nazwa]]. Dzięki temu struktura JSON zostaje odwzorowana bez zgadywania typów — liczby i wartości logiczne pozostają bez cudzysłowów, a teksty są w cudzysłowach.

Przykład krok po kroku

1. Wejściowy JSON: {"service":{"timeout":8080,"host":"localhost"},"logs":["stdout","file"],"debug":true}. To obiekt z trzema kluczami: service, logs i debug.
2. Parser rozpoznaje, że klucz service wskazuje na obiekt, więc odkłada go do osobnej sekcji. Klucze logs i debug są wartościami prostymi lub tablicą wartości prostych.
3. Zgodnie z zasadą kolejności najpierw zapisywane są klucze proste: logs = ["stdout", "file"] oraz debug = true. Dzięki temu nie znajdą się one po nagłówku tabeli.
4. Następnie powstaje sekcja [service]. W jej wnętrzu zapisywane są pary: timeout = 8080 (bez cudzysłowów, bo to liczba) oraz host = "localhost" (w cudzysłowach, bo to tekst).
5. Cały wynikowy TOML to: logs = ["stdout", "file"]; debug = true; [service]; timeout = 8080; host = "localhost". W pliku każda z tych instrukcji znajdzie się w osobnej linii.
6. Na końcu narzędzie sprawdza, czy nie powstały puste sekcje i czy kolejność kluczy jest poprawna. Otrzymany plik można wkleić do Cargo.toml lub pyproject.toml po ręcznej weryfikacji.

Tabela referencyjna zachowań konwertera

Praktyczne wskazówki

• Sprawdź JSON przed konwersją. Konwerter nie naprawi brakujących cudzysłowów ani przecinków. Użyj walidatora JSON, jeśli nie masz pewności co do składni.
• Pamiętaj o kolejności kluczy. W TOML klucze proste muszą być przed tabelami. Narzędzie układa je automatycznie, ale jeśli edytujesz wynik ręcznie, nie przenoś ich pod nagłówki sekcji.
• Uważaj na null. TOML nie ma odpowiednika null. Konwerter zamienia je na pusty tekst, więc jeśli null ma znaczenie, popraw wynik po konwersji.
• Zagnieżdżaj tabele świadomie. Głęboko zagnieżdżone obiekty tworzą długie nagłówki typu [a.b.c]. W TOML są poprawne, ale trudniejsze w utrzymaniu — rozważ spłaszczenie struktury.
• Testuj wynik w docelowym narzędziu. Po konwersji wczytaj plik do programu, który go używa (np. Cargo lub Python), aby upewnić się, że typy i klucze są interpretowane zgodnie z oczekiwaniem.

Ograniczenia narzędzia

• Brak konwersji odwrotnej. Narzędzie działa tylko z JSON na TOML. Nie przekształci TOML z powrotem na JSON.
• Brak obsługi null. TOML nie ma typu null, więc wartość null staje się pustym tekstem. To może zmienić logikę konfiguracji.
• Brak wnioskowania o datach. JSON nie ma typu daty. Nawet jeśli tekst wygląda jak data, TOML zapisze go jako zwykły łańcuch w cudzysłowach, a nie jako typ daty.
• Brak komentarzy. JSON nie obsługuje komentarzy, więc konwerter nie ma ich skąd wziąć. Jeśli chcesz dodać komentarze do TOML, musisz zrobić to ręcznie po konwersji.

Najczęstsze pytania