README.md
1[](https://travis-ci.org/flightaware/yajl-tcl)
2
3### This is yajl-tcl, a direct Tcl interface to the yajl JSON generator library.
4
5*Version 1.7.0*
6
7This package is a freely available open source package under the "Berkeley" license, same as Tcl. You can do virtually anything you like with it, such as modifying it, redistributing it, and selling it either in whole or in part. See the file "LICENSE" for complete information.
8
9yajl-tcl was written by Karl Lehenbauer of FlightAware. This company-funded work was generously open-sourced.
10
11Using yajl-tcl
12-----------
13
14```tcl
15package require yajltcl
16```
17
18Example
19===========
20
21Create a yajl-tcl object...
22
23```tcl
24yajl create x -beautify 1
25```
26
27or
28
29```tcl
30set x [yajl create #auto]
31```
32
33then generate some json
34
35```tcl
36x map_open string type string FeatureCollection string features array_open
37
38proc json_major_airport {obj icao lat lon} {
39 $obj map_open string type string Feature string geometry map_open string type string Point string coordinates array_open number $lon number $lat array_close map_close string properties map_open string label string $icao map_close map_close
40}
41
42json_major_airport x KABQ 35.0401944 -106.6091944
43json_major_airport x KBUR 34.206667 -118.3586667
44
45x array_close map_close
46
47puts [x get]
48```
49
50produces...
51
52```javascript
53{
54 "type": "FeatureCollection",
55 "features": [
56 {
57 "type": "Feature",
58 "geometry": {
59 "type": "Point",
60 "coordinates": [
61 -106.6091944,
62 35.0401944
63 ]
64 },
65 "properties": {
66 "label": "KABQ"
67 }
68 },
69 {
70 "type": "Feature",
71 "geometry": {
72 "type": "Point",
73 "coordinates": [
74 -118.3586667,
75 34.206667
76 ]
77 },
78 "properties": {
79 "label": "KBUR"
80 }
81 }
82 ]
83}
84```
85
86```tcl
87x reset - prepare the object for reuse
88```
89
90or
91
92```tcl
93x delete - delete the object and all of its internal data
94```
95
96Yajl-tcl Quick Reference
97==================
98
99Create the object as above.
100
101Invoke the object with one or more methods. They are invoked left to right. Some have no arguments and some have one.
102
103Methods
104-----------
105
106```array_open```, ```array_close```, bool, clear, double, integer, map_close, map_open, null, number, string, free, get, reset, or delete
107
108```array_open``` - start an array
109
110```array_close``` - end an array
111
112```clear``` - clears the buffer but doesn't reset the parser's state (not sure how useful this is)
113
114```bool``` - add a boolean, value follows
115
116```double``` - add a double precision floating point value, value follows
117
118```integer``` - add an integer value, value follows
119
120```number``` - add a numeric value, value follows
121
122Note that with respect to "double" yajl internally formats that only with "%g"
123providing six digits of precision and this is not currently configurable
124via YAJL. If you need higher precision, use "format" or equivalent, coupled
125with yajl-tcl's "number" method.
126
127```map_open``` - open a map
128
129```map_close``` - close a map
130
131```null``` - insert a null value
132
133```free``` - nothing yet
134
135```get``` - get the JSON generated so far. clears the generator buffer. maintains
136state so you can keep going, i.e. stream it.
137
138```reset``` - free, reallocate and configure the yajl generator object for reuse
139
140```delete``` - delete the object and all of its internal data
141
142Parsing
143=======
144
145As of version 1.2, yajl-tcl can also parse.
146
147```tcl
148set list [$object parse $json]
149```
150
151List will be as above.
152
153Alternatively, you can use ```::yajl::json2dict``` to turn JSON into a key-value
154list that be loaded into an array. As an example, the JSON from the prior
155section can be parsed using code similar to the following:
156
157```tcl
158set jsonkv [::yajl::json2dict $json]
159puts "raw = $jsonkv"
160array set myArray $jsonkv
161puts "outerType = $myArray(type)"
162foreach featurekv $myArray(features) {
163 unset -nocomplain featureAry
164 array set featureAry $featurekv
165 puts "innerType = $featureAry(type), geom = $featureAry(geometry)"
166}
167```
168
169That will output the following:
170
171```javascript
172raw = type FeatureCollection features {{type Feature geometry
173 {type Point coordinates {-106.6091944 35.0401944}} properties {label KABQ}}
174 {type Feature geometry {type Point coordinates {-118.3586667
175 34.206667}} properties {label KBUR}}}
176outerType = FeatureCollection
177innerType = Feature, geom = type Point coordinates {-106.6091944 35.0401944}
178innerType = Feature, geom = type Point coordinates {-118.3586667 34.206667}
179```
180
181A slight variation of json2dict is ```yajl::json2dict_ex```. This version turns JSON into a fully traversable Tcl dictionary by virtue of that it expands JSON arrays into key-value pairs, as might be done with a map, where the keys are synthesized sequential integers starting from zero.
182
183After having parsed a list of channels returned from the Slack API, for instance, to fetch the ID of the third member of the fourth channel you might say ```dict get $dict channels 3 members 2```. See the tests file json2dict_ex.test included in the distro for a nice big JSON structure that hopefully will make clear what's going on.
184
185Parsing to huddle
186=================
187
188You can use ```::yajl::json2huddle``` to turn JSON into a huddle string. Let's use the
189json from the prior examples:
190
191```tcl
192set myhuddle [::yajl::json2huddle $json]
193huddle set myhuddle features 0 geometry coordinates 0 -99.9999
194puts [huddle jsondump $myhuddle]
195```
196
197That will output the following:
198
199```javascript
200{
201 "type": "FeatureCollection",
202 "features": [
203 {
204 "type": "Feature",
205 "geometry": {
206 "type": "Point",
207 "coordinates": [
208 -99.9999,
209 35.0401944
210 ]
211 },
212 "properties": {"label": "KABQ"}
213 },
214 {
215 "type": "Feature",
216 "geometry": {
217 "type": "Point",
218 "coordinates": [
219 -118.3586667,
220 34.206667
221 ]
222 },
223 "properties": {"label": "KBUR"}
224 }
225 ]
226}
227```
228
229Yajl Library Routines
230=====================
231
232```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.
233
234Example usage:
235
236```tcl
237set json [yajl create #auto]
238add_array_to_json $json array
239puts [$json get]
240$json delete
241```
242
243```array_to_json arrayName``` - return the contents of the array as JSON text
244
245```add_pgresult_tuples_to_json``` - 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.
246
247```pg_select_to_json``` - given a postgres connection handle and a sql select statement, perform the select and return the results of the select as JSON text.
248
249Bugs?
250====
251
252About for sure. None known at this time.
253
254Contents
255========
256
257```Makefile.in``` Makefile template. The configure script uses this file to
258 produce the final Makefile.
259
260```README``` This file
261
262```aclocal.m4``` Generated file. Do not edit. Autoconf uses this as input
263 when generating the final configure script. See "tcl.m4"
264 below.
265
266```configure``` Generated file. Do not edit. This must be regenerated with autoconf
267 anytime configure.in or tclconfig/tcl.m4 changes.
268
269```configure.in``` Configure script template. Autoconf uses this file as input
270 to produce the final configure script.
271
272```generic/yajltcl.c``` YAJL Tcl interface routines.
273```generic/yajltcl.h``` include file
274```generic/tclyajltcl.c``` Init routines.
275
276
277```tclconfig/``` This directory contains various template files that build
278 the configure script. They should not need modification.
279
280```install-sh``` Program used for copying binaries and script files
281 to their install locations.
282
283```tcl.m4``` Collection of Tcl autoconf macros. Included by
284 aclocal.m4 to define SC_* macros.
285
286Building
287==========
288
289Unix
290----------
291
292Building under most UNIX systems is easy, just run the configure script and then run make.
293You will need to have the yajl library itself already installed, since it is not included with yajl-tcl.
294In some cases, you may also need to specify where your Tcl library directory is located.
295
296```bash
297$ cd yajl-tcl
298$ autoconf
299$ ./configure
300$ make
301$ sudo make install
302```
303
304
305FreeBSD
306----------
307
308```bash
309$ sudo portinstall devel/yajl
310$ cd yajl-tcl
311$ autoconf
312$ ./configure --with-tcl=/usr/local/lib/tcl8.5
313$ make
314$ sudo make install
315```
316
317
318Debian/Raspbian
319----------
320```bash
321$ sudo apt-get install pkg-config libyajl-dev
322$ cd yajl-tcl
323$ autoconf
324$ ./configure --with-tcl=/usr/lib/tcl8.5
325$ make
326$ sudo make install
327```
328
329
330Windows
331----------
332
333yajl-tcl has not been built under Windows at this time.
334
335The recommended method to build extensions under Windows is to use the Msys + Mingw build process. This provides a Unix-style build while generating native Windows binaries. Using the Msys + Mingw build tools means that you can use the same configure script as per the Unix build to create a Makefile.
336
337If you have VC++, then you may wish to use the files in the win subdirectory and build the extension using just VC++.
338
339Instructions for using the VC++ makefile are written in the first part of the Makefile.vc file.
340
341Installation
342============
343
344```bash
345make install
346```
347
348yajltcl installs like so:
349
350```
351 $exec_prefix
352 / \
353 lib bin
354 | |
355 PACKAGEx.y (dependent .dll files on Windows)
356 |
357 pkgIndex.tcl (.so|.dll files)
358```
359
360The main ```.so|.dll``` library file gets installed in the versioned ```PACKAGE``` directory, which is OK on all platforms because it will be directly referenced with by 'load' in the ```pkgIndex.tcl``` file. Dependent DLL files on Windows must go in the bin directory (or other directory on the user's PATH) in order for them to be found.
361
362Yajl-tcl has not been tested with Windows so none of the above may be true.
363
364FlightAware
365---
366FlightAware has released over a dozen applications (under the free and liberal BSD license) into the open source community. FlightAware's repositories are available on GitHub for public use, discussion, bug reports, and contribution. Read more at https://flightaware.com/about/code/
367
368
){kind=link}