{
    "content": [
        {
            "type": "text",
            "text": "# JSON::PP (perldoc)\n\n**Summary:** JSON::PP - JSON::XS compatible pure-Perl module.\n\n**Synopsis:** use JSON::PP;\n# exported functions, they croak on error\n# and expect/generate UTF-8\n$utf8encodedjsontext = encodejson $perlhashorarrayref;\n$perlhashorarrayref  = decodejson $utf8encodedjsontext;\n# OO-interface\n$json = JSON::PP->new->ascii->pretty->allownonref;\n$prettyprintedjsontext = $json->encode( $perlscalar );\n$perlscalar = $json->decode( $jsontext );\n# Note that JSON version 2.0 and above will automatically use\n# JSON::XS or JSON::PP, so you should be able to just:\nuse JSON;\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (20 lines)\n- **VERSION** (2 lines)\n- **DESCRIPTION** (17 lines)\n- **FUNCTIONAL INTERFACE** (38 lines)\n- **OBJECT-ORIENTED INTERFACE** (699 lines)\n- **INCREMENTAL PARSING** (101 lines)\n- **MAPPING** (287 lines)\n- **ENCODING/CODESET FLAG NOTES** (96 lines)\n- **BUGS** (15 lines)\n- **SEE ALSO** (13 lines)\n- **AUTHOR** (2 lines)\n- **CURRENT MAINTAINER** (2 lines)\n- **COPYRIGHT AND LICENSE** (7 lines)\n\n## Full Content\n\n### NAME\n\nJSON::PP - JSON::XS compatible pure-Perl module.\n\n### SYNOPSIS\n\nuse JSON::PP;\n\n# exported functions, they croak on error\n# and expect/generate UTF-8\n\n$utf8encodedjsontext = encodejson $perlhashorarrayref;\n$perlhashorarrayref  = decodejson $utf8encodedjsontext;\n\n# OO-interface\n\n$json = JSON::PP->new->ascii->pretty->allownonref;\n\n$prettyprintedjsontext = $json->encode( $perlscalar );\n$perlscalar = $json->decode( $jsontext );\n\n# Note that JSON version 2.0 and above will automatically use\n# JSON::XS or JSON::PP, so you should be able to just:\n\nuse JSON;\n\n### VERSION\n\n4.05\n\n### DESCRIPTION\n\nJSON::PP is a pure perl JSON decoder/encoder, and (almost) compatible to\nmuch faster JSON::XS written by Marc Lehmann in C. JSON::PP works as a\nfallback module when you use JSON module without having installed\nJSON::XS.\n\nBecause of this fallback feature of JSON.pm, JSON::PP tries not to be\nmore JavaScript-friendly than JSON::XS (i.e. not to escape extra\ncharacters such as U+2028 and U+2029, etc), in order for you not to lose\nsuch JavaScript-friendliness silently when you use JSON.pm and install\nJSON::XS for speed or by accident. If you need JavaScript-friendly\nRFC7159-compliant pure perl module, try JSON::Tiny, which is derived\nfrom Mojolicious web framework and is also smaller and faster than\nJSON::PP.\n\nJSON::PP has been in the Perl core since Perl 5.14, mainly for CPAN\ntoolchain modules to parse META.json.\n\n### FUNCTIONAL INTERFACE\n\nThis section is taken from JSON::XS almost verbatim. \"encodejson\" and\n\"decodejson\" are exported by default.\n\nencodejson\n$jsontext = encodejson $perlscalar\n\nConverts the given Perl data structure to a UTF-8 encoded, binary string\n(that is, the string contains octets only). Croaks on error.\n\nThis function call is functionally identical to:\n\n$jsontext = JSON::PP->new->utf8->encode($perlscalar)\n\nExcept being faster.\n\ndecodejson\n$perlscalar = decodejson $jsontext\n\nThe opposite of \"encodejson\": expects an UTF-8 (binary) string and\ntries to parse that as an UTF-8 encoded JSON text, returning the\nresulting reference. Croaks on error.\n\nThis function call is functionally identical to:\n\n$perlscalar = JSON::PP->new->utf8->decode($jsontext)\n\nExcept being faster.\n\nJSON::PP::isbool\n$isboolean = JSON::PP::isbool($scalar)\n\nReturns true if the passed scalar represents either JSON::PP::true or\nJSON::PP::false, two constants that act like 1 and 0 respectively and\nare also used to represent JSON \"true\" and \"false\" in Perl strings.\n\nSee MAPPING, below, for more information on how JSON values are mapped\nto Perl.\n\n### OBJECT-ORIENTED INTERFACE\n\nThis section is also taken from JSON::XS.\n\nThe object oriented interface lets you configure your own encoding or\ndecoding style, within the limits of supported formats.\n\nnew\n$json = JSON::PP->new\n\nCreates a new JSON::PP object that can be used to de/encode JSON\nstrings. All boolean flags described below are by default *disabled*\n(with the exception of \"allownonref\", which defaults to *enabled* since\nversion 4.0).\n\nThe mutators for flags all return the JSON::PP object again and thus\ncalls can be chained:\n\nmy $json = JSON::PP->new->utf8->spaceafter->encode({a => [1,2]})\n=> {\"a\": [1, 2]}\n\nascii\n$json = $json->ascii([$enable])\n\n$enabled = $json->getascii\n\nIf $enable is true (or missing), then the \"encode\" method will not\ngenerate characters outside the code range 0..127 (which is ASCII). Any\nUnicode characters outside that range will be escaped using either a\nsingle \\uXXXX (BMP characters) or a double \\uHHHH\\uLLLLL escape\nsequence, as per RFC4627. The resulting encoded JSON text can be treated\nas a native Unicode string, an ascii-encoded, latin1-encoded or UTF-8\nencoded string, or any other superset of ASCII.\n\nIf $enable is false, then the \"encode\" method will not escape Unicode\ncharacters unless required by the JSON syntax or other flags. This\nresults in a faster and more compact format.\n\nSee also the section *ENCODING/CODESET FLAG NOTES* later in this\ndocument.\n\nThe main use for this flag is to produce JSON texts that can be\ntransmitted over a 7-bit channel, as the encoded JSON texts will not\ncontain any 8 bit characters.\n\nJSON::PP->new->ascii(1)->encode([chr 0x10401])\n=> [\"\\ud801\\udc01\"]\n\nlatin1\n$json = $json->latin1([$enable])\n\n$enabled = $json->getlatin1\n\nIf $enable is true (or missing), then the \"encode\" method will encode\nthe resulting JSON text as latin1 (or iso-8859-1), escaping any\ncharacters outside the code range 0..255. The resulting string can be\ntreated as a latin1-encoded JSON text or a native Unicode string. The\n\"decode\" method will not be affected in any way by this flag, as\n\"decode\" by default expects Unicode, which is a strict superset of\nlatin1.\n\nIf $enable is false, then the \"encode\" method will not escape Unicode\ncharacters unless required by the JSON syntax or other flags.\n\nSee also the section *ENCODING/CODESET FLAG NOTES* later in this\ndocument.\n\nThe main use for this flag is efficiently encoding binary data as JSON\ntext, as most octets will not be escaped, resulting in a smaller encoded\nsize. The disadvantage is that the resulting JSON text is encoded in\nlatin1 (and must correctly be treated as such when storing and\ntransferring), a rare encoding for JSON. It is therefore most useful\nwhen you want to store data structures known to contain binary data\nefficiently in files or databases, not when talking to other JSON\nencoders/decoders.\n\nJSON::PP->new->latin1->encode ([\"\\x{89}\\x{abc}\"]\n=> [\"\\x{89}\\\\u0abc\"]    # (perl syntax, U+abc escaped, U+89 not)\n\nutf8\n$json = $json->utf8([$enable])\n\n$enabled = $json->getutf8\n\nIf $enable is true (or missing), then the \"encode\" method will encode\nthe JSON result into UTF-8, as required by many protocols, while the\n\"decode\" method expects to be handled an UTF-8-encoded string. Please\nnote that UTF-8-encoded strings do not contain any characters outside\nthe range 0..255, they are thus useful for bytewise/binary I/O. In\nfuture versions, enabling this option might enable autodetection of the\nUTF-16 and UTF-32 encoding families, as described in RFC4627.\n\nIf $enable is false, then the \"encode\" method will return the JSON\nstring as a (non-encoded) Unicode string, while \"decode\" expects thus a\nUnicode string. Any decoding or encoding (e.g. to UTF-8 or UTF-16) needs\nto be done yourself, e.g. using the Encode module.\n\nSee also the section *ENCODING/CODESET FLAG NOTES* later in this\ndocument.\n\nExample, output UTF-16BE-encoded JSON:\n\nuse Encode;\n$jsontext = encode \"UTF-16BE\", JSON::PP->new->encode ($object);\n\nExample, decode UTF-32LE-encoded JSON:\n\nuse Encode;\n$object = JSON::PP->new->decode (decode \"UTF-32LE\", $jsontext);\n\npretty\n$json = $json->pretty([$enable])\n\nThis enables (or disables) all of the \"indent\", \"spacebefore\" and\n\"spaceafter\" (and in the future possibly more) flags in one call to\ngenerate the most readable (or most compact) form possible.\n\nindent\n$json = $json->indent([$enable])\n\n$enabled = $json->getindent\n\nIf $enable is true (or missing), then the \"encode\" method will use a\nmultiline format as output, putting every array member or object/hash\nkey-value pair into its own line, indenting them properly.\n\nIf $enable is false, no newlines or indenting will be produced, and the\nresulting JSON text is guaranteed not to contain any \"newlines\".\n\nThis setting has no effect when decoding JSON texts.\n\nThe default indent space length is three. You can use \"indentlength\" to\nchange the length.\n\nspacebefore\n$json = $json->spacebefore([$enable])\n\n$enabled = $json->getspacebefore\n\nIf $enable is true (or missing), then the \"encode\" method will add an\nextra optional space before the \":\" separating keys from values in JSON\nobjects.\n\nIf $enable is false, then the \"encode\" method will not add any extra\nspace at those places.\n\nThis setting has no effect when decoding JSON texts. You will also most\nlikely combine this setting with \"spaceafter\".\n\nExample, spacebefore enabled, spaceafter and indent disabled:\n\n{\"key\" :\"value\"}\n\nspaceafter\n$json = $json->spaceafter([$enable])\n\n$enabled = $json->getspaceafter\n\nIf $enable is true (or missing), then the \"encode\" method will add an\nextra optional space after the \":\" separating keys from values in JSON\nobjects and extra whitespace after the \",\" separating key-value pairs\nand array members.\n\nIf $enable is false, then the \"encode\" method will not add any extra\nspace at those places.\n\nThis setting has no effect when decoding JSON texts.\n\nExample, spacebefore and indent disabled, spaceafter enabled:\n\n{\"key\": \"value\"}\n\nrelaxed\n$json = $json->relaxed([$enable])\n\n$enabled = $json->getrelaxed\n\nIf $enable is true (or missing), then \"decode\" will accept some\nextensions to normal JSON syntax (see below). \"encode\" will not be\naffected in anyway. *Be aware that this option makes you accept invalid\nJSON texts as if they were valid!*. I suggest only to use this option to\nparse application-specific files written by humans (configuration files,\nresource files etc.)\n\nIf $enable is false (the default), then \"decode\" will only accept valid\nJSON texts.\n\nCurrently accepted extensions are:\n\n*   list items can have an end-comma\n\nJSON *separates* array elements and key-value pairs with commas.\nThis can be annoying if you write JSON texts manually and want to be\nable to quickly append elements, so this extension accepts comma at\nthe end of such items not just between them:\n\n[\n1,\n2, <- this comma not normally allowed\n]\n{\n\"k1\": \"v1\",\n\"k2\": \"v2\", <- this comma not normally allowed\n}\n\n*   shell-style '#'-comments\n\nWhenever JSON allows whitespace, shell-style comments are\nadditionally allowed. They are terminated by the first\ncarriage-return or line-feed character, after which more white-space\nand comments are allowed.\n\n[\n1, # this comment not allowed in JSON\n# neither this one...\n]\n\n*   C-style multiple-line '/* */'-comments (JSON::PP only)\n\nWhenever JSON allows whitespace, C-style multiple-line comments are\nadditionally allowed. Everything between \"/*\" and \"*/\" is a comment,\nafter which more white-space and comments are allowed.\n\n[\n1, /* this comment not allowed in JSON */\n/* neither this one... */\n]\n\n*   C++-style one-line '//'-comments (JSON::PP only)\n\nWhenever JSON allows whitespace, C++-style one-line comments are\nadditionally allowed. They are terminated by the first\ncarriage-return or line-feed character, after which more white-space\nand comments are allowed.\n\n[\n1, // this comment not allowed in JSON\n// neither this one...\n]\n\n*   literal ASCII TAB characters in strings\n\nLiteral ASCII TAB characters are now allowed in strings (and treated\nas \"\\t\").\n\n[\n\"Hello\\tWorld\",\n\"Hello<TAB>World\", # literal <TAB> would not normally be allowed\n]\n\ncanonical\n$json = $json->canonical([$enable])\n\n$enabled = $json->getcanonical\n\nIf $enable is true (or missing), then the \"encode\" method will output\nJSON objects by sorting their keys. This is adding a comparatively high\noverhead.\n\nIf $enable is false, then the \"encode\" method will output key-value\npairs in the order Perl stores them (which will likely change between\nruns of the same script, and can change even within the same run from\n5.18 onwards).\n\nThis option is useful if you want the same data structure to be encoded\nas the same JSON text (given the same overall settings). If it is\ndisabled, the same hash might be encoded differently even if contains\nthe same data, as key-value pairs have no inherent ordering in Perl.\n\nThis setting has no effect when decoding JSON texts.\n\nThis setting has currently no effect on tied hashes.\n\nallownonref\n$json = $json->allownonref([$enable])\n\n$enabled = $json->getallownonref\n\nUnlike other boolean options, this opotion is enabled by default\nbeginning with version 4.0.\n\nIf $enable is true (or missing), then the \"encode\" method can convert a\nnon-reference into its corresponding string, number or null JSON value,\nwhich is an extension to RFC4627. Likewise, \"decode\" will accept those\nJSON values instead of croaking.\n\nIf $enable is false, then the \"encode\" method will croak if it isn't\npassed an arrayref or hashref, as JSON texts must either be an object or\narray. Likewise, \"decode\" will croak if given something that is not a\nJSON object or array.\n\nExample, encode a Perl scalar as JSON value without enabled\n\"allownonref\", resulting in an error:\n\nJSON::PP->new->allownonref(0)->encode (\"Hello, World!\")\n=> hash- or arrayref expected...\n\nallowunknown\n$json = $json->allowunknown([$enable])\n\n$enabled = $json->getallowunknown\n\nIf $enable is true (or missing), then \"encode\" will *not* throw an\nexception when it encounters values it cannot represent in JSON (for\nexample, filehandles) but instead will encode a JSON \"null\" value. Note\nthat blessed objects are not included here and are handled separately by\nc<allowblessed>.\n\nIf $enable is false (the default), then \"encode\" will throw an exception\nwhen it encounters anything it cannot encode as JSON.\n\nThis option does not affect \"decode\" in any way, and it is recommended\nto leave it off unless you know your communications partner.\n\nallowblessed\n$json = $json->allowblessed([$enable])\n\n$enabled = $json->getallowblessed\n\nSee \"OBJECT SERIALISATION\" for details.\n\nIf $enable is true (or missing), then the \"encode\" method will not barf\nwhen it encounters a blessed reference that it cannot convert otherwise.\nInstead, a JSON \"null\" value is encoded instead of the object.\n\nIf $enable is false (the default), then \"encode\" will throw an exception\nwhen it encounters a blessed object that it cannot convert otherwise.\n\nThis setting has no effect on \"decode\".\n\nconvertblessed\n$json = $json->convertblessed([$enable])\n\n$enabled = $json->getconvertblessed\n\nSee \"OBJECT SERIALISATION\" for details.\n\nIf $enable is true (or missing), then \"encode\", upon encountering a\nblessed object, will check for the availability of the \"TOJSON\" method\non the object's class. If found, it will be called in scalar context and\nthe resulting scalar will be encoded instead of the object.\n\nThe \"TOJSON\" method may safely call die if it wants. If \"TOJSON\"\nreturns other blessed objects, those will be handled in the same way.\n\"TOJSON\" must take care of not causing an endless recursion cycle (==\ncrash) in this case. The name of \"TOJSON\" was chosen because other\nmethods called by the Perl core (== not by the user of the object) are\nusually in upper case letters and to avoid collisions with any \"tojson\"\nfunction or method.\n\nIf $enable is false (the default), then \"encode\" will not consider this\ntype of conversion.\n\nThis setting has no effect on \"decode\".\n\nallowtags\n$json = $json->allowtags([$enable])\n\n$enabled = $json->getallowtags\n\nSee \"OBJECT SERIALISATION\" for details.\n\nIf $enable is true (or missing), then \"encode\", upon encountering a\nblessed object, will check for the availability of the \"FREEZE\" method\non the object's class. If found, it will be used to serialise the object\ninto a nonstandard tagged JSON value (that JSON decoders cannot decode).\n\nIt also causes \"decode\" to parse such tagged JSON values and deserialise\nthem via a call to the \"THAW\" method.\n\nIf $enable is false (the default), then \"encode\" will not consider this\ntype of conversion, and tagged JSON values will cause a parse error in\n\"decode\", as if tags were not part of the grammar.\n\nbooleanvalues\n$json->booleanvalues([$false, $true])\n\n($false,  $true) = $json->getbooleanvalues\n\nBy default, JSON booleans will be decoded as overloaded $JSON::PP::false\nand $JSON::PP::true objects.\n\nWith this method you can specify your own boolean values for decoding -\non decode, JSON \"false\" will be decoded as a copy of $false, and JSON\n\"true\" will be decoded as $true (\"copy\" here is the same thing as\nassigning a value to another variable, i.e. \"$copy = $false\").\n\nThis is useful when you want to pass a decoded data structure directly\nto other serialisers like YAML, Data::MessagePack and so on.\n\nNote that this works only when you \"decode\". You can set incompatible\nboolean objects (like boolean), but when you \"encode\" a data structure\nwith such boolean objects, you still need to enable \"convertblessed\"\n(and add a \"TOJSON\" method if necessary).\n\nCalling this method without any arguments will reset the booleans to\ntheir default values.\n\n\"getbooleanvalues\" will return both $false and $true values, or the\nempty list when they are set to the default.\n\nfilterjsonobject\n$json = $json->filterjsonobject([$coderef])\n\nWhen $coderef is specified, it will be called from \"decode\" each time it\ndecodes a JSON object. The only argument is a reference to the\nnewly-created hash. If the code references returns a single scalar\n(which need not be a reference), this value (or rather a copy of it) is\ninserted into the deserialised data structure. If it returns an empty\nlist (NOTE: *not* \"undef\", which is a valid scalar), the original\ndeserialised hash will be inserted. This setting can slow down decoding\nconsiderably.\n\nWhen $coderef is omitted or undefined, any existing callback will be\nremoved and \"decode\" will not change the deserialised hash in any way.\n\nExample, convert all JSON objects into the integer 5:\n\nmy $js = JSON::PP->new->filterjsonobject(sub { 5 });\n# returns [5]\n$js->decode('[{}]');\n# returns 5\n$js->decode('{\"a\":1, \"b\":2}');\n\nfilterjsonsinglekeyobject\n$json = $json->filterjsonsinglekeyobject($key [=> $coderef])\n\nWorks remotely similar to \"filterjsonobject\", but is only called for\nJSON objects having a single key named $key.\n\nThis $coderef is called before the one specified via\n\"filterjsonobject\", if any. It gets passed the single value in the\nJSON object. If it returns a single value, it will be inserted into the\ndata structure. If it returns nothing (not even \"undef\" but the empty\nlist), the callback from \"filterjsonobject\" will be called next, as if\nno single-key callback were specified.\n\nIf $coderef is omitted or undefined, the corresponding callback will be\ndisabled. There can only ever be one callback for a given key.\n\nAs this callback gets called less often then the \"filterjsonobject\"\none, decoding speed will not usually suffer as much. Therefore,\nsingle-key objects make excellent targets to serialise Perl objects\ninto, especially as single-key JSON objects are as close to the\ntype-tagged value concept as JSON gets (it's basically an ID/VALUE\ntuple). Of course, JSON does not support this in any way, so you need to\nmake sure your data never looks like a serialised Perl hash.\n\nTypical names for the single object key are \"classwhatever\", or\n\"$dollarsarerarelyused$\" or \"}uglybraceplacement\", or even\nthings like \"classmd5sum(classname)\", to reduce the risk of\nclashing with real hashes.\n\nExample, decode JSON objects of the form \"{ \"widget\" => <id> }\" into\nthe corresponding $WIDGET{<id>} object:\n\n# return whatever is in $WIDGET{5}:\nJSON::PP\n->new\n->filterjsonsinglekeyobject (widget => sub {\n$WIDGET{ $[0] }\n})\n->decode ('{\"widget\": 5')\n\n# this can be used with a TOJSON method in some \"widget\" class\n# for serialisation to json:\nsub WidgetBase::TOJSON {\nmy ($self) = @;\n\nunless ($self->{id}) {\n$self->{id} = ..get..some..id..;\n$WIDGET{$self->{id}} = $self;\n}\n\n{ widget => $self->{id} }\n}\n\nshrink\n$json = $json->shrink([$enable])\n\n$enabled = $json->getshrink\n\nIf $enable is true (or missing), the string returned by \"encode\" will be\nshrunk (i.e. downgraded if possible).\n\nThe actual definition of what shrink does might change in future\nversions, but it will always try to save space at the expense of time.\n\nIf $enable is false, then JSON::PP does nothing.\n\nmaxdepth\n$json = $json->maxdepth([$maximumnestingdepth])\n\n$maxdepth = $json->getmaxdepth\n\nSets the maximum nesting level (default 512) accepted while encoding or\ndecoding. If a higher nesting level is detected in JSON text or a Perl\ndata structure, then the encoder and decoder will stop and croak at that\npoint.\n\nNesting level is defined by number of hash- or arrayrefs that the\nencoder needs to traverse to reach a given point or the number of \"{\" or\n\"[\" characters without their matching closing parenthesis crossed to\nreach a given character in a string.\n\nSetting the maximum depth to one disallows any nesting, so that ensures\nthat the object is only a single hash/object or array.\n\nIf no argument is given, the highest possible setting will be used,\nwhich is rarely useful.\n\nSee \"SECURITY CONSIDERATIONS\" in JSON::XS for more info on why this is\nuseful.\n\nmaxsize\n$json = $json->maxsize([$maximumstringsize])\n\n$maxsize = $json->getmaxsize\n\nSet the maximum length a JSON text may have (in bytes) where decoding is\nbeing attempted. The default is 0, meaning no limit. When \"decode\" is\ncalled on a string that is longer then this many bytes, it will not\nattempt to decode the string but throw an exception. This setting has no\neffect on \"encode\" (yet).\n\nIf no argument is given, the limit check will be deactivated (same as\nwhen 0 is specified).\n\nSee \"SECURITY CONSIDERATIONS\" in JSON::XS for more info on why this is\nuseful.\n\nencode\n$jsontext = $json->encode($perlscalar)\n\nConverts the given Perl value or data structure to its JSON\nrepresentation. Croaks on error.\n\ndecode\n$perlscalar = $json->decode($jsontext)\n\nThe opposite of \"encode\": expects a JSON text and tries to parse it,\nreturning the resulting simple scalar or reference. Croaks on error.\n\ndecodeprefix\n($perlscalar, $characters) = $json->decodeprefix($jsontext)\n\nThis works like the \"decode\" method, but instead of raising an exception\nwhen there is trailing garbage after the first JSON object, it will\nsilently stop parsing there and return the number of characters consumed\nso far.\n\nThis is useful if your JSON texts are not delimited by an outer protocol\nand you need to know where the JSON text ends.\n\nJSON::PP->new->decodeprefix (\"[1] the tail\")\n=> ([1], 3)\n\nFLAGS FOR JSON::PP ONLY\nThe following flags and properties are for JSON::PP only. If you use any\nof these, you can't make your application run faster by replacing\nJSON::PP with JSON::XS. If you need these and also speed boost, you\nmight want to try Cpanel::JSON::XS, a fork of JSON::XS by Reini Urban,\nwhich supports some of these (with a different set of\nincompatibilities). Most of these historical flags are only kept for\nbackward compatibility, and should not be used in a new application.\n\nallowsinglequote\n$json = $json->allowsinglequote([$enable])\n$enabled = $json->getallowsinglequote\n\nIf $enable is true (or missing), then \"decode\" will accept invalid JSON\ntexts that contain strings that begin and end with single quotation\nmarks. \"encode\" will not be affected in any way. *Be aware that this\noption makes you accept invalid JSON texts as if they were valid!*. I\nsuggest only to use this option to parse application-specific files\nwritten by humans (configuration files, resource files etc.)\n\nIf $enable is false (the default), then \"decode\" will only accept valid\nJSON texts.\n\n$json->allowsinglequote->decode(qq|{\"foo\":'bar'}|);\n$json->allowsinglequote->decode(qq|{'foo':\"bar\"}|);\n$json->allowsinglequote->decode(qq|{'foo':'bar'}|);\n\nallowbarekey\n$json = $json->allowbarekey([$enable])\n$enabled = $json->getallowbarekey\n\nIf $enable is true (or missing), then \"decode\" will accept invalid JSON\ntexts that contain JSON objects whose names don't begin and end with\nquotation marks. \"encode\" will not be affected in any way. *Be aware\nthat this option makes you accept invalid JSON texts as if they were\nvalid!*. I suggest only to use this option to parse application-specific\nfiles written by humans (configuration files, resource files etc.)\n\nIf $enable is false (the default), then \"decode\" will only accept valid\nJSON texts.\n\n$json->allowbarekey->decode(qq|{foo:\"bar\"}|);\n\nallowbignum\n$json = $json->allowbignum([$enable])\n$enabled = $json->getallowbignum\n\nIf $enable is true (or missing), then \"decode\" will convert big integers\nPerl cannot handle as integer into Math::BigInt objects and convert\nfloating numbers into Math::BigFloat objects. \"encode\" will convert\n\"Math::BigInt\" and \"Math::BigFloat\" objects into JSON numbers.\n\n$json->allownonref->allowbignum;\n$bigfloat = $json->decode('2.000000000000000000000000001');\nprint $json->encode($bigfloat);\n# => 2.000000000000000000000000001\n\nSee also MAPPING.\n\nloose\n$json = $json->loose([$enable])\n$enabled = $json->getloose\n\nIf $enable is true (or missing), then \"decode\" will accept invalid JSON\ntexts that contain unescaped [\\x00-\\x1f\\x22\\x5c] characters. \"encode\"\nwill not be affected in any way. *Be aware that this option makes you\naccept invalid JSON texts as if they were valid!*. I suggest only to use\nthis option to parse application-specific files written by humans\n(configuration files, resource files etc.)\n\nIf $enable is false (the default), then \"decode\" will only accept valid\nJSON texts.\n\n$json->loose->decode(qq|[\"abc\ndef\"]|);\n\nescapeslash\n$json = $json->escapeslash([$enable])\n$enabled = $json->getescapeslash\n\nIf $enable is true (or missing), then \"encode\" will explicitly escape\n*slash* (solidus; \"U+002F\") characters to reduce the risk of XSS (cross\nsite scripting) that may be caused by \"</script>\" in a JSON text, with\nthe cost of bloating the size of JSON texts.\n\nThis option may be useful when you embed JSON in HTML, but embedding\narbitrary JSON in HTML (by some HTML template toolkit or by string\ninterpolation) is risky in general. You must escape necessary characters\nin correct order, depending on the context.\n\n\"decode\" will not be affected in any way.\n\nindentlength\n$json = $json->indentlength($numberofspaces)\n$length = $json->getindentlength\n\nThis option is only useful when you also enable \"indent\" or \"pretty\".\n\nJSON::XS indents with three spaces when you \"encode\" (if requested by\n\"indent\" or \"pretty\"), and the number cannot be changed. JSON::PP allows\nyou to change/get the number of indent spaces with these\nmutator/accessor. The default number of spaces is three (the same as\nJSON::XS), and the acceptable range is from 0 (no indentation; it'd be\nbetter to disable indentation by indent(0)) to 15.\n\nsortby\n$json = $json->sortby($coderef)\n$json = $json->sortby($subroutinename)\n\nIf you just want to sort keys (names) in JSON objects when you \"encode\",\nenable \"canonical\" option (see above) that allows you to sort object\nkeys alphabetically.\n\nIf you do need to sort non-alphabetically for whatever reasons, you can\ngive a code reference (or a subroutine name) to \"sortby\", then the\nargument will be passed to Perl's \"sort\" built-in function.\n\nAs the sorting is done in the JSON::PP scope, you usually need to\nprepend \"JSON::PP::\" to the subroutine name, and the special variables\n$a and $b used in the subrontine used by \"sort\" function.\n\nExample:\n\nmy %ORDER = (id => 1, class => 2, name => 3);\n$json->sortby(sub {\n($ORDER{$JSON::PP::a} // 999) <=> ($ORDER{$JSON::PP::b} // 999)\nor $JSON::PP::a cmp $JSON::PP::b\n});\nprint $json->encode([\n{name => 'CPAN', id => 1, href => 'http://cpan.org'}\n]);\n# [{\"id\":1,\"name\":\"CPAN\",\"href\":\"http://cpan.org\"}]\n\nNote that \"sortby\" affects all the plain hashes in the data structure.\nIf you need finer control, \"tie\" necessary hashes with a module that\nimplements ordered hash (such as Hash::Ordered and Tie::IxHash).\n\"canonical\" and \"sortby\" don't affect the key order in \"tie\"d hashes.\n\nuse Hash::Ordered;\ntie my %hash, 'Hash::Ordered',\n(name => 'CPAN', id => 1, href => 'http://cpan.org');\nprint $json->encode([\\%hash]);\n# [{\"name\":\"CPAN\",\"id\":1,\"href\":\"http://cpan.org\"}] # order is kept\n\n### INCREMENTAL PARSING\n\nThis section is also taken from JSON::XS.\n\nIn some cases, there is the need for incremental parsing of JSON texts.\nWhile this module always has to keep both JSON text and resulting Perl\ndata structure in memory at one time, it does allow you to parse a JSON\nstream incrementally. It does so by accumulating text until it has a\nfull JSON object, which it then can decode. This process is similar to\nusing \"decodeprefix\" to see if a full JSON object is available, but is\nmuch more efficient (and can be implemented with a minimum of method\ncalls).\n\nJSON::PP will only attempt to parse the JSON text once it is sure it has\nenough text to get a decisive result, using a very simple but truly\nincremental parser. This means that it sometimes won't stop as early as\nthe full parser, for example, it doesn't detect mismatched parentheses.\nThe only thing it guarantees is that it starts decoding as soon as a\nsyntactically valid JSON text has been seen. This means you need to set\nresource limits (e.g. \"maxsize\") to ensure the parser will stop parsing\nin the presence if syntax errors.\n\nThe following methods implement this incremental parser.\n\nincrparse\n$json->incrparse( [$string] ) # void context\n\n$objorundef = $json->incrparse( [$string] ) # scalar context\n\n@objorempty = $json->incrparse( [$string] ) # list context\n\nThis is the central parsing function. It can both append new text and\nextract objects from the stream accumulated so far (both of these\nfunctions are optional).\n\nIf $string is given, then this string is appended to the already\nexisting JSON fragment stored in the $json object.\n\nAfter that, if the function is called in void context, it will simply\nreturn without doing anything further. This can be used to add more text\nin as many chunks as you want.\n\nIf the method is called in scalar context, then it will try to extract\nexactly *one* JSON object. If that is successful, it will return this\nobject, otherwise it will return \"undef\". If there is a parse error,\nthis method will croak just as \"decode\" would do (one can then use\n\"incrskip\" to skip the erroneous part). This is the most common way of\nusing the method.\n\nAnd finally, in list context, it will try to extract as many objects\nfrom the stream as it can find and return them, or the empty list\notherwise. For this to work, there must be no separators (other than\nwhitespace) between the JSON objects or arrays, instead they must be\nconcatenated back-to-back. If an error occurs, an exception will be\nraised as in the scalar context case. Note that in this case, any\npreviously-parsed JSON texts will be lost.\n\nExample: Parse some JSON arrays/objects in a given string and return\nthem.\n\nmy @objs = JSON::PP->new->incrparse (\"[5][7][1,2]\");\n\nincrtext\n$lvaluestring = $json->incrtext\n\nThis method returns the currently stored JSON fragment as an lvalue,\nthat is, you can manipulate it. This *only* works when a preceding call\nto \"incrparse\" in *scalar context* successfully returned an object.\nUnder all other circumstances you must not call this function (I mean\nit. although in simple tests it might actually work, it *will* fail\nunder real world conditions). As a special exception, you can also call\nthis method before having parsed anything.\n\nThat means you can only use this function to look at or manipulate text\nbefore or after complete JSON objects, not while the parser is in the\nmiddle of parsing a JSON object.\n\nThis function is useful in two cases: a) finding the trailing text after\na JSON object or b) parsing multiple JSON objects separated by non-JSON\ntext (such as commas).\n\nincrskip\n$json->incrskip\n\nThis will reset the state of the incremental parser and will remove the\nparsed text from the input buffer so far. This is useful after\n\"incrparse\" died, in which case the input buffer and incremental parser\nstate is left unchanged, to skip the text parsed so far and to reset the\nparse state.\n\nThe difference to \"incrreset\" is that only text until the parse error\noccurred is removed.\n\nincrreset\n$json->incrreset\n\nThis completely resets the incremental parser, that is, after this call,\nit will be as if the parser had never parsed anything.\n\nThis is useful if you want to repeatedly parse JSON objects and want to\nignore any trailing data, which means you have to reset the parser after\neach successful decode.\n\n### MAPPING\n\nMost of this section is also taken from JSON::XS.\n\nThis section describes how JSON::PP maps Perl values to JSON values and\nvice versa. These mappings are designed to \"do the right thing\" in most\ncircumstances automatically, preserving round-tripping characteristics\n(what you put in comes out as something equivalent).\n\nFor the more enlightened: note that in the following descriptions,\nlowercase *perl* refers to the Perl interpreter, while uppercase *Perl*\nrefers to the abstract Perl language itself.\n\nJSON -> PERL\nobject\nA JSON object becomes a reference to a hash in Perl. No ordering of\nobject keys is preserved (JSON does not preserve object key ordering\nitself).\n\narray\nA JSON array becomes a reference to an array in Perl.\n\nstring\nA JSON string becomes a string scalar in Perl - Unicode codepoints\nin JSON are represented by the same codepoints in the Perl string,\nso no manual decoding is necessary.\n\nnumber\nA JSON number becomes either an integer, numeric (floating point) or\nstring scalar in perl, depending on its range and any fractional\nparts. On the Perl level, there is no difference between those as\nPerl handles all the conversion details, but an integer may take\nslightly less memory and might represent more values exactly than\nfloating point numbers.\n\nIf the number consists of digits only, JSON::PP will try to\nrepresent it as an integer value. If that fails, it will try to\nrepresent it as a numeric (floating point) value if that is possible\nwithout loss of precision. Otherwise it will preserve the number as\na string value (in which case you lose roundtripping ability, as the\nJSON number will be re-encoded to a JSON string).\n\nNumbers containing a fractional or exponential part will always be\nrepresented as numeric (floating point) values, possibly at a loss\nof precision (in which case you might lose perfect roundtripping\nability, but the JSON number will still be re-encoded as a JSON\nnumber).\n\nNote that precision is not accuracy - binary floating point values\ncannot represent most decimal fractions exactly, and when converting\nfrom and to floating point, JSON::PP only guarantees precision up to\nbut not including the least significant bit.\n\nWhen \"allowbignum\" is enabled, big integer values and any numeric\nvalues will be converted into Math::BigInt and Math::BigFloat\nobjects respectively, without becoming string scalars or losing\nprecision.\n\ntrue, false\nThese JSON atoms become \"JSON::PP::true\" and \"JSON::PP::false\",\nrespectively. They are overloaded to act almost exactly like the\nnumbers 1 and 0. You can check whether a scalar is a JSON boolean by\nusing the \"JSON::PP::isbool\" function.\n\nnull\nA JSON null atom becomes \"undef\" in Perl.\n\nshell-style comments (\"# *text*\")\nAs a nonstandard extension to the JSON syntax that is enabled by the\n\"relaxed\" setting, shell-style comments are allowed. They can start\nanywhere outside strings and go till the end of the line.\n\ntagged values (\"(*tag*)*value*\").\nAnother nonstandard extension to the JSON syntax, enabled with the\n\"allowtags\" setting, are tagged values. In this implementation, the\n*tag* must be a perl package/class name encoded as a JSON string,\nand the *value* must be a JSON array encoding optional constructor\narguments.\n\nSee \"OBJECT SERIALISATION\", below, for details.\n\nPERL -> JSON\nThe mapping from Perl to JSON is slightly more difficult, as Perl is a\ntruly typeless language, so we can only guess which JSON type is meant\nby a Perl value.\n\nhash references\nPerl hash references become JSON objects. As there is no inherent\nordering in hash keys (or JSON objects), they will usually be\nencoded in a pseudo-random order. JSON::PP can optionally sort the\nhash keys (determined by the *canonical* flag and/or *sortby*\nproperty), so the same data structure will serialise to the same\nJSON text (given same settings and version of JSON::PP), but this\nincurs a runtime overhead and is only rarely useful, e.g. when you\nwant to compare some JSON text against another for equality.\n\narray references\nPerl array references become JSON arrays.\n\nother references\nOther unblessed references are generally not allowed and will cause\nan exception to be thrown, except for references to the integers 0\nand 1, which get turned into \"false\" and \"true\" atoms in JSON. You\ncan also use \"JSON::PP::false\" and \"JSON::PP::true\" to improve\nreadability.\n\ntojson [\\0, JSON::PP::true]      # yields [false,true]\n\nJSON::PP::true, JSON::PP::false\nThese special values become JSON true and JSON false values,\nrespectively. You can also use \"\\1\" and \"\\0\" directly if you want.\n\nJSON::PP::null\nThis special value becomes JSON null.\n\nblessed objects\nBlessed objects are not directly representable in JSON, but\n\"JSON::PP\" allows various ways of handling objects. See \"OBJECT\nSERIALISATION\", below, for details.\n\nsimple scalars\nSimple Perl scalars (any scalar that is not a reference) are the\nmost difficult objects to encode: JSON::PP will encode undefined\nscalars as JSON \"null\" values, scalars that have last been used in a\nstring context before encoding as JSON strings, and anything else as\nnumber value:\n\n# dump as number\nencodejson [2]                      # yields [2]\nencodejson [-3.0e17]                # yields [-3e+17]\nmy $value = 5; encodejson [$value]  # yields [5]\n\n# used as string, so dump as string\nprint $value;\nencodejson [$value]                 # yields [\"5\"]\n\n# undef becomes null\nencodejson [undef]                  # yields [null]\n\nYou can force the type to be a JSON string by stringifying it:\n\nmy $x = 3.1; # some variable containing a number\n\"$x\";        # stringified\n$x .= \"\";    # another, more awkward way to stringify\nprint $x;    # perl does it for you, too, quite often\n# (but for older perls)\n\nYou can force the type to be a JSON number by numifying it:\n\nmy $x = \"3\"; # some variable containing a string\n$x += 0;     # numify it, ensuring it will be dumped as a number\n$x *= 1;     # same thing, the choice is yours.\n\nYou can not currently force the type in other, less obscure, ways.\n\nSince version 2.9101, JSON::PP uses a different number detection\nlogic that converts a scalar that is possible to turn into a number\nsafely. The new logic is slightly faster, and tends to help people\nwho use older perl or who want to encode complicated data structure.\nHowever, this may results in a different JSON text from the one\nJSON::XS encodes (and thus may break tests that compare entire JSON\ntexts). If you do need the previous behavior for compatibility or\nfor finer control, set PERLJSONPPUSEB environmental variable to\ntrue before you \"use\" JSON::PP (or JSON.pm).\n\nNote that numerical precision has the same meaning as under Perl (so\nbinary to decimal conversion follows the same rules as in Perl,\nwhich can differ to other languages). Also, your perl interpreter\nmight expose extensions to the floating point numbers of your\nplatform, such as infinities or NaN's - these cannot be represented\nin JSON, and it is an error to pass those in.\n\nJSON::PP (and JSON::XS) trusts what you pass to \"encode\" method (or\n\"encodejson\" function) is a clean, validated data structure with\nvalues that can be represented as valid JSON values only, because\nit's not from an external data source (as opposed to JSON texts you\npass to \"decode\" or \"decodejson\", which JSON::PP considers tainted\nand doesn't trust). As JSON::PP doesn't know exactly what you and\nconsumers of your JSON texts want the unexpected values to be (you\nmay want to convert them into null, or to stringify them with or\nwithout normalisation (string representation of infinities/NaN may\nvary depending on platforms), or to croak without conversion),\nyou're advised to do what you and your consumers need before you\nencode, and also not to numify values that may start with values\nthat look like a number (including infinities/NaN), without\nvalidating.\n\nOBJECT SERIALISATION\nAs JSON cannot directly represent Perl objects, you have to choose\nbetween a pure JSON representation (without the ability to deserialise\nthe object automatically again), and a nonstandard extension to the JSON\nsyntax, tagged values.\n\nSERIALISATION\nWhat happens when \"JSON::PP\" encounters a Perl object depends on the\n\"allowblessed\", \"convertblessed\", \"allowtags\" and \"allowbignum\"\nsettings, which are used in this order:\n\n1. \"allowtags\" is enabled and the object has a \"FREEZE\" method.\nIn this case, \"JSON::PP\" creates a tagged JSON value, using a\nnonstandard extension to the JSON syntax.\n\nThis works by invoking the \"FREEZE\" method on the object, with the\nfirst argument being the object to serialise, and the second\nargument being the constant string \"JSON\" to distinguish it from\nother serialisers.\n\nThe \"FREEZE\" method can return any number of values (i.e. zero or\nmore). These values and the paclkage/classname of the object will\nthen be encoded as a tagged JSON value in the following format:\n\n(\"classname\")[FREEZE return values...]\n\ne.g.:\n\n(\"URI\")[\"http://www.google.com/\"]\n(\"MyDate\")[2013,10,29]\n(\"ImageData::JPEG\")[\"Z3...VlCg==\"]\n\nFor example, the hypothetical \"My::Object\" \"FREEZE\" method might use\nthe objects \"type\" and \"id\" members to encode the object:\n\nsub My::Object::FREEZE {\nmy ($self, $serialiser) = @;\n\n($self->{type}, $self->{id})\n}\n\n2. \"convertblessed\" is enabled and the object has a \"TOJSON\" method.\nIn this case, the \"TOJSON\" method of the object is invoked in\nscalar context. It must return a single scalar that can be directly\nencoded into JSON. This scalar replaces the object in the JSON text.\n\nFor example, the following \"TOJSON\" method will convert all URI\nobjects to JSON strings when serialised. The fact that these values\noriginally were URI objects is lost.\n\nsub URI::TOJSON {\nmy ($uri) = @;\n$uri->asstring\n}\n\n3. \"allowbignum\" is enabled and the object is a \"Math::BigInt\" or\n\"Math::BigFloat\".\nThe object will be serialised as a JSON number value.\n\n4. \"allowblessed\" is enabled.\nThe object will be serialised as a JSON null value.\n\n5. none of the above\nIf none of the settings are enabled or the respective methods are\nmissing, \"JSON::PP\" throws an exception.\n\nDESERIALISATION\nFor deserialisation there are only two cases to consider: either\nnonstandard tagging was used, in which case \"allowtags\" decides, or\nobjects cannot be automatically be deserialised, in which case you can\nuse postprocessing or the \"filterjsonobject\" or\n\"filterjsonsinglekeyobject\" callbacks to get some real objects our\nof your JSON.\n\nThis section only considers the tagged value case: a tagged JSON object\nis encountered during decoding and \"allowtags\" is disabled, a parse\nerror will result (as if tagged values were not part of the grammar).\n\nIf \"allowtags\" is enabled, \"JSON::PP\" will look up the \"THAW\" method of\nthe package/classname used during serialisation (it will not attempt to\nload the package as a Perl module). If there is no such method, the\ndecoding will fail with an error.\n\nOtherwise, the \"THAW\" method is invoked with the classname as first\nargument, the constant string \"JSON\" as second argument, and all the\nvalues from the JSON array (the values originally returned by the\n\"FREEZE\" method) as remaining arguments.\n\nThe method must then return the object. While technically you can return\nany Perl scalar, you might have to enable the \"allownonref\" setting to\nmake that work in all cases, so better return an actual blessed\nreference.\n\nAs an example, let's implement a \"THAW\" function that regenerates the\n\"My::Object\" from the \"FREEZE\" example earlier:\n\nsub My::Object::THAW {\nmy ($class, $serialiser, $type, $id) = @;\n\n$class->new (type => $type, id => $id)\n}\n\n### ENCODING/CODESET FLAG NOTES\n\nThis section is taken from JSON::XS.\n\nThe interested reader might have seen a number of flags that signify\nencodings or codesets - \"utf8\", \"latin1\" and \"ascii\". There seems to be\nsome confusion on what these do, so here is a short comparison:\n\n\"utf8\" controls whether the JSON text created by \"encode\" (and expected\nby \"decode\") is UTF-8 encoded or not, while \"latin1\" and \"ascii\" only\ncontrol whether \"encode\" escapes character values outside their\nrespective codeset range. Neither of these flags conflict with each\nother, although some combinations make less sense than others.\n\nCare has been taken to make all flags symmetrical with respect to\n\"encode\" and \"decode\", that is, texts encoded with any combination of\nthese flag values will be correctly decoded when the same flags are used\n- in general, if you use different flag settings while encoding vs. when\ndecoding you likely have a bug somewhere.\n\nBelow comes a verbose discussion of these flags. Note that a \"codeset\"\nis simply an abstract set of character-codepoint pairs, while an\nencoding takes those codepoint numbers and *encodes* them, in our case\ninto octets. Unicode is (among other things) a codeset, UTF-8 is an\nencoding, and ISO-8859-1 (= latin 1) and ASCII are both codesets *and*\nencodings at the same time, which can be confusing.\n\n\"utf8\" flag disabled\nWhen \"utf8\" is disabled (the default), then \"encode\"/\"decode\"\ngenerate and expect Unicode strings, that is, characters with high\nordinal Unicode values (> 255) will be encoded as such characters,\nand likewise such characters are decoded as-is, no changes to them\nwill be done, except \"(re-)interpreting\" them as Unicode codepoints\nor Unicode characters, respectively (to Perl, these are the same\nthing in strings unless you do funny/weird/dumb stuff).\n\nThis is useful when you want to do the encoding yourself (e.g. when\nyou want to have UTF-16 encoded JSON texts) or when some other layer\ndoes the encoding for you (for example, when printing to a terminal\nusing a filehandle that transparently encodes to UTF-8 you certainly\ndo NOT want to UTF-8 encode your data first and have Perl encode it\nanother time).\n\n\"utf8\" flag enabled\nIf the \"utf8\"-flag is enabled, \"encode\"/\"decode\" will encode all\ncharacters using the corresponding UTF-8 multi-byte sequence, and\nwill expect your input strings to be encoded as UTF-8, that is, no\n\"character\" of the input string must have any value > 255, as UTF-8\ndoes not allow that.\n\nThe \"utf8\" flag therefore switches between two modes: disabled means\nyou will get a Unicode string in Perl, enabled means you get an\nUTF-8 encoded octet/binary string in Perl.\n\n\"latin1\" or \"ascii\" flags enabled\nWith \"latin1\" (or \"ascii\") enabled, \"encode\" will escape characters\nwith ordinal values > 255 (> 127 with \"ascii\") and encode the\nremaining characters as specified by the \"utf8\" flag.\n\nIf \"utf8\" is disabled, then the result is also correctly encoded in\nthose character sets (as both are proper subsets of Unicode, meaning\nthat a Unicode string with all character values < 256 is the same\nthing as a ISO-8859-1 string, and a Unicode string with all\ncharacter values < 128 is the same thing as an ASCII string in\nPerl).\n\nIf \"utf8\" is enabled, you still get a correct UTF-8-encoded string,\nregardless of these flags, just some more characters will be escaped\nusing \"\\uXXXX\" then before.\n\nNote that ISO-8859-1-*encoded* strings are not compatible with UTF-8\nencoding, while ASCII-encoded strings are. That is because the\nISO-8859-1 encoding is NOT a subset of UTF-8 (despite the ISO-8859-1\n*codeset* being a subset of Unicode), while ASCII is.\n\nSurprisingly, \"decode\" will ignore these flags and so treat all\ninput values as governed by the \"utf8\" flag. If it is disabled, this\nallows you to decode ISO-8859-1- and ASCII-encoded strings, as both\nstrict subsets of Unicode. If it is enabled, you can correctly\ndecode UTF-8 encoded strings.\n\nSo neither \"latin1\" nor \"ascii\" are incompatible with the \"utf8\"\nflag - they only govern when the JSON output engine escapes a\ncharacter or not.\n\nThe main use for \"latin1\" is to relatively efficiently store binary\ndata as JSON, at the expense of breaking compatibility with most\nJSON decoders.\n\nThe main use for \"ascii\" is to force the output to not contain\ncharacters with values > 127, which means you can interpret the\nresulting string as UTF-8, ISO-8859-1, ASCII, KOI8-R or most about\nany character set and 8-bit-encoding, and still get the same data\nstructure back. This is useful when your channel for JSON transfer\nis not 8-bit clean or the encoding might be mangled in between (e.g.\nin mail), and works because ASCII is a proper subset of most 8-bit\nand multibyte encodings in use in the world.\n\n### BUGS\n\nPlease report bugs on a specific behavior of this module to RT or GitHub\nissues (preferred):\n\n<https://github.com/makamaka/JSON-PP/issues>\n\n<https://rt.cpan.org/Public/Dist/Display.html?Queue=JSON-PP>\n\nAs for new features and requests to change common behaviors, please ask\nthe author of JSON::XS (Marc Lehmann, <schmorp[at]schmorp.de>) first, by\nemail (important!), to keep compatibility among JSON.pm backends.\n\nGenerally speaking, if you need something special for you, you are\nadvised to create a new module, maybe based on JSON::Tiny, which is\nsmaller and written in a much cleaner way than this module.\n\n### SEE ALSO\n\nThe jsonpp command line utility for quick experiments.\n\nJSON::XS, Cpanel::JSON::XS, and JSON::Tiny for faster alternatives. JSON\nand JSON::MaybeXS for easy migration.\n\nJSON::PP::Compat5005 and JSON::PP::Compat5006 for older perl users.\n\nRFC4627 (<http://www.ietf.org/rfc/rfc4627.txt>)\n\nRFC7159 (<http://www.ietf.org/rfc/rfc7159.txt>)\n\nRFC8259 (<http://www.ietf.org/rfc/rfc8259.txt>)\n\n### AUTHOR\n\nMakamaka Hannyaharamitu, <makamaka[at]cpan.org>\n\n### CURRENT MAINTAINER\n\nKenichi Ishigaki, <ishigaki[at]cpan.org>\n\n### COPYRIGHT AND LICENSE\n\nCopyright 2007-2016 by Makamaka Hannyaharamitu\n\nMost of the documentation is taken from JSON::XS by Marc Lehmann\n\nThis library is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\n"
        }
    ],
    "structuredContent": {
        "command": "JSON::PP",
        "section": "",
        "mode": "perldoc",
        "summary": "JSON::PP - JSON::XS compatible pure-Perl module.",
        "synopsis": "use JSON::PP;\n# exported functions, they croak on error\n# and expect/generate UTF-8\n$utf8encodedjsontext = encodejson $perlhashorarrayref;\n$perlhashorarrayref  = decodejson $utf8encodedjsontext;\n# OO-interface\n$json = JSON::PP->new->ascii->pretty->allownonref;\n$prettyprintedjsontext = $json->encode( $perlscalar );\n$perlscalar = $json->decode( $jsontext );\n# Note that JSON version 2.0 and above will automatically use\n# JSON::XS or JSON::PP, so you should be able to just:\nuse JSON;",
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 20,
                "subsections": []
            },
            {
                "name": "VERSION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 17,
                "subsections": []
            },
            {
                "name": "FUNCTIONAL INTERFACE",
                "lines": 38,
                "subsections": []
            },
            {
                "name": "OBJECT-ORIENTED INTERFACE",
                "lines": 699,
                "subsections": []
            },
            {
                "name": "INCREMENTAL PARSING",
                "lines": 101,
                "subsections": []
            },
            {
                "name": "MAPPING",
                "lines": 287,
                "subsections": []
            },
            {
                "name": "ENCODING/CODESET FLAG NOTES",
                "lines": 96,
                "subsections": []
            },
            {
                "name": "BUGS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 13,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "CURRENT MAINTAINER",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT AND LICENSE",
                "lines": 7,
                "subsections": []
            }
        ]
    }
}