cson  Hex Artifact Content

Artifact 3a98a7088c8eea3eac6025c6ed023af74f97e353:

Wiki page [HowTo] by stephan 2011-05-09 17:58:45.
0000: 44 20 32 30 31 31 2d 30 35 2d 30 39 54 31 37 3a  D 2011-05-09T17:
0010: 35 38 3a 34 35 2e 39 36 37 0a 4c 20 48 6f 77 54  58:45.967.L HowT
0020: 6f 0a 50 20 65 62 34 63 34 62 39 62 32 38 61 63  o.P eb4c4b9b28ac
0030: 61 66 65 65 37 34 62 31 31 65 35 38 36 39 62 65  afee74b11e5869be
0040: 33 66 36 62 31 36 38 37 61 66 30 38 0a 55 20 73  3f6b1687af08.U s
0050: 74 65 70 68 61 6e 0a 57 20 31 35 36 38 38 0a 3c  tephan.W 15688.<
0060: 73 74 72 6f 6e 67 3e 41 43 48 54 55 4e 47 3a 20  strong>ACHTUNG: 
0070: 54 48 49 53 20 50 41 47 45 20 49 53 20 4e 4f 57  THIS PAGE IS NOW
0080: 20 4d 41 49 4e 54 41 49 4e 45 44 20 49 4e 20 54   MAINTAINED IN T
0090: 48 45 20 4e 45 57 20 57 49 4b 49 3a 3c 2f 73 74  HE NEW WIKI:</st
00a0: 72 6f 6e 67 3e 20 5b 68 74 74 70 3a 2f 2f 77 68  rong> [http://wh
00b0: 69 6b 69 2e 77 61 6e 64 65 72 69 6e 67 68 6f 72  iki.wanderinghor
00c0: 73 65 2e 6e 65 74 2f 77 69 6b 69 73 2f 63 73 6f  se.net/wikis/cso
00d0: 6e 2f 3f 70 61 67 65 3d 48 6f 77 54 6f 5d 0a 0a  n/?page=HowTo]..
00e0: 0a 53 65 65 20 61 6c 73 6f 3a 20 5b 54 69 70 73  .See also: [Tips
00f0: 41 6e 64 54 72 69 63 6b 73 5d 0d 0a 0d 0a 3c 68  AndTricks]....<h
0100: 31 3e 48 6f 77 20 74 6f 20 75 73 65 20 63 73 6f  1>How to use cso
0110: 6e 3c 2f 68 31 3e 0d 0a 0d 0a 54 68 69 73 20 70  n</h1>....This p
0120: 61 67 65 20 64 65 6d 6f 6e 73 74 72 61 74 65 73  age demonstrates
0130: 20 6a 75 73 74 20 61 62 6f 75 74 20 65 76 65 72   just about ever
0140: 79 74 68 69 6e 67 20 6f 6e 65 20 6e 65 65 64 73  ything one needs
0150: 20 74 6f 20 6b 6e 6f 77 20 69 6e 20 6f 72 64 65   to know in orde
0160: 72 20 74 6f 20 75 73 65 20 74 68 65 20 6c 69 62  r to use the lib
0170: 72 61 72 79 2e 20 46 75 6c 6c 20 64 65 74 61 69  rary. Full detai
0180: 6c 73 20 6f 66 20 74 68 65 20 74 79 70 65 73 20  ls of the types 
0190: 61 6e 64 20 66 75 6e 63 74 69 6f 6e 73 20 73 68  and functions sh
01a0: 6f 77 6e 20 68 65 72 65 20 61 72 65 20 69 6e 20  own here are in 
01b0: 74 68 65 20 41 50 49 20 64 6f 63 73 20 28 69 6e  the API docs (in
01c0: 20 3c 74 74 3e 63 73 6f 6e 2e 68 3c 2f 74 74 3e   <tt>cson.h</tt>
01d0: 29 2e 0d 0a 0d 0a 53 65 65 20 61 6c 73 6f 3a 20  ).....See also: 
01e0: 5b 63 73 6f 6e 5f 73 71 6c 69 74 65 33 5d 0d 0a  [cson_sqlite3]..
01f0: 0d 0a 3c 68 31 3e 43 6f 6d 70 69 6c 69 6e 67 3c  ..<h1>Compiling<
0200: 2f 68 31 3e 0d 0a 0d 0a 54 68 65 20 62 75 69 6c  /h1>....The buil
0210: 64 20 74 72 65 65 20 63 6f 6d 65 73 20 77 69 74  d tree comes wit
0220: 68 20 61 20 47 4e 55 20 4d 61 6b 65 66 69 6c 65  h a GNU Makefile
0230: 2e 20 49 66 20 79 6f 75 20 68 61 76 65 20 61 20  . If you have a 
0240: 64 69 66 66 65 72 65 6e 74 20 62 75 69 6c 64 20  different build 
0250: 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 20 74 68 65  environment, the
0260: 20 66 69 6c 65 73 20 79 6f 75 20 77 69 6c 6c 20   files you will 
0270: 6e 65 65 64 20 61 72 65 3a 0d 0a 0d 0a 20 20 20  need are:....   
0280: 2a 20 20 3c 74 74 3e 69 6e 63 6c 75 64 65 2f 77  *  <tt>include/w
0290: 68 2f 63 73 6f 6e 2f 63 73 6f 6e 2e 68 3c 2f 74  h/cson/cson.h</t
02a0: 74 3e 20 28 70 75 62 6c 69 63 20 41 50 49 20 61  t> (public API a
02b0: 6e 64 20 64 6f 63 73 29 0d 0a 20 20 20 2a 20 20  nd docs)..   *  
02c0: 3c 74 74 3e 63 73 6f 6e 2e 63 3c 2f 74 74 3e 20  <tt>cson.c</tt> 
02d0: 28 74 68 65 20 63 6f 72 65 20 6c 69 62 72 61 72  (the core librar
02e0: 79 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  y implementation
02f0: 29 0d 0a 20 20 20 2a 20 20 3c 74 74 3e 63 73 6f  )..   *  <tt>cso
0300: 6e 5f 6c 69 73 74 73 2e 68 3c 2f 74 74 3e 20 28  n_lists.h</tt> (
0310: 75 74 69 6c 69 74 79 20 63 6f 64 65 20 75 73 65  utility code use
0320: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
0330: 74 68 65 20 63 6f 72 65 20 6c 69 62 72 61 72 79  the core library
0340: 29 0d 0a 20 20 20 2a 20 20 3c 74 74 3e 70 61 72  )..   *  <tt>par
0350: 73 65 72 2f 4a 53 4f 4e 5f 70 61 72 73 65 72 2e  ser/JSON_parser.
0360: 7b 63 2c 68 7d 3c 2f 74 74 3e 20 28 74 68 65 20  {c,h}</tt> (the 
0370: 75 6e 64 65 72 6c 79 69 6e 67 20 69 6e 70 75 74  underlying input
0380: 20 70 61 72 73 65 72 29 0d 0a 0d 0a 54 68 65 20   parser)....The 
0390: 3c 74 74 3e 74 65 73 74 2e 63 3c 2f 74 74 3e 20  <tt>test.c</tt> 
03a0: 61 6e 64 20 3c 74 74 3e 6a 73 6f 6e 2d 70 61 72  and <tt>json-par
03b0: 73 65 72 2e 63 3c 2f 74 74 3e 20 70 72 6f 67 72  ser.c</tt> progr
03c0: 61 6d 73 20 64 65 6d 6f 6e 73 74 72 61 74 65 20  ams demonstrate 
03d0: 68 6f 77 20 74 6f 20 75 73 65 20 69 74 2e 0d 0a  how to use it...
03e0: 0d 0a 41 6c 74 65 72 6e 61 74 65 6c 79 20 28 61  ..Alternately (a
03f0: 6e 64 20 6d 6f 72 65 20 73 69 6d 70 6c 79 29 2c  nd more simply),
0400: 20 79 6f 75 20 63 61 6e 20 75 73 65 20 5b 41 6d   you can use [Am
0410: 61 6c 67 61 6d 61 74 69 6f 6e 42 75 69 6c 64 7c  algamationBuild|
0420: 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e  the amalgamation
0430: 20 62 75 69 6c 64 5d 2e 0d 0a 0d 0a 49 74 20 73   build].....It s
0440: 68 6f 75 6c 64 20 63 6f 6d 70 69 6c 65 20 63 6c  hould compile cl
0450: 65 61 6e 6c 79 20 6f 6e 20 33 32 2d 20 61 6e 64  eanly on 32- and
0460: 20 36 34 2d 62 69 74 20 70 6c 61 74 66 6f 72 6d   64-bit platform
0470: 73 20 69 6e 20 43 38 39 20 6d 6f 64 65 2e 0d 0a  s in C89 mode...
0480: 0d 0a 49 74 20 68 61 73 20 6e 6f 20 33 72 64 2d  ..It has no 3rd-
0490: 70 61 72 74 79 20 64 65 70 65 6e 64 65 6e 63 69  party dependenci
04a0: 65 73 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  es other than th
04b0: 65 20 5b 68 74 74 70 3a 2f 2f 66 61 72 61 2e 63  e [http://fara.c
04c0: 73 2e 75 6e 69 2d 70 6f 74 73 64 61 6d 2e 64 65  s.uni-potsdam.de
04d0: 2f 7e 6a 73 67 2f 6a 73 6f 6e 5f 70 61 72 73 65  /~jsg/json_parse
04e0: 72 2f 7c 75 6e 64 65 72 6c 79 69 6e 67 20 4a 53  r/|underlying JS
04f0: 4f 4e 5f 70 61 72 73 65 72 20 63 6f 64 65 5d 2c  ON_parser code],
0500: 20 77 68 69 63 68 20 69 73 20 69 6e 63 6c 75 64   which is includ
0510: 65 64 20 69 6e 20 74 68 65 20 73 6f 75 72 63 65  ed in the source
0520: 20 74 72 65 65 2e 20 54 68 65 20 4a 53 4f 4e 5f   tree. The JSON_
0530: 70 61 72 73 65 72 20 63 6f 64 65 20 69 73 20 61  parser code is a
0540: 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
0550: 20 64 65 74 61 69 6c 2c 20 6e 6f 74 20 70 61 72   detail, not par
0560: 74 20 6f 66 20 74 68 65 20 70 75 62 6c 69 63 20  t of the public 
0570: 41 50 49 2e 20 54 68 65 20 70 6f 69 6e 74 20 69  API. The point i
0580: 73 3a 20 72 65 6c 79 20 6f 6e 6c 79 20 6f 6e 20  s: rely only on 
0590: 74 68 65 20 64 6f 63 75 6d 65 6e 74 65 64 20 70  the documented p
05a0: 75 62 6c 69 63 20 41 50 49 20 69 6e 20 3c 74 74  ublic API in <tt
05b0: 3e 63 73 6f 6e 2e 68 3c 2f 74 74 3e 2e 0d 0a 0d  >cson.h</tt>....
05c0: 0a 3c 68 31 3e 41 50 49 20 44 6f 63 73 3c 2f 68  .<h1>API Docs</h
05d0: 31 3e 0d 0a 0d 0a 54 68 65 20 41 50 49 20 64 6f  1>....The API do
05e0: 63 73 20 61 72 65 20 69 6e 20 3c 74 74 3e 63 73  cs are in <tt>cs
05f0: 6f 6e 2e 68 3c 2f 74 74 3e 2c 20 61 6e 64 20 64  on.h</tt>, and d
0600: 6f 78 79 67 65 6e 20 63 61 6e 20 62 65 20 75 73  oxygen can be us
0610: 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 74 68  ed to process th
0620: 65 6d 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74 69 6d  em:....<verbatim
0630: 3e 0d 0a 7e 3e 20 63 64 20 64 6f 63 0d 0a 7e 3e  >..~> cd doc..~>
0640: 20 6d 61 6b 65 20 64 6f 63 0d 0a 3c 2f 76 65 72   make doc..</ver
0650: 62 61 74 69 6d 3e 0d 0a 0d 0a 3c 68 31 3e 47 65  batim>....<h1>Ge
0660: 6e 65 72 61 74 69 6e 67 20 4a 53 4f 4e 3c 2f 68  nerating JSON</h
0670: 31 3e 0d 0a 0d 0a 4a 53 4f 4e 20 69 73 20 74 79  1>....JSON is ty
0680: 70 69 63 61 6c 6c 79 20 67 65 6e 65 72 61 74 65  pically generate
0690: 64 20 62 79 20 70 6f 70 75 6c 61 74 69 6e 67 20  d by populating 
06a0: 61 20 72 6f 6f 74 2d 6c 65 76 65 6c 20 6f 62 6a  a root-level obj
06b0: 65 63 74 20 6f 72 20 61 72 72 61 79 20 77 69 74  ect or array wit
06c0: 68 20 76 61 6c 75 65 73 2c 20 61 73 20 73 68 6f  h values, as sho
06d0: 77 6e 20 68 65 72 65 2e 0d 0a 0d 0a 3c 76 65 72  wn here.....<ver
06e0: 62 61 74 69 6d 3e 0d 0a 2f 2f 20 43 72 65 61 74  batim>..// Creat
06f0: 65 20 61 20 72 6f 6f 74 20 6f 62 6a 65 63 74 3a  e a root object:
0700: 0d 0a 63 73 6f 6e 5f 76 61 6c 75 65 20 2a 20 6f  ..cson_value * o
0710: 62 6a 56 20 3d 20 63 73 6f 6e 5f 76 61 6c 75 65  bjV = cson_value
0720: 5f 6e 65 77 5f 6f 62 6a 65 63 74 28 29 3b 0d 0a  _new_object();..
0730: 2f 2f 20 4f 62 6a 65 63 74 73 2c 20 41 72 72 61  // Objects, Arra
0740: 79 73 2c 20 61 6e 64 20 53 74 72 69 6e 67 73 20  ys, and Strings 
0750: 61 72 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  are represented 
0760: 62 79 20 68 69 67 68 65 72 2d 6c 65 76 65 6c 0d  by higher-level.
0770: 0a 2f 2f 20 6f 62 6a 65 63 74 73 20 6f 77 6e 65  .// objects owne
0780: 64 20 62 79 20 74 68 65 69 72 20 63 6f 6e 74 61  d by their conta
0790: 69 6e 69 6e 67 20 63 73 6f 6e 5f 76 61 6c 75 65  ining cson_value
07a0: 2c 20 73 6f 20 77 65 20 66 65 74 63 68 0d 0a 2f  , so we fetch../
07b0: 2f 20 74 68 61 74 20 4f 62 6a 65 63 74 3a 0d 0a  / that Object:..
07c0: 63 73 6f 6e 5f 6f 62 6a 65 63 74 20 2a 20 6f 62  cson_object * ob
07d0: 6a 20 3d 20 63 73 6f 6e 5f 76 61 6c 75 65 5f 67  j = cson_value_g
07e0: 65 74 5f 6f 62 6a 65 63 74 28 6f 62 6a 56 29 3b  et_object(objV);
07f0: 0d 0a 2f 2f 20 41 63 68 75 6e 74 67 3a 20 64 65  ..// Achuntg: de
0800: 73 74 72 6f 79 69 6e 67 20 6f 62 6a 56 20 77 69  stroying objV wi
0810: 6c 6c 20 61 6c 73 6f 20 69 6e 76 61 6c 69 64 61  ll also invalida
0820: 74 65 2f 64 65 73 74 72 6f 79 20 6f 62 6a 2e 0d  te/destroy obj..
0830: 0a 0d 0a 2f 2f 20 41 64 64 20 73 6f 6d 65 20 76  ...// Add some v
0840: 61 6c 75 65 73 20 74 6f 20 69 74 3a 0d 0a 63 73  alues to it:..cs
0850: 6f 6e 5f 6f 62 6a 65 63 74 5f 73 65 74 28 20 6f  on_object_set( o
0860: 62 6a 2c 20 22 6d 79 49 6e 74 22 2c 20 63 73 6f  bj, "myInt", cso
0870: 6e 5f 76 61 6c 75 65 5f 6e 65 77 5f 69 6e 74 65  n_value_new_inte
0880: 67 65 72 28 34 32 29 20 29 3b 0d 0a 63 73 6f 6e  ger(42) );..cson
0890: 5f 6f 62 6a 65 63 74 5f 73 65 74 28 20 6f 62 6a  _object_set( obj
08a0: 2c 20 22 6d 79 44 6f 75 62 6c 65 22 2c 20 63 73  , "myDouble", cs
08b0: 6f 6e 5f 76 61 6c 75 65 5f 6e 65 77 5f 64 6f 75  on_value_new_dou
08c0: 62 6c 65 28 34 32 2e 32 34 29 20 29 3b 0d 0a 0d  ble(42.24) );...
08d0: 0a 2f 2f 20 41 64 64 20 61 6e 20 61 72 72 61 79  .// Add an array
08e0: 3a 0d 0a 63 73 6f 6e 5f 76 61 6c 75 65 20 2a 20  :..cson_value * 
08f0: 61 72 56 20 3d 20 63 73 6f 6e 5f 76 61 6c 75 65  arV = cson_value
0900: 5f 6e 65 77 5f 61 72 72 61 79 28 29 3b 0d 0a 63  _new_array();..c
0910: 73 6f 6e 5f 6f 62 6a 65 63 74 5f 73 65 74 28 20  son_object_set( 
0920: 6f 62 6a 2c 20 22 6d 79 41 72 72 61 79 22 2c 20  obj, "myArray", 
0930: 61 72 56 20 29 3b 20 2f 2f 20 74 72 61 6e 73 66  arV ); // transf
0940: 65 72 73 20 6f 77 6e 65 72 73 68 69 70 20 6f 66  ers ownership of
0950: 20 61 72 56 20 74 6f 20 6f 62 6a 0d 0a 63 73 6f   arV to obj..cso
0960: 6e 5f 61 72 72 61 79 20 2a 20 61 72 20 3d 20 63  n_array * ar = c
0970: 73 6f 6e 5f 76 61 6c 75 65 5f 67 65 74 5f 61 72  son_value_get_ar
0980: 72 61 79 28 61 72 56 29 3b 0d 0a 63 73 6f 6e 5f  ray(arV);..cson_
0990: 61 72 72 61 79 5f 73 65 74 28 20 61 72 2c 20 30  array_set( ar, 0
09a0: 2c 20 63 73 6f 6e 5f 6e 65 77 5f 76 61 6c 75 65  , cson_new_value
09b0: 5f 73 74 72 69 6e 67 28 22 48 69 2c 20 77 6f 72  _string("Hi, wor
09c0: 6c 64 21 22 2c 20 31 30 29 20 29 3b 0d 0a 0d 0a  ld!", 10) );....
09d0: 2f 2f 20 4f 75 74 70 75 74 20 69 74 20 74 6f 20  // Output it to 
09e0: 73 74 64 6f 75 74 3a 0d 0a 63 73 6f 6e 5f 6f 75  stdout:..cson_ou
09f0: 74 70 75 74 5f 46 49 4c 45 28 20 6f 62 6a 56 2c  tput_FILE( objV,
0a00: 20 73 74 64 6f 75 74 2c 20 4e 55 4c 4c 20 29 3b   stdout, NULL );
0a10: 0d 0a 0d 0a 2f 2f 20 46 72 65 65 20 75 70 20 74  ....// Free up t
0a20: 68 65 20 72 6f 6f 74 20 61 6e 64 20 61 6c 6c 20  he root and all 
0a30: 76 61 6c 75 65 73 20 69 74 20 6f 77 6e 73 3a 0d  values it owns:.
0a40: 0a 63 73 6f 6e 5f 76 61 6c 75 65 5f 66 72 65 65  .cson_value_free
0a50: 28 20 6f 62 6a 56 20 29 3b 0d 0a 3c 2f 76 65 72  ( objV );..</ver
0a60: 62 61 74 69 6d 3e 0d 0a 0d 0a 3c 73 74 72 6f 6e  batim>....<stron
0a70: 67 20 73 74 79 6c 65 3d 27 63 6f 6c 6f 72 3a 72  g style='color:r
0a80: 65 64 27 3e 41 43 48 54 55 4e 47 20 41 43 48 54  ed'>ACHTUNG ACHT
0a90: 55 4e 47 20 41 43 48 54 55 4e 47 3a 3c 2f 73 74  UNG ACHTUNG:</st
0aa0: 72 6f 6e 67 3e 20 69 74 20 69 73 20 63 72 69 74  rong> it is crit
0ab0: 69 63 61 6c 20 74 68 61 74 20 61 72 72 61 79 2f  ical that array/
0ac0: 6f 62 6a 65 63 74 20 76 61 6c 75 65 73 20 64 6f  object values do
0ad0: 20 6e 6f 74 20 66 6f 72 6d 20 63 79 63 6c 65 73   not form cycles
0ae0: 20 3c 65 6d 3e 61 6e 79 77 68 65 72 65 3c 2f 65   <em>anywhere</e
0af0: 6d 3e 20 28 77 68 65 74 68 65 72 20 61 63 72 6f  m> (whether acro
0b00: 73 73 20 63 6f 6e 74 61 69 6e 65 72 73 20 6f 72  ss containers or
0b10: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
0b20: 20 63 6f 6e 74 61 69 6e 65 72 29 2e 20 49 6e 20   container). In 
0b30: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
0b40: 72 65 20 6d 61 79 20 62 65 20 3c 65 6d 3e 61 62  re may be <em>ab
0b50: 73 6f 6c 75 74 65 6c 79 20 6e 6f 3c 2f 65 6d 3e  solutely no</em>
0b60: 20 63 69 72 63 75 6c 61 72 20 72 65 66 65 72 65   circular refere
0b70: 6e 63 65 73 2e 20 49 66 20 74 68 65 72 65 20 61  nces. If there a
0b80: 72 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  re, the results 
0b90: 77 69 6c 6c 20 62 65 20 6c 65 61 6b 73 20 61 6e  will be leaks an
0ba0: 64 2f 6f 72 20 63 6f 72 72 75 70 74 69 6f 6e 20  d/or corruption 
0bb0: 61 6e 64 2f 6f 72 20 63 72 61 73 68 65 73 20 64  and/or crashes d
0bc0: 75 65 20 74 6f 20 64 6f 75 62 6c 65 2d 3c 74 74  ue to double-<tt
0bd0: 3e 66 72 65 65 28 29 3c 2f 74 74 3e 73 2e 0d 0a  >free()</tt>s...
0be0: 0d 0a 41 73 20 6f 66 20 32 30 31 31 30 33 32 35  ..As of 20110325
0bf0: 20 69 74 20 69 73 20 6c 65 67 61 6c 20 66 6f 72   it is legal for
0c00: 20 61 20 67 69 76 65 6e 20 76 61 6c 75 65 20 69   a given value i
0c10: 6e 73 74 61 6e 63 65 20 74 6f 20 62 65 20 69 6e  nstance to be in
0c20: 73 65 72 74 65 64 20 69 6e 74 6f 20 6d 75 6c 74  serted into mult
0c30: 69 70 6c 65 20 63 6f 6e 74 61 69 6e 65 72 73 20  iple containers 
0c40: 6f 72 20 69 6e 74 6f 20 74 68 65 20 73 61 6d 65  or into the same
0c50: 20 63 6f 6e 74 61 69 6e 65 72 20 6d 75 6c 74 69   container multi
0c60: 70 6c 65 20 74 69 6d 65 73 2c 20 70 72 6f 76 69  ple times, provi
0c70: 64 65 64 20 74 68 61 74 20 6e 6f 20 63 79 63 6c  ded that no cycl
0c80: 65 73 20 61 72 65 20 69 6e 74 72 6f 64 75 63 65  es are introduce
0c90: 64 20 28 73 65 65 20 61 62 6f 76 65 29 2e 20 54  d (see above). T
0ca0: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 74 65 72  he library inter
0cb0: 6e 61 6c 6c 79 20 72 65 66 65 72 65 6e 63 65 2d  nally reference-
0cc0: 63 6f 75 6e 74 73 20 74 68 65 20 76 61 6c 75 65  counts the value
0cd0: 73 20 61 6e 64 20 74 68 65 79 20 77 69 6c 6c 20  s and they will 
0ce0: 62 65 20 63 6c 65 61 6e 65 64 20 75 70 20 77 68  be cleaned up wh
0cf0: 65 6e 20 74 68 65 20 6c 61 73 74 20 63 6f 6e 74  en the last cont
0d00: 61 69 6e 65 72 20 68 6f 6c 64 69 6e 67 20 74 68  ainer holding th
0d10: 61 74 20 76 61 6c 75 65 20 69 73 20 63 6c 65 61  at value is clea
0d20: 6e 65 64 20 75 70 2e 0d 0a 0d 0a 3c 68 32 3e 4f  ned up.....<h2>O
0d30: 75 74 70 75 74 69 6e 67 20 74 6f 20 61 20 73 74  utputing to a st
0d40: 72 69 6e 67 20 62 75 66 66 65 72 3c 2f 68 32 3e  ring buffer</h2>
0d50: 0d 0a 0d 0a 54 6f 20 6f 75 74 70 75 74 20 79 6f  ....To output yo
0d60: 75 72 20 4a 53 4f 4e 20 6f 62 6a 65 63 74 73 20  ur JSON objects 
0d70: 74 6f 20 61 20 73 74 72 69 6e 67 20 62 75 66 66  to a string buff
0d80: 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
0d90: 46 49 4c 45 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74  FILE:....<verbat
0da0: 69 6d 3e 0d 0a 63 73 6f 6e 5f 62 75 66 66 65 72  im>..cson_buffer
0db0: 20 62 75 66 20 3d 20 63 73 6f 6e 5f 62 75 66 66   buf = cson_buff
0dc0: 65 72 5f 65 6d 70 74 79 3b 0d 0a 69 6e 74 20 72  er_empty;..int r
0dd0: 63 20 3d 20 63 73 6f 6e 5f 6f 75 74 70 75 74 5f  c = cson_output_
0de0: 62 75 66 66 65 72 28 20 6f 62 6a 56 2c 20 26 62  buffer( objV, &b
0df0: 75 66 2c 20 4e 55 4c 4c 20 29 3b 0d 0a 69 66 28  uf, NULL );..if(
0e00: 20 30 20 21 3d 20 72 63 20 29 20 7b 20 2e 2e 2e   0 != rc ) { ...
0e10: 20 65 72 72 6f 72 20 2e 2e 2e 20 7d 0d 0a 65 6c   error ... }..el
0e20: 73 65 20 7b 0d 0a 20 20 20 4a 53 4f 4e 20 64 61  se {..   JSON da
0e30: 74 61 20 69 73 20 74 68 65 20 66 69 72 73 74 20  ta is the first 
0e40: 28 62 75 66 2e 75 73 65 64 29 20 62 79 74 65 73  (buf.used) bytes
0e50: 20 6f 66 20 28 62 75 66 2e 6d 65 6d 29 2e 0d 0a   of (buf.mem)...
0e60: 7d 0d 0a 2f 2f 20 52 65 67 61 72 64 6c 65 73 73  }..// Regardless
0e70: 20 6f 66 20 73 75 63 63 65 73 73 20 6f 72 20 66   of success or f
0e80: 61 69 6c 75 72 65 2c 20 6d 61 6b 65 20 73 75 72  ailure, make sur
0e90: 65 20 74 6f 20 65 69 74 68 65 72 0d 0a 2f 2f 20  e to either..// 
0ea0: 63 6c 65 61 6e 20 75 70 20 74 68 65 20 62 75 66  clean up the buf
0eb0: 66 65 72 3a 0d 0a 7b 0d 0a 20 20 63 73 6f 6e 5f  fer:..{..  cson_
0ec0: 62 75 66 66 65 72 5f 72 65 73 65 72 76 65 28 20  buffer_reserve( 
0ed0: 26 62 75 66 2c 20 30 20 29 3a 0d 0a 7d 0d 0a 2f  &buf, 0 ):..}../
0ee0: 2f 20 6f 72 20 74 61 6b 65 20 6f 76 65 72 20 6f  / or take over o
0ef0: 77 6e 65 72 73 68 69 70 20 6f 66 20 69 74 73 20  wnership of its 
0f00: 62 79 74 65 73 3a 0d 0a 7b 0d 0a 20 20 20 63 68  bytes:..{..   ch
0f10: 61 72 20 2a 20 6d 65 6d 20 3d 20 28 63 68 61 72  ar * mem = (char
0f20: 20 2a 29 62 75 66 2e 6d 65 6d 3b 0d 0a 20 20 20   *)buf.mem;..   
0f30: 2f 2f 20 6d 65 6d 20 69 73 20 28 62 75 66 2e 63  // mem is (buf.c
0f40: 61 70 61 63 69 74 79 29 20 62 79 74 65 73 20 6c  apacity) bytes l
0f50: 6f 6e 67 2c 20 6f 66 20 77 68 69 63 68 20 28 62  ong, of which (b
0f60: 75 66 2e 75 73 65 64 29 0d 0a 20 20 20 2f 2f 20  uf.used)..   // 
0f70: 61 72 65 20 22 75 73 65 64 22 20 28 74 68 65 79  are "used" (they
0f80: 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 4a 53 4f   contain the JSO
0f90: 4e 20 64 61 74 61 20 69 6e 20 74 68 69 73 20 63  N data in this c
0fa0: 61 73 65 29 2e 0d 0a 20 20 20 62 75 66 20 3d 20  ase)...   buf = 
0fb0: 63 73 6f 6e 5f 62 75 66 66 65 72 5f 65 6d 70 74  cson_buffer_empt
0fc0: 79 3b 0d 0a 20 20 20 2e 2e 2e 20 79 6f 75 20 6e  y;..   ... you n
0fd0: 6f 77 20 6f 77 6e 20 74 68 65 20 62 75 66 66 65  ow own the buffe
0fe0: 72 27 73 20 6d 65 6d 6f 72 79 20 61 6e 64 20 6d  r's memory and m
0ff0: 75 73 74 20 65 76 65 6e 74 75 61 6c 6c 79 20 66  ust eventually f
1000: 72 65 65 28 29 20 69 74 20 2e 2e 2e 0d 0a 7d 0d  ree() it .....}.
1010: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0d 0a 0d 0a  .</verbatim>....
1020: 3c 68 32 3e 43 68 61 6e 67 69 6e 67 20 46 6f 72  <h2>Changing For
1030: 6d 61 74 74 69 6e 67 20 4f 70 74 69 6f 6e 73 3c  matting Options<
1040: 2f 68 32 3e 0d 0a 0d 0a 54 68 65 20 3c 74 74 3e  /h2>....The <tt>
1050: 63 73 6f 6e 5f 6f 75 74 70 75 74 28 29 3c 2f 74  cson_output()</t
1060: 74 3e 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  t> family of fun
1070: 63 74 69 6f 6e 73 20 61 6c 6c 20 74 61 6b 65 20  ctions all take 
1080: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 3c 74 74 3e  an optional <tt>
1090: 63 73 6f 6e 5f 6f 75 74 70 75 74 5f 6f 70 74 3c  cson_output_opt<
10a0: 2f 74 74 3e 20 61 72 67 75 6d 65 6e 74 20 77 68  /tt> argument wh
10b0: 69 63 68 20 63 61 6e 20 62 65 20 75 73 65 20 6c  ich can be use l
10c0: 69 6b 65 20 74 68 69 73 3a 0d 0a 0d 0a 3c 76 65  ike this:....<ve
10d0: 72 62 61 74 69 6d 3e 0d 0a 63 73 6f 6e 5f 6f 75  rbatim>..cson_ou
10e0: 74 70 75 74 5f 6f 70 74 20 6f 70 74 20 3d 20 63  tput_opt opt = c
10f0: 73 6f 6e 5f 6f 75 74 70 75 74 5f 6f 70 74 5f 65  son_output_opt_e
1100: 6d 70 74 79 3b 0d 0a 6f 70 74 2e 61 64 64 4e 65  mpty;..opt.addNe
1110: 77 6c 69 6e 65 20 3d 20 31 3b 20 2f 2f 20 62 6f  wline = 1; // bo
1120: 6f 6c 65 61 6e 3a 20 61 64 64 20 61 20 6e 65 77  olean: add a new
1130: 6c 69 6e 65 20 74 6f 20 74 68 65 20 66 69 6e 61  line to the fina
1140: 6c 20 6f 75 74 70 75 74 3f 0d 0a 6f 70 74 2e 6d  l output?..opt.m
1150: 61 78 44 65 70 74 68 20 3d 20 31 35 3b 20 2f 2f  axDepth = 15; //
1160: 20 77 69 6c 6c 20 65 72 72 6f 72 20 6f 75 74 20   will error out 
1170: 69 66 20 74 68 65 20 74 72 65 65 20 69 73 20 64  if the tree is d
1180: 65 65 70 65 72 20 74 68 61 6e 20 74 68 69 73 0d  eeper than this.
1190: 0a 6f 70 74 2e 69 6e 64 65 6e 74 61 74 69 6f 6e  .opt.indentation
11a0: 20 3d 20 31 3b 20 2f 2f 28 30 29 3d 6f 66 66 2c   = 1; //(0)=off,
11b0: 20 28 31 29 3d 31 20 74 61 62 2f 6c 65 76 65 6c   (1)=1 tab/level
11c0: 2c 20 28 3e 31 29 3d 74 68 61 74 20 6d 61 6e 79  , (>1)=that many
11d0: 20 73 70 61 63 65 73 2f 6c 65 76 65 6c 0d 0a 63   spaces/level..c
11e0: 73 6f 6e 5f 6f 75 74 70 75 74 5f 46 49 4c 45 28  son_output_FILE(
11f0: 20 6d 79 56 61 6c 75 65 2c 20 73 74 64 6f 75 74   myValue, stdout
1200: 2c 20 26 6f 70 74 20 29 3b 0d 0a 3c 2f 76 65 72  , &opt );..</ver
1210: 62 61 74 69 6d 3e 0d 0a 0d 0a 3c 68 31 3e 52 65  batim>....<h1>Re
1220: 61 64 69 6e 67 20 4a 53 4f 4e 3c 2f 68 31 3e 0d  ading JSON</h1>.
1230: 0a 0d 0a 49 74 27 73 20 70 72 65 74 74 79 20 65  ...It's pretty e
1240: 61 73 79 3a 20 73 65 6c 65 63 74 20 61 6e 20 69  asy: select an i
1250: 6e 70 75 74 20 73 6f 75 72 63 65 20 61 6e 64 20  nput source and 
1260: 74 65 6c 6c 20 3c 74 74 3e 63 73 6f 6e 5f 70 61  tell <tt>cson_pa
1270: 72 73 65 28 29 3c 2f 74 74 3e 20 74 6f 20 75 73  rse()</tt> to us
1280: 65 20 69 74 2e 2e 2e 0d 0a 0d 0a 3c 76 65 72 62  e it.......<verb
1290: 61 74 69 6d 3e 0d 0a 63 73 6f 6e 5f 76 61 6c 75  atim>..cson_valu
12a0: 65 20 2a 20 72 6f 6f 74 20 3d 20 4e 55 4c 4c 3b  e * root = NULL;
12b0: 0d 0a 69 6e 74 20 72 63 20 3d 20 63 73 6f 6e 5f  ..int rc = cson_
12c0: 70 61 72 73 65 5f 46 49 4c 45 28 20 26 72 6f 6f  parse_FILE( &roo
12d0: 74 2c 20 73 74 64 69 6e 2c 20 4e 55 4c 4c 2c 20  t, stdin, NULL, 
12e0: 4e 55 4c 4c 20 29 3b 0d 0a 2f 2f 20 54 68 65 20  NULL );..// The 
12f0: 4e 55 4c 4c 20 61 72 67 75 6d 65 6e 74 73 20 68  NULL arguments h
1300: 6f 6c 64 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 66  old optional inf
1310: 6f 72 6d 61 74 69 6f 6e 20 66 6f 72 2f 61 62 6f  ormation for/abo
1320: 75 74 0d 0a 2f 2f 20 74 68 65 20 70 61 72 73 65  ut..// the parse
1330: 20 72 65 73 75 6c 74 73 2e 20 54 68 65 73 65 20   results. These 
1340: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 73  can be used to s
1350: 65 74 20 63 65 72 74 61 69 6e 0d 0a 2f 2f 20 70  et certain..// p
1360: 61 72 73 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  arsing options a
1370: 6e 64 20 67 65 74 20 6d 6f 72 65 20 64 65 74 61  nd get more deta
1380: 69 6c 65 64 20 65 72 72 6f 72 20 69 6e 66 6f 72  iled error infor
1390: 6d 61 74 69 6f 6e 0d 0a 2f 2f 20 69 66 20 70 61  mation..// if pa
13a0: 72 73 69 6e 67 20 66 61 69 6c 73 2e 0d 0a 0d 0a  rsing fails.....
13b0: 69 66 28 20 30 20 21 3d 20 72 63 20 29 20 7b 0d  if( 0 != rc ) {.
13c0: 0a 20 20 20 70 72 69 6e 74 66 28 22 45 72 72 6f  .   printf("Erro
13d0: 72 20 63 6f 64 65 20 25 64 20 28 25 73 29 21 5c  r code %d (%s)!\
13e0: 6e 22 2c 20 72 63 2c 20 63 73 6f 6e 5f 72 63 5f  n", rc, cson_rc_
13f0: 73 74 72 69 6e 67 28 72 63 29 20 29 3b 0d 0a 20  string(rc) );.. 
1400: 20 20 72 65 74 75 72 6e 20 2e 2e 2e 3b 0d 0a 7d    return ...;..}
1410: 0d 0a 0d 0a 69 66 28 20 63 73 6f 6e 5f 76 61 6c  ....if( cson_val
1420: 75 65 5f 69 73 5f 6f 62 6a 65 63 74 28 72 6f 6f  ue_is_object(roo
1430: 74 29 20 29 20 7b 0d 0a 20 20 20 20 63 73 6f 6e  t) ) {..    cson
1440: 5f 6f 62 6a 65 63 74 20 2a 20 6f 62 6a 20 3d 20  _object * obj = 
1450: 63 73 6f 6e 5f 76 61 6c 75 65 5f 67 65 74 5f 6f  cson_value_get_o
1460: 62 6a 65 63 74 28 72 6f 6f 74 29 3b 0d 0a 20 20  bject(root);..  
1470: 20 20 2e 2e 2e 0d 0a 7d 0d 0a 65 6c 73 65 20 69    .....}..else i
1480: 66 28 20 63 73 6f 6e 5f 76 61 6c 75 65 5f 69 73  f( cson_value_is
1490: 5f 61 72 72 61 79 28 72 6f 6f 74 29 20 29 20 7b  _array(root) ) {
14a0: 0d 0a 20 20 20 20 63 73 6f 6e 5f 61 72 72 61 79  ..    cson_array
14b0: 20 2a 20 61 72 20 3d 20 63 73 6f 6e 5f 76 61 6c   * ar = cson_val
14c0: 75 65 5f 67 65 74 5f 61 72 72 61 79 28 72 6f 6f  ue_get_array(roo
14d0: 74 29 3b 0d 0a 20 20 20 20 2e 2e 2e 0d 0a 7d 0d  t);..    .....}.
14e0: 0a 65 6c 73 65 20 7b 0d 0a 20 20 20 2f 2f 20 22  .else {..   // "
14f0: 43 61 6e 6e 6f 74 20 68 61 70 70 65 6e 22 20 62  Cannot happen" b
1500: 65 63 61 75 73 65 20 70 61 72 73 65 20 77 6f 75  ecause parse wou
1510: 6c 64 20 66 61 69 6c 20 69 6e 20 74 68 69 73 20  ld fail in this 
1520: 63 61 73 65 2e 0d 0a 7d 0d 0a 0d 0a 2f 2f 20 43  case...}....// C
1530: 6c 65 61 6e 20 75 70 3a 0d 0a 63 73 6f 6e 5f 76  lean up:..cson_v
1540: 61 6c 75 65 5f 66 72 65 65 28 72 6f 6f 74 29 3b  alue_free(root);
1550: 0d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0d 0a 0d  ..</verbatim>...
1560: 0a 59 6f 75 20 63 61 6e 20 75 73 65 20 3c 74 74  .You can use <tt
1570: 3e 63 73 6f 6e 5f 70 61 72 73 65 5f 73 74 72 69  >cson_parse_stri
1580: 6e 67 28 29 3c 2f 74 74 3e 20 74 6f 20 72 65 61  ng()</tt> to rea
1590: 64 20 4a 53 4f 4e 20 66 72 6f 6d 20 73 74 72 69  d JSON from stri
15a0: 6e 67 2e 20 53 65 65 20 62 65 6c 6f 77 20 66 6f  ng. See below fo
15b0: 72 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  r an example of 
15c0: 63 72 65 61 74 69 6e 67 20 79 6f 75 72 20 6f 77  creating your ow
15d0: 6e 20 69 6e 70 75 74 20 73 6f 75 72 63 65 2e 0d  n input source..
15e0: 0a 0d 0a 54 68 65 20 4f 62 6a 65 63 74 20 61 6e  ...The Object an
15f0: 64 20 41 72 72 61 79 20 41 50 49 73 20 70 72 6f  d Array APIs pro
1600: 76 69 64 65 20 6d 65 63 68 61 6e 69 73 6d 20 66  vide mechanism f
1610: 6f 72 20 61 64 64 69 6e 67 2c 20 66 65 74 63 68  or adding, fetch
1620: 69 6e 67 2c 20 61 6e 64 20 74 72 61 76 65 72 73  ing, and travers
1630: 69 6e 67 20 74 68 65 20 63 68 69 6c 64 20 65 6c  ing the child el
1640: 65 6d 65 6e 74 73 2e 0d 0a 0d 0a 3c 68 31 3e 54  ements.....<h1>T
1650: 72 61 76 65 72 73 69 6e 67 20 61 6e 64 20 66 65  raversing and fe
1660: 74 63 68 69 6e 67 20 76 61 6c 75 65 73 20 66 72  tching values fr
1670: 6f 6d 20 4a 53 4f 4e 20 41 72 72 61 79 73 20 61  om JSON Arrays a
1680: 6e 64 20 4f 62 6a 65 63 74 73 3c 2f 68 31 3e 0d  nd Objects</h1>.
1690: 0a 0d 0a 48 65 72 65 20 61 72 65 20 65 78 61 6d  ...Here are exam
16a0: 70 6c 65 73 20 6f 66 20 68 6f 77 20 74 6f 20 66  ples of how to f
16b0: 65 74 63 68 20 61 6e 64 20 74 72 61 76 65 72 73  etch and travers
16c0: 65 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 41 72  e values from Ar
16d0: 72 61 79 73 20 61 6e 64 20 4f 62 6a 65 63 74 73  rays and Objects
16e0: 3a 0d 0a 0d 0a 46 6f 72 20 74 68 65 20 66 6f 6c  :....For the fol
16f0: 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65 73 2c  lowing examples,
1700: 20 61 73 73 75 6d 65 20 74 68 61 74 20 3c 74 74   assume that <tt
1710: 3e 6f 62 6a 3c 2f 74 74 3e 20 69 73 20 61 20 70  >obj</tt> is a p
1720: 6f 70 75 6c 61 74 65 64 20 3c 74 74 3e 63 73 6f  opulated <tt>cso
1730: 6e 5f 6f 62 6a 65 63 74 3c 2f 74 74 3e 0d 0a 61  n_object</tt>..a
1740: 6e 64 20 3c 74 74 3e 61 72 3c 2f 74 74 3e 20 69  nd <tt>ar</tt> i
1750: 73 20 61 20 70 6f 70 75 6c 61 74 65 64 20 3c 74  s a populated <t
1760: 74 3e 63 73 6f 6e 5f 61 72 72 61 79 3c 2f 74 74  t>cson_array</tt
1770: 3e 2e 0d 0a 0d 0a 3c 73 74 72 6f 6e 67 3e 46 65  >.....<strong>Fe
1780: 74 63 68 20 61 20 73 69 6e 67 6c 65 20 61 72 72  tch a single arr
1790: 61 79 20 65 6c 65 6d 65 6e 74 3a 3c 2f 73 74 72  ay element:</str
17a0: 6f 6e 67 3e 0d 0a 3c 76 65 72 62 61 74 69 6d 3e  ong>..<verbatim>
17b0: 0d 0a 63 73 6f 6e 5f 76 61 6c 75 65 20 2a 20 76  ..cson_value * v
17c0: 20 3d 20 63 73 6f 6e 5f 61 72 72 61 79 5f 67 65   = cson_array_ge
17d0: 74 28 20 61 72 2c 20 31 20 2f 2a 20 61 72 72 61  t( ar, 1 /* arra
17e0: 79 20 69 6e 64 65 78 20 2a 2f 20 29 3b 0d 0a 3c  y index */ );..<
17f0: 2f 76 65 72 62 61 74 69 6d 3e 0d 0a 0d 0a 3c 73  /verbatim>....<s
1800: 74 72 6f 6e 67 3e 49 74 65 72 61 74 65 20 6f 76  trong>Iterate ov
1810: 65 72 20 61 72 72 61 79 3a 3c 2f 73 74 72 6f 6e  er array:</stron
1820: 67 3e 0d 0a 3c 76 65 72 62 61 74 69 6d 3e 0d 0a  g>..<verbatim>..
1830: 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 6c 65 6e  unsigned int len
1840: 20 3d 20 63 73 6f 6e 5f 61 72 72 61 79 5f 6c 65   = cson_array_le
1850: 6e 67 74 68 5f 67 65 74 28 61 72 29 3b 0d 0a 75  ngth_get(ar);..u
1860: 6e 73 69 67 6e 65 64 20 69 6e 74 20 69 3b 0d 0a  nsigned int i;..
1870: 66 6f 72 28 20 69 20 3d 20 30 3b 20 69 20 3c 20  for( i = 0; i < 
1880: 6c 65 6e 3b 20 2b 2b 69 20 29 20 7b 0d 0a 20 20  len; ++i ) {..  
1890: 76 20 3d 20 63 73 6f 6e 5f 61 72 72 61 79 5f 67  v = cson_array_g
18a0: 65 74 28 20 61 72 2c 20 69 20 29 3b 0d 0a 20 20  et( ar, i );..  
18b0: 2e 2e 2e 0d 0a 7d 0d 0a 3c 2f 76 65 72 62 61 74  .....}..</verbat
18c0: 69 6d 3e 0d 0a 0d 0a 3c 73 74 72 6f 6e 67 3e 46  im>....<strong>F
18d0: 65 74 63 68 20 73 69 6e 67 6c 65 20 70 72 6f 70  etch single prop
18e0: 65 72 74 79 20 66 72 6f 6d 20 61 6e 20 6f 62 6a  erty from an obj
18f0: 65 63 74 3a 3c 2f 73 74 72 6f 6e 67 3e 0d 0a 3c  ect:</strong>..<
1900: 76 65 72 62 61 74 69 6d 3e 0d 0a 63 73 6f 6e 5f  verbatim>..cson_
1910: 76 61 6c 75 65 20 2a 20 76 20 3d 20 63 73 6f 6e  value * v = cson
1920: 5f 6f 62 6a 65 63 74 5f 67 65 74 28 20 6f 62 6a  _object_get( obj
1930: 2c 20 22 6d 79 4b 65 79 22 20 29 3b 0d 0a 3c 2f  , "myKey" );..</
1940: 76 65 72 62 61 74 69 6d 3e 0d 0a 0d 0a 3c 73 74  verbatim>....<st
1950: 72 6f 6e 67 3e 46 65 74 63 68 20 73 69 6e 67 6c  rong>Fetch singl
1960: 65 20 6e 65 73 74 65 64 20 70 72 6f 70 65 72 74  e nested propert
1970: 79 20 66 72 6f 6d 20 61 6e 20 6f 62 6a 65 63 74  y from an object
1980: 3a 3c 2f 73 74 72 6f 6e 67 3e 0d 0a 3c 76 65 72  :</strong>..<ver
1990: 62 61 74 69 6d 3e 0d 0a 2f 2f 20 53 65 61 72 63  batim>..// Searc
19a0: 68 20 66 6f 72 20 76 61 6c 75 65 20 69 6e 20 61  h for value in a
19b0: 6e 20 6f 62 6a 65 63 74 20 73 74 72 75 63 74 75  n object structu
19c0: 72 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0d 0a  red like this:..
19d0: 2f 2f 20 20 20 20 7b 20 22 73 75 62 6f 62 6a 22  //    { "subobj"
19e0: 3a 20 7b 20 22 73 75 62 32 6f 62 6a 22 3a 20 7b  : { "sub2obj": {
19f0: 20 22 6d 79 4b 65 79 22 3a 20 77 68 61 74 65 76   "myKey": whatev
1a00: 65 72 20 7d 20 7d 20 7d 0d 0a 63 73 6f 6e 5f 76  er } } }..cson_v
1a10: 61 6c 75 65 20 2a 20 76 20 3d 20 63 73 6f 6e 5f  alue * v = cson_
1a20: 6f 62 6a 65 63 74 5f 67 65 74 5f 73 75 62 28 20  object_get_sub( 
1a30: 6f 62 6a 2c 20 22 73 75 62 6f 62 6a 2e 73 75 62  obj, "subobj.sub
1a40: 6f 62 6a 32 2e 6d 79 4b 65 79 22 2c 20 27 2e 27  obj2.myKey", '.'
1a50: 20 29 3b 0d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e   );..</verbatim>
1a60: 0d 0a 0d 0a 3c 73 74 72 6f 6e 67 3e 49 74 65 72  ....<strong>Iter
1a70: 61 74 65 20 6f 76 65 72 20 6f 62 6a 65 63 74 20  ate over object 
1a80: 65 6e 74 72 69 65 73 3a 3c 2f 73 74 72 6f 6e 67  entries:</strong
1a90: 3e 0d 0a 0d 0a 3c 76 65 72 62 61 74 69 6d 3e 0d  >....<verbatim>.
1aa0: 0a 63 73 6f 6e 5f 6f 62 6a 65 63 74 5f 69 74 65  .cson_object_ite
1ab0: 72 61 74 6f 72 20 69 74 65 72 3b 0d 0a 69 6e 74  rator iter;..int
1ac0: 20 72 63 20 3d 20 63 73 6f 6e 5f 6f 62 6a 65 63   rc = cson_objec
1ad0: 74 5f 69 74 65 72 5f 69 6e 69 74 28 20 6f 62 6a  t_iter_init( obj
1ae0: 2c 20 26 69 74 65 72 20 29 3b 0d 0a 69 66 28 20  , &iter );..if( 
1af0: 30 20 21 3d 20 72 63 20 29 20 7b 20 65 72 72 6f  0 != rc ) { erro
1b00: 72 2c 20 62 75 74 20 63 61 6e 20 6f 6e 6c 79 20  r, but can only 
1b10: 66 61 69 6c 20 69 66 20 6f 62 6a 20 69 73 20 4e  fail if obj is N
1b20: 55 4c 4c 20 7d 0d 0a 63 73 6f 6e 5f 6b 76 70 20  ULL }..cson_kvp 
1b30: 2a 20 6b 76 70 3b 20 2f 2f 20 6b 65 79 2f 76 61  * kvp; // key/va
1b40: 6c 75 65 20 70 61 69 72 0d 0a 77 68 69 6c 65 28  lue pair..while(
1b50: 20 28 6b 76 70 20 3d 20 63 73 6f 6e 5f 6f 62 6a   (kvp = cson_obj
1b60: 65 63 74 5f 69 74 65 72 5f 6e 65 78 74 28 26 69  ect_iter_next(&i
1b70: 74 65 72 29 29 20 29 0d 0a 7b 0d 0a 20 20 20 20  ter)) )..{..    
1b80: 63 73 6f 6e 5f 73 74 72 69 6e 67 20 63 6f 6e 73  cson_string cons
1b90: 74 20 2a 20 63 6b 65 79 20 3d 20 63 73 6f 6e 5f  t * ckey = cson_
1ba0: 6b 76 70 5f 6b 65 79 28 6b 76 70 29 3b 0d 0a 20  kvp_key(kvp);.. 
1bb0: 20 20 20 63 73 6f 6e 5f 76 61 6c 75 65 20 2a 20     cson_value * 
1bc0: 76 20 3d 20 63 73 6f 6e 5f 6b 76 70 5f 76 61 6c  v = cson_kvp_val
1bd0: 75 65 28 6b 76 70 29 3b 0d 0a 20 20 20 20 2e 2e  ue(kvp);..    ..
1be0: 2e 20 75 73 65 20 63 6b 65 79 20 61 6e 64 20 76  . use ckey and v
1bf0: 20 2e 2e 2e 0d 0a 20 20 20 20 2f 2f 20 48 65 72   .....    // Her
1c00: 65 20 77 65 20 6a 75 73 74 20 70 72 69 6e 74 20  e we just print 
1c10: 6f 75 74 3a 20 4b 45 59 3d 56 41 4c 55 45 0d 0a  out: KEY=VALUE..
1c20: 20 20 20 20 66 70 72 69 6e 74 66 28 20 73 74 64      fprintf( std
1c30: 6f 75 74 2c 20 22 25 73 22 2c 20 63 73 6f 6e 5f  out, "%s", cson_
1c40: 73 74 72 69 6e 67 5f 63 73 74 72 28 63 6b 65 79  string_cstr(ckey
1c50: 29 20 29 3b 0d 0a 20 20 20 20 70 75 74 63 68 61  ) );..    putcha
1c60: 72 28 27 3d 27 29 3b 0d 0a 20 20 20 20 63 73 6f  r('=');..    cso
1c70: 6e 5f 6f 75 74 70 75 74 5f 46 49 4c 45 28 20 76  n_output_FILE( v
1c80: 2c 20 73 74 64 6f 75 74 2c 20 4e 55 4c 4c 20 29  , stdout, NULL )
1c90: 3b 0d 0a 7d 0d 0a 2f 2f 20 63 73 6f 6e 5f 6f 62  ;..}..// cson_ob
1ca0: 6a 65 63 74 5f 69 74 65 72 61 74 6f 72 20 6f 62  ject_iterator ob
1cb0: 6a 65 63 74 73 20 6f 77 6e 20 6e 6f 20 6d 65 6d  jects own no mem
1cc0: 6f 72 79 20 61 6e 64 20 6e 65 65 64 20 6e 6f 74  ory and need not
1cd0: 20 62 65 20 63 6c 65 61 6e 65 64 20 75 70 2e 0d   be cleaned up..
1ce0: 0a 2f 2f 20 49 74 65 72 61 74 69 6f 6e 20 72 65  .// Iteration re
1cf0: 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1d00: 6e 65 64 20 69 66 20 74 68 65 20 6f 62 6a 65 63  ned if the objec
1d10: 74 20 62 65 69 6e 67 20 69 74 65 72 61 74 65 64  t being iterated
1d20: 20 6f 76 65 72 20 69 73 0d 0a 2f 2f 20 6d 6f 64   over is..// mod
1d30: 69 66 69 65 64 20 28 6b 65 79 73 20 61 64 64 65  ified (keys adde
1d40: 64 2f 72 65 6d 6f 76 65 64 29 20 77 68 69 6c 65  d/removed) while
1d50: 20 69 74 65 72 61 74 69 6e 67 2e 0d 0a 3c 2f 76   iterating...</v
1d60: 65 72 62 61 74 69 6d 3e 0d 0a 0d 0a 0d 0a 3c 68  erbatim>......<h
1d70: 31 3e 55 73 69 6e 67 20 61 20 63 75 73 74 6f 6d  1>Using a custom
1d80: 20 69 6e 70 75 74 20 73 6f 75 72 63 65 3c 2f 68   input source</h
1d90: 31 3e 0d 0a 0d 0a 3c 74 74 3e 63 73 6f 6e 5f 70  1>....<tt>cson_p
1da0: 61 72 73 65 28 29 3c 2f 74 74 3e 20 69 73 20 74  arse()</tt> is t
1db0: 68 65 20 67 65 6e 65 72 69 63 20 66 72 6f 6e 74  he generic front
1dc0: 2d 65 6e 64 20 74 6f 20 70 61 72 73 69 6e 67 20  -end to parsing 
1dd0: 69 6e 70 75 74 2e 20 49 74 20 74 61 6b 65 73 20  input. It takes 
1de0: 70 61 72 61 6d 65 74 65 72 73 20 77 68 69 63 68  parameters which
1df0: 20 74 65 6c 6c 20 69 74 20 77 68 65 72 65 20 74   tell it where t
1e00: 6f 20 70 75 6c 6c 20 69 74 73 20 64 61 74 61 2c  o pull its data,
1e10: 20 77 68 65 72 65 20 74 6f 20 73 74 6f 72 65 20   where to store 
1e20: 74 68 65 20 72 65 73 75 6c 74 20 6f 62 6a 65 63  the result objec
1e30: 74 2f 61 72 72 61 79 2c 20 61 6e 64 20 73 6f 6d  t/array, and som
1e40: 65 20 6f 70 74 69 6f 6e 61 6c 20 73 65 74 74 69  e optional setti
1e50: 6e 67 73 20 74 6f 20 74 77 65 61 6b 20 68 6f 77  ngs to tweak how
1e60: 20 74 68 65 20 70 61 72 73 65 72 20 77 6f 72 6b   the parser work
1e70: 73 2e 20 54 68 61 74 20 66 75 6e 63 74 69 6f 6e  s. That function
1e80: 20 69 73 20 64 72 69 76 65 6e 20 62 79 20 61 20   is driven by a 
1e90: 67 65 6e 65 72 69 63 20 63 61 6c 6c 62 61 63 6b  generic callback
1ea0: 20 69 6e 74 65 72 66 61 63 65 20 77 68 69 63 68   interface which
1eb0: 20 63 6c 69 65 6e 74 73 20 6d 61 79 20 69 6d 70   clients may imp
1ec0: 6c 65 6d 65 6e 74 20 69 6e 20 6f 72 64 65 72 20  lement in order 
1ed0: 74 6f 20 73 74 72 65 61 6d 20 64 61 74 61 20 66  to stream data f
1ee0: 72 6f 6d 20 61 72 62 69 74 72 61 72 79 20 73 6f  rom arbitrary so
1ef0: 75 72 63 65 73 2e 20 41 20 63 6f 75 70 6c 65 20  urces. A couple 
1f00: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
1f10: 61 72 65 20 70 72 6f 76 69 64 65 64 2c 20 61 6e  are provided, an
1f20: 64 20 61 64 64 69 6e 67 20 6e 65 77 20 6f 6e 65  d adding new one
1f30: 73 20 69 73 20 72 65 61 6c 6c 79 20 65 61 73 79  s is really easy
1f40: 2e 0d 0a 0d 0a 54 68 65 20 66 6f 6c 6c 6f 77 69  .....The followi
1f50: 6e 67 20 65 78 61 6d 70 6c 65 20 64 65 6d 6f 6e  ng example demon
1f60: 73 74 72 61 74 65 73 20 68 6f 77 20 74 6f 20 63  strates how to c
1f70: 72 65 61 74 65 20 61 20 63 75 73 74 6f 6d 20 69  reate a custom i
1f80: 6e 70 75 74 20 73 6f 75 72 63 65 20 68 61 6e 64  nput source hand
1f90: 6c 65 72 2c 20 73 6f 20 74 68 61 74 20 3c 74 74  ler, so that <tt
1fa0: 3e 63 73 6f 6e 5f 70 61 72 73 65 28 29 3c 2f 74  >cson_parse()</t
1fb0: 74 3e 20 63 61 6e 20 72 65 61 64 20 66 72 6f 6d  t> can read from
1fc0: 20 77 68 65 72 65 76 65 72 20 79 6f 75 20 6e 65   wherever you ne
1fd0: 65 64 20 69 74 20 74 6f 2e 20 54 68 69 73 20 63  ed it to. This c
1fe0: 6f 64 65 20 61 63 74 75 61 6c 6c 79 20 63 6f 6d  ode actually com
1ff0: 65 73 20 66 72 6f 6d 20 74 68 65 20 63 6f 72 65  es from the core
2000: 20 6c 69 62 72 61 72 79 20 28 77 68 69 63 68 20   library (which 
2010: 65 78 70 6c 61 69 6e 73 20 77 68 79 20 69 74 20  explains why it 
2020: 68 61 73 20 73 6f 20 6d 75 63 68 20 65 72 72 6f  has so much erro
2030: 72 20 63 68 65 63 6b 69 6e 67 29 20 61 6e 64 20  r checking) and 
2040: 69 6d 70 6c 65 6d 65 6e 74 73 20 72 65 61 64 69  implements readi
2050: 6e 67 20 6f 66 20 4a 53 4f 4e 20 66 72 6f 6d 20  ng of JSON from 
2060: 61 20 63 6c 69 65 6e 74 2d 73 75 70 70 6c 69 65  a client-supplie
2070: 64 20 43 20 73 74 72 69 6e 67 2e 0d 0a 0d 0a 3c  d C string.....<
2080: 76 65 72 62 61 74 69 6d 3e 0d 0a 2f 2a 2a 20 49  verbatim>../** I
2090: 6e 74 65 72 6e 61 6c 20 74 79 70 65 20 74 6f 20  nternal type to 
20a0: 68 6f 6c 64 20 73 74 61 74 65 20 66 6f 72 20 61  hold state for a
20b0: 20 4a 53 4f 4e 20 69 6e 70 75 74 20 73 74 72 69   JSON input stri
20c0: 6e 67 2e 0d 0a 20 2a 2f 0d 0a 74 79 70 65 64 65  ng... */..typede
20d0: 66 20 73 74 72 75 63 74 0d 0a 7b 0d 0a 20 20 20  f struct..{..   
20e0: 20 2f 2a 20 53 74 61 72 74 20 6f 66 20 69 6e 70   /* Start of inp
20f0: 75 74 20 73 74 72 69 6e 67 2e 20 2a 2f 0d 0a 20  ut string. */.. 
2100: 20 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 20     char const * 
2110: 73 74 72 3b 0d 0a 20 20 20 20 2f 2a 20 43 75 72  str;..    /* Cur
2120: 72 65 6e 74 20 69 74 65 72 61 74 69 6f 6e 20 70  rent iteration p
2130: 6f 73 69 74 69 6f 6e 2e 20 4d 75 73 74 20 69 6e  osition. Must in
2140: 69 74 69 61 6c 6c 79 20 62 65 20 3d 3d 20 73 74  itially be == st
2150: 72 2e 20 2a 2f 0d 0a 20 20 20 20 63 68 61 72 20  r. */..    char 
2160: 63 6f 6e 73 74 20 2a 20 70 6f 73 3b 0d 0a 20 20  const * pos;..  
2170: 20 20 2f 2a 20 4c 6f 67 69 63 61 6c 20 45 4f 46    /* Logical EOF
2180: 2c 20 6f 6e 65 2d 70 61 73 74 2d 74 68 65 2d 65  , one-past-the-e
2190: 6e 64 20 6f 66 20 73 74 72 2e 20 2a 2f 0d 0a 20  nd of str. */.. 
21a0: 20 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 20     char const * 
21b0: 65 6e 64 3b 0d 0a 7d 20 20 53 74 72 69 6e 67 53  end;..}  StringS
21c0: 6f 75 72 63 65 5f 74 3b 0d 0a 0d 0a 2f 2a 2a 0d  ource_t;..../**.
21d0: 0a 20 20 20 41 20 63 73 6f 6e 5f 64 61 74 61 5f  .   A cson_data_
21e0: 73 6f 75 72 63 65 5f 66 28 29 20 69 6d 70 6c 65  source_f() imple
21f0: 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2200: 72 65 71 75 69 72 65 73 20 74 68 65 20 73 74 61  requires the sta
2210: 74 65 20 61 72 67 75 6d 65 6e 74 0d 0a 20 20 20  te argument..   
2220: 74 6f 20 62 65 20 61 20 70 72 6f 70 65 72 6c 79  to be a properly
2230: 20 70 6f 70 75 6c 61 74 65 64 20 28 53 74 72 69   populated (Stri
2240: 6e 67 53 6f 75 72 63 65 5f 74 2a 29 2e 0d 0a 2a  ngSource_t*)...*
2250: 2f 0d 0a 73 74 61 74 69 63 20 69 6e 74 20 63 73  /..static int cs
2260: 6f 6e 5f 64 61 74 61 5f 73 6f 75 72 63 65 5f 53  on_data_source_S
2270: 74 72 69 6e 67 53 6f 75 72 63 65 28 20 76 6f 69  tringSource( voi
2280: 64 20 2a 20 73 74 61 74 65 2c 20 76 6f 69 64 20  d * state, void 
2290: 2a 20 64 65 73 74 2c 0d 0a 20 20 20 20 20 20 20  * dest,..       
22a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22c0: 20 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20     unsigned int 
22d0: 2a 20 6e 20 29 0d 0a 7b 0d 0a 20 20 20 20 53 74  * n )..{..    St
22e0: 72 69 6e 67 53 6f 75 72 63 65 5f 74 20 2a 20 73  ringSource_t * s
22f0: 73 20 3d 20 28 53 74 72 69 6e 67 53 6f 75 72 63  s = (StringSourc
2300: 65 5f 74 2a 29 20 73 74 61 74 65 3b 0d 0a 20 20  e_t*) state;..  
2310: 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 69    unsigned int i
2320: 3b 0d 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  ;..    unsigned 
2330: 63 68 61 72 20 2a 20 74 67 74 20 3d 20 28 75 6e  char * tgt = (un
2340: 73 69 67 6e 65 64 20 63 68 61 72 20 2a 29 64 65  signed char *)de
2350: 73 74 3b 0d 0a 20 20 20 20 69 66 28 20 21 20 73  st;..    if( ! s
2360: 73 20 7c 7c 20 21 20 6e 20 7c 7c 20 21 64 65 73  s || ! n || !des
2370: 74 20 29 20 72 65 74 75 72 6e 20 63 73 6f 6e 5f  t ) return cson_
2380: 72 63 2e 41 72 67 45 72 72 6f 72 3b 0d 0a 20 20  rc.ArgError;..  
2390: 20 20 65 6c 73 65 20 69 66 28 20 21 2a 6e 20 29    else if( !*n )
23a0: 20 72 65 74 75 72 6e 20 30 20 2f 2a 69 67 6e 6f   return 0 /*igno
23b0: 72 65 20 69 74 20 6f 72 20 72 65 74 75 72 6e 20  re it or return 
23c0: 63 73 6f 6e 5f 72 63 2e 52 61 6e 67 65 45 72 72  cson_rc.RangeErr
23d0: 6f 72 2a 2f 3b 0d 0a 20 20 20 20 2f 2a 20 43 6f  or*/;..    /* Co
23e0: 70 79 20 74 68 65 20 73 73 20 64 61 74 61 2c 20  py the ss data, 
23f0: 73 74 61 72 74 69 6e 67 20 61 74 20 74 68 65 20  starting at the 
2400: 63 75 72 72 65 6e 74 20 63 75 72 73 6f 72 20 70  current cursor p
2410: 6f 73 69 74 69 6f 6e 2c 0d 0a 20 20 20 20 20 20  osition,..      
2420: 20 74 6f 20 64 65 73 74 2e 20 57 65 20 75 70 64   to dest. We upd
2430: 61 74 65 20 74 68 65 20 73 73 20 73 74 61 74 65  ate the ss state
2440: 20 73 6f 20 74 68 61 74 20 74 68 65 20 6e 65 78   so that the nex
2450: 74 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 0d 0a  t call to this..
2460: 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
2470: 28 66 72 6f 6d 20 63 73 6f 6e 5f 70 61 72 73 65  (from cson_parse
2480: 28 29 2c 20 77 68 69 63 68 20 63 6f 6c 6c 65 63  (), which collec
2490: 74 73 20 69 74 73 20 69 6e 70 75 74 20 62 79 20  ts its input by 
24a0: 6c 6f 6f 70 69 6e 67 0d 0a 20 20 20 20 20 20 20  looping..       
24b0: 6f 76 65 72 20 74 68 69 73 20 66 75 6e 63 74 69  over this functi
24c0: 6f 6e 29 20 77 69 6c 6c 20 6b 6e 6f 77 20 69 74  on) will know it
24d0: 73 20 63 75 72 73 6f 72 20 70 6f 73 69 74 69 6f  s cursor positio
24e0: 6e 2e 0d 0a 20 20 20 20 2a 2f 0d 0a 20 20 20 20  n...    */..    
24f0: 66 6f 72 28 20 69 20 3d 20 30 3b 20 28 69 20 3c  for( i = 0; (i <
2500: 20 2a 6e 29 20 26 26 20 28 73 73 2d 3e 70 6f 73   *n) && (ss->pos
2510: 20 3c 20 73 73 2d 3e 65 6e 64 29 3b 20 2b 2b 69   < ss->end); ++i
2520: 2c 20 2b 2b 73 73 2d 3e 70 6f 73 2c 20 2b 2b 74  , ++ss->pos, ++t
2530: 67 74 20 29 0d 0a 20 20 20 20 7b 0d 0a 20 20 20  gt )..    {..   
2540: 20 20 20 20 20 2a 74 67 74 20 3d 20 2a 73 73 2d       *tgt = *ss-
2550: 3e 70 6f 73 3b 0d 0a 20 20 20 20 7d 0d 0a 20 20  >pos;..    }..  
2560: 20 20 2a 6e 20 3d 20 69 20 2f 2a 20 54 65 6c 6c    *n = i /* Tell
2570: 73 20 63 73 6f 6e 5f 70 61 72 73 65 28 29 20 68  s cson_parse() h
2580: 6f 77 20 6d 61 6e 79 20 62 79 74 65 73 20 77 65  ow many bytes we
2590: 20 63 6f 70 69 65 64 2e 0d 0a 20 20 20 20 20 20   copied...      
25a0: 20 20 20 20 20 20 20 20 49 66 20 74 68 69 73 20          If this 
25b0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
25c0: 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
25d0: 66 20 2a 6e 20 74 68 65 6e 0d 0a 20 20 20 20 20  f *n then..     
25e0: 20 20 20 20 20 20 20 20 20 45 4f 46 20 69 73 20           EOF is 
25f0: 61 73 73 75 6d 65 64 2e 0d 0a 20 20 20 20 20 20  assumed...      
2600: 20 20 20 20 20 2a 2f 3b 0d 0a 20 20 20 20 72 65       */;..    re
2610: 74 75 72 6e 20 30 3b 0d 0a 0d 0a 7d 0d 0a 0d 0a  turn 0;....}....
2620: 2f 2a 2a 0d 0a 20 43 6f 6e 76 65 6e 69 65 6e 63  /**.. Convenienc
2630: 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  e wrapper around
2640: 20 63 73 6f 6e 5f 70 61 72 73 65 28 29 20 77 68   cson_parse() wh
2650: 69 63 68 20 75 73 65 73 20 74 68 65 20 66 69 72  ich uses the fir
2660: 73 74 20 6c 65 6e 0d 0a 20 62 79 74 65 73 20 6f  st len.. bytes o
2670: 66 20 74 68 65 20 67 69 76 65 6e 20 73 74 72 69  f the given stri
2680: 6e 67 20 61 73 20 4a 53 4f 4e 2e 0d 0a 2a 2f 0d  ng as JSON...*/.
2690: 0a 69 6e 74 20 63 73 6f 6e 5f 70 61 72 73 65 5f  .int cson_parse_
26a0: 73 74 72 69 6e 67 28 20 63 73 6f 6e 5f 76 61 6c  string( cson_val
26b0: 75 65 20 2a 2a 20 74 67 74 2c 20 63 68 61 72 20  ue ** tgt, char 
26c0: 63 6f 6e 73 74 20 2a 20 73 72 63 2c 20 75 6e 73  const * src, uns
26d0: 69 67 6e 65 64 20 69 6e 74 20 6c 65 6e 2c 0d 0a  igned int len,..
26e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26f0: 20 20 20 20 20 20 20 63 73 6f 6e 5f 70 61 72 73         cson_pars
2700: 65 5f 6f 70 74 20 63 6f 6e 73 74 20 2a 20 6f 70  e_opt const * op
2710: 74 2c 20 63 73 6f 6e 5f 70 61 72 73 65 5f 69 6e  t, cson_parse_in
2720: 66 6f 20 2a 20 69 6e 66 6f 20 29 0d 0a 7b 0d 0a  fo * info )..{..
2730: 20 20 20 20 69 66 28 20 21 20 74 67 74 20 7c 7c      if( ! tgt ||
2740: 20 21 73 72 63 20 29 20 72 65 74 75 72 6e 20 63   !src ) return c
2750: 73 6f 6e 5f 72 63 2e 41 72 67 45 72 72 6f 72 3b  son_rc.ArgError;
2760: 0d 0a 20 20 20 20 65 6c 73 65 20 69 66 28 20 21  ..    else if( !
2770: 2a 73 72 63 20 7c 7c 20 28 6c 65 6e 3c 32 20 2f  *src || (len<2 /
2780: 2a 32 3d 3d 6c 65 6e 20 6f 66 20 7b 7d 20 61 6e  *2==len of {} an
2790: 64 20 5b 5d 2a 2f 29 20 29 0d 0a 20 20 20 20 20  d []*/) )..     
27a0: 20 20 20 20 72 65 74 75 72 6e 20 63 73 6f 6e 5f      return cson_
27b0: 72 63 2e 52 61 6e 67 65 45 72 72 6f 72 3b 0d 0a  rc.RangeError;..
27c0: 20 20 20 2f 2a 20 57 65 20 63 6f 75 6c 64 20 6f     /* We could o
27d0: 70 74 69 6f 6e 61 6c 6c 79 20 64 6f 20 61 20 71  ptionally do a q
27e0: 75 69 63 6b 20 63 68 65 63 6b 20 6f 66 20 2a 73  uick check of *s
27f0: 72 63 20 66 6f 72 20 27 7b 27 2c 20 27 5b 27 2c  rc for '{', '[',
2800: 20 6f 72 20 73 70 61 63 65 73 2c 0d 0a 20 20 20   or spaces,..   
2810: 20 20 20 61 6e 64 20 66 61 69 6c 20 65 61 72 6c     and fail earl
2820: 79 20 69 66 20 74 68 6f 73 65 20 61 72 65 20 6e  y if those are n
2830: 6f 74 20 66 6f 75 6e 64 2e 0d 0a 20 20 20 20 2a  ot found...    *
2840: 2f 0d 0a 20 20 20 20 65 6c 73 65 0d 0a 20 20 20  /..    else..   
2850: 20 7b 0d 0a 20 20 20 20 20 20 20 20 53 74 72 69   {..        Stri
2860: 6e 67 53 6f 75 72 63 65 5f 74 20 73 73 3b 0d 0a  ngSource_t ss;..
2870: 20 20 20 20 20 20 20 20 73 73 2e 73 74 72 20 3d          ss.str =
2880: 20 73 73 2e 70 6f 73 20 3d 20 73 72 63 3b 0d 0a   ss.pos = src;..
2890: 20 20 20 20 20 20 20 20 73 73 2e 65 6e 64 20 3d          ss.end =
28a0: 20 73 72 63 20 2b 20 6c 65 6e 3b 0d 0a 20 20 20   src + len;..   
28b0: 20 20 20 20 20 72 65 74 75 72 6e 20 63 73 6f 6e       return cson
28c0: 5f 70 61 72 73 65 28 20 74 67 74 2c 20 53 74 72  _parse( tgt, Str
28d0: 69 6e 67 53 6f 75 72 63 65 2c 20 26 73 73 2c 20  ingSource, &ss, 
28e0: 6f 70 74 2c 20 69 6e 66 6f 20 29 3b 0d 0a 20 20  opt, info );..  
28f0: 20 20 7d 0d 0a 0d 0a 7d 0d 0a 3c 2f 76 65 72 62    }....}..</verb
2900: 61 74 69 6d 3e 0d 0a 0d 0a 0d 0a 3c 68 31 3e 55  atim>......<h1>U
2910: 73 69 6e 67 20 61 20 63 75 73 74 6f 6d 20 6f 75  sing a custom ou
2920: 74 70 75 74 20 64 65 73 74 69 6e 61 74 69 6f 6e  tput destination
2930: 3c 2f 68 31 3e 0d 0a 0d 0a 4c 69 6b 65 20 3c 74  </h1>....Like <t
2940: 74 3e 63 73 6f 6e 5f 70 61 72 73 65 28 29 3c 2f  t>cson_parse()</
2950: 74 74 3e 2c 20 3c 74 74 3e 63 73 6f 6e 5f 6f 75  tt>, <tt>cson_ou
2960: 74 70 75 74 28 29 3c 2f 74 74 3e 20 61 6c 73 6f  tput()</tt> also
2970: 20 74 61 6b 65 73 20 61 20 63 61 6c 6c 62 61 63   takes a callbac
2980: 6b 20 77 68 69 63 68 20 61 6c 6c 6f 77 73 20 69  k which allows i
2990: 74 20 74 6f 20 73 74 72 65 61 6d 20 69 74 73 20  t to stream its 
29a0: 6f 75 74 70 75 74 20 74 6f 20 61 6e 20 61 72 62  output to an arb
29b0: 69 74 72 61 72 79 20 64 65 73 74 69 6e 61 74 69  itrary destinati
29c0: 6f 6e 2e 0d 0a 0d 0a 54 68 65 20 77 68 6f 6c 65  on.....The whole
29d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29e0: 66 6f 72 20 74 68 65 20 3c 74 74 3e 46 49 4c 45  for the <tt>FILE
29f0: 3c 2f 74 74 3e 2d 68 61 6e 64 6c 69 6e 67 20 6f  </tt>-handling o
2a00: 75 74 70 75 74 20 41 50 49 20 6c 6f 6f 6b 73 20  utput API looks 
2a10: 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
2a20: 68 69 73 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74 69  his:....<verbati
2a30: 6d 3e 0d 0a 2f 2a 20 63 73 6f 6e 5f 64 61 74 61  m>../* cson_data
2a40: 5f 64 65 73 74 5f 66 28 29 20 69 6d 70 6c 20 77  _dest_f() impl w
2a50: 68 69 63 68 20 72 65 71 75 69 72 65 73 20 74 68  hich requires th
2a60: 61 74 20 73 74 61 74 65 20 62 65 20 61 0d 0a 20  at state be a.. 
2a70: 20 20 77 72 69 74 61 62 6c 65 20 28 46 49 4c 45    writable (FILE
2a80: 2a 29 2e 0d 0a 2a 2f 0d 0a 69 6e 74 20 63 73 6f  *)...*/..int cso
2a90: 6e 5f 64 61 74 61 5f 64 65 73 74 5f 46 49 4c 45  n_data_dest_FILE
2aa0: 28 20 76 6f 69 64 20 2a 20 73 74 61 74 65 2c 20  ( void * state, 
2ab0: 76 6f 69 64 20 63 6f 6e 73 74 20 2a 20 73 72 63  void const * src
2ac0: 2c 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 6e  , unsigned int n
2ad0: 20 29 0d 0a 7b 0d 0a 20 20 20 20 69 66 28 20 21   )..{..    if( !
2ae0: 20 73 74 61 74 65 20 29 20 72 65 74 75 72 6e 20   state ) return 
2af0: 63 73 6f 6e 5f 72 63 2e 41 72 67 45 72 72 6f 72  cson_rc.ArgError
2b00: 3b 0d 0a 20 20 20 20 65 6c 73 65 20 69 66 28 20  ;..    else if( 
2b10: 21 73 72 63 20 7c 7c 20 21 6e 20 29 20 72 65 74  !src || !n ) ret
2b20: 75 72 6e 20 30 3b 0d 0a 20 20 20 20 65 6c 73 65  urn 0;..    else
2b30: 0d 0a 20 20 20 20 7b 0d 0a 20 20 20 20 20 20 20  ..    {..       
2b40: 20 46 49 4c 45 20 2a 20 66 20 3d 20 28 46 49 4c   FILE * f = (FIL
2b50: 45 2a 29 20 73 74 61 74 65 3b 0d 0a 20 20 20 20  E*) state;..    
2b60: 20 20 20 20 73 69 7a 65 5f 74 20 63 6f 6e 73 74      size_t const
2b70: 20 77 73 7a 20 3d 20 66 77 72 69 74 65 28 20 73   wsz = fwrite( s
2b80: 72 63 2c 20 6e 2c 20 31 2c 20 66 20 29 3b 0d 0a  rc, n, 1, f );..
2b90: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 28          return (
2ba0: 31 20 3d 3d 20 77 73 7a 29 20 3f 20 30 20 3a 20  1 == wsz) ? 0 : 
2bb0: 63 73 6f 6e 5f 72 63 2e 49 4f 45 72 72 6f 72 3b  cson_rc.IOError;
2bc0: 0d 0a 20 20 20 20 7d 0d 0a 7d 0d 0a 2f 2a 20 43  ..    }..}../* C
2bd0: 6f 6e 76 65 6e 69 65 6e 63 65 2f 74 79 70 65 2d  onvenience/type-
2be0: 73 61 66 65 74 79 20 77 72 61 70 70 65 72 20 61  safety wrapper a
2bf0: 72 6f 75 6e 64 20 63 73 6f 6e 5f 6f 75 74 70 75  round cson_outpu
2c00: 74 28 29 2e 0d 0a 0d 0a 20 20 20 50 65 64 61 6e  t().....   Pedan
2c10: 74 69 63 20 6e 6f 74 65 3a 20 74 68 69 73 20 65  tic note: this e
2c20: 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 71 75  xample is not qu
2c30: 69 74 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  ite equivalent t
2c40: 6f 20 74 68 65 20 72 65 61 6c 0d 0a 20 20 20 63  o the real..   c
2c50: 73 6f 6e 5f 6f 75 74 70 75 74 5f 46 49 4c 45 28  son_output_FILE(
2c60: 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
2c70: 3a 20 74 68 61 74 20 6f 6e 65 20 75 73 65 73 20  : that one uses 
2c80: 64 69 66 66 65 72 65 6e 74 20 64 65 66 61 75 6c  different defaul
2c90: 74 0d 0a 20 20 20 6f 70 74 69 6f 6e 73 20 69 66  t..   options if
2ca0: 20 28 66 6d 74 3d 3d 4e 55 4c 4c 29 2e 0d 0a 2a   (fmt==NULL)...*
2cb0: 2f 0d 0a 69 6e 74 20 63 73 6f 6e 5f 6f 75 74 70  /..int cson_outp
2cc0: 75 74 5f 46 49 4c 45 28 20 63 73 6f 6e 5f 76 61  ut_FILE( cson_va
2cd0: 6c 75 65 20 63 6f 6e 73 74 20 2a 20 73 72 63 2c  lue const * src,
2ce0: 20 46 49 4c 45 20 2a 20 64 65 73 74 2c 0d 0a 20   FILE * dest,.. 
2cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d00: 20 20 20 20 20 63 73 6f 6e 5f 66 6f 72 6d 61 74       cson_format
2d10: 5f 6f 70 74 20 63 6f 6e 73 74 20 2a 20 66 6d 74  _opt const * fmt
2d20: 20 29 0d 0a 7b 0d 0a 20 20 20 20 72 65 74 75 72   )..{..    retur
2d30: 6e 20 63 73 6f 6e 5f 6f 75 74 70 75 74 28 20 73  n cson_output( s
2d40: 72 63 2c 20 63 73 6f 6e 5f 64 61 74 61 5f 64 65  rc, cson_data_de
2d50: 73 74 5f 46 49 4c 45 2c 20 64 65 73 74 2c 20 66  st_FILE, dest, f
2d60: 6d 74 20 29 3b 0d 0a 7d 0d 0a 3c 2f 76 65 72 62  mt );..}..</verb
2d70: 61 74 69 6d 3e 0d 0a 0d 0a 41 6e 64 20 69 74 20  atim>....And it 
2d80: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 6c 69  can be called li
2d90: 6b 65 3a 0d 0a 0d 0a 3c 76 65 72 62 61 74 69 6d  ke:....<verbatim
2da0: 3e 0d 0a 63 73 6f 6e 5f 6f 75 74 70 75 74 5f 46  >..cson_output_F
2db0: 49 4c 45 28 20 6d 79 56 61 6c 75 65 2c 20 73 74  ILE( myValue, st
2dc0: 64 6f 75 74 2c 20 4e 55 4c 4c 20 2f 2a 20 3d 20  dout, NULL /* = 
2dd0: 75 73 65 20 64 65 66 61 75 6c 74 20 6f 70 74 69  use default opti
2de0: 6f 6e 73 20 2a 2f 20 29 3b 0d 0a 0d 0a 2f 2f 20  ons */ );....// 
2df0: 6f 72 2e 2e 2e 0d 0a 0d 0a 63 73 6f 6e 5f 6f 75  or.......cson_ou
2e00: 74 70 75 74 5f 6f 70 74 20 6f 70 74 20 3d 20 63  tput_opt opt = c
2e10: 73 6f 6e 5f 6f 75 74 70 75 74 5f 6f 70 74 5f 65  son_output_opt_e
2e20: 6d 70 74 79 3b 0d 0a 6f 70 74 2e 61 64 64 4e 65  mpty;..opt.addNe
2e30: 77 6c 69 6e 65 20 3d 20 31 3b 0d 0a 6f 70 74 2e  wline = 1;..opt.
2e40: 6d 61 78 44 65 70 74 68 20 3d 20 31 35 3b 20 2f  maxDepth = 15; /
2e50: 2f 20 77 69 6c 6c 20 65 72 72 6f 72 20 6f 75 74  / will error out
2e60: 20 69 66 20 74 68 65 20 74 72 65 65 20 69 73 20   if the tree is 
2e70: 64 65 65 70 65 72 20 74 68 61 6e 20 74 68 69 73  deeper than this
2e80: 0d 0a 6f 70 74 2e 69 6e 64 65 6e 74 61 74 69 6f  ..opt.indentatio
2e90: 6e 20 3d 20 31 3b 20 2f 2f 28 30 29 3d 6f 66 66  n = 1; //(0)=off
2ea0: 2c 20 28 31 29 3d 31 20 74 61 62 2f 6c 65 76 65  , (1)=1 tab/leve
2eb0: 6c 2c 20 28 3e 31 29 3d 74 68 61 74 20 6d 61 6e  l, (>1)=that man
2ec0: 79 20 73 70 61 63 65 73 2f 6c 65 76 65 6c 0d 0a  y spaces/level..
2ed0: 63 73 6f 6e 5f 6f 75 74 70 75 74 5f 46 49 4c 45  cson_output_FILE
2ee0: 28 20 6d 79 56 61 6c 75 65 2c 20 73 74 64 6f 75  ( myValue, stdou
2ef0: 74 2c 20 26 6f 70 74 20 29 3b 0d 0a 3c 2f 76 65  t, &opt );..</ve
2f00: 72 62 61 74 69 6d 3e 0d 0a 0d 0a 54 68 65 20 70  rbatim>....The p
2f10: 72 69 6d 61 72 79 20 72 65 61 73 6f 6e 20 66 6f  rimary reason fo
2f20: 72 20 73 65 74 74 69 6e 67 20 61 20 6d 61 78 69  r setting a maxi
2f30: 6d 75 6d 20 6f 75 74 70 75 74 20 64 65 70 74 68  mum output depth
2f40: 20 69 73 20 74 6f 20 68 65 6c 70 20 61 76 6f 69   is to help avoi
2f50: 64 20 65 6e 64 6c 65 73 73 20 72 65 63 75 72 73  d endless recurs
2f60: 69 6f 6e 2e 20 44 65 65 70 20 6c 65 76 65 6c 73  ion. Deep levels
2f70: 20 63 61 6e 20 62 65 20 61 6e 20 69 6e 64 69 63   can be an indic
2f80: 61 74 69 6f 6e 20 6f 66 20 63 79 63 6c 65 73 20  ation of cycles 
2f90: 69 6e 20 61 6e 20 6f 62 6a 65 63 74 2f 61 72 72  in an object/arr
2fa0: 61 79 20 74 72 65 65 2c 20 61 6e 64 20 63 79 63  ay tree, and cyc
2fb0: 6c 65 73 20 61 72 65 20 73 74 72 69 63 74 6c 79  les are strictly
2fc0: 20 66 6f 72 62 69 64 64 65 6e 20 62 79 20 74 68   forbidden by th
2fd0: 65 20 41 50 49 2e 20 49 66 20 63 79 63 6c 65 73  e API. If cycles
2fe0: 20 61 70 70 65 61 72 2c 20 6f 75 74 70 75 74 74   appear, outputt
2ff0: 69 6e 67 20 6d 61 79 20 66 61 69 6c 20 61 6e 64  ing may fail and
3000: 20 69 74 20 6d 61 79 20 72 65 73 75 6c 74 20 69   it may result i
3010: 6e 20 6d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  n memory corrupt
3020: 69 6f 6e 20 6f 72 20 63 72 61 73 68 65 73 20 77  ion or crashes w
3030: 68 65 6e 20 74 68 65 20 6f 62 6a 65 63 74 73 20  hen the objects 
3040: 61 72 65 20 63 6c 65 61 6e 65 64 20 75 70 2e 0d  are cleaned up..
3050: 0a 0d 0a 3c 68 31 3e 45 78 74 65 6e 64 69 6e 67  ...<h1>Extending
3060: 20 74 68 65 20 4c 69 66 65 74 69 6d 65 20 6f 66   the Lifetime of
3070: 20 49 6e 2d 63 6f 6e 74 61 69 6e 65 72 20 56 61   In-container Va
3080: 6c 75 65 73 3c 2f 68 31 3e 0d 0a 0d 0a 54 68 65  lues</h1>....The
3090: 20 6c 69 62 72 61 72 79 20 69 6e 74 65 72 6e 61   library interna
30a0: 6c 6c 79 20 72 65 66 65 72 65 6e 63 65 20 63 6f  lly reference co
30b0: 75 6e 74 73 20 76 61 6c 75 65 73 20 61 73 20 74  unts values as t
30c0: 68 65 79 20 61 72 65 20 61 64 64 65 64 20 74 6f  hey are added to
30d0: 20 63 6f 6e 74 61 69 6e 65 72 73 20 28 6f 62 6a   containers (obj
30e0: 65 63 74 73 2f 61 72 72 61 79 73 29 2c 20 73 6f  ects/arrays), so
30f0: 20 74 68 61 74 20 61 20 67 69 76 65 6e 20 76 61   that a given va
3100: 6c 75 65 20 63 61 6e 20 62 65 20 70 6c 61 63 65  lue can be place
3110: 64 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  d in more than o
3120: 6e 65 20 63 6f 6e 74 61 69 6e 65 72 20 6f 72 20  ne container or 
3130: 69 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  in the same cont
3140: 61 69 6e 65 72 20 6d 75 6c 74 69 70 6c 65 20 74  ainer multiple t
3150: 69 6d 65 73 20 28 65 2e 67 2e 2c 20 61 73 20 61  imes (e.g., as a
3160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
3170: 6f 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  on optimization 
3180: 77 68 65 72 65 20 61 20 67 69 76 65 6e 20 76 61  where a given va
3190: 6c 75 65 20 69 73 20 75 73 65 64 20 6f 66 74 65  lue is used ofte
31a0: 6e 29 2e 20 41 64 64 69 6e 67 20 61 20 3c 74 74  n). Adding a <tt
31b0: 3e 63 73 6f 6e 5f 76 61 6c 75 65 3c 2f 74 74 3e  >cson_value</tt>
31c0: 20 69 6e 73 74 61 6e 63 65 20 74 6f 20 61 20 63   instance to a c
31d0: 6f 6e 74 61 69 6e 65 72 20 74 72 61 6e 73 66 65  ontainer transfe
31e0: 72 73 20 6f 77 6e 65 72 73 68 69 70 20 6f 66 20  rs ownership of 
31f0: 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 74 68  that value to th
3200: 65 20 63 6f 6e 74 61 69 6e 65 72 2c 20 6d 65 61  e container, mea
3210: 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 76 61  ning that the va
3220: 6c 75 65 27 73 20 72 65 73 6f 75 72 63 65 73 20  lue's resources 
3230: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
3240: 62 65 20 63 6c 65 61 6e 65 64 20 75 70 20 62 79  be cleaned up by
3250: 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 2e 20   the container. 
3260: 49 74 20 6d 61 79 20 62 65 20 75 73 65 66 75 6c  It may be useful
3270: 20 69 6e 20 73 6f 6d 65 20 63 61 73 65 73 20 74   in some cases t
3280: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 61 20  o ensure that a 
3290: 63 6f 6e 74 61 69 6e 65 72 2d 68 65 6c 64 20 76  container-held v
32a0: 61 6c 75 65 20 68 61 73 20 61 6e 20 6c 69 66 65  alue has an life
32b0: 73 70 61 6e 20 69 6e 64 65 70 65 6e 64 65 6e 74  span independent
32c0: 20 6f 66 20 74 68 61 74 20 63 6f 6e 74 61 69 6e   of that contain
32d0: 65 72 20 28 6f 72 20 73 65 76 65 72 61 6c 20 63  er (or several c
32e0: 6f 6e 74 61 69 6e 65 72 73 29 2e 20 54 6f 20 64  ontainers). To d
32f0: 6f 20 74 68 61 74 20 74 68 65 20 63 6c 69 65 6e  o that the clien
3300: 74 20 63 61 6e 20 6d 61 6e 75 61 6c 6c 79 20 69  t can manually i
3310: 6e 63 72 65 6d 65 6e 74 20 74 68 65 20 72 65 66  ncrement the ref
3320: 65 72 65 6e 63 65 20 63 6f 75 6e 74 2c 20 6c 69  erence count, li
3330: 6b 65 20 74 68 69 73 3a 0d 0a 0d 0a 3c 76 65 72  ke this:....<ver
3340: 62 61 74 69 6d 3e 0d 0a 63 73 6f 6e 5f 76 61 6c  batim>..cson_val
3350: 75 65 20 2a 20 6d 79 56 61 6c 75 65 20 3d 20 2e  ue * myValue = .
3360: 2e 2e 3b 0d 0a 2e 2e 2e 0d 0a 63 73 6f 6e 5f 76  ..;.......cson_v
3370: 61 6c 75 65 5f 61 64 64 5f 72 65 66 65 72 65 6e  alue_add_referen
3380: 63 65 28 20 6d 79 56 61 6c 75 65 20 29 3b 0d 0a  ce( myValue );..
3390: 3c 2f 76 65 72 62 61 74 69 6d 3e 0d 0a 0d 0a 54  </verbatim>....T
33a0: 68 65 20 76 61 6c 75 65 20 63 61 6e 20 74 68 65  he value can the
33b0: 6e 20 62 65 20 66 72 65 65 64 20 75 73 69 6e 67  n be freed using
33c0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 6d 65 63 68   the normal mech
33d0: 61 6e 69 73 6d 3a 0d 0a 0d 0a 3c 76 65 72 62 61  anism:....<verba
33e0: 74 69 6d 3e 0d 0a 63 73 6f 6e 5f 76 61 6c 75 65  tim>..cson_value
33f0: 5f 66 72 65 65 28 20 6d 79 56 61 6c 75 65 20 29  _free( myValue )
3400: 3b 0d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0d 0a  ;..</verbatim>..
3410: 0d 0a 54 68 61 74 20 77 69 6c 6c 20 64 65 63 72  ..That will decr
3420: 65 61 73 65 20 69 74 73 20 72 65 66 65 72 65 6e  ease its referen
3430: 63 65 20 63 6f 75 6e 74 2c 20 63 6c 65 61 6e 69  ce count, cleani
3440: 6e 67 20 69 74 20 75 70 20 69 66 20 74 68 65 20  ng it up if the 
3450: 63 6f 75 6e 74 20 64 72 6f 70 73 20 74 6f 20 30  count drops to 0
3460: 2e 20 49 66 20 61 20 63 6f 6e 74 61 69 6e 65 72  . If a container
3470: 20 28 6f 72 20 61 6e 6f 74 68 65 72 20 63 61 6c   (or another cal
3480: 6c 20 74 6f 20 3c 74 74 3e 63 73 6f 6e 5f 76 61  l to <tt>cson_va
3490: 6c 75 65 5f 61 64 64 5f 72 65 66 65 72 65 6e 63  lue_add_referenc
34a0: 65 28 29 3c 2f 74 74 3e 29 20 68 61 73 20 69 6e  e()</tt>) has in
34b0: 63 72 65 61 73 65 64 20 74 68 65 20 63 6f 75 6e  creased the coun
34c0: 74 2c 20 74 68 65 20 76 61 6c 75 65 20 77 6f 6e  t, the value won
34d0: 27 74 20 62 65 20 63 6c 65 61 6e 65 64 20 75 70  't be cleaned up
34e0: 20 75 6e 74 69 6c 20 74 68 65 20 6c 61 73 74 20   until the last 
34f0: 72 65 66 65 72 65 6e 63 65 20 69 73 20 72 65 6c  reference is rel
3500: 65 61 73 65 64 2e 0d 0a 0d 0a 54 68 69 73 20 63  eased.....This c
3510: 61 6e 20 61 6c 73 6f 20 62 65 20 75 73 65 64 20  an also be used 
3520: 77 68 65 6e 20 69 6d 70 6c 65 6d 65 6e 74 69 6e  when implementin
3530: 67 20 63 75 73 74 6f 6d 20 3c 74 74 3e 63 73 6f  g custom <tt>cso
3540: 6e 5f 76 61 6c 75 65 3c 2f 74 74 3e 20 63 6f 6e  n_value</tt> con
3550: 74 61 69 6e 65 72 73 20 6e 6f 74 20 73 70 65 63  tainers not spec
3560: 69 66 69 65 64 20 62 79 20 74 68 65 20 4a 53 4f  ified by the JSO
3570: 4e 20 41 50 49 2e 20 65 2e 67 2e 20 77 68 65 6e  N API. e.g. when
3580: 20 73 74 6f 72 69 6e 67 20 3c 74 74 3e 63 73 6f   storing <tt>cso
3590: 6e 5f 76 61 6c 75 65 3c 2f 74 74 3e 20 6f 62 6a  n_value</tt> obj
35a0: 65 63 74 73 20 69 6e 20 43 2b 2b 20 53 54 4c 20  ects in C++ STL 
35b0: 63 6f 6e 74 61 69 6e 65 72 20 28 69 6e 20 70 61  container (in pa
35c0: 72 74 69 63 75 6c 61 72 20 69 66 20 61 20 76 61  rticular if a va
35d0: 6c 75 65 20 6d 69 67 68 74 20 62 65 20 69 6e 20  lue might be in 
35e0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 63 6f  more than one co
35f0: 6e 74 61 69 6e 65 72 29 2c 20 69 74 20 6d 61 79  ntainer), it may
3600: 20 62 65 20 6e 65 63 65 73 73 61 72 79 20 74 6f   be necessary to
3610: 20 6d 61 6e 75 61 6c 6c 79 20 61 64 64 20 61 20   manually add a 
3620: 72 65 66 65 72 65 6e 63 65 2e 0d 0a 0d 0a 41 6e  reference.....An
3630: 6f 74 68 65 72 20 77 61 79 20 74 6f 20 61 63 68  other way to ach
3640: 69 65 76 65 20 74 68 65 20 6c 6f 6e 67 65 72 2d  ieve the longer-
3650: 6c 69 66 65 74 69 6d 65 20 65 66 66 65 63 74 20  lifetime effect 
3660: 69 73 20 74 6f 20 6b 65 65 70 20 61 6e 20 65 78  is to keep an ex
3670: 74 72 61 20 3c 74 74 3e 63 73 6f 6e 5f 6f 62 6a  tra <tt>cson_obj
3680: 65 63 74 3c 2f 74 74 3e 20 20 6f 72 20 3c 74 74  ect</tt>  or <tt
3690: 3e 63 73 6f 6e 5f 61 72 72 61 79 3c 2f 74 74 3e  >cson_array</tt>
36a0: 20 69 6e 20 79 6f 75 72 20 61 70 70 6c 69 63 61   in your applica
36b0: 74 69 6f 6e 20 61 6e 64 20 73 74 6f 72 65 20 61  tion and store a
36c0: 6c 6c 20 69 6d 70 6f 72 74 61 6e 74 2f 72 65 2d  ll important/re-
36d0: 75 73 61 62 6c 65 20 76 61 6c 75 65 73 20 74 68  usable values th
36e0: 65 72 65 20 28 69 6e 20 61 64 64 69 74 69 6f 6e  ere (in addition
36f0: 20 74 6f 20 69 6e 20 61 6e 79 20 6f 74 68 65 72   to in any other
3700: 20 63 6f 6e 74 61 69 6e 65 72 73 20 79 6f 75 20   containers you 
3710: 61 70 70 20 75 73 65 73 29 2e 20 49 6e 20 74 68  app uses). In th
3720: 61 74 20 63 61 73 65 2c 20 74 68 65 20 22 65 78  at case, the "ex
3730: 74 72 61 22 20 63 6f 6e 74 61 69 6e 65 72 20 68  tra" container h
3740: 6f 6c 64 73 20 69 74 73 20 6f 77 6e 20 72 65 66  olds its own ref
3750: 65 72 65 6e 63 65 20 74 6f 20 74 68 6f 73 65 20  erence to those 
3760: 76 61 6c 75 65 73 2c 20 73 6f 20 74 68 6f 73 65  values, so those
3770: 20 76 61 6c 75 65 73 20 61 72 65 20 67 75 61 72   values are guar
3780: 61 6e 74 65 65 64 20 74 6f 20 6c 69 76 65 20 61  anteed to live a
3790: 74 20 6c 65 61 73 74 20 61 73 20 6c 6f 6e 67 20  t least as long 
37a0: 61 73 20 74 68 65 20 65 78 74 72 61 20 63 6f 6e  as the extra con
37b0: 74 61 69 6e 65 72 20 64 6f 65 73 20 28 69 74 20  tainer does (it 
37c0: 77 6f 75 6c 64 20 70 72 65 73 75 6d 61 62 6c 79  would presumably
37d0: 20 62 65 20 63 6c 65 61 6e 65 64 20 75 70 20 77   be cleaned up w
37e0: 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
37f0: 69 6f 6e 20 65 78 69 74 73 29 2e 0d 0a 0d 0a 3c  ion exits).....<
3800: 68 31 3e 54 68 72 65 61 64 69 6e 67 3c 2f 68 31  h1>Threading</h1
3810: 3e 0d 0a 0d 0a 43 6f 6e 63 75 72 72 65 6e 74 20  >....Concurrent 
3820: 3c 65 6d 3e 72 65 61 64 2d 6f 6e 6c 79 3c 2f 65  <em>read-only</e
3830: 6d 3e 20 61 63 63 65 73 73 20 74 6f 20 61 6e 79  m> access to any
3840: 20 67 69 76 65 6e 20 6f 62 6a 65 63 74 2f 61 72   given object/ar
3850: 72 61 79 20 74 72 65 65 20 69 73 20 6c 65 67 61  ray tree is lega
3860: 6c 2c 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  l, as long as no
3870: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 72 65   two threads are
3880: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
3890: 74 72 61 76 65 72 73 61 6c 20 64 61 74 61 20 28  traversal data (
38a0: 65 2e 67 2e 20 74 68 65 20 73 61 6d 65 20 3c 74  e.g. the same <t
38b0: 74 3e 63 73 6f 6e 5f 6f 62 6a 65 63 74 5f 69 74  t>cson_object_it
38c0: 65 72 61 74 6f 72 3c 2f 74 74 3e 20 6f 72 20 73  erator</tt> or s
38d0: 61 6d 65 20 63 6f 70 79 20 6f 66 20 61 6e 20 61  ame copy of an a
38e0: 72 72 61 79 20 69 6e 64 65 78 20 76 61 72 69 61  rray index varia
38f0: 62 6c 65 29 2e 20 41 6c 6c 20 77 72 69 74 65 20  ble). All write 
3900: 61 63 63 65 73 73 20 74 6f 20 61 6e 79 20 63 73  access to any cs
3910: 6f 6e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  on value must be
3920: 20 64 6f 6e 65 20 69 6e 20 61 20 73 69 6e 67 6c   done in a singl
3930: 65 20 74 68 72 65 61 64 20 6f 72 20 6d 75 73 74  e thread or must
3940: 20 62 65 20 63 61 72 65 66 75 6c 6c 79 20 73 65   be carefully se
3950: 72 69 61 6c 69 7a 65 64 20 62 79 20 74 68 65 20  rialized by the 
3960: 63 6c 69 65 6e 74 2e 20 57 68 69 6c 65 20 77 72  client. While wr
3970: 69 74 65 20 61 63 63 65 73 73 20 69 73 20 67 6f  ite access is go
3980: 69 6e 67 20 6f 6e 2c 20 61 6e 79 20 63 6f 6e 63  ing on, any conc
3990: 75 72 72 65 6e 74 20 72 65 61 64 20 61 63 63 65  urrent read acce
39a0: 73 73 20 68 61 73 20 75 6e 73 70 65 63 69 66 69  ss has unspecifi
39b0: 65 64 20 72 65 73 75 6c 74 73 2e 0d 0a 0d 0a 54  ed results.....T
39c0: 68 65 20 3c 74 74 3e 63 73 6f 6e 5f 70 61 72 73  he <tt>cson_pars
39d0: 65 28 29 3c 2f 74 74 3e 20 61 6e 64 20 3c 74 74  e()</tt> and <tt
39e0: 3e 63 73 6f 6e 5f 6f 75 74 70 75 74 28 29 3c 2f  >cson_output()</
39f0: 74 74 3e 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  tt> family of fu
3a00: 6e 63 74 69 6f 6e 73 20 75 73 65 20 6e 6f 20 73  nctions use no s
3a10: 68 61 72 65 64 20 73 74 61 74 65 20 61 6e 64 20  hared state and 
3a20: 61 72 65 20 20 74 68 72 65 61 64 20 73 61 66 65  are  thread safe
3a30: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
3a40: 77 6f 20 74 68 72 65 61 64 73 20 70 61 73 73 20  wo threads pass 
3a50: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
3a60: 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 76  same parameter v
3a70: 61 6c 75 65 73 2e 20 65 2e 67 2e 20 70 61 73 73  alues. e.g. pass
3a80: 69 6e 67 20 74 68 65 20 73 61 6d 65 20 3c 74 74  ing the same <tt
3a90: 3e 63 73 6f 6e 5f 70 61 72 73 65 5f 69 6e 66 6f  >cson_parse_info
3aa0: 3c 2f 74 74 3e 20 6f 62 6a 65 63 74 20 74 6f 20  </tt> object to 
3ab0: 74 77 6f 20 63 6f 6e 63 75 72 72 65 6e 74 20 63  two concurrent c
3ac0: 61 6c 6c 73 20 74 6f 20 3c 74 74 3e 63 73 6f 6e  alls to <tt>cson
3ad0: 5f 70 61 72 73 65 28 29 3c 2f 74 74 3e 20 77 6f  _parse()</tt> wo
3ae0: 75 6c 64 20 68 61 76 65 20 75 6e 64 65 66 69 6e  uld have undefin
3af0: 65 64 20 72 65 73 75 6c 74 73 2e 0d 0a 0d 0a 54  ed results.....T
3b00: 68 65 20 67 6c 6f 62 61 6c 6c 79 2d 73 68 61 72  he globally-shar
3b10: 65 64 20 73 74 61 74 65 20 75 73 65 64 20 62 79  ed state used by
3b20: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 73 20   the library is 
3b30: 6c 69 6d 69 74 65 64 20 74 6f 3a 0d 0a 0d 0a 20  limited to:.... 
3b40: 20 20 2a 20 20 49 6e 74 65 72 6e 61 6c 20 63 6f    *  Internal co
3b50: 6e 73 74 61 6e 74 20 6f 62 6a 65 63 74 73 20 77  nstant objects w
3b60: 68 69 63 68 20 61 72 65 20 69 6e 69 74 69 61 6c  hich are initial
3b70: 69 7a 65 64 20 70 72 65 2d 3c 74 74 3e 6d 61 69  ized pre-<tt>mai
3b80: 6e 28 29 3c 2f 74 74 3e 20 61 6e 64 20 6e 65 76  n()</tt> and nev
3b90: 65 72 20 6d 6f 64 69 66 69 65 64 2c 20 73 6f 20  er modified, so 
3ba0: 74 68 65 73 65 20 61 72 65 20 73 61 66 65 20 76  these are safe v
3bb0: 69 73 2d 61 2d 76 69 73 20 74 68 72 65 61 64 73  is-a-vis threads
3bc0: 20 28 61 73 73 75 6d 69 6e 67 20 74 68 65 20 74   (assuming the t
3bd0: 68 72 65 61 64 73 20 61 72 65 20 6e 6f 74 20 73  hreads are not s
3be0: 74 61 72 74 65 64 20 70 72 65 2d 3c 74 74 3e 6d  tarted pre-<tt>m
3bf0: 61 69 6e 28 29 3c 2f 74 74 3e 2c 20 65 2e 67 2e  ain()</tt>, e.g.
3c00: 20 61 73 20 61 20 73 69 64 65 2d 65 66 66 65 63   as a side-effec
3c10: 74 20 6f 66 20 73 74 61 74 69 63 20 43 2b 2b 20  t of static C++ 
3c20: 6f 62 6a 65 63 74 20 69 6e 69 74 69 61 6c 69 7a  object initializ
3c30: 61 74 69 6f 6e 29 2e 20 42 65 63 61 75 73 65 20  ation). Because 
3c40: 74 68 65 79 20 61 72 65 20 6e 65 76 65 72 20 6d  they are never m
3c50: 6f 64 69 66 69 65 64 20 61 6e 64 20 43 20 68 61  odified and C ha
3c60: 73 20 6e 6f 20 64 65 73 74 72 75 63 74 6f 72 73  s no destructors
3c70: 2c 20 74 68 65 73 65 20 69 6e 73 74 61 6e 63 65  , these instance
3c80: 20 22 73 68 6f 75 6c 64 22 20 62 65 20 73 61 66   "should" be saf
3c90: 65 20 69 66 20 75 73 65 64 20 70 6f 73 74 2d 3c  e if used post-<
3ca0: 74 74 3e 6d 61 69 6e 28 29 3c 2f 74 74 3e 2c 20  tt>main()</tt>, 
3cb0: 65 2e 67 2e 20 76 69 61 20 61 6e 20 3c 74 74 3e  e.g. via an <tt>
3cc0: 61 74 65 78 69 74 28 29 3c 2f 74 74 3e 20 68 61  atexit()</tt> ha
3cd0: 6e 64 6c 65 72 2c 20 61 73 73 75 6d 69 6e 67 20  ndler, assuming 
3ce0: 6d 79 20 75 6e 64 65 72 73 74 61 6e 64 69 6e 67  my understanding
3cf0: 20 6f 66 20 74 68 65 20 3c 74 74 3e 65 78 69 74   of the <tt>exit
3d00: 28 29 3c 2f 74 74 3e 2f 72 65 74 75 72 6e 2d 66  ()</tt>/return-f
3d10: 72 6f 6d 2d 3c 74 74 3e 6d 61 69 6e 28 29 3c 2f  rom-<tt>main()</
3d20: 74 74 3e 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  tt> handling is 
3d30: 63 6f 72 72 65 63 74 2e 0d 0a 20 20 20 2a 20 20  correct...   *  
3d40: 54 68 65 20 73 79 73 74 65 6d 27 73 20 3c 74 74  The system's <tt
3d50: 3e 6d 61 6c 6c 6f 63 28 29 3c 2f 74 74 3e 20 61  >malloc()</tt> a
3d60: 6e 64 20 66 72 69 65 6e 64 73 2c 20 73 6f 20 69  nd friends, so i
3d70: 74 20 69 6e 68 65 72 69 74 73 20 61 6e 79 20 74  t inherits any t
3d80: 68 72 65 61 64 69 6e 67 20 6c 69 6d 69 74 61 74  hreading limitat
3d90: 69 6f 6e 73 20 74 68 6f 73 65 20 6d 61 79 20 69  ions those may i
3da0: 6d 70 6f 73 65 2e 0a 0a 5a 20 35 63 32 61 62 39  mpose...Z 5c2ab9
3db0: 65 32 66 62 36 66 35 62 37 34 34 31 61 62 37 31  e2fb6f5b7441ab71
3dc0: 66 37 36 65 64 37 38 62 62 63 0a                 f76ed78bbc.