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.
369 lines
8.9 KiB
369 lines
8.9 KiB
'\" |
|
'\" Generated from file '_module_tomlish-1\&.1\&.6\&.tm\&.man' by tcllib/doctools with format 'nroff' |
|
'\" Copyright (c) 2024 |
|
'\" |
|
.TH "tomlish_module_tomlish" 0 1\&.1\&.6 doc "tomlish" |
|
.\" The -*- nroff -*- definitions below are for supplemental macros used |
|
.\" in Tcl/Tk manual entries. |
|
.\" |
|
.\" .AP type name in/out ?indent? |
|
.\" Start paragraph describing an argument to a library procedure. |
|
.\" type is type of argument (int, etc.), in/out is either "in", "out", |
|
.\" or "in/out" to describe whether procedure reads or modifies arg, |
|
.\" and indent is equivalent to second arg of .IP (shouldn't ever be |
|
.\" needed; use .AS below instead) |
|
.\" |
|
.\" .AS ?type? ?name? |
|
.\" Give maximum sizes of arguments for setting tab stops. Type and |
|
.\" name are examples of largest possible arguments that will be passed |
|
.\" to .AP later. If args are omitted, default tab stops are used. |
|
.\" |
|
.\" .BS |
|
.\" Start box enclosure. From here until next .BE, everything will be |
|
.\" enclosed in one large box. |
|
.\" |
|
.\" .BE |
|
.\" End of box enclosure. |
|
.\" |
|
.\" .CS |
|
.\" Begin code excerpt. |
|
.\" |
|
.\" .CE |
|
.\" End code excerpt. |
|
.\" |
|
.\" .VS ?version? ?br? |
|
.\" Begin vertical sidebar, for use in marking newly-changed parts |
|
.\" of man pages. The first argument is ignored and used for recording |
|
.\" the version when the .VS was added, so that the sidebars can be |
|
.\" found and removed when they reach a certain age. If another argument |
|
.\" is present, then a line break is forced before starting the sidebar. |
|
.\" |
|
.\" .VE |
|
.\" End of vertical sidebar. |
|
.\" |
|
.\" .DS |
|
.\" Begin an indented unfilled display. |
|
.\" |
|
.\" .DE |
|
.\" End of indented unfilled display. |
|
.\" |
|
.\" .SO ?manpage? |
|
.\" Start of list of standard options for a Tk widget. The manpage |
|
.\" argument defines where to look up the standard options; if |
|
.\" omitted, defaults to "options". The options follow on successive |
|
.\" lines, in three columns separated by tabs. |
|
.\" |
|
.\" .SE |
|
.\" End of list of standard options for a Tk widget. |
|
.\" |
|
.\" .OP cmdName dbName dbClass |
|
.\" Start of description of a specific option. cmdName gives the |
|
.\" option's name as specified in the class command, dbName gives |
|
.\" the option's name in the option database, and dbClass gives |
|
.\" the option's class in the option database. |
|
.\" |
|
.\" .UL arg1 arg2 |
|
.\" Print arg1 underlined, then print arg2 normally. |
|
.\" |
|
.\" .QW arg1 ?arg2? |
|
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). |
|
.\" |
|
.\" .PQ arg1 ?arg2? |
|
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally |
|
.\" (for trailing punctuation) and then a closing parenthesis. |
|
.\" |
|
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
|
.if t .wh -1.3i ^B |
|
.nr ^l \n(.l |
|
.ad b |
|
.\" # Start an argument description |
|
.de AP |
|
.ie !"\\$4"" .TP \\$4 |
|
.el \{\ |
|
. ie !"\\$2"" .TP \\n()Cu |
|
. el .TP 15 |
|
.\} |
|
.ta \\n()Au \\n()Bu |
|
.ie !"\\$3"" \{\ |
|
\&\\$1 \\fI\\$2\\fP (\\$3) |
|
.\".b |
|
.\} |
|
.el \{\ |
|
.br |
|
.ie !"\\$2"" \{\ |
|
\&\\$1 \\fI\\$2\\fP |
|
.\} |
|
.el \{\ |
|
\&\\fI\\$1\\fP |
|
.\} |
|
.\} |
|
.. |
|
.\" # define tabbing values for .AP |
|
.de AS |
|
.nr )A 10n |
|
.if !"\\$1"" .nr )A \\w'\\$1'u+3n |
|
.nr )B \\n()Au+15n |
|
.\" |
|
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
|
.nr )C \\n()Bu+\\w'(in/out)'u+2n |
|
.. |
|
.AS Tcl_Interp Tcl_CreateInterp in/out |
|
.\" # BS - start boxed text |
|
.\" # ^y = starting y location |
|
.\" # ^b = 1 |
|
.de BS |
|
.br |
|
.mk ^y |
|
.nr ^b 1u |
|
.if n .nf |
|
.if n .ti 0 |
|
.if n \l'\\n(.lu\(ul' |
|
.if n .fi |
|
.. |
|
.\" # BE - end boxed text (draw box now) |
|
.de BE |
|
.nf |
|
.ti 0 |
|
.mk ^t |
|
.ie n \l'\\n(^lu\(ul' |
|
.el \{\ |
|
.\" Draw four-sided box normally, but don't draw top of |
|
.\" box if the box started on an earlier page. |
|
.ie !\\n(^b-1 \{\ |
|
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
|
.\} |
|
.el \}\ |
|
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
|
.\} |
|
.\} |
|
.fi |
|
.br |
|
.nr ^b 0 |
|
.. |
|
.\" # VS - start vertical sidebar |
|
.\" # ^Y = starting y location |
|
.\" # ^v = 1 (for troff; for nroff this doesn't matter) |
|
.de VS |
|
.if !"\\$2"" .br |
|
.mk ^Y |
|
.ie n 'mc \s12\(br\s0 |
|
.el .nr ^v 1u |
|
.. |
|
.\" # VE - end of vertical sidebar |
|
.de VE |
|
.ie n 'mc |
|
.el \{\ |
|
.ev 2 |
|
.nf |
|
.ti 0 |
|
.mk ^t |
|
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
|
.sp -1 |
|
.fi |
|
.ev |
|
.\} |
|
.nr ^v 0 |
|
.. |
|
.\" # Special macro to handle page bottom: finish off current |
|
.\" # box/sidebar if in box/sidebar mode, then invoked standard |
|
.\" # page bottom macro. |
|
.de ^B |
|
.ev 2 |
|
'ti 0 |
|
'nf |
|
.mk ^t |
|
.if \\n(^b \{\ |
|
.\" Draw three-sided box if this is the box's first page, |
|
.\" draw two sides but no top otherwise. |
|
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
|
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
|
.\} |
|
.if \\n(^v \{\ |
|
.nr ^x \\n(^tu+1v-\\n(^Yu |
|
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
|
.\} |
|
.bp |
|
'fi |
|
.ev |
|
.if \\n(^b \{\ |
|
.mk ^y |
|
.nr ^b 2 |
|
.\} |
|
.if \\n(^v \{\ |
|
.mk ^Y |
|
.\} |
|
.. |
|
.\" # DS - begin display |
|
.de DS |
|
.RS |
|
.nf |
|
.sp |
|
.. |
|
.\" # DE - end display |
|
.de DE |
|
.fi |
|
.RE |
|
.sp |
|
.. |
|
.\" # SO - start of list of standard options |
|
.de SO |
|
'ie '\\$1'' .ds So \\fBoptions\\fR |
|
'el .ds So \\fB\\$1\\fR |
|
.SH "STANDARD OPTIONS" |
|
.LP |
|
.nf |
|
.ta 5.5c 11c |
|
.ft B |
|
.. |
|
.\" # SE - end of list of standard options |
|
.de SE |
|
.fi |
|
.ft R |
|
.LP |
|
See the \\*(So manual entry for details on the standard options. |
|
.. |
|
.\" # OP - start of full description for a single option |
|
.de OP |
|
.LP |
|
.nf |
|
.ta 4c |
|
Command-Line Name: \\fB\\$1\\fR |
|
Database Name: \\fB\\$2\\fR |
|
Database Class: \\fB\\$3\\fR |
|
.fi |
|
.IP |
|
.. |
|
.\" # CS - begin code excerpt |
|
.de CS |
|
.RS |
|
.nf |
|
.ta .25i .5i .75i 1i |
|
.. |
|
.\" # CE - end code excerpt |
|
.de CE |
|
.fi |
|
.RE |
|
.. |
|
.\" # UL - underline word |
|
.de UL |
|
\\$1\l'|0\(ul'\\$2 |
|
.. |
|
.\" # QW - apply quotation marks to word |
|
.de QW |
|
.ie '\\*(lq'"' ``\\$1''\\$2 |
|
.\"" fix emacs highlighting |
|
.el \\*(lq\\$1\\*(rq\\$2 |
|
.. |
|
.\" # PQ - apply parens and quotation marks to word |
|
.de PQ |
|
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 |
|
.\"" fix emacs highlighting |
|
.el (\\*(lq\\$1\\*(rq\\$2)\\$3 |
|
.. |
|
.\" # QR - quoted range |
|
.de QR |
|
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 |
|
.\"" fix emacs highlighting |
|
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 |
|
.. |
|
.\" # MT - "empty" string |
|
.de MT |
|
.QW "" |
|
.. |
|
.BS |
|
.SH NAME |
|
tomlish_module_tomlish \- tomlish toml parser |
|
.SH SYNOPSIS |
|
package require \fBtomlish\fR |
|
.sp |
|
\fBtypedjson_to_toml\fR \fIjson\fR |
|
.sp |
|
\fBlindex_resolve_basic\fR \fIlist\fR \fIindex\fR |
|
.sp |
|
.BE |
|
.SH DESCRIPTION |
|
.PP |
|
tomlish is an intermediate representation of toml data in a tree structure (tagged lists representing type information) |
|
.PP |
|
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 |
|
.PP |
|
The tomlish representation can then be converted to a Tcl dict structure or to other formats such as json, |
|
.PP |
|
although these other formats are generally unlikely to retain whitespace or comments |
|
.PP |
|
The other formats also won't preserve roundtripability e\&.g \\t and a literal tab coming from a toml file will be indistinguishable\&. |
|
.PP |
|
A further goal is to allow at least a useful subset of in-place editing operations which also preserve whitespace and comments\&. |
|
.PP |
|
e\&.g leaf key value editing, and table reordering/sorting, key-renaming at any level, key insertions/deletions |
|
.PP |
|
The API for editing (tomldoc object?) may require explicit setting of type if accessing an existing key |
|
.PP |
|
e\&.g setting a key that already exists and is a different type (especially if nested structure such as a table or array) |
|
.PP |
|
will need a -type option (-force ?) to force overriding with another type such as an int\&. |
|
.SH OVERVIEW |
|
.PP |
|
overview of tomlish |
|
.SS CONCEPTS |
|
.PP |
|
- |
|
.SS DEPENDENCIES |
|
.PP |
|
packages used by tomlish |
|
.IP \(bu |
|
\fBTcl 8\&.6-\fR |
|
.IP \(bu |
|
\fBstruct::stack\fR |
|
.PP |
|
.SH API |
|
.SS "NAMESPACE TOMLISH" |
|
.PP |
|
Core API functions for tomlish |
|
.TP |
|
\fBtypedjson_to_toml\fR \fIjson\fR |
|
.sp |
|
.PP |
|
.SS "NAMESPACE TOMLISH::ENCODE" |
|
.PP |
|
.PP |
|
.SS "NAMESPACE TOMLISH::DECODE" |
|
.PP |
|
.PP |
|
.SS "NAMESPACE TOMLISH::UTILS" |
|
.PP |
|
.PP |
|
.SS "NAMESPACE TOMLISH::PARSE" |
|
.PP |
|
.PP |
|
.SS "NAMESPACE TOMLISH::APP" |
|
.PP |
|
.PP |
|
.SS "NAMESPACE TOMLISH::LIB" |
|
.PP |
|
Secondary functions that are part of the API |
|
.PP |
|
.SS "NAMESPACE TOMLISH::SYSTEM" |
|
.PP |
|
.TP |
|
\fBlindex_resolve_basic\fR \fIlist\fR \fIindex\fR |
|
.sp |
|
Accepts index of the forms accepted by Tcl's list commands\&. (e\&.g compound indices such as 3+1 end-2) |
|
.sp |
|
returns -1 for out of range at either end, or a valid integer index |
|
.sp |
|
Unlike lindex_resolve; lindex_resolve_basic can't determine if an out of range index was out of range at the lower or upper bound |
|
.sp |
|
This is only likely to be faster than average over lindex_resolve for Tcl which has the builtin lseq command |
|
.sp |
|
The performance advantage is more likely to be present when using compound indexes such as $x+1 or end-1 |
|
.sp |
|
For pure integer indices the performance should be equivalent |
|
.PP |
|
.SH KEYWORDS |
|
configuration, module, parsing, toml |
|
.SH COPYRIGHT |
|
.nf |
|
Copyright (c) 2024 |
|
|
|
.fi
|
|
|