1XS::Type(3)           User Contributed Perl Documentation          XS::Type(3)
2
3
4

NAME

6       Cpanel::JSON::XS::Type - Type support for JSON encode
7

SYNOPSIS

9        use Cpanel::JSON::XS;
10        use Cpanel::JSON::XS::Type;
11
12
13        encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING]);
14        # '[10,10,"10.25"]'
15
16        encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT));
17        # '[10,10,10]'
18
19        encode_json(1, JSON_TYPE_BOOL);
20        # 'true'
21
22        my $perl_struct = { key1 => 1, key2 => "2", key3 => 1 };
23        my $type_spec = { key1 => JSON_TYPE_STRING, key2 => JSON_TYPE_INT, key3 => JSON_TYPE_BOOL };
24        my $json_string = encode_json($perl_struct, $type_spec);
25        # '{"key1":"1","key2":2,"key3":true}'
26
27        my $perl_struct = { key1 => "value1", key2 => "value2", key3 => 0, key4 => 1, key5 => "string", key6 => "string2" };
28        my $type_spec = json_type_hashof(JSON_TYPE_STRING);
29        my $json_string = encode_json($perl_struct, $type_spec);
30        # '{"key1":"value1","key2":"value2","key3":"0","key4":"1","key5":"string","key6":"string2"}'
31
32        my $perl_struct = { key1 => { key2 => [ 10, "10", 10.6 ] }, key3 => "10.5" };
33        my $type_spec = { key1 => json_type_anyof(JSON_TYPE_FLOAT, json_type_hashof(json_type_arrayof(JSON_TYPE_INT))), key3 => JSON_TYPE_FLOAT };
34        my $json_string = encode_json($perl_struct, $type_spec);
35        # '{"key1":{"key2":[10,10,10]},"key3":10.5}'
36
37
38        my $value = decode_json('false', 1, my $type);
39        # $value is 0 and $type is JSON_TYPE_BOOL
40
41        my $value = decode_json('0', 1, my $type);
42        # $value is 0 and $type is JSON_TYPE_INT
43
44        my $value = decode_json('"0"', 1, my $type);
45        # $value is 0 and $type is JSON_TYPE_STRING
46
47        my $json_string = '{"key1":{"key2":[10,"10",10.6]},"key3":"10.5"}';
48        my $perl_struct = decode_json($json_string, 0, my $type_spec);
49        # $perl_struct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }
50        # $type_spec is { key1 => { key2 => [ JSON_TYPE_INT, JSON_TYPE_STRING, JSON_TYPE_FLOAT ] }, key3 => JSON_TYPE_STRING }
51

DESCRIPTION

53       This module provides stable JSON type support for the Cpanel::JSON::XS
54       encoder which doesn't depend on any internal perl scalar flags or
55       characteristics. Also it provides real JSON types for Cpanel::JSON::XS
56       decoder.
57
58       In most cases perl structures passed to encode_json come from other
59       functions or from other modules and caller of Cpanel::JSON::XS module
60       does not have control of internals or they are subject of change. So it
61       is not easy to support enforcing types as described in the simple
62       scalars section.
63
64       For services based on JSON contents it is sometimes needed to correctly
65       process and enforce JSON types.
66
67       The function decode_json takes optional third scalar parameter and
68       fills it with specification of json types.
69
70       The function encode_json takes a perl structure as its input and
71       optionally also a json type specification in the second parameter.
72
73       If the specification is not provided (or is undef) internal perl scalar
74       flags are used for the resulting JSON type. The internal flags can be
75       changed by perl itself, but also by external modules. Which means that
76       types in resulting JSON string aren't stable. Specially it does not
77       work reliable for dual vars and scalars which were used in both numeric
78       and string operations. See simple scalars.
79
80   JSON type specification for scalars:
81       JSON_TYPE_BOOL
82           It enforces JSON boolean in resulting JSON, i.e. either "true" or
83           "false". For determining whether the scalar passed to the encoder
84           is true, standard perl boolean logic is used.
85
86       JSON_TYPE_INT
87           It enforces JSON number without fraction part in the resulting
88           JSON.  Equivalent of perl function int is used for conversion.
89
90       JSON_TYPE_FLOAT
91           It enforces JSON number with fraction part in the resulting JSON.
92           Equivalent of perl operation +0 is used for conversion.
93
94       JSON_TYPE_STRING
95           It enforces JSON string type in the resulting JSON.
96
97       JSON_TYPE_NULL
98           It represents JSON "null" value. Makes sense only when passing
99           perl's "undef" value.
100
101       For each type, there also exists a type with the suffix "_OR_NULL"
102       which encodes perl's "undef" into JSON "null". Without type with suffix
103       "_OR_NULL" perl's "undef" is converted to specific type according to
104       above rules.
105
106   JSON type specification for arrays:
107       [...]
108           The array must contain the same number of elements as in the perl
109           array passed for encoding. Each element of the array describes the
110           JSON type which is enforced for the corresponding element of the
111           perl array.
112
113       json_type_arrayof
114           This function takes a JSON type specification as its argument which
115           is enforced for every element of the passed perl array.
116
117   JSON type specification for hashes:
118       {...}
119           Each hash value for corresponding key describes the JSON type
120           specification for values of passed perl hash structure. Keys in
121           hash which are not present in passed perl hash structure are simple
122           ignored and not used.
123
124       json_type_hashof
125           This function takes a JSON type specification as its argument which
126           is enforced for every value of passed perl hash structure.
127
128   JSON type specification for alternatives:
129       json_type_anyof
130           This function takes a list of JSON type alternative specifications
131           (maximally one scalar, one array, and one hash) as its input and
132           the JSON encoder chooses one that matches.
133
134       json_type_null_or_anyof
135           Like "json_type_anyof", but scalar can be only perl's "undef".
136
137       json_type_weaken
138           This function can be used as an argument for "json_type_arrayof",
139           "json_type_hashof" or "json_type_anyof" functions to create weak
140           references suitable for complicated recursive structures. It
141           depends on the weaken function from Scalar::Util module.  See
142           following example:
143
144             my $struct = {
145                 type => JSON_TYPE_STRING,
146                 array => json_type_arrayof(JSON_TYPE_INT),
147             };
148             $struct->{recursive} = json_type_anyof(
149                 json_type_weaken($struct),
150                 json_type_arrayof(JSON_TYPE_STRING),
151             );
152

AUTHOR

154       Pali <pali@cpan.org>
155
157       Copyright (c) 2017, GoodData Corporation. All rights reserved.
158
159       This module is available under the same licences as perl, the Artistic
160       license and the GPL.
161
162
163
164perl v5.28.0                      2018-08-19                       XS::Type(3)
Impressum