You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
73 lines
3.6 KiB
73 lines
3.6 KiB
[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]
|
|
|