.\"                                      Hey, EMACS: -*- nroff -*-
.\" (C) Copyright 2019 Massimo Manghi <mxmanghi@apache.org>,
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH YAJLTCL 3tcl "December  3 2019"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
yajltcl \- Tcl binding to YAJL, a JSON messages parser and generator
.SH SYNOPSIS
.B package require yajltcl
.br
.B set yajl [yajltcl <cmdname>] or
.br
.B set yail [yajltcl #auto]

.SH DESCRIPTION

Create your yajltcl object as above then invoke the object with one or more methods.
They are generated left to right. Some have no arguments and some have one.
.BR
The methods are: array_open, array_close, bool, clear, double, integer, map_close,
map_open, null, number, string, free, get, and reset
.BR
.in 1em

    array_open  - start an array
    array_close - end an array
    clear       - clears the buffer but doesn't reset the parser's state (not sure how useful this is)
    bool        - add a boolean, value follows
    double      - add a double precision floating point value, value follows
    integer     - add an integer value, value follows
    number      - add a numeric value, value follows
.in 0em

Note that with respect to "double" yajl internally formats that only with "%g", providing six digits of precision, and this is not
currently configurable via YAJL. If you need higher precision, use "format" or equivalent, coupled with yajltcl's "number" method.
.br

.in 1em
    map_open  - open a map
    map_close - close a map
    null      - insert a null value
    free      - nothing yet
    get       - get the JSON generated so far. clears the generator buffer. maintains state so you can keep going, i.e. stream it.
    reset     - free, reallocate and configure the yajl generator object 
.in 0em
.BR
.SH PARSING

As of version 1.2, yajltcl can also parse...
.BR
set list [$object parse $json]
.BR
List will be as above. 

.SH YAJLTCL LIBRARY ROUTINES
.br
add_array_to_json jsonObject arrayName - append a Tcl array into the specified json object by doing a JSON map open and then
storing the array as key-value pairs and then doing a map close. Example usage:
.br
.in 1em

        set json [yajl create #auto]
        add_array_to_json $json array
        puts [$json get]
        rename $json ""

.in 0em
.br
    array_to_json arrayName     - return the contents of the array as JSON text
    add_pgresult_tuples_to_json jsonObject res 
                                - append a JSON array of JSON objects of a Postgres result,
                                  one array entry per tuple in the result, with the non-null 
                                  values set in each row object.
    pg_select_to_json conn sql  - given a postgres connection handle and a sql select statement,
                                  perform the select and return the results of the select as JSON text.