1XS::Type(3) User Contributed Perl Documentation XS::Type(3)
2
6 Cpanel::JSON::XS::Type - Type support for JSON encode
7
9 use Cpanel::JSON::XS;
10 use Cpanel::JSON::XS::Type;
11 encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING]);
14 # '[10,10,"10.25"]'
15 encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT));
17 # '[10,10,10]'
18 encode_json(1, JSON_TYPE_BOOL);
20 # 'true'
21 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 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 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 my $value = decode_json('false', 1, my $type);
39 # $value is 0 and $type is JSON_TYPE_BOOL
40 my $value = decode_json('0', 1, my $type);
42 # $value is 0 and $type is JSON_TYPE_INT
43 my $value = decode_json('"0"', 1, my $type);
45 # $value is 0 and $type is JSON_TYPE_STRING
46 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
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 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 For services based on JSON contents it is sometimes needed to correctly
65 process and enforce JSON types.
66 The function decode_json takes optional third scalar parameter and
68 fills it with specification of json types.
69 The function encode_json takes a perl structure as its input and
71 optionally also a json type specification in the second parameter.
72 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 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 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 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 JSON_TYPE_STRING
95 It enforces JSON string type in the resulting JSON.
96 JSON_TYPE_NULL
98 It represents JSON "null" value. Makes sense only when passing
99 perl's "undef" value.
100 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 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 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 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 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 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 json_type_null_or_anyof
135 Like "json_type_anyof", but scalar can be only perl's "undef".
136 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 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
154 Pali <pali@cpan.org>
155
157 Copyright (c) 2017, GoodData Corporation. All rights reserved.
158 This module is available under the same licences as perl, the Artistic
160 license and the GPL.
161perl v5.28.0 2018-08-19 XS::Type(3)