{ "content": [ { "type": "text", "text": "# JSON::Parse (perldoc)\n\n## NAME\n\nJSON::Parse - Parse JSON\n\n## SYNOPSIS\n\nuse JSON::Parse 'parsejson';\nmy $json = '[\"golden\", \"fleece\"]';\nmy $perl = parsejson ($json);\n# Same effect as $perl = ['golden', 'fleece'];\nConvert JSON into Perl.\n\n## DESCRIPTION\n\nA module for parsing JSON. (JSON means \"JavaScript Object Notation\" and it is specified in \"RFC\n8259\".)\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **VERSION**\n- **DESCRIPTION**\n- **FUNCTIONS**\n- **METHODS** (1 subsections)\n- **OLD INTERFACE**\n- **Mapping from JSON to Perl** (1 subsections)\n- **RESTRICTIONS**\n- **DIAGNOSTICS**\n- **PERFORMANCE**\n- **SEE ALSO** (1 subsections)\n- **SCRIPT**\n- **DEPENDENCIES**\n- **EXPORTS**\n- **TESTING** (1 subsections)\n- **ACKNOWLEDGEMENTS**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "JSON::Parse", "section": "", "mode": "perldoc", "summary": "JSON::Parse - Parse JSON", "synopsis": "use JSON::Parse 'parsejson';\nmy $json = '[\"golden\", \"fleece\"]';\nmy $perl = parsejson ($json);\n# Same effect as $perl = ['golden', 'fleece'];\nConvert JSON into Perl.", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "VERSION", "lines": 5, "subsections": [] }, { "name": "DESCRIPTION", "lines": 15, "subsections": [] }, { "name": "FUNCTIONS", "lines": 143, "subsections": [] }, { "name": "METHODS", "lines": 150, "subsections": [ { "name": "Methods for manipulating literals", "lines": 113 } ] }, { "name": "OLD INTERFACE", "lines": 20, "subsections": [] }, { "name": "Mapping from JSON to Perl", "lines": 193, "subsections": [ { "name": "Literals", "lines": 132 } ] }, { "name": "RESTRICTIONS", "lines": 49, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 189, "subsections": [] }, { "name": "PERFORMANCE", "lines": 93, "subsections": [] }, { "name": "SEE ALSO", "lines": 7, "subsections": [ { "name": "Other CPAN modules for parsing and producing JSON", "lines": 552 } ] }, { "name": "SCRIPT", "lines": 21, "subsections": [] }, { "name": "DEPENDENCIES", "lines": 2, "subsections": [] }, { "name": "EXPORTS", "lines": 8, "subsections": [] }, { "name": "TESTING", "lines": 1, "subsections": [ { "name": "Internal testing code", "lines": 55 } ] }, { "name": "ACKNOWLEDGEMENTS", "lines": 7, "subsections": [] }, { "name": "AUTHOR", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "JSON::Parse - Parse JSON\n", "subsections": [] }, "SYNOPSIS": { "content": "use JSON::Parse 'parsejson';\nmy $json = '[\"golden\", \"fleece\"]';\nmy $perl = parsejson ($json);\n# Same effect as $perl = ['golden', 'fleece'];\n\nConvert JSON into Perl.\n", "subsections": [] }, "VERSION": { "content": "This documents version 0.61 of JSON::Parse corresponding to git commit\n033269fa8972fdce8626aa65cd11a5394ab50492\n\nreleased on Thu Feb 11 09:14:04 2021 +0900.\n", "subsections": [] }, "DESCRIPTION": { "content": "A module for parsing JSON. (JSON means \"JavaScript Object Notation\" and it is specified in \"RFC\n8259\".)\n\nJSON::Parse offers the function \"parsejson\", which takes a string containing JSON, and returns\nan equivalent Perl structure. It also offers validation of JSON via \"validjson\", which returns\ntrue or false depending on whether the JSON is correct or not, and \"assertvalidjson\", which\nproduces a descriptive fatal error if the JSON is invalid. A function \"readjson\" reads JSON\nfrom a file, and there is a safer version of \"parsejson\" called \"parsejsonsafe\" which doesn't\nthrow exceptions.\n\nFor special cases of parsing, there are also methods \"new\" and \"parse\", which create a JSON\nparsing object and run it on text. See \"METHODS\".\n\nJSON::Parse accepts only UTF-8 as input. See \"UTF-8 only\" and \"Handling of Unicode\".\n", "subsections": [] }, "FUNCTIONS": { "content": "assertvalidjson\nuse JSON::Parse 'assertvalidjson';\neval {\nassertvalidjson ('[\"xyz\":\"b\"]');\n};\nif ($@) {\nprint \"Your JSON was invalid: $@\\n\";\n}\n# Prints \"Unexpected character ':' parsing array\"\n\nproduces output\n\nYour JSON was invalid: JSON error at line 1, byte 7/11: Unexpected character ':' parsing array starting from byte 1: expecting whitespace: 'n', '\\r', '\\t', ' ' or comma: ',' or end of array: ']' at /usr/home/ben/projects/json-parse/examples/assert.pl line 6.\n\n(This example is included as assert.pl\n in the\ndistribution.)\n\nThis is the underlying function for \"validjson\". It runs at the same speed, but it throws an\nerror if the JSON is wrong, rather than returning 1 or 0. See \"DIAGNOSTICS\" for the error\nformat, which is identical to \"parsejson\".\n\nThis cannot detect key collisions in the JSON since it does not store values. See \"Key\ncollisions\" for more on this module's handling of non-unique names in the JSON.\n\nThe method equivalent to this is \"check\".\n\nThe behaviour of disallowing empty inputs was changed in version 0.49.\n\nparsejson\nuse JSON::Parse 'parsejson';\nmy $perl = parsejson ('{\"x\":1, \"y\":2}');\n\nThis function converts JSON into a Perl structure, either an array reference, a hash reference,\nor a scalar.\n\nIf the first argument does not contain a complete valid JSON text, is the undefined value, an\nempty string, or a string containing only whitespace \"parsejson\" throws a fatal error (\"dies\").\n\nIf the argument contains valid JSON, the return value is either a hash reference, an array\nreference, or a scalar. If the input JSON text is a serialized object, a hash reference is\nreturned:\n\nuse JSON::Parse ':all';\nmy $perl = parsejson ('{\"a\":1, \"b\":2}');\nprint ref $perl, \"\\n\";\n\nproduces output\n\nHASH\n\n(This example is included as hash.pl\n in the distribution.)\n\nIf the input JSON text is a serialized array, an array reference is returned:\n\nuse JSON::Parse ':all';\nmy $perl = parsejson ('[\"a\", \"b\", \"c\"]');\nprint ref $perl, \"\\n\";\n\nproduces output\n\nARRAY\n\n(This example is included as array.pl\n in the\ndistribution.)\n\nOtherwise a Perl scalar is returned.\n\nThe behaviour of allowing a scalar was added in version 0.32 of this module. This brings it into\nline with the new specification for JSON. The behaviour of disallowing empty inputs was changed\nin version 0.49.\n\nThe function \"parsejsonsafe\" offers a version of this function with various safety features\nenabled. The method \"parse\" is equivalent to this.\n\nparsejsonsafe\nThis is almost the same thing as \"parsejson\", but has the following differences:\n\nDoes not throw exceptions\nIf the JSON is invalid, a warning is printed and the undefined value is returned, as if\ncalling \"parsejson\" like this:\n\neval {\n$out = parsejson ($json);\n};\nif ($@) {\ncarp $@;\n$out = undef;\n}\n\nDetects key collisions\nThis switches on \"detectcollisions\", so that if the JSON contains non-unique names, a\nwarning is printed and the undefined value is returned. See \"Key collisions\" for an\nexplanation of what a key collision is.\n\nBooleans are not read-only\nThis switches on \"copyliterals\" so that JSON true, false and null values are copied. These\nvalues can be modified, but they will not be converted back into \"true\" and \"false\" by\nJSON::Create.\n\nErrors are reported by carp\nParsing errors are reported by \"carp\" in Carp, so the error line number refers to the\ncaller's line.\n\nAs the name implies, this is meant to be a \"safety-first\" version of \"parsejson\".\n\n๐ŸŽฒ This function was added in version 0.38.\n\nreadjson\nuse JSON::Parse 'readjson';\nmy $p = readjson ('filename');\n\nThis is exactly the same as \"parsejson\" except that it reads the JSON from the specified file\nrather than a scalar. The file must be in the UTF-8 encoding, and is opened as a character file\nusing \":encoding(utf8)\" (see PerlIO::encoding and perluniintro). The output is marked as\ncharacter strings.\n\nThe method equivalent is \"read\".\n\nThis is a convenience function written in Perl. You may prefer to read the file yourself using\nanother module if you need faster performance.\n\nThis was renamed from \"jsonfiletoperl\" in version 0.59. The old name will also continue to\nwork indefinitely.\n\nvalidjson\nuse JSON::Parse 'validjson';\nif (validjson ($json)) {\n# do something\n}\n\n\"validjson\" returns *1* if its argument is valid JSON and *0* if not. It runs several times\nfaster than \"parsejson\". This gain in speed is obtained because it discards the input data\nafter reading it, rather than storing it into Perl variables.\n\nThis does not supply the actual errors which caused invalidity. Use \"assertvalidjson\" to get\nerror messages when the JSON is invalid.\n\nThis cannot detect duplicate keys in JSON objects because it does not store values. See \"Key\ncollisions\" for more on this module's handling of non-unique names in the JSON.\n", "subsections": [] }, "METHODS": { "content": "If you need to parse JSON and you are not satisfied with the parsing options offered by\n\"parsejson\" and \"parsejsonsafe\", you can create a JSON parsing object with \"new\" and set\nvarious options on the object, then use it with \"parse\" or \"read\".\n\nThere are options to copy JSON literals (\"true\", \"false\", \"null\") with \"copyliterals\", switch\noff fatal errors with \"warnonly\", detect duplicate keys in objects with \"detectcollisions\",\nset the maximum depth of nested objects and arrays with \"setmaxdepth\", produce\nmachine-readable parsing errors with \"diagnosticshash\", and set the JSON literals to user\ndefined values with the methods described under \"Methods for manipulating literals\".\n\nThese methods only affect the object created with \"new\"; they do not globally affect the\nbehaviour of \"parsejson\" or \"parsejsonsafe\".\n\ncheck\neval {\n$jp->check ($json);\n};\n\nThis does the same thing as \"assertvalidjson\", except its behaviour can be modified using the\n\"diagnosticshash\" method.\n\n๐ŸŽฒ This method was added in version 0.48. This is for the benefit of JSON::Repair.\n\ncopyliterals\n$jp->copyliterals (1);\n\nWith a true value, copy JSON literal values (\"null\", \"true\", and \"false\") into new Perl scalar\nvalues, and don't put read-only values into the output.\n\nWith a false value, use read-only scalars:\n\n$jp->copyliterals (0);\n\nThe \"copyliterals (1)\" behaviour is the behaviour of \"parsejsonsafe\". The \"copyliterals (0)\"\nbehaviour is the behaviour of \"parsejson\".\n\nIf the user also sets user-defined literals with \"settrue\", \"setfalse\" and \"setnull\", that\ntakes precedence over this.\n\n๐ŸŽฒ This method was added in version 0.38.\n\ndetectcollisions\n$jp->detectcollisions (1);\n\nThis switches on a check for hash key collisions (non-unique names in JSON objects). If a\ncollision is found, an error message \"Name is not unique\" is printed, which also gives the\nnon-unique name and the byte position where the start of the colliding string was found:\n\nuse JSON::Parse;\nmy $jp = JSON::Parse->new ();\n$jp->detectcollisions (1);\neval {\n$jp->parse ('{\"animals\":{\"cat\":\"moggy\",\"cat\":\"feline\",\"cat\":\"neko\"}}');\n};\nprint \"$@\\n\" if $@;\n\nproduces output\n\nJSON error at line 1, byte 28/55: Name is not unique: \"cat\" parsing object starting from byte 12 at /usr/home/ben/projects/json-parse/examples/../blib/lib/JSON/Parse.pm line 131.\n\n(This example is included as collide.pl\n in the\ndistribution.)\n\nThe \"detectcollisions (1)\" behaviour is the behaviour of \"parsejsonsafe\". The\n\"detectcollisions (0)\" behaviour is the behaviour of \"parsejson\".\n\n๐ŸŽฒ This method was added in version 0.38.\n\ndiagnosticshash\n$jp->diagnosticshash (1);\n\nThis changes diagnostics produced by errors from a simple string into a hash reference\ncontaining various fields. This is incompatible with \"warnonly\".\n\nThis replaces the previous experimental global variable $jsondiagnostics, which was removed\nfrom the module. The hash keys and values are identical to those provided in the object returned\nby $jsondiagnostics, with the addition of a key \"error as string\" which returns the usual\nerror.\n\nThis requires Perl version 5.14 or later.\n\nAn example of the use of this method to \"repair\" broken JSON is in the module \"JSON::Repair\".\n\n๐ŸŽฒ This method was added in version 0.46.\n\ngetmaxdepth\nmy $maxdepth = $jp->getmaxdepth ();\n\nThis returns the maximum nesting depth of objects or arrays in the input JSON. The default value\nis 10,000.\n\n๐ŸŽฒ This method was added in version 0.58.\n\nnew\nmy $jp = JSON::Parse->new ();\n\nCreate a new JSON::Parse object.\n\n๐ŸŽฒ This method was added in version 0.38.\n\nparse\nmy $out = $jp->parse ($json);\n\nThis does the same thing as \"parsejson\", except its behaviour can be modified using object\nmethods.\n\n๐ŸŽฒ This method was added in version 0.38.\n\nThis was renamed from \"run\" in version 0.60.\n\nread\nmy $json = $jp->read ($file);\n\nRead a file, parse the contained JSON, and return the output. This method is equivalent to the\nfunction \"readjson\".\n\n๐ŸŽฒ This method was added in version 0.60.\n\nsetmaxdepth\n$jp->setmaxdepth (42);\n\nSet the maximum nesting depth of objects or arrays in the input JSON. The default value is\n10,000.\n\n๐ŸŽฒ This method was added in version 0.58.\n\nupgradeutf8\n$jp->upgradeutf8 (1);\n\nUpgrade input from bytes to characters automatically.\n\nThis can be switched off again using any false value:\n\n$jp->upgradeutf8 (0);\n\n๐ŸŽฒ This method was added in version 0.61.\n\nwarnonly\n$jp->warnonly (1);\n\nWarn, don't die, on error. Failed parsing returns the undefined value, \"undef\", and prints a\nwarning.\n\nThis can be switched off again using any false value:\n\n$jp->warnonly ('');\n\n๐ŸŽฒ This method was added in version 0.41.\n", "subsections": [ { "name": "Methods for manipulating literals", "content": "These methods alter what is written into the Perl structure when the parser sees a literal\nvalue, \"true\", \"false\" or \"null\" in the input JSON.\n\nThis number of methods is needed because of the possibility that a user wants to set the output\nfor \"false\" to be \"undef\":\n\n$jp->setfalse (undef);\n\nThus, we cannot use a single function \"$jp->false (undef)\" to cover both setting and deleting of\nvalues.\n\n๐ŸŽฒ This facility was added in version 0.38.\n\nsettrue\n$jp->settrue (\"Yes, that is so true\");\n\nSupply a scalar to be used in place of the JSON \"true\" literal.\n\nThis example puts the string \"Yes, that is so true\" into the hash or array when we hit a \"true\"\nliteral, rather than the default read-only scalar:\n\nuse JSON::Parse;\nmy $json = '{\"yes\":true,\"no\":false}';\nmy $jp = JSON::Parse->new ();\n$jp->settrue ('Yes, that is so true');\nmy $out = $jp->parse ($json);\nprint $out->{yes}, \"\\n\";\n\nprints\n\nYes, that is so true\n\nTo override the previous value, call it again with a new value. To delete the value and revert\nto the default behaviour, use \"deletetrue\".\n\nIf you give this a value which is not \"true\", as in Perl will evaluate it as a false in an if\nstatement, it prints a warning \"User-defined value for JSON true evaluates as false\". You can\nswitch this warning off with \"nowarnliterals\".\n\n๐ŸŽฒ This method was added in version 0.38.\n\ndeletetrue\n$jp->deletetrue ();\n\nDelete the user-defined true value. See \"settrue\".\n\nThis method is \"safe\" in that it has absolutely no effect if no user-defined value is in place.\nIt does not return a value.\n\n๐ŸŽฒ This method was added in version 0.38.\n\nsetfalse\n$jp->setfalse (JSON::PP::Boolean::false);\n\nSupply a scalar to be used in place of the JSON \"false\" literal.\n\nIn the above example, when we hit a \"false\" literal, we put \"JSON::PP::Boolean::false\" in the\noutput, similar to JSON::PP and other CPAN modules like Mojo::JSON or JSON::XS.\n\nTo override the previous value, call it again with a new value. To delete the value and revert\nto the default behaviour, use \"deletefalse\".\n\nIf you give this a value which is not \"false\", as in Perl will evaluate it as a false in an if\nstatement, it prints a warning \"User-defined value for JSON false evaluates as true\". You can\nswitch this warning off with \"nowarnliterals\".\n\n๐ŸŽฒ This method was added in version 0.38.\n\ndeletefalse\n$jp->deletefalse ();\n\nDelete the user-defined false value. See \"setfalse\".\n\nThis method is \"safe\" in that it has absolutely no effect if no user-defined value is in place.\nIt does not return a value.\n\n๐ŸŽฒ This method was added in version 0.38.\n\nsetnull\n$jp->setnull (0);\n\nSupply a scalar to be used in place of the JSON \"null\" literal.\n\nTo override the previous value, call it again with a new value. To delete the value and revert\nto the default behaviour, use \"deletenull\".\n\n๐ŸŽฒ This method was added in version 0.38.\n\ndeletenull\n$jp->deletenull ();\n\nDelete the user-defined null value. See \"setnull\".\n\nThis method is \"safe\" in that it has absolutely no effect if no user-defined value is in place.\nIt does not return a value.\n\n๐ŸŽฒ This method was added in version 0.38.\n\nnowarnliterals\n$jp->nowarnliterals (1);\n\nUse a true value to switch off warnings about setting boolean values to contradictory things.\nFor example if you want to set the JSON \"false\" literal to turn into the string \"false\",\n\n$jp->nowarnliterals (1);\n$jp->setfalse (\"false\");\n\nSee also \"Contradictory values for \"true\" and \"false\"\".\n\nThis also switches off the warning \"User-defined value overrules copyliterals\".\n\n๐ŸŽฒ This method was added in version 0.38.\n" } ] }, "OLD INTERFACE": { "content": "The following alternative function names are accepted. These are the names used for the\nfunctions in old versions of this module. These names are not deprecated and will never be\nremoved from the module.\n\nThe names ending in \"toperl\" seem quite silly in retrospect since surely it is obvious that\none is programming in Perl.\n\njsontoperl\nThis is exactly the same function as \"parsejson\".\n\njsonfiletoperl\nThis is exactly the same function as \"readjson\". The function was renamed in version 0.59,\nafter the same function in \"File::JSON::Slurper\".\n\nrun\nThis is the old name for \"parse\".\n\nvalidatejson\nThis is exactly the same function as \"assertvalidjson\".\n", "subsections": [] }, "Mapping from JSON to Perl": { "content": "JSON elements are mapped to Perl as follows:\n\nJSON numbers\nJSON numbers become Perl numbers, either integers or double-precision floating point numbers, or\npossibly strings containing the number if parsing of a number by the usual methods fails\nsomehow.\n\nJSON does not allow leading zeros, like *0123*, or leading plus signs, like *+100*, in numbers,\nso these cause an \"Unexpected character\" error. JSON also does not allow numbers of the form\n*1.*, but it does allow things like *0e0* or *1E999999*. As far as possible these are accepted\nby JSON::Parse.\n\nJSON strings\nJSON strings become Perl strings. The JSON escape characters such as \"\\t\" for the tab character\n(see section 2.5 of \"RFC 8259\") are mapped to the equivalent ASCII character.\n\nHandling of Unicode\nInputs must be in the UTF-8 format. See \"UTF-8 only\".\n\nIn addition, JSON::Parse rejects UTF-8 which encodes non-characters such as \"U+FFFF\" and\nill-formed characters such as incomplete halves of surrogate pairs.\n\nUnicode encoding points in the input of the form \"\\u3000\" are converted into the equivalent\nUTF-8 bytes.\n\nSurrogate pairs in the form \"\\uD834\\uDD1E\" are also handled. If the second half of the surrogate\npair is missing, an \"Unexpected character\" or \"Unexpected end of input\" error is thrown. If the\nsecond half of the surrogate pair is present but contains an impossible value, a \"Not surrogate\npair\" error is thrown.\n\nIf the input to \"parsejson\" is marked as Unicode characters, the output strings will be marked\nas Unicode characters. If the input is not marked as Unicode characters, the output strings will\nnot be marked as Unicode characters. Thus,\n\nuse JSON::Parse ':all';\n# The scalar $sasori looks like Unicode to Perl\nuse utf8;\nmy $sasori = '[\"่ \"]';\nmy $p = parsejson ($sasori);\nprint utf8::isutf8 ($p->[0]);\n# Prints 1.\n\nbut\n\nuse JSON::Parse ':all';\n# The scalar $ebi does not look like Unicode to Perl\nno utf8;\nmy $ebi = '[\"ๆตท่€\"]';\nmy $p = parsejson ($ebi);\nprint utf8::isutf8 ($p->[0]);\n# Prints nothing.\n\nEscapes of the form \\uXXXX (see page three of \"RFC 8259\") are mapped to ASCII if XXXX is less\nthan 0x80, or to UTF-8 if XXXX is greater than or equal to 0x80.\n\nStrings containing \\uXXXX escapes greater than 0x80 are also upgraded to character strings,\nregardless of whether the input is a character string or a byte string, thus regardless of\nwhether Perl thinks the input string is Unicode, escapes like \\u87f9 are converted into the\nequivalent UTF-8 bytes and the particular string in which they occur is marked as a character\nstring:\n\nuse JSON::Parse ':all';\nno utf8;\n# ่Ÿน\nmy $kani = '[\"\\u87f9\"]';\nmy $p = parsejson ($kani);\nprint \"It's marked as a character string\" if utf8::isutf8 ($p->[0]);\n# Prints \"It's marked as a character string\" because it's upgraded\n# regardless of the input string's flags.\n\nThis is modelled on the behaviour of Perl's \"chr\":\n\nno utf8;\nmy $kani = '87f9';\nprint \"hex is character string\\n\" if utf8::isutf8 ($kani);\n# prints nothing\n$kani = chr (hex ($kani));\nprint \"chr makes it a character string\\n\" if utf8::isutf8 ($kani);\n# prints \"chr makes it a character string\"\n\nHowever, JSON::Parse also upgrades the remaining part of the string into a character string,\neven when it's not marked as a character string. For example,\n\nuse JSON::Parse ':all';\nuse Unicode::UTF8 'decodeutf8';\nno utf8;\nmy $highbytes = \"ใ‹\";\nmy $notutf8 = \"$highbytes\\\\u3042\";\nmy $test = \"{\\\"a\\\":\\\"$notutf8\\\"}\";\nmy $out = parsejson ($test);\n# JSON::Parse does something unusual here in promoting the first part\n# of the string into UTF-8.\nprint \"JSON::Parse gives this: \", $out->{a}, \"\\n\";\n# Perl cannot assume that $highbytes is in UTF-8, so it has to just\n# turn the initial characters into garbage.\nmy $addchr = $highbytes . chr (0x3042);\nprint \"Perl's output is like this: \", $addchr, \"\\n\";\n# In fact JSON::Parse's behaviour is equivalent to this:\nmy $equiv = decodeutf8 ($highbytes) . chr (0x3042);\nprint \"JSON::Parse did something like this: \", $equiv, \"\\n\";\n# With character strings switched on, Perl and JSON::Parse do the same\n# thing.\nuse utf8;\nmy $isutf8 = \"ใ‹\";\nmy $test2 = \"{\\\"a\\\":\\\"$isutf8\\\\u3042\\\"}\";\nmy $out2 = parsejson ($test2);\nprint \"JSON::Parse: \", $out2->{a}, \"\\n\";\nmy $addchr2 = $isutf8 . chr (0x3042);\nprint \"Native Perl: \", $addchr2, \"\\n\";\n\nproduces output\n\nJSON::Parse gives this: ใ‹ใ‚\nPerl's output is like this: รฃยย‹ใ‚\nJSON::Parse did something like this: ใ‹ใ‚\nJSON::Parse: ใ‹ใ‚\nNative Perl: ใ‹ใ‚\n\n(This example is included as unicode-details.pl\n in the\ndistribution.)\n\nAlthough in general the above would be an unsafe practice, JSON::Parse can do things this way\nbecause JSON is a text-only, Unicode-only format. To ensure that invalid inputs are never\nupgraded, JSON::Parse checks each input byte to make sure that it forms UTF-8. See also \"UTF-8\nonly\". Doing things this way, rather than the way that Perl does it, was one of the original\nmotivations for writing this module.\n\nJSON arrays\nJSON arrays become Perl array references. The elements of the Perl array are in the same order\nas they appear in the JSON.\n\nThus\n\nmy $p = parsejson ('[\"monday\", \"tuesday\", \"wednesday\"]');\n\nhas the same result as a Perl declaration of the form\n\nmy $p = [ 'monday', 'tuesday', 'wednesday' ];\n\nJSON objects\nJSON objects become Perl hashes. The members of the JSON object become key and value pairs in\nthe Perl hash. The string part of each object member becomes the key of the Perl hash. The value\npart of each member is mapped to the value of the Perl hash.\n\nThus\n\nmy $j = < ['blue', 'black'],\ntuesday => ['grey', 'heart attack'],\nfriday => 'Gotta get down on Friday',\n};\n\nKey collisions\nA key collision is something like the following.\n\nuse JSON::Parse qw/parsejson parsejsonsafe/;\nmy $j = '{\"a\":1, \"a\":2}';\nmy $p = parsejson ($j);\nprint \"Ambiguous key 'a' is \", $p->{a}, \"\\n\";\nmy $q = parsejsonsafe ($j);\n\nproduces output\n\nJSON::Parse::parsejsonsafe: Name is not unique: \"a\" parsing object starting from byte 1 at /usr/home/ben/projects/json-parse/examples/key-collision.pl line 8.\nAmbiguous key 'a' is 2\n\n(This example is included as key-collision.pl\n in the\ndistribution.)\n\nHere the key \"a\" could be either 1 or 2. As seen in the example, \"parsejson\" overwrites the\nfirst value with the second value. \"parsejsonsafe\" halts and prints a warning. If you use\n\"new\" you can switch key collision on and off with the \"detectcollisions\" method.\n\nThe rationale for \"parsejson\" not to give warnings is that Perl doesn't give information about\ncollisions when storing into hash values, and checking for collisions for every key will degrade\nperformance for the sake of an unlikely occurrence. The JSON specification says \"The names\nwithin an object SHOULD be unique.\" (see \"RFC 8259\", page 5), although it's not a requirement.\n\nFor performance, \"validjson\" and \"assertvalidjson\" do not store hash keys, thus they cannot\ndetect this variety of problem.\n", "subsections": [ { "name": "Literals", "content": "false\n\"parsejson\" maps the JSON false literal to a readonly scalar which evaluates to the empty\nstring, or to zero in a numeric context. (This behaviour changed from version 0.36 to 0.37. In\nversions up to 0.36, the false literal was mapped to a readonly scalar which evaluated to 0\nonly.) \"parsejsonsafe\" maps the JSON literal to a similar scalar without the readonly\nconstraints. If you use a parser created with \"new\", you can choose either of these behaviours\nwith \"copyliterals\", or you can tell JSON::Parse to put your own value in place of falses using\nthe \"setfalse\" method.\n\nnull\n\"parsejson\" maps the JSON null literal to a readonly scalar $JSON::Parse::null which evaluates\nto \"undef\". \"parsejsonsafe\" maps the JSON literal to the undefined value. If you use a parser\ncreated with \"new\", you can choose either of these behaviours with \"copyliterals\", or you can\ntell JSON::Parse to put your own value in place of nulls using the \"setnull\" method.\n\ntrue\n\"parsejson\" maps the JSON true literal to a readonly scalar which evaluates to 1.\n\"parsejsonsafe\" maps the JSON literal to the value 1. If you use a parser created with \"new\",\nyou can choose either of these behaviours with \"copyliterals\", or you can tell JSON::Parse to\nput your own value in place of trues using the \"settrue\" method.\n\nRound trips and compatibility\nThe Perl versions of literals produced by \"parsejson\" will be converted back to JSON literals\nif you use \"createjson\" in JSON::Create. However, JSON::Parse's literals are incompatible with\nthe other CPAN JSON modules. For compatibility with other CPAN modules, create a JSON::Parse\nobject with \"new\", and set JSON::Parse's literals with \"settrue\", \"setfalse\", and \"setnull\".\n\nA round trip with JSON::Tiny\nThis example demonstrates round-trip compatibility using JSON::Tiny, version 0.58:\n\nuse utf8;\nuse JSON::Tiny '0.58', qw(decodejson encodejson);\nuse JSON::Parse;\nuse JSON::Create;\nmy $cream = '{\"clapton\":true,\"hendrix\":false}';\nmy $jp = JSON::Parse->new ();\nmy $jc = JSON::Create->new (sort => 1);\n\nprint \"First do a round-trip of our modules:\\n\\n\";\nprint $jc->create ($jp->parse ($cream)), \"\\n\\n\";\n\nprint \"Now do a round-trip of JSON::Tiny:\\n\\n\";\nprint encodejson (decodejson ($cream)), \"\\n\\n\";\n\nprint \"๐Ÿฅด First, incompatible mode:\\n\\n\";\nprint 'tiny(parse): ', encodejson ($jp->parse ($cream)), \"\\n\";\nprint 'create(tiny): ', $jc->create (decodejson ($cream)), \"\\n\\n\";\n\n# Set our parser to produce these things as literals:\n$jp->settrue (JSON::Tiny::true);\n$jp->setfalse (JSON::Tiny::false);\n\nprint \"๐Ÿ”„ Compatibility with JSON::Parse:\\n\\n\";\nprint 'tiny(parse):', encodejson ($jp->parse ($cream)), \"\\n\\n\";\n$jc->bool ('JSON::Tiny::Bool');\n\nprint \"๐Ÿ”„ Compatibility with JSON::Create:\\n\\n\";\nprint 'create(tiny):', $jc->create (decodejson ($cream)), \"\\n\\n\";\n\nprint \"๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:\\n\\n\";\nprint $jc->create ($jp->parse ($cream)), \"\\n\";\n\nproduces output\n\nFirst do a round-trip of our modules:\n\n{\"clapton\":true,\"hendrix\":false}\n\nNow do a round-trip of JSON::Tiny:\n\n{\"clapton\":true,\"hendrix\":false}\n\n๐Ÿฅด First, incompatible mode:\n\ntiny(parse): {\"clapton\":1,\"hendrix\":\"\"}\ncreate(tiny): {\"clapton\":1,\"hendrix\":0}\n\n๐Ÿ”„ Compatibility with JSON::Parse:\n\ntiny(parse):{\"clapton\":true,\"hendrix\":false}\n\n๐Ÿ”„ Compatibility with JSON::Create:\n\ncreate(tiny):{\"clapton\":true,\"hendrix\":false}\n\n๐Ÿ”„ JSON::Parse and JSON::Create are still compatible too:\n\n{\"clapton\":true,\"hendrix\":false}\n\n(This example is included as json-tiny-round-trip-demo.pl\n\nin the distribution.)\n\nMost of the other CPAN modules use similar methods to JSON::Tiny, so the above example can\neasily be adapted. See also \"Interoperability\" in JSON::Create for various examples.\n\nModifying the values\n\"parsejson\" maps all the literals to read-only values. Because of this, attempting to modifying\nthe boolean values in the hash reference returned by \"parsejson\" will cause \"Modification of a\nread-only value attempted\" errors:\n\nmy $in = '{\"hocus\":true,\"pocus\":false,\"focus\":null}';\nmy $p = jsonparse ($in);\n$p->{hocus} = 99;\n# \"Modification of a read-only value attempted\" error occurs\n\nSince the hash values are read-only scalars, \"$p->{hocus} = 99\" is like this:\n\nundef = 99;\n\nIf you need to modify the returned hash reference, then delete the value first:\n\nmy $in = '{\"hocus\":true,\"pocus\":false,\"focus\":null}';\nmy $p = jsonparse ($in);\ndelete $p->{pocus};\n$p->{pocus} = 99;\n# OK\n\nSimilarly with array references, delete the value before altering:\n\nmy $in = '[true,false,null]';\nmy $q = jsonparse ($in);\ndelete $q->[1];\n$q->[1] = 'magic';\n\nNote that the return values from parsing bare literals are not read-only scalars, so\n\nmy $true = JSON::Parse::jsonparse ('true');\n$true = 99;\n\nproduces no error. This is because Perl copies the scalar.\n" } ] }, "RESTRICTIONS": { "content": "This module imposes the following restrictions on its input.\n\nJSON only\nJSON::Parse is a strict parser. It only accepts input which exactly meets the criteria of\n\"RFC 8259\". That means, for example, JSON::Parse does not accept single quotes (') instead\nof double quotes (\"), or numbers with leading zeros, like 0123. JSON::Parse does not accept\ncontrol characters (0x00 - 0x1F) in strings, missing commas between array or hash elements\nlike \"[\"a\" \"b\"]\", or trailing commas like \"[\"a\",\"b\",\"c\",]\". It also does not accept trailing\nnon-whitespace, like the second \"]\" in \"[\"a\"]]\".\n\nYou may find \"JSON::Repair\" by the same authors as JSON::Parse useful if you need to process\nJSON-like text with tolerance for errors.\n\nNo incremental parsing\nJSON::Parse does not parse incrementally. It only parses fully-formed JSON strings which\ninclude all opening and closing brackets. This is an inherent part of the design of the\nmodule. Incremental parsing in the style of XML::Parser would require some kind of callback\nstructure to deal with the elements of the partially digested structures, but JSON::Parse\nwas never designed to do this; it merely converts what it sees into a Perl structure. Claims\nto offer incremental JSON parsing in other modules' documentation should be diligently\nverified.\n\nUTF-8 only\nJSON::Parse only parses the UTF-8 format. If input is in a different Unicode encoding than\nUTF-8, convert the input before handing it to this module. For example, for the UTF-16\nformat,\n\nuse Encode 'decode';\nmy $inpututf8 = decode ('UTF-16', $input);\nmy $perl = parsejson ($inpututf8);\n\nor, for a file, use \":encoding\" (see PerlIO::encoding and perluniintro):\n\nopen my $input, \"<:encoding(UTF-16)\", 'some-json-file';\n\nJSON::Parse does not try to determine the nature of the octet stream using BOM markers. A\nBOM marker in the input consists of bytes 0xFE and 0xFF, both of which are invalid as UTF-8,\nand thus will cause a fatal error.\n\nThis restriction to UTF-8 applies regardless of whether Perl thinks that the input string is\na character string or a byte string. Non-UTF-8 input will cause an \"Unexpected character\"\nerror.\n\nThe latest specification for JSON, \"RFC 8259\", specifies it to be a UTF-8 only format.\n\nJSON::Parse does not accept Unicode non-characters (U+FFFF, UFDDO, etc.), UTF-8 representing\nsurrogate pair code points, or bytes outside the range of Unicode code points as UTF-8\nbytes.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "\"validjson\" does not produce error messages. \"parsejson\" and \"assertvalidjson\" die on\nencountering invalid input. \"parsejsonsafe\" uses \"carp\" in Carp to pass error messages as\nwarnings.\n\nError messages have the line number, and the byte number where appropriate, of the input which\ncaused the problem. The line number is formed simply by counting the number of \"\\n\" (linefeed,\nASCII 0x0A) characters in the whitespace part of the JSON.\n\nIn \"parsejson\" and \"assertvalidjson\", parsing errors are fatal, so to continue after an error\noccurs, put the parsing into an \"eval\" block:\n\nmy $p;\neval {\n$p = parsejson ($j);\n};\nif ($@) {\n# handle error\n}\n\nThe following error messages are produced:\n\nUnexpected character\nAn unexpected character (byte) was encountered in the input. For example, when looking at\nthe beginning of a string supposedly containing JSON, if the module encounters a plus sign,\nit will give an error like this:\n\nassertvalidjson ('+');\n\ngives output\n\nJSON error at line 1, byte 1/1: Unexpected character '+' parsing initial state: expecting whitespace: 'n', '\\r', '\\t', ' ' or start of string: '\"' or digit: '0-9' or minus: '-' or start of an array or object: '{', '[' or start of literal: 't', 'f', 'n'\n\nThe message always includes a list of what characters are allowed.\n\nIf there is some recognizable structure being parsed, the error message will include its\nstarting point in the form \"starting from byte n\":\n\nassertvalidjson ('{\"this\":\"\\a\"}');\n\ngives output\n\nJSON error at line 1, byte 11/13: Unexpected character 'a' parsing string starting from byte 9: expecting escape: '', '/', '\"', 'b', 'f', 'n', 'r', 't', 'u'\n\nA feature of JSON is that parsing it requires only one byte to be examined at a time. Thus\nalmost all parsing problems can be handled using the \"Unexpected character\" error type,\nincluding spelling errors in literals:\n\nassertvalidjson ('[true,folse]');\n\ngives output\n\nJSON error at line 1, byte 8/12: Unexpected character 'o' parsing literal starting from byte 7: expecting 'a'\n\nand the missing second half of a surrogate pair:\n\nassertvalidjson ('[\"\\udc00? <-- should be a second half here\"]');\n\ngives output\n\nJSON error at line 1, byte 9/44: Unexpected character '?' parsing unicode escape starting from byte 3: expecting '\\'\n\nAll kinds of errors can occur parsing numbers, for example a missing fraction,\n\nassertvalidjson ('[1.e9]');\n\ngives output\n\nJSON error at line 1, byte 4/6: Unexpected character 'e' parsing number starting from byte 2: expecting digit: '0-9'\n\nand a leading zero,\n\nassertvalidjson ('[0123]');\n\ngives output\n\nJSON error at line 1, byte 3/6: Unexpected character '1' parsing number starting from byte 2: expecting whitespace: 'n', '\\r', '\\t', ' ' or comma: ',' or end of array: ']' or dot: '.' or exponential sign: 'e', 'E'\n\nThe error message is this complicated because all of the following are valid here:\nwhitespace: \"[0 ]\"; comma: \"[0,1]\", end of array: \"[0]\", dot: \"[0.1]\", or exponential:\n\"[0e0]\".\n\nThese are all handled by this error. Thus the error messages are a little confusing as\ndiagnostics.\n\nVersions of this module prior to 0.29 gave more informative messages like \"leading zero in\nnumber\". (The messages weren't documented.) The reason to change over to the single message\nwas because it makes the parsing code simpler, and because the testing code described in\n\"TESTING\" makes use of the internals of this error to check that the error message produced\nactually do correspond to the invalid and valid bytes allowed by the parser, at the exact\nbyte given.\n\nThis is a bytewise error, thus for example if a miscoded UTF-8 appears in the input, an\nerror message saying what bytes would be valid at that point will be printed.\n\nno utf8;\nuse JSON::Parse 'assertvalidjson';\n\n# Error in first byte:\n\nmy $badutf81 = chr (hex (\"81\"));\neval { assertvalidjson (\"[\\\"$badutf81\\\"]\"); };\nprint \"$@\\n\";\n\n# Error in third byte:\n\nmy $badutf82 = chr (hex ('e2')) . chr (hex ('9C')) . 'b';\neval { assertvalidjson (\"[\\\"$badutf82\\\"]\"); };\nprint \"$@\\n\";\n\nprints\n\nJSON error at line 1, byte 3/5: Unexpected character 0x81 parsing string starting from byte 2: expecting printable ASCII or first byte of UTF-8: '\\x20-\\x7f', '\\xC2-\\xF4' at examples/bad-utf8.pl line 10.\n\nJSON error at line 1, byte 5/7: Unexpected character 'b' parsing string starting from byte 2: expecting bytes in range 80-bf: '\\x80-\\xbf' at examples/bad-utf8.pl line 16.\n\nUnexpected end of input\nThe end of the string was encountered before the end of whatever was being parsed was. For\nexample, if a quote is missing from the end of the string, it will give an error like this:\n\nassertvalidjson ('{\"first\":\"Suzuki\",\"second\":\"Murakami\",\"third\":\"Asada}');\n\ngives output\n\nJSON error at line 1: Unexpected end of input parsing string starting from byte 47\n\nNot surrogate pair\nWhile parsing a string, a surrogate pair was encountered. While trying to turn this into\nUTF-8, the second half of the surrogate pair turned out to be an invalid value.\n\nassertvalidjson ('[\"\\uDC00\\uABCD\"]');\n\ngives output\n\nJSON error at line 1: Not surrogate pair parsing unicode escape starting from byte 11\n\nEmpty input\nThis error occurs for an input which is an empty (no length or whitespace only) or an\nundefined value.\n\nassertvalidjson ('');\n\ngives output\n\nJSON error: Empty input parsing initial state\n\nPrior to version 0.49, this error was produced by \"assertvalidjson\" only, but it is now\nalso produced by \"parsejson\".\n\nName is not unique\nThis error occurs when parsing JSON when the user has chosen \"detectcollisions\". For\nexample an input like\n\nmy $p = JSON::Parse->new ();\n$p->detectcollisions (1);\n$p->run ('{\"hocus\":1,\"pocus\":2,\"hocus\":3}');\n\ngives output\n\nJSON error at line 1, byte 23/31: Name is not unique: \"hocus\" parsing object starting from byte 1 at blib/lib/JSON/Parse.pm line 131.\n\nwhere the JSON object has two keys with the same name, \"hocus\". The terminology \"name is not\nunique\" is from the JSON specification.\n\nContradictory values for \"true\" and \"false\"\n\nUser-defined value for JSON false evaluates as true\nThis happens if you set JSON false to map to a true value:\n\n$jp->setfalse (1);\n\nTo switch off this warning, use \"nowarnliterals\".\n\n๐ŸŽฒ This warning was added in version 0.38.\n\nUser-defined value for JSON true evaluates as false\nThis happens if you set JSON true to map to a false value:\n\n$jp->settrue (undef);\n\nTo switch off this warning, use \"nowarnliterals\".\n\n๐ŸŽฒ This warning was added in version 0.38.\n\nUser-defined value overrules copyliterals\nThis warning is given if you set up literals with \"copyliterals\" then you also set up\nyour own true, false, or null values with \"settrue\", \"setfalse\", or \"setnull\".\n\n๐ŸŽฒ This warning was added in version 0.38.\n", "subsections": [] }, "PERFORMANCE": { "content": "On the author's computer, the module's speed of parsing is approximately the same as JSON::XS,\nwith small variations depending on the type of input. For validation, \"validjson\" is faster\nthan any other module known to the author, and up to ten times faster than JSON::XS.\n\nSome special types of input, such as floating point numbers containing an exponential part, like\n\"1e09\", seem to be about two or three times faster to parse with this module than with JSON::XS.\nIn JSON::Parse, parsing of exponentials is done by the system's \"strtod\" function, but JSON::XS\ncontains its own parser for exponentials, so these results may be system-dependent.\n\nAt the moment the main place JSON::XS wins over JSON::Parse is in strings containing escape\ncharacters, where JSON::XS is about 10% faster on the module author's computer and compiler. As\nof version 0.33, despite some progress in improving JSON::Parse, I haven't been able to fully\nwork out the reason behind the better speed.\n\nThere is some benchmarking code in the github repository under the directory \"benchmarks\" for\nthose wishing to test these claims. The script benchmarks/bench\n is an adaptation of the similar script in the JSON::XS distribution. The script\nbenchmarks/pub-bench.pl\n runs the benchmarks and prints them out as POD.\n\nThe following benchmark tests used version 0.5801 of JSON::Parse, version 4.03 of \"JSON::XS\",\nand version 4.25 of \"Cpanel::JSON::XS\" on Perl version v5.32.0 compiled with Clang version\nFreeBSD clang version 10.0.1 on FreeBSD 12.2. The files in the \"benchmarks\" directory of\nJSON::Parse. short.json and long.json are the benchmarks used by \"JSON::XS\".\n\nshort.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 313007.761 | 0.0000319 |\nJP::valid | 838860.800 | 0.0000119 |\nJSON::Parse | 310689.185 | 0.0000322 |\nJSON::XS | 303935.072 | 0.0000329 |\n--------------+------------+------------+\n\nlong.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 5611.860 | 0.0017819 |\nJP::valid | 13586.991 | 0.0007360 |\nJSON::Parse | 4924.048 | 0.0020308 |\nJSON::XS | 6406.452 | 0.0015609 |\n--------------+------------+------------+\n\nwords-array.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 34749.826 | 0.0002878 |\nJP::valid | 270600.258 | 0.0000370 |\nJSON::Parse | 34017.064 | 0.0002940 |\nJSON::XS | 35726.610 | 0.0002799 |\n--------------+------------+------------+\n\nexp.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 46759.242 | 0.0002139 |\nJP::valid | 117817.528 | 0.0000849 |\nJSON::Parse | 46759.242 | 0.0002139 |\nJSON::XS | 19195.899 | 0.0005209 |\n--------------+------------+------------+\n\nliterals.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 33026.016 | 0.0003028 |\nJP::valid | 384798.532 | 0.0000260 |\nJSON::Parse | 40840.351 | 0.0002449 |\nJSON::XS | 33689.189 | 0.0002968 |\n--------------+------------+------------+\n\ncpantesters.json\nRepetitions: 10 x 100 = 1000\n--------------+------------+------------+\nmodule | 1/min | min |\n--------------|------------|------------|\nCpanel | 212.377 | 0.0470860 |\nJP::valid | 1309.043 | 0.0076392 |\nJSON::Parse | 207.491 | 0.0481949 |\nJSON::XS | 226.439 | 0.0441620 |\n--------------+------------+------------+\n", "subsections": [] }, "SEE ALSO": { "content": "RFC 8259\nJSON is specified in RFC 8259 \"The JavaScript Object Notation (JSON) Data Interchange\nFormat\" .\n\njson.org\n is the website for JSON, authored by Douglas Crockford.\n", "subsections": [ { "name": "Other CPAN modules for parsing and producing JSON", "content": "The โญ represents the number of votes this module has received on metacpan, on a logarithmic\nscale. Modules which we recommend are marked with ๐Ÿ‘. Deprecated modules and modules which are\ndefinitely buggy (bug reports/pull requests ignored) and abandoned (no releases for several\nyears) are marked with ๐Ÿ‘Ž and/or ๐Ÿ›. Modules we can't work out are marked with ๐Ÿ˜•.\n\nModules by the same author\n\nJSON::Create\n๐Ÿ‘ JSON::Create is a companion module to JSON::Parse by the same author.\n\nJSON::Repair\nJSON::Repair is an example module which demonstrates using JSON::Parse to apply some\nkinds of heuristics to repair \"relaxed JSON\" or otherwise broken JSON into compliant\nJSON.\n\nJSON::Server\nJSON::Server is a module which offers a JSON-only, UTF-8 only server using \"JSON::Parse\"\nand \"JSON::Create\".\n\nJSON::Tokenize\nJSON::Tokenize is part of the JSON::Parse distribution, a tokenizer which reduces a JSON\nstring to tokens. This makes the JSON::Parse tokenizer available to people who want to\nwrite their own JSON parsers.\n\nJSON::Whitespace\nJSON::Whitespace is for manipulating the \"insignificant whitespace\" part of JSON.\n\nReading and writing JSON\n\nCpanel::JSON::XS\n[โญโญ Author: RURBAN ; Date: \"2020-10-28\"; Version:\n4.25]\n\nThis is a fork of JSON::XS. Please see the module for details about the reasons for the\nfork.\n\nFile::JSON::Slurper\n[โญ Author: NEILB ; Date: \"2020-11-18\"; Version: 1.00]\n\nSlurp a JSON file into a data structure, and the reverse. It relies on \"JSON::MaybeXS\".\n\nGlib::JSON\n[โญ Author: EBASSI ; Date: \"2015-04-19\"; Version:\n0.002]\n\nUses the JSON library from Glib, a library of C functions for the Linux GNOME desktop\nproject, so it is independent of the other CPAN modules. Judging from the fairly sparse\ndocumentation, it seems to be a module where you build the JSON on the fly rather than\nconverting a Perl structure wholesale into JSON.\n\nJSON\n[โญโญ Author: ISHIGAKI ; Date: \"2021-01-24\";\nVersion: 4.03]\n\nThis calls on either JSON::PP or JSON::XS.\n\nJSON::DWIW\n[Author: DOWENS ; Date: \"2010-09-29\"; Version: 0.47]\n\n๐Ÿ‘Ž๐Ÿ› This module \"Does What I Want\", where \"I\" refers to the module's author. Development\nseems to have ceased in 2010, there is a long list of unfixed bugs, and some of the\nmodule's features seem to predate Unicode support in Perl. It is written in XS, and it\nclaims to accept a wide variety of non-JSON formats such as comments, single-quoted\nstrings, trailing commas, etc.\n\nJSON::PP\n[โญโญ Author: ISHIGAKI ; Date: \"2021-01-23\";\nVersion: 4.06]\n\nThis is part of the Perl core, installed when you install Perl. \"PP\" stands for \"Pure\nPerl\", which means it is in Perl-only without the XS (C-based) parsing. This is slower\nbut may be necessary if you cannot install modules requiring a C compiler.\n\nJSON::Slurper\n[โญ Author: SRCHULO ; Date: \"2019-10-30\"; Version:\n0.12]\n\nConvenient file slurping and spurting of data using JSON. Uses \"JSON::PP\" or\n\"Cpanel::JSON::XS\" if available. The basic idea seems to be that it uses context to\nreturn arrays or hashes as required, and read and write files without extra stages of\nopening and closing the file.\n\nJSON::Syck\n[โญโญ Author: TODDR ; Date: \"2020-10-26\"; Version:\n1.34]\n\n๐Ÿ‘Ž๐Ÿ› Takes advantage of a similarity between YAML (yet another markup language) and JSON\nto provide a JSON parser/producer using YAML::Syck.\n\nWe have never tried this module, but it seems to be semi-deprecated (the ABSTRACT says\n\"consider using JSON::XS instead!\") and there are a lot of bug reports\n about things like failing to process equals\nsigns. However, the maintainer is fixing some of the bugs and making new releases, so\nwe're not really sure.\n\nJSON::Tiny\n[โญโญ Author: DAVIDO ; Date: \"2017-11-12\"; Version:\n0.58]\n\nThis is a fork of \"Mojo::JSON\".\n\nJSON::XS\n[โญโญโญ Author: MLEHMANN ; Date: \"2020-10-27\";\nVersion: 4.03]\n\nThis is an all-purpose JSON module in XS, which means it requires a C compiler to\ninstall.\n\nJSON::YAJL\n[โญ Author: LBROCARD ; Date: \"2011-08-05\"; Version:\n0.10]\n\n๐Ÿ‘Ž๐Ÿ› Wraps a C library called yajl. The module has been abandoned since ten years ago. Bug\nreports include serious errors, and pull requests have been ignored.\n\nMojo::JSON\n[โญโญโญ Author: SRI ; Date: \"2021-01-17\"; Version: 8.71]\n\nPart of the Mojolicious standalone web framework, \"pure Perl\" JSON reader/writer. As of\nversion 8.70 of Mojolicious, this actually depends on \"JSON::PP\" but will load\n\"Cpanel::JSON::XS\" if it is available.\n\nCombination modules\nThese modules rely on more than one back-end module to process JSON for you.\n\nJSON::Any\n[โญ Author: ETHER ; Date: \"2015-06-10\"; Version: 1.39]\n\n๐Ÿ‘Ž This now-deprecated module combines \"JSON::DWIW\", \"JSON::XS\" versions one and two, and\n\"JSON::Syck\".\n\nJSON::MaybeXS\n[โญโญ Author: ETHER ; Date: \"2020-11-13\"; Version:\n1.004003]\n\nA module which combines \"Cpanel::JSON::XS\", \"JSON::XS\", and \"JSON::PP\". The original\n\"JSON\" combines \"JSON::XS\" and \"JSON::PP\", but this prioritizes \"Cpanel::JSON::XS\" over\n\"JSON::XS\".\n\nJSON::XS::VersionOneAndTwo\n[Author: LBROCARD ; Date: \"2008-02-13\"; Version:\n0.31]\n\n๐Ÿ‘Ž A \"combination module\" which supports two different interfaces of \"JSON::XS\". However,\nJSON::XS is now onto version 4.\n\nMojo::JSON::MaybeXS\n[โญ Author: DBOOK ; Date: \"2019-08-07\"; Version:\n1.002]\n\n๐Ÿ‘Ž This pulls in \"JSON::MaybeXS\" instead of \"Mojo::JSON\" for Mojolicious users. It seems\nto have been rendered obsolete by modern versions of Mojolicious due to changes to make\nthat depend on \"Cpanel::JSON::XS\" if available.\n\nTest-related modules\n\nTest2::Tools::JSON\n[Author: AKIYM ; Date: \"2019-08-07\"; Version: 0.05]\n\nTest::Deep::JSON\n[โญ Author: MOTEMEN ; Date: \"2018-04-24\"; Version:\n0.05]\n\nCompare JSON with Test::Deep. As of version 0.05, it relies on \"JSON::MaybeXS\".\n\nTest::JSON\n[โญ Author: OVID ; Date: \"2009-08-09\"; Version: 0.11]\n\n๐Ÿ‘Ž This offers a way to compare two different JSON strings to see if they refer to the\nsame object. The most recent version, 0.11, was released in 2009, and it relies on the\ndeprecated \"JSON::Any\", which makes it essentially abandoned.\n\nTest::JSON::Entails\n[Author: VOJ ; Date: \"2012-09-14\"; Version: 0.2]\n\n๐Ÿ‘Ž Test whether one JSON or Perl structure entails/subsumes another. The most recent\nversion is from 2012, and it relies on \"JSON::Any\", so it is probably abandoned. Also,\noddly but not uniquely for CPAN modules with the name JSON in the title, it seems to not\nactually have that much to do with JSON, which is a data serialisation format, but\nactually be testing Perl hashes and arrays.\n\nTest::JSON::More\n[Author: BAYASHI ; Date: \"2016-04-28\"; Version:\n0.02]\n\nJSON Test Utility. As of version 0.02, it relies on \"JSON\" but it is able to use\n\"JSON::XS\" instead, and so probably \"Cpanel::JSON::XS\" would be OK too. According to the\ndocumentation, it can test JSON for validity and compare JSON strings with keys in a\ndifferent order, and presumably with different whitespace.\n\nType-related modules\nThese untangle numbers, strings, and booleans into JSON types.\n\nJSON::TypeInference\n[Author: AEREAL ; Date: \"2015-10-26\"; Version:\n\"v1.0.2\"]\n\n๐Ÿ˜• Virtually undocumented, it's not clear what this does.\n\nJSON::Types\n[โญ Author: TYPESTER ; Date: \"2012-10-17\"; Version:\n0.05]\n\nChange the type of a Perl variable so that it comes out as a number, a string, or a\nboolean in the output JSON.\n\nJSON::Types::Flexible\n[Author: PINE ; Date: \"2017-04-01\"; Version: 0.03]\n\nThe module is barely documented, but from looking at the test file\n, this seems to enable you to change the output type of a number or a string so\nthat you can, for example, make the number 1 come out as either a number, 1, a string\n\"1\", or a boolean, \"true\", in the output JSON.\n\nJSON::Typist\n[โญ Author: RJBS ; Date: \"2019-12-26\"; Version: 0.006]\n\n\"Replace mushy strings and numbers with rigidly typed replacements\"\n\nSince Perl muddles strings and numbers, this enables you to work out whether your input\nJSON was \"123\" (a string) or 123 (a number).\n\nSpecial-purpose modules\n\nApp::JSON::to\n[โญ Author: DOLMEN ; Date: \"2015-03-04\"; Version:\n1.000]\n\nConvert JSON data to other formats. It reads your JSON file or input and converts it\ninto either YAML or Perl native format using Data::Dumper.\n\nboolean\n[โญโญ Author: INGY ; Date: \"2016-07-08\"; Version: 0.46]\n\n๐Ÿ‘ This module offers \"true\" and \"false\" literals in Perl, so you just have\n\nuse boolean;\nmy $something = true;\n\nThis is very useful for dealing with JSON.\n\nConfig::JSON\n[Author: RIZEN ; Date: \"2014-12-25\"; Version: 1.5202]\n\nConfiguration files in JSON, with hash comments also allowed.\n\nDevel::JSON\n[โญ Author: DOLMEN ; Date: \"2017-09-03\"; Version:\n1.001]\n\nFor one-liners.\n\nIf you use this module from the command-line, the last value of your one-liner (-e)\ncode will be serialized as JSON data.\n\nInline::JSON\n[Author: KILNA ; Date: \"2012-07-27\"; Version:\n\"v1.0.4\"]\n\n\"Embed JSON data structures directly into your Perl code\". Relies on \"JSON\".\n\nJSON::Builder\n[Author: KNI ; Date: \"2015-04-16\"; Version: 0.04]\n\nCreate JSON under memory limitations.\n\nJSON::Color\n[โญ Author: PERLANCAR ; Date: \"2020-06-09\";\nVersion: 0.130]\n\n๐ŸŒˆ This module generates JSON colorized with ANSI escape sequences.\n\nJSONFile\n[โญ Author: GETTY ; Date: \"2014-09-11\"; Version:\n0.004]\n\nJSON::MultiValueOrdered\n[Author: TOBYINK ; Date: \"2020-01-27\"; Version:\n0.006]\n\n\"JSON::MultiValueOrdered\" is a special-purpose module for parsing JSON objects which\nhave key collisions (something like \"{\"a\":1,\"a\":2}\") within objects.\n\n(JSON::Parse's handling of key collisions is discussed in \"Key collisions\" in this\ndocument.)\n\nJSON::String\n[Author: BRUMMETT ; Date: \"2015-02-04\"; Version:\n\"v0.2.0\"]\n\nAutomatically change a JSON string when a data structure changes using tied scalars.\n\nPatch, path, pointer, schema, and transform modules\n\nJSON::Assert\n[Author: SGREEN ; Date: \"2017-07-07\"; Version: 0.08]\n\n\"Asserts JSONPaths into a JSON data structure for correct values/matches\"\n\nJSON::GRDDL\nJSON::Hyper\nJSON::MergePatch\n[โญ Author: SOJIRO ; Date: \"2016-02-24\"; Version:\n0.04]\n\nJSON::Patch\n[Author: MIXAS ; Date: \"2018-10-25\"; Version: 0.04]\n\n๐Ÿ˜• We don't know what this does, or how it relates to JSON. The example in the synopsis\nsection of the document doesn't show any JSON, it shows an example of altering nested\nhashes in Perl.\n\nJSON::Path\n[โญ Author: POPEFELIX ; Date: \"2018-05-05\";\nVersion: 0.420]\n\nSearch nested hashref/arrayref structures using JSONPath.\n\nJSON::Pointer\n[โญ Author: ZIGOROU ; Date: \"2015-08-13\"; Version:\n0.07]\n\nExtract parts of a JSON string.\n\nJSON::Schema::ToJSON\n\"Generate example JSON structures from JSON Schema definitions\"\n\nJSON::T\n[โญ Author: TOBYINK ; Date: \"2014-09-28\"; Version:\n0.104]\n\nTransform JSON using JsonT\n\nJSON::Transform\n[โญ Author: ETJ ; Date: \"2020-01-01\"; Version: 0.03]\n\nJSON::Validator\n[โญโญ Author: JHTHORSEN ; Date: \"2021-01-24\";\nVersion: 4.12]\n\n\"Validate data against a JSON schema\" - you can decide what the JSON is supposed to\ncontain.\n\nJSON extensions\nThese modules extend JSON with comments and other things.\n\nJSON::Diffable\n[โญ Author: PHAYLON ; Date: \"2014-12-10\"; Version:\n0.000002]\n\n\"A relaxed and easy diffable JSON variant\"\n\nJSON::Relaxed\n[Author: MIKO ; Date: \"2016-04-30\"; Version: 0.05]\n\n\"An extension of JSON that allows for better human-readability\".\n\nJSONY\n[โญ Author: INGY ; Date: \"2020-04-27\"; Version:\n\"v0.1.21\"]\n\n\"Relaxed JSON with a little bit of YAML\"\n\nWeb interactions via JSON\n\nCrypt::JWT\n[โญโญ Author: MIK ; Date: \"2021-01-10\"; Version: 0.031]\n\nModule covers JSON Web Tokens, JSON Web Signature, and JSON Web Encryption.\n\nJSON::API\n[โญ Author: GFRANKS ; Date: \"2019-07-01\"; Version:\n\"v1.1.1\"]\n\nCombines LWP::UserAgent and JSON to make a unified module to communicate with a web\nserver via JSON.\n\nLWP::JSON::Tiny\n[โญ Author: SKINGTON ; Date: \"2018-05-11\"; Version:\n0.014]\n\nWWW::JSON\n[โญ Author: ANTIPASTA ; Date: \"2015-05-27\";\nVersion: 1.02]\n\n\"Make working with JSON Web API's as painless as possible\"\n\nExtension modules\nThese modules extend the existing modules with some extra bits.\n\nJSON::XS::Sugar\n[Author: MAXMIND ; Date: \"2015-04-01\"; Version:\n1.01]\n\nProvides booleans and number/string forcing for \"JSON::XS\".\n\nSilki::JSON\n[โญ Author: DROLSKY ; Date: \"2011-09-19\"; Version:\n0.29]\n\nSwitches on formatting and strict utf8 in a \"JSON::XS\" object.\n\nDemonstration modules\nThese modules provide a JSON parser as a demonstration of another technology.\n\nJSON::Decode::Marpa\n[Author: PERLANCAR ; Date: \"2014-08-27\"; Version:\n0.02]\n\nJSON::Decode::Regexp\n[Author: PERLANCAR ; Date: \"2018-03-25\"; Version:\n0.101]\n\n๐Ÿ›๐ŸฆŸ๐Ÿฆ‹๐Ÿž JSON parser as a single Perl Regex, originally by Randal Schwartz. This may be\ningenious, but it's not remotely a useful JSON parser. For example, looking at the\nstring part, it provides no Unicode validation, no support for Unicode escapes\n\nand it allows invalid escapes such as \"\\xFF\"\n.\n\nMarpaX::Demo::JSONParser\n[Author: RSAVAGE ; Date: \"2019-06-18\"; Version:\n1.08]\n\nPegex::JSON\n[Author: INGY ; Date: \"2020-01-22\"; Version: 0.31]\n\n๐Ÿ› Based on Pegex. See our bug report\n.\n\nOther modules\nModules which are parts of bigger distributions have not been included here except by\naccident.\n\nApp::JSON::Tools\n[Author: KABLAMO ; Date: \"2016-08-05\"; Version:\n0.01]\n\nUndocumented command-line tools for JSON.\n\nApp::JSONPretty\n[โญ Author: MSTROUT ; Date: \"2011-02-02\"; Version:\n1]\n\n๐Ÿ‘Ž๐Ÿ› JSON prettification script. For whatever reason the script encapsulates the entirety\nof an old version of the \"JSON\" module dating from before \"JSON::PP\" was included in the\nPerl core.\n\nIf you need this kind of script, there is something called jsonxs which comes with\n\"JSON::XS\", or equivalently cpaneljsonxs in the forked module \"Cpanel::JSON::XS\".\n\nARGV::JSON\n[โญ Author: MOTEMEN ; Date: \"2013-12-18\"; Version:\n0.01]\n\nJasonify\n[Author: BOBK ; Date: \"2020-03-04\"; Version:\n\"v0.20.064\"]\n\nJS::JSON\n[Author: INGY ; Date: \"2008-08-30\"; Version: 0.02]\n\n๐Ÿ‘Ž This is JavaScript code which was uploaded to CPAN. The original JavaScript is now\nobsolete since the thing it codes is included in all modern web browsers.\n\nJSON::Eval\n[Author: TOBYINK ; Date: \"2019-10-27\"; Version:\n0.002]\n\nEval Perl code found in JSON. This module enables one to encode and decode Perl scalar\nreferences and code references to JSON.\n\nJSON::ize\n[โญ Author: MAJENSEN ; Date: \"2019-07-13\"; Version:\n0.202]\n\nSomething about one-liners.\n\nJSON::JSend\n[Author: HOEKIT ; Date: \"2016-04-23\"; Version: 0.02]\n\nJSON::Lines\n[โญ Author: LNATION ; Date: \"2020-10-25\"; Version:\n0.03]\n\n\"JSON Lines is a convenient format for storing structured data that may be processed one\nrecord at a time.\"\n\nJSON::Meth\n[โญ Author: ZOFFIX ; Date: \"2015-11-28\"; Version:\n1.001007]\n\n๐Ÿ˜• Claims to be \"no nonsense JSON encoding/decoding as method calls on data\". From the\ndocumentation:\n\nDon't make me think and give me what I want! This module automatically figures out\nwhether you want to encode a Perl data structure to JSON or decode a JSON string to\na Perl data structure.\n\nJSON::ON\n[Author: EWILHELM ; Date: \"2013-06-26\"; Version:\n\"v0.0.3\"]\n\nJavaScript object notation object notator.\n\nJSON::SL\n[โญ Author: MNUNBERG ; Date: \"2017-11-10\"; Version:\n\"v1.0.7\"]\n\nJSON::Streaming::Reader\n[โญ Author: MART ; Date: \"2012-11-24\"; Version: 0.06]\n\nJSON::Streaming::Writer\n[Author: MART ; Date: \"2012-11-24\"; Version: 0.03]\n\nJSON::Util\n[Author: JKUTEJ ; Date: \"2015-09-03\"; Version: 0.06]\n\nRelies on JSON::MaybeXS and the author's other module IO::Any, so that you can put\neither a file name or a JSON string as the argument and it tries to work out which one\nyou have given it. That is ingenious, but it seems that if you are a programmer who\ncannot distinguish whether your input string is a file name or JSON, you have a very\nserious problem.\n\nJSON::XS::ByteString\n[โญ Author: CINDY ; Date: \"2020-04-18\"; Version:\n1.004]\n\n๐Ÿ˜• The README claims\nit is a \"thin wrapper around JSON::XS\", but it contains a complete implementation of\nJSON , which\nseems to have partly been copy-pasted from the JSON::XS source code, but internally it\ndoesn't make any reference to JSON::XS. The licence and copyright statement don't\nmention JSON::XS's original author at all so we're not sure if this is a fork, a\nwrapper, or a reimplementation.\n\nWe haven't tried downloading this or installing it, but according to the documentation,\nthis module encodes numbers with quotes around them, so \"{this => 2}\" turns into\n\"{\"this\":\"2\"}\".\n\nJSONminify\n[Author: RCOSCALI ; Date: \"2021-01-24\"; Version:\n1.1]\n\nText::JSON::Nibble\n[Author: DAEMON ; Date: \"2017-05-02\"; Version: 1.01]\n\nNibble complete JSON objects from buffers.\n\nThis seems to be for extracting JSON from the midst of noise.\n" } ] }, "SCRIPT": { "content": "A script \"validjson\" is supplied with the module. This runs \"assertvalidjson\" on its inputs,\nso run it like this.\n\nvalidjson *.json\n\nThe default behaviour is to just do nothing if the input is valid. For invalid input it prints\nwhat the problem is:\n\nvalidjson ids.go\nids.go: JSON error at line 1, byte 1/7588: Unexpected character '/' parsing initial state: expecting whitespace: '\\n', '\\r', '\\t', ' ' or start of string: '\"' or digit: '0-9' or minus: '-' or start of an array or object: '{', '[' or start of literal: 't', 'f', 'n'.\n\nIf you need confirmation, use its --verbose option:\n\nvalidjson -v *.json\n\natoms.json is valid JSON.\nids.json is valid JSON.\nkanjidic.json is valid JSON.\nlinedecomps.json is valid JSON.\nradkfile-radicals.json is valid JSON.\n", "subsections": [] }, "DEPENDENCIES": { "content": "Carp\n", "subsections": [] }, "EXPORTS": { "content": "The module exports nothing by default. Functions \"parsejson\", \"parsejsonsafe\", \"readjson\",\n\"validjson\" and \"assertvalidjson\", as well as the old function names \"validatejson\",\n\"jsonfiletoperl\", and \"jsontoperl\", can be exported on request.\n\nAll of the functions can be exported using the tag ':all':\n\nuse JSON::Parse ':all';\n", "subsections": [] }, "TESTING": { "content": "", "subsections": [ { "name": "Internal testing code", "content": "The module incorporates extensive testing related to the production of error messages and\nvalidation of input. Some of the testing code is supplied with the module in the /t/\nsubdirectory of the distribution.\n\nMore extensive testing code is in the git repository. This is not supplied in the CPAN\ndistribution. A script, randomjson.pl\n, generates a set number of bytes of random JSON and checks that the module's bytewise\nvalidation of input is correct. It does this by taking a valid fragment, then adding each\npossible byte from 0 to 255 to see whether the module correctly identifies it as valid or\ninvalid at that point, then randomly picking one of the valid bytes and adding it to the\nfragment and continuing the process until a complete valid JSON input is formed. The module has\nundergone about a billion repetitions of this test.\n\nThis setup relies on a C file, json-random-test.c\n, which isn't in the CPAN distribution, and it also requires Json3.xs\n to be edited to make the macro \"TESTRANDOM\" true (uncomment line 7 of the file). The testing\ncode uses C setjmp/longjmp, so it's not guaranteed to work on all operating systems and is\ncommented out for CPAN releases.\n\nA pure C version called random-test.c\n also exists. This applies exactly the same tests, and requires no Perl at all.\n\nIf you're interested in testing your own JSON parser, the outputs generated by randomjson.pl\n are quite a good place to start. The default is to produce UTF-8 output, which looks\npretty horrible since it tends to produce long strings of UTF-8 garbage. (This is because it\nchooses randomly from 256 bytes and the end-of-string marker \"\"\" has only a 1/256 chance of\nbeing chosen, so the strings tend to get long and messy). You can mess with the internals of\nJSON::Parse by setting MAXBYTE in json-common.c to 0x80, recompiling (you can ignore the\ncompiler warnings), and running randomjson.pl again to get just ASCII random JSON things. This\nbreaks the UTF-8 functionality of JSON::Parse, so please don't install that version.\n\nJSON Parsing Test Suite\nJSON::Parse version 0.58 passes most of the JSON Parsing Test Suite, with the exception that\nJSON::Parse rejects various erroneous UTF-8 inputs, for example JSON::Parse will throw an error\nfor non-character code points like Unicode U+FFFF and U+10FFFF. This parser only accepts valid\nUTF-8 as input. See \"UTF-8 only\".\n\nIn our opinion it would be a disservice to users of this module to allow bytes containing\nuseless fragments such as incomplete parts of surrogate pairs, or invalid characters, just\nbecause the JSON specification doesn't actually explicitly demand rejecting these kinds of\ngarbage inputs. Please see the function \"dafttest\" in the file xt/JPXT.pm for exactly which of\nthese elements of the test suite we do not comply with. We note that this comment from Douglas\nCrockford, the inventor of JSON, JSON parser\n, dated 2005,\nagrees with our opinion on this point.\n\nJSON::Parse version 0.58 also introduced \"getmaxdepth\" and \"setmaxdepth\" to prevent the\nstack overflow errors caused by some very deeply nested inputs such as those of the JSON Parsing\nTest Suite.\n" } ] }, "ACKNOWLEDGEMENTS": { "content": "Toby Inkster (TOBYINK) suggested some of the new function names which replaced the \"OLD\nINTERFACE\" names. Nicolas Immelman and Shlomi Fish (SHLOMIF) reported memory leaks which were\nfixed in 0.32 and 0.40. Github user kolmogorov42 reported a bug which led to 0.42. Github user\nSteveGlassman found an error in string copying for long strings, fixed in 0.57. Lars Dษชแด‡แด„แด‹แดแดก\n(DAXIM) pointed out problems with the JSON Parsing Test Suite which led to the addition of stack\nprotection and \"setmaxdepth\" and \"getmaxdepth\" in 0.58.\n", "subsections": [] }, "AUTHOR": { "content": "Ben Bullock, \n\nCOPYRIGHT & LICENCE\nThis package and associated files are copyright (C) 2013-2021 Ben Bullock.\n\nYou can use, copy, modify and redistribute this package and associated files under the Perl\nArtistic Licence or the GNU General Public Licence.\n", "subsections": [] } } } }