sys/man/2/json

   1 .TH JSON 2
   2 .SH NAME
   3 jsonparse,
   4 jsonfree,
   5 jsonbyname,
   6 jsonstr
   7 \- JSON parser
   8 .SH SYNOPSIS
   9 .\" .ta 0.75i 1.5i 2.25i 3i 3.75i 4.5i
  10 .ta 0.7i +0.7i +0.7i +0.7i +0.7i +0.7i +0.7i
  11 .EX
  12 #include <u.h>
  13 #include <libc.h>
  14 #include <json.h>
  15
  16 enum {
  17         JSONNull,
  18         JSONBool,
  19         JSONNumber,
  20         JSONString,
  21         JSONArray,
  22         JSONObject,
  23 };
  24
  25 typedef struct JSONEl JSONEl;
  26 struct JSONEl {
  27         char *name;
  28         JSON *val;
  29         JSONEl *next;
  30 };
  31
  32 typedef struct JSON JSON;
  33 struct JSON
  34 {
  35         int t;
  36         union {
  37                 double n;
  38                 char *s;
  39                 JSONEl *first;
  40         };
  41 };
  42
  43 JSON*   jsonparse(char *s);
  44 void    jsonfree(JSON *j);
  45 JSON*   jsonbyname(JSON *j, char *s);
  46 char*   jsonstr(JSON *j);
  47 int     JSONfmt(Fmt *f)
  48 void    JSONfmtinstall(void);
  49 .EE
  50 .SH DESCRIPTION
  51 The
  52 .B JSON
  53 structure represents a variant json value. The variant type
  54 is stored in the
  55 .I t
  56 member of the structure. String values use
  57 .BR s ,
  58 booleans and numbers use the
  59 .B n
  60 members in the structure.
  61 Arrays and objects (dictionaries) are represented by
  62 a singly-linked list of
  63 .B JSONEl
  64 structures referred to from the
  65 .B first
  66 pointer in the
  67 .B JSON
  68 structure.
  69 Each
  70 .B JSONEl
  71 has a
  72 .B val
  73 pointer to the associated value and a
  74 .B next
  75 pointer to the next element in the array or object.
  76 Dictionary objects have the
  77 .B name
  78 member set to the key of the association.
  79 .P
  80 A json object is parsed by calling
  81 .I jsonparse
  82 with a
  83 .B UTF-8
  84 string of the json encoded data. On success, a non-nil pointer to a
  85 newly allocated
  86 .B JSON
  87 structure is returned.
  88 To free the parsed objects,
  89 .I jsonfree
  90 has to be called.
  91 .P
  92 The
  93 .I jsonbyname
  94 function returns the associated value of a dictionary item.
  95 .P
  96 The function
  97 .I jsonstr
  98 returns the string value of a json object or
  99 .B nil
 100 for any other object type.
 101 .P
 102 .I JSONfmt
 103 is a
 104 .IR print (2)
 105 formatting routine that prints a well-formatted JSON structure.
 106 It can be installed by hand but
 107 .I JSONfmtinstall
 108 installs it under the standard format character J. The header
 109 .B <json.h>
 110 contains a #pragma statement so the compiler can
 111 type-check uses of
 112 .B %J
 113 in
 114 .IR print (2)
 115 format strings.
 116 .SH SOURCE
 117 .B /sys/src/libjson
 118 .SH DIAGNOSTICS
 119 The functions
 120 .I jsonparse,
 121 .I jsonbyname
 122 and
 123 .I jsonstr
 124 return
 125 .B nil
 126 on error and set an error string (see
 127 .IR errstr (2)).