XS::Type(3) User Contributed Perl Documentation XS::Type(3)
NAME
Cpanel::JSON::XS::Type - Type support for JSON encode
SYNOPSIS
use Cpanel::JSON::XS;
use Cpanel::JSON::XS::Type;
encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING]);
# '[10,10,"10.25"]'
encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT));
# '[10,10,10]'
encode_json(1, JSON_TYPE_BOOL);
# 'true'
my $perl_struct = { key1 => 1, key2 => "2", key3 => 1 };
my $type_spec = { key1 => JSON_TYPE_STRING, key2 => JSON_TYPE_INT, key3 => JSON_TYPE_BOOL };
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":"1","key2":2,"key3":true}'
my $perl_struct = { key1 => "value1", key2 => "value2", key3 => 0, key4 => 1, key5 => "string", key6 => "string2" };
my $type_spec = json_type_hashof(JSON_TYPE_STRING);
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":"value1","key2":"value2","key3":"0","key4":"1","key5":"string","key6":"string2"}'
my $perl_struct = { key1 => { key2 => [ 10, "10", 10.6 ] }, key3 => "10.5" };
my $type_spec = { key1 => json_type_anyof(JSON_TYPE_FLOAT, json_type_hashof(json_type_arrayof(JSON_TYPE_INT))), key3 => JSON_TYPE_FLOAT };
my $json_string = encode_json($perl_struct, $type_spec);
# '{"key1":{"key2":[10,10,10]},"key3":10.5}'
my $value = decode_json('false', 1, my $type);
# $value is 0 and $type is JSON_TYPE_BOOL
my $value = decode_json('0', 1, my $type);
# $value is 0 and $type is JSON_TYPE_INT
my $value = decode_json('"0"', 1, my $type);
# $value is 0 and $type is JSON_TYPE_STRING
my $json_string = '{"key1":{"key2":[10,"10",10.6]},"key3":"10.5"}';
my $perl_struct = decode_json($json_string, 0, my $type_spec);
# $perl_struct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }
# $type_spec is { key1 => { key2 => [ JSON_TYPE_INT, JSON_TYPE_STRING, JSON_TYPE_FLOAT ] }, key3 => JSON_TYPE_STRING }
DESCRIPTION
This module provides stable JSON type support for the Cpanel::JSON::XS
encoder which doesn't depend on any internal perl scalar flags or
characteristics. Also it provides real JSON types for Cpanel::JSON::XS
decoder.
In most cases perl structures passed to encode_json come from other
functions or from other modules and caller of Cpanel::JSON::XS module
does not have control of internals or they are subject of change. So it
is not easy to support enforcing types as described in the simple
scalars section.
For services based on JSON contents it is sometimes needed to correctly
process and enforce JSON types.
The function decode_json takes optional third scalar parameter and
fills it with specification of json types.
The function encode_json takes a perl structure as its input and
optionally also a json type specification in the second parameter.
If the specification is not provided (or is undef) internal perl scalar
flags are used for the resulting JSON type. The internal flags can be
changed by perl itself, but also by external modules. Which means that
types in resulting JSON string aren't stable. Specially it does not
work reliable for dual vars and scalars which were used in both numeric
and string operations. See simple scalars.
To enforce that specification is always provided use "require_types".
In this case when "encode" is called without second argument (or is
undef) then it croaks. It applies recursively for all sub-structures.
JSON type specification for scalars:
JSON_TYPE_BOOL
It enforces JSON boolean in resulting JSON, i.e. either "true" or
"false". For determining whether the scalar passed to the encoder
is true, standard perl boolean logic is used.
JSON_TYPE_INT
It enforces JSON number without fraction part in the resulting
JSON. Equivalent of perl function int is used for conversion.
JSON_TYPE_FLOAT
It enforces JSON number with fraction part in the resulting JSON.
Equivalent of perl operation +0 is used for conversion.
JSON_TYPE_STRING
It enforces JSON string type in the resulting JSON.
JSON_TYPE_NULL
It represents JSON "null" value. Makes sense only when passing
perl's "undef" value.
For each type, there also exists a type with the suffix "_OR_NULL"
which encodes perl's "undef" into JSON "null". Without type with suffix
"_OR_NULL" perl's "undef" is converted to specific type according to
above rules.
JSON type specification for arrays:
[...]
The array must contain the same number of elements as in the perl
array passed for encoding. Each element of the array describes the
JSON type which is enforced for the corresponding element of the
perl array.
json_type_arrayof
This function takes a JSON type specification as its argument which
is enforced for every element of the passed perl array.
JSON type specification for hashes:
{...}
Each hash value for corresponding key describes the JSON type
specification for values of passed perl hash structure. Keys in
hash which are not present in passed perl hash structure are simple
ignored and not used.
json_type_hashof
This function takes a JSON type specification as its argument which
is enforced for every value of passed perl hash structure.
JSON type specification for alternatives:
json_type_anyof
This function takes a list of JSON type alternative specifications
(maximally one scalar, one array, and one hash) as its input and
the JSON encoder chooses one that matches.
json_type_null_or_anyof
Like "json_type_anyof", but scalar can be only perl's "undef".
Recursive specifications
json_type_weaken
This function can be used as an argument for "json_type_arrayof",
"json_type_hashof" or "json_type_anyof" functions to create weak
references suitable for complicated recursive structures. It
depends on the weaken function from Scalar::Util module. See
following example:
my $struct = {
type => JSON_TYPE_STRING,
array => json_type_arrayof(JSON_TYPE_INT),
};
$struct->{recursive} = json_type_anyof(
json_type_weaken($struct),
json_type_arrayof(JSON_TYPE_STRING),
);
If you want to encode all perl scalars to JSON string types despite
how complicated is input perl structure you can define JSON type
specification for alternatives recursively. It could be defined as:
my $type = json_type_anyof();
$type->[0] = JSON_TYPE_STRING_OR_NULL;
$type->[1] = json_type_arrayof(json_type_weaken($type));
$type->[2] = json_type_hashof(json_type_weaken($type));
print encode_json([ 10, "10", { key => 10 } ], $type);
# ["10","10",{"key":"10"}]
An alternative solution for encoding all scalars to JSON strings is
to use "type_all_string" method of Cpanel::JSON::XS itself:
my $json = Cpanel::JSON::XS->new->type_all_string;
print $json->encode([ 10, "10", { key => 10 } ]);
# ["10","10",{"key":"10"}]
AUTHOR
Pali <pali@cpan.org>
COPYRIGHT & LICENSE
Copyright (c) 2017, GoodData Corporation. All rights reserved.
This module is available under the same licences as perl, the Artistic
license and the GPL.
perl v5.34.3 2024-12-21 XS::Type(3)
cpanel-json-xs 4.390.0 - Generated Sat Dec 21 10:42:14 CST 2024