.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XS::Type 3pm"
.TH XS::Type 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Cpanel::JSON::XS::Type \- Type support for JSON encode
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use Cpanel::JSON::XS;
\& use Cpanel::JSON::XS::Type;
\&
\&
\& encode_json([10, "10", 10.25], [JSON_TYPE_INT, JSON_TYPE_INT, JSON_TYPE_STRING]);
\& # \*(Aq[10,10,"10.25"]\*(Aq
\&
\& encode_json([10, "10", 10.25], json_type_arrayof(JSON_TYPE_INT));
\& # \*(Aq[10,10,10]\*(Aq
\&
\& encode_json(1, JSON_TYPE_BOOL);
\& # \*(Aqtrue\*(Aq
\&
\& 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);
\& # \*(Aq{"key1":"1","key2":2,"key3":true}\*(Aq
\&
\& 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);
\& # \*(Aq{"key1":"value1","key2":"value2","key3":"0","key4":"1","key5":"string","key6":"string2"}\*(Aq
\&
\& 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);
\& # \*(Aq{"key1":{"key2":[10,10,10]},"key3":10.5}\*(Aq
\&
\&
\& my $value = decode_json(\*(Aqfalse\*(Aq, 1, my $type);
\& # $value is 0 and $type is JSON_TYPE_BOOL
\&
\& my $value = decode_json(\*(Aq0\*(Aq, 1, my $type);
\& # $value is 0 and $type is JSON_TYPE_INT
\&
\& my $value = decode_json(\*(Aq"0"\*(Aq, 1, my $type);
\& # $value is 0 and $type is JSON_TYPE_STRING
\&
\& my $json_string = \*(Aq{"key1":{"key2":[10,"10",10.6]},"key3":"10.5"}\*(Aq;
\& 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 }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides stable \s-1JSON\s0 type support for the
Cpanel::JSON::XS encoder which doesn't depend on
any internal perl scalar flags or characteristics. Also it provides
real \s-1JSON\s0 types for Cpanel::JSON::XS decoder.
.PP
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.
.PP
For services based on \s-1JSON\s0 contents it is sometimes needed to correctly
process and enforce \s-1JSON\s0 types.
.PP
The function decode_json takes optional
third scalar parameter and fills it with specification of json types.
.PP
The function encode_json takes a perl
structure as its input and optionally also a json type specification in
the second parameter.
.PP
If the specification is not provided (or is undef) internal perl
scalar flags are used for the resulting \s-1JSON\s0 type. The internal flags
can be changed by perl itself, but also by external modules. Which
means that types in resulting \s-1JSON\s0 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.
.PP
To enforce that specification is always provided use \f(CW\*(C`require_types\*(C'\fR.
In this case when \f(CW\*(C`encode\*(C'\fR is called without second argument (or is
undef) then it croaks. It applies recursively for all sub-structures.
.SS "\s-1JSON\s0 type specification for scalars:"
.IX Subsection "JSON type specification for scalars:"
.IP "\s-1JSON_TYPE_BOOL\s0" 4
.IX Item "JSON_TYPE_BOOL"
It enforces \s-1JSON\s0 boolean in resulting \s-1JSON,\s0 i.e. either \f(CW\*(C`true\*(C'\fR or
\&\f(CW\*(C`false\*(C'\fR. For determining whether the scalar passed to the encoder
is true, standard perl boolean logic is used.
.IP "\s-1JSON_TYPE_INT\s0" 4
.IX Item "JSON_TYPE_INT"
It enforces \s-1JSON\s0 number without fraction part in the resulting \s-1JSON.\s0
Equivalent of perl function int is used for conversion.
.IP "\s-1JSON_TYPE_FLOAT\s0" 4
.IX Item "JSON_TYPE_FLOAT"
It enforces \s-1JSON\s0 number with fraction part in the resulting \s-1JSON.\s0
Equivalent of perl operation \f(CW+0\fR is used for conversion.
.IP "\s-1JSON_TYPE_STRING\s0" 4
.IX Item "JSON_TYPE_STRING"
It enforces \s-1JSON\s0 string type in the resulting \s-1JSON.\s0
.IP "\s-1JSON_TYPE_NULL\s0" 4
.IX Item "JSON_TYPE_NULL"
It represents \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value. Makes sense only when passing
perl's \f(CW\*(C`undef\*(C'\fR value.
.PP
For each type, there also exists a type with the suffix \f(CW\*(C`_OR_NULL\*(C'\fR
which encodes perl's \f(CW\*(C`undef\*(C'\fR into \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR. Without type with
suffix \f(CW\*(C`_OR_NULL\*(C'\fR perl's \f(CW\*(C`undef\*(C'\fR is converted to specific type
according to above rules.
.SS "\s-1JSON\s0 type specification for arrays:"
.IX Subsection "JSON type specification for arrays:"
.IP "[...]" 4
The array must contain the same number of elements as in the perl
array passed for encoding. Each element of the array describes the
\&\s-1JSON\s0 type which is enforced for the corresponding element of the
perl array.
.IP "json_type_arrayof" 4
.IX Item "json_type_arrayof"
This function takes a \s-1JSON\s0 type specification as its argument which
is enforced for every element of the passed perl array.
.SS "\s-1JSON\s0 type specification for hashes:"
.IX Subsection "JSON type specification for hashes:"
.IP "{...}" 4
Each hash value for corresponding key describes the \s-1JSON\s0 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.
.IP "json_type_hashof" 4
.IX Item "json_type_hashof"
This function takes a \s-1JSON\s0 type specification as its argument which
is enforced for every value of passed perl hash structure.
.SS "\s-1JSON\s0 type specification for alternatives:"
.IX Subsection "JSON type specification for alternatives:"
.IP "json_type_anyof" 4
.IX Item "json_type_anyof"
This function takes a list of \s-1JSON\s0 type alternative specifications
(maximally one scalar, one array, and one hash) as its input and the
\&\s-1JSON\s0 encoder chooses one that matches.
.IP "json_type_null_or_anyof" 4
.IX Item "json_type_null_or_anyof"
Like \f(CW\*(C`json_type_anyof\*(C'\fR, but scalar can be only
perl's \f(CW\*(C`undef\*(C'\fR.
.SS "Recursive specifications"
.IX Subsection "Recursive specifications"
.IP "json_type_weaken" 4
.IX Item "json_type_weaken"
This function can be used as an argument for \*(L"json_type_arrayof\*(R",
\&\*(L"json_type_hashof\*(R" or \*(L"json_type_anyof\*(R" functions to create weak
references suitable for complicated recursive structures. It depends
on the weaken function from Scalar::Util module.
See following example:
.Sp
.Vb 8
\&  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),
\&  );
.Ve
.Sp
If you want to encode all perl scalars to \s-1JSON\s0 string types despite
how complicated is input perl structure you can define \s-1JSON\s0 type
specification for alternatives recursively. It could be defined as:
.Sp
.Vb 4
\&  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"}]
.Ve
.Sp
An alternative solution for encoding all scalars to \s-1JSON\s0 strings is to
use \f(CW\*(C`type_all_string\*(C'\fR method of Cpanel::JSON::XS itself:
.Sp
.Vb 3
\&  my $json = Cpanel::JSON::XS\->new\->type_all_string;
\&  print $json\->encode([ 10, "10", { key => 10 } ]);
\&  # ["10","10",{"key":"10"}]
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Pali <pali@cpan.org>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2017, GoodData Corporation. All rights reserved.
.PP
This module is available under the same licences as perl, the Artistic
license and the \s-1GPL.\s0