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 To enforce that specification is always provided use "require_types".
81 In this case when "encode" is called without second argument (or is
82 undef) then it croaks. It applies recursively for all sub-structures.
83 JSON type specification for scalars:
85 JSON_TYPE_BOOL
86 It enforces JSON boolean in resulting JSON, i.e. either "true" or
87 "false". For determining whether the scalar passed to the encoder
88 is true, standard perl boolean logic is used.
89 JSON_TYPE_INT
91 It enforces JSON number without fraction part in the resulting
92 JSON. Equivalent of perl function int is used for conversion.
93 JSON_TYPE_FLOAT
95 It enforces JSON number with fraction part in the resulting JSON.
96 Equivalent of perl operation +0 is used for conversion.
97 JSON_TYPE_STRING
99 It enforces JSON string type in the resulting JSON.
100 JSON_TYPE_NULL
102 It represents JSON "null" value. Makes sense only when passing
103 perl's "undef" value.
104 For each type, there also exists a type with the suffix "_OR_NULL"
106 which encodes perl's "undef" into JSON "null". Without type with suffix
107 "_OR_NULL" perl's "undef" is converted to specific type according to
108 above rules.
109 JSON type specification for arrays:
111 [...]
112 The array must contain the same number of elements as in the perl
113 array passed for encoding. Each element of the array describes the
114 JSON type which is enforced for the corresponding element of the
115 perl array.
116 json_type_arrayof
118 This function takes a JSON type specification as its argument which
119 is enforced for every element of the passed perl array.
120 JSON type specification for hashes:
122 {...}
123 Each hash value for corresponding key describes the JSON type
124 specification for values of passed perl hash structure. Keys in
125 hash which are not present in passed perl hash structure are simple
126 ignored and not used.
127 json_type_hashof
129 This function takes a JSON type specification as its argument which
130 is enforced for every value of passed perl hash structure.
131 JSON type specification for alternatives:
133 json_type_anyof
134 This function takes a list of JSON type alternative specifications
135 (maximally one scalar, one array, and one hash) as its input and
136 the JSON encoder chooses one that matches.
137 json_type_null_or_anyof
139 Like "json_type_anyof", but scalar can be only perl's "undef".
140 Recursive specifications
142 json_type_weaken
143 This function can be used as an argument for "json_type_arrayof",
144 "json_type_hashof" or "json_type_anyof" functions to create weak
145 references suitable for complicated recursive structures. It
146 depends on the weaken function from Scalar::Util module. See
147 following example:
148 my $struct = {
150 type => JSON_TYPE_STRING,
151 array => json_type_arrayof(JSON_TYPE_INT),
152 };
153 $struct->{recursive} = json_type_anyof(
154 json_type_weaken($struct),
155 json_type_arrayof(JSON_TYPE_STRING),
156 );
157 If you want to encode all perl scalars to JSON string types despite
159 how complicated is input perl structure you can define JSON type
160 specification for alternatives recursively. It could be defined as:
161 my $type = json_type_anyof();
163 $type->[0] = JSON_TYPE_STRING_OR_NULL;
164 $type->[1] = json_type_arrayof(json_type_weaken($type));
165 $type->[2] = json_type_hashof(json_type_weaken($type));
166 print encode_json([ 10, "10", { key => 10 } ], $type);
168 # ["10","10",{"key":"10"}]
169 An alternative solution for encoding all scalars to JSON strings is
171 to use "type_all_string" method of Cpanel::JSON::XS itself:
172 my $json = Cpanel::JSON::XS->new->type_all_string;
174 print $json->encode([ 10, "10", { key => 10 } ]);
175 # ["10","10",{"key":"10"}]
176
178 Pali <pali@cpan.org>
179
181 Copyright (c) 2017, GoodData Corporation. All rights reserved.
182 This module is available under the same licences as perl, the Artistic
184 license and the GPL.
185perl v5.38.0 2023-07-20 XS::Type(3)