[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin tomlish_module_tomlish 0 1.1.2]
[copyright "2024"]
[titledesc {tomlish toml parser}]  [comment {-- Name section and table of contents description --}]
[moddesc {tomlish}]             [comment {-- Description at end of page heading --}]
[require tomlish]
[keywords module parsing toml configuration]
[description]
[para] tomlish is an intermediate representation of toml data in a tree structure (tagged lists representing type information)
[para] The design goals are for tomlish to be whitespace and comment preserving ie byte-for byte preservation during roundtrips from toml to tomlish and back to toml
[para] The tomlish representation can then be converted to a Tcl dict structure or to other formats such as json,
[para] although these other formats are generally unlikely to retain whitespace or comments
[para] A further goal is to allow at least a useful subset of in-place editing operations which also preserve whitespace and comments.
[para] e.g leaf key value editing, and table reordering/sorting, key-renaming at any level, key insertions/deletions
[para] The API for editing (tomldoc object?) may require explicit setting of type if accessing an existing key
[para] e.g setting a key that already exists and is a different type (especially if nested structure such as a table or array)
[para] will need a -type option (-force ?) to force overriding with another type such as an int.
[section Overview]
[para] overview of tomlish
[subsection Concepts]
[para] -
[subsection dependencies]
[para] packages used by tomlish
[list_begin itemized]
[item] [package {Tcl 8.6-}]
[item] [package {struct::stack}]
[list_end]
[section API]
[subsection {Namespace tomlish}]
[para] Core API functions for tomlish
[list_begin definitions]
[call [fun json_to_toml] [arg json]]
[para]
[list_end] [comment {--- end definitions namespace tomlish ---}]
[subsection {Namespace tomlish::encode}]
[para]
[list_begin definitions]
[list_end] [comment {--- end definitions namespace tomlish::encode ---}]
[subsection {Namespace tomlish::decode}]
[para]
[list_begin definitions]
[call [fun toml] [arg arg...]]
[para] return a Tcl list of tomlish tokens
[list_end] [comment {--- end definitions namespace tomlish::decode ---}]
[subsection {Namespace tomlish::utils}]
[para]
[list_begin definitions]
[list_end] [comment {--- end definitions namespace tomlish::utils ---}]
[subsection {Namespace tomlish::parse}]
[para]
[list_begin definitions]
[list_end] [comment {--- end definitions namespace tomlish::parse ---}]
[subsection {Namespace tomlish::app}]
[para]
[list_begin definitions]
[call app::[fun decoder] [arg args]]
[para] read toml on stdin until EOF
[para] on error   - returns non-zero exit code and writes error on stderr
[para] on success - returns zero exit code and writes JSON encoding of the data on stdout
[para] This decoder is intended to be compatible with toml-test
[call app::[fun encoder] [arg args]]
[para] read JSON on stdin until EOF
[para] return non-zero exitcode if JSON data cannot be converted to a valid TOML representation
[para] return zero exitcode and TOML data on stdout if JSON data can be converted.
[para] This encoder is intended to be compatible with toml-test
[list_end] [comment {--- end definitions namespace tomlish::app ---}]
[subsection {Namespace tomlish::lib}]
[para] Secondary functions that are part of the API
[list_begin definitions]
[list_end] [comment {--- end definitions namespace tomlish::lib ---}]
[manpage_end]