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       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
84   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
90       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
94       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
98       JSON_TYPE_STRING
99           It enforces JSON string type in the resulting JSON.
100
101       JSON_TYPE_NULL
102           It represents JSON "null" value. Makes sense only when passing
103           perl's "undef" value.
104
105       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
110   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
117       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
121   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
128       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
132   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
138       json_type_null_or_anyof
139           Like "json_type_anyof", but scalar can be only perl's "undef".
140
141   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
149             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
158           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
162             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
167             print encode_json([ 10, "10", { key => 10 } ], $type);
168             # ["10","10",{"key":"10"}]
169
170           An alternative solution for encoding all scalars to JSON strings is
171           to use "type_all_string" method of Cpanel::JSON::XS itself:
172
173             my $json = Cpanel::JSON::XS->new->type_all_string;
174             print $json->encode([ 10, "10", { key => 10 } ]);
175             # ["10","10",{"key":"10"}]
176

AUTHOR

178       Pali <pali@cpan.org>
179
181       Copyright (c) 2017, GoodData Corporation. All rights reserved.
182
183       This module is available under the same licences as perl, the Artistic
184       license and the GPL.
185
186
187
188perl v5.38.0                      2023-07-20                       XS::Type(3)
Impressum