{
    "content": [
        {
            "type": "text",
            "text": "# Cpanel::JSON::XS::Type (perldoc)\n\n## NAME\n\nCpanel::JSON::XS::Type - Type support for JSON encode\n\n## SYNOPSIS\n\nuse Cpanel::JSON::XS;\nuse Cpanel::JSON::XS::Type;\nencodejson([10, \"10\", 10.25], [JSONTYPEINT, JSONTYPEINT, JSONTYPESTRING]);\n# '[10,10,\"10.25\"]'\nencodejson([10, \"10\", 10.25], jsontypearrayof(JSONTYPEINT));\n# '[10,10,10]'\nencodejson(1, JSONTYPEBOOL);\n# 'true'\nmy $perlstruct = { key1 => 1, key2 => \"2\", key3 => 1 };\nmy $typespec = { key1 => JSONTYPESTRING, key2 => JSONTYPEINT, key3 => JSONTYPEBOOL };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"1\",\"key2\":2,\"key3\":true}'\nmy $perlstruct = { key1 => \"value1\", key2 => \"value2\", key3 => 0, key4 => 1, key5 => \"string\", key6 => \"string2\" };\nmy $typespec = jsontypehashof(JSONTYPESTRING);\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"value1\",\"key2\":\"value2\",\"key3\":\"0\",\"key4\":\"1\",\"key5\":\"string\",\"key6\":\"string2\"}'\nmy $perlstruct = { key1 => { key2 => [ 10, \"10\", 10.6 ] }, key3 => \"10.5\" };\nmy $typespec = { key1 => jsontypeanyof(JSONTYPEFLOAT, jsontypehashof(jsontypearrayof(JSONTYPEINT))), key3 => JSONTYPEFLOAT };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":{\"key2\":[10,10,10]},\"key3\":10.5}'\nmy $value = decodejson('false', 1, my $type);\n# $value is 0 and $type is JSONTYPEBOOL\nmy $value = decodejson('0', 1, my $type);\n# $value is 0 and $type is JSONTYPEINT\nmy $value = decodejson('\"0\"', 1, my $type);\n# $value is 0 and $type is JSONTYPESTRING\nmy $jsonstring = '{\"key1\":{\"key2\":[10,\"10\",10.6]},\"key3\":\"10.5\"}';\nmy $perlstruct = decodejson($jsonstring, 0, my $typespec);\n# $perlstruct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }\n# $typespec is { key1 => { key2 => [ JSONTYPEINT, JSONTYPESTRING, JSONTYPEFLOAT ] }, key3 => JSONTYPESTRING }\n\n## DESCRIPTION\n\nThis module provides stable JSON type support for the Cpanel::JSON::XS encoder which doesn't\ndepend on any internal perl scalar flags or characteristics. Also it provides real JSON types\nfor Cpanel::JSON::XS decoder.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Cpanel::JSON::XS::Type",
        "section": "",
        "mode": "perldoc",
        "summary": "Cpanel::JSON::XS::Type - Type support for JSON encode",
        "synopsis": "use Cpanel::JSON::XS;\nuse Cpanel::JSON::XS::Type;\nencodejson([10, \"10\", 10.25], [JSONTYPEINT, JSONTYPEINT, JSONTYPESTRING]);\n# '[10,10,\"10.25\"]'\nencodejson([10, \"10\", 10.25], jsontypearrayof(JSONTYPEINT));\n# '[10,10,10]'\nencodejson(1, JSONTYPEBOOL);\n# 'true'\nmy $perlstruct = { key1 => 1, key2 => \"2\", key3 => 1 };\nmy $typespec = { key1 => JSONTYPESTRING, key2 => JSONTYPEINT, key3 => JSONTYPEBOOL };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"1\",\"key2\":2,\"key3\":true}'\nmy $perlstruct = { key1 => \"value1\", key2 => \"value2\", key3 => 0, key4 => 1, key5 => \"string\", key6 => \"string2\" };\nmy $typespec = jsontypehashof(JSONTYPESTRING);\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"value1\",\"key2\":\"value2\",\"key3\":\"0\",\"key4\":\"1\",\"key5\":\"string\",\"key6\":\"string2\"}'\nmy $perlstruct = { key1 => { key2 => [ 10, \"10\", 10.6 ] }, key3 => \"10.5\" };\nmy $typespec = { key1 => jsontypeanyof(JSONTYPEFLOAT, jsontypehashof(jsontypearrayof(JSONTYPEINT))), key3 => JSONTYPEFLOAT };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":{\"key2\":[10,10,10]},\"key3\":10.5}'\nmy $value = decodejson('false', 1, my $type);\n# $value is 0 and $type is JSONTYPEBOOL\nmy $value = decodejson('0', 1, my $type);\n# $value is 0 and $type is JSONTYPEINT\nmy $value = decodejson('\"0\"', 1, my $type);\n# $value is 0 and $type is JSONTYPESTRING\nmy $jsonstring = '{\"key1\":{\"key2\":[10,\"10\",10.6]},\"key3\":\"10.5\"}';\nmy $perlstruct = decodejson($jsonstring, 0, my $typespec);\n# $perlstruct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }\n# $typespec is { key1 => { key2 => [ JSONTYPEINT, JSONTYPESTRING, JSONTYPEFLOAT ] }, key3 => JSONTYPESTRING }",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 43,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 79,
                "subsections": [
                    {
                        "name": "Recursive specifications",
                        "lines": 34
                    }
                ]
            },
            {
                "name": "AUTHOR",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Cpanel::JSON::XS::Type - Type support for JSON encode\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use Cpanel::JSON::XS;\nuse Cpanel::JSON::XS::Type;\n\n\nencodejson([10, \"10\", 10.25], [JSONTYPEINT, JSONTYPEINT, JSONTYPESTRING]);\n# '[10,10,\"10.25\"]'\n\nencodejson([10, \"10\", 10.25], jsontypearrayof(JSONTYPEINT));\n# '[10,10,10]'\n\nencodejson(1, JSONTYPEBOOL);\n# 'true'\n\nmy $perlstruct = { key1 => 1, key2 => \"2\", key3 => 1 };\nmy $typespec = { key1 => JSONTYPESTRING, key2 => JSONTYPEINT, key3 => JSONTYPEBOOL };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"1\",\"key2\":2,\"key3\":true}'\n\nmy $perlstruct = { key1 => \"value1\", key2 => \"value2\", key3 => 0, key4 => 1, key5 => \"string\", key6 => \"string2\" };\nmy $typespec = jsontypehashof(JSONTYPESTRING);\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":\"value1\",\"key2\":\"value2\",\"key3\":\"0\",\"key4\":\"1\",\"key5\":\"string\",\"key6\":\"string2\"}'\n\nmy $perlstruct = { key1 => { key2 => [ 10, \"10\", 10.6 ] }, key3 => \"10.5\" };\nmy $typespec = { key1 => jsontypeanyof(JSONTYPEFLOAT, jsontypehashof(jsontypearrayof(JSONTYPEINT))), key3 => JSONTYPEFLOAT };\nmy $jsonstring = encodejson($perlstruct, $typespec);\n# '{\"key1\":{\"key2\":[10,10,10]},\"key3\":10.5}'\n\n\nmy $value = decodejson('false', 1, my $type);\n# $value is 0 and $type is JSONTYPEBOOL\n\nmy $value = decodejson('0', 1, my $type);\n# $value is 0 and $type is JSONTYPEINT\n\nmy $value = decodejson('\"0\"', 1, my $type);\n# $value is 0 and $type is JSONTYPESTRING\n\nmy $jsonstring = '{\"key1\":{\"key2\":[10,\"10\",10.6]},\"key3\":\"10.5\"}';\nmy $perlstruct = decodejson($jsonstring, 0, my $typespec);\n# $perlstruct is { key1 => { key2 => [ 10, 10, 10.6 ] }, key3 => 10.5 }\n# $typespec is { key1 => { key2 => [ JSONTYPEINT, JSONTYPESTRING, JSONTYPEFLOAT ] }, key3 => JSONTYPESTRING }\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module provides stable JSON type support for the Cpanel::JSON::XS encoder which doesn't\ndepend on any internal perl scalar flags or characteristics. Also it provides real JSON types\nfor Cpanel::JSON::XS decoder.\n\nIn most cases perl structures passed to encodejson come from other functions or from other\nmodules and caller of Cpanel::JSON::XS module does not have control of internals or they are\nsubject of change. So it is not easy to support enforcing types as described in the simple\nscalars section.\n\nFor services based on JSON contents it is sometimes needed to correctly process and enforce JSON\ntypes.\n\nThe function decodejson takes optional third scalar parameter and fills it with specification\nof json types.\n\nThe function encodejson takes a perl structure as its input and optionally also a json type\nspecification in the second parameter.\n\nIf the specification is not provided (or is undef) internal perl scalar flags are used for the\nresulting JSON type. The internal flags can be changed by perl itself, but also by external\nmodules. Which means that types in resulting JSON string aren't stable. Specially it does not\nwork reliable for dual vars and scalars which were used in both numeric and string operations.\nSee simple scalars.\n\nTo enforce that specification is always provided use \"requiretypes\". In this case when \"encode\"\nis called without second argument (or is undef) then it croaks. It applies recursively for all\nsub-structures.\n\nJSON type specification for scalars:\nJSONTYPEBOOL\nIt enforces JSON boolean in resulting JSON, i.e. either \"true\" or \"false\". For determining\nwhether the scalar passed to the encoder is true, standard perl boolean logic is used.\n\nJSONTYPEINT\nIt enforces JSON number without fraction part in the resulting JSON. Equivalent of perl\nfunction int is used for conversion.\n\nJSONTYPEFLOAT\nIt enforces JSON number with fraction part in the resulting JSON. Equivalent of perl\noperation +0 is used for conversion.\n\nJSONTYPESTRING\nIt enforces JSON string type in the resulting JSON.\n\nJSONTYPENULL\nIt represents JSON \"null\" value. Makes sense only when passing perl's \"undef\" value.\n\nFor each type, there also exists a type with the suffix \"ORNULL\" which encodes perl's \"undef\"\ninto JSON \"null\". Without type with suffix \"ORNULL\" perl's \"undef\" is converted to specific\ntype according to above rules.\n\nJSON type specification for arrays:\n[...]\nThe array must contain the same number of elements as in the perl array passed for encoding.\nEach element of the array describes the JSON type which is enforced for the corresponding\nelement of the perl array.\n\njsontypearrayof\nThis function takes a JSON type specification as its argument which is enforced for every\nelement of the passed perl array.\n\nJSON type specification for hashes:\n{...}\nEach hash value for corresponding key describes the JSON type specification for values of\npassed perl hash structure. Keys in hash which are not present in passed perl hash structure\nare simple ignored and not used.\n\njsontypehashof\nThis function takes a JSON type specification as its argument which is enforced for every\nvalue of passed perl hash structure.\n\nJSON type specification for alternatives:\njsontypeanyof\nThis function takes a list of JSON type alternative specifications (maximally one scalar,\none array, and one hash) as its input and the JSON encoder chooses one that matches.\n\njsontypenulloranyof\nLike \"jsontypeanyof\", but scalar can be only perl's \"undef\".\n",
                "subsections": [
                    {
                        "name": "Recursive specifications",
                        "content": "jsontypeweaken\nThis function can be used as an argument for \"jsontypearrayof\", \"jsontypehashof\" or\n\"jsontypeanyof\" functions to create weak references suitable for complicated recursive\nstructures. It depends on the weaken function from Scalar::Util module. See following\nexample:\n\nmy $struct = {\ntype => JSONTYPESTRING,\narray => jsontypearrayof(JSONTYPEINT),\n};\n$struct->{recursive} = jsontypeanyof(\njsontypeweaken($struct),\njsontypearrayof(JSONTYPESTRING),\n);\n\nIf you want to encode all perl scalars to JSON string types despite how complicated is input\nperl structure you can define JSON type specification for alternatives recursively. It could\nbe defined as:\n\nmy $type = jsontypeanyof();\n$type->[0] = JSONTYPESTRINGORNULL;\n$type->[1] = jsontypearrayof(jsontypeweaken($type));\n$type->[2] = jsontypehashof(jsontypeweaken($type));\n\nprint encodejson([ 10, \"10\", { key => 10 } ], $type);\n# [\"10\",\"10\",{\"key\":\"10\"}]\n\nAn alternative solution for encoding all scalars to JSON strings is to use \"typeallstring\"\nmethod of Cpanel::JSON::XS itself:\n\nmy $json = Cpanel::JSON::XS->new->typeallstring;\nprint $json->encode([ 10, \"10\", { key => 10 } ]);\n# [\"10\",\"10\",{\"key\":\"10\"}]\n"
                    }
                ]
            },
            "AUTHOR": {
                "content": "Pali <pali@cpan.org>\n\nCOPYRIGHT & LICENSE\nCopyright (c) 2017, GoodData Corporation. All rights reserved.\n\nThis module is available under the same licences as perl, the Artistic license and the GPL.\n",
                "subsections": []
            }
        }
    }
}