1JSON(3am)                  GNU Awk Extension Modules                 JSON(3am)
2
3
4

NAME

6       json - import from and export to JSON format
7

SYNOPSIS

9       @load "json"
10
11       status = json_fromJSON(string, array)
12
13       encoded = json_toJSON(array [, use_real_array])
14

DESCRIPTION

16       JSON  objects represent associations of names with values, what we will
17       call linear arrays (arrays  with  numeric  indices),  and  subgroupings
18       (nested  associative  arrays).   Such objects map well onto gawk's true
19       multidimensional associative arrays.  This extension provides a  mecha‐
20       nism  to  encode  a  gawk  array  as a JSON string and to decode a JSON
21       object into a gawk array.
22
23       The json extension adds two functions as follows:
24
25       json_fromJSON(string, array)
26              This function takes a string  representing  a  JSON  object  and
27              decodes it into the array argument.  The array is cleared first.
28              The return status is one upon success or zero upon failure.   In
29              addition, gawk's ERRNO variable is updated to (sort of) indicate
30              what the problem was.
31
32       json_toJSON(array[, use_real_array])
33              This function takes an array argument and encodes the array con‐
34              tents  as  a  JSON  object in the returned string.  The returned
35              string will be empty if an error  of  some  kind  occurred.   In
36              addition, gawk's ERRNO variable is updated to (sort of) indicate
37              what the problem was.
38
39              If the optional parameter use_real_array is not zero,  json_toJ‐
40              SON()  encodes arrays indexed from 1 to N as JSON linear arrays,
41              instead of as associative arrays. This gives a better  rendition
42              into  JSON, at the expense of some additional CPU time to verify
43              that the array is indeed indexed linearly.
44

BUGS

46       The mapping between gawk objects and JSON objects  isn't  perfect.   In
47       particular,  JSON  boolean  objects map to 1 or 0, losing the type dis‐
48       tinction.  Typed regular expression constants in gawk are encoded as  a
49       string,  with  the  regexp  bracketed  by  @/ and /.  For example, pat‐
50       tern:"@/[a-z]+[0-9]?/".
51

EXAMPLE

53       @load "filefuncs"
54       @load "json"
55       ...
56       BEGIN {
57            stat("/etc/passwd", data)
58            statinfo = json_toJSON(data)
59            print statinfo
60       }
61
62       BEGIN {
63            getline statinfo
64            if (! json_fromJSON(statinfo, data))
65                 print "JSON import failed!" > "/dev/stderr"
66                 exit 1
67            }
68
69            # do something with the info
70       }
71

NOTES

73       This extension uses RapidJSON to parse a  JSON  document  into  a  gawk
74       array.  This approximates the Document Object Model (DOM) paradigm.  In
75       the author's humble opinion, the SAX paradigm for parsing JSON does not
76       match  well  with  awk's  design. If you want SAX parsing of JSON, this
77       isn't the place.
78

SEE ALSO

80       JSON home page:     https://www.json.org/
81
82       Wikipedia:          https://en.wikipedia.org/wiki/JSON
83
84       RapidJSON home page:     http://rapidjson.org/
85

AUTHOR

87       Arnold D. Robbins
88

COPYING PERMISSIONS

90       Copyright © 2017, the Free Software Foundation, Inc.
91       Copyright © 2017, Arnold David Robbins.
92
93       Permission is granted to make and distribute verbatim  copies  of  this
94       manual  page  provided  the copyright notice and this permission notice
95       are preserved on all copies.
96
97       Permission is granted to copy and distribute modified versions of  this
98       manual  page  under  the conditions for verbatim copying, provided that
99       the entire resulting derived work is distributed under the terms  of  a
100       permission notice identical to this one.
101
102       Permission  is granted to copy and distribute translations of this man‐
103       ual page into another language, under the above conditions for modified
104       versions,  except that this permission notice may be stated in a trans‐
105       lation approved by the Foundation.
106
107
108
109Free Software Foundation          Nov 22 2017                        JSON(3am)
Impressum