Error message for parsing errors could be improved

[multiplemonomials]

Hi, I'm submitting this from the Mbed CE project as you said you were interested in feedback on how to improve the error messages generated by this library.

For example, suppose I have the following json5 file test.json5 (filled with content grabbed from a random file in Mbed CE):

{
    "MCU_LPC17XX": {
        "inherits": [
            "LPCTarget"
        ],
        "public": false,
        "core": "Cortex-M3",
        "extra_labels_add": [
            "NXP",
            "LPC17XX",
            "NXP_EMAC"
        ],
        "supported_toolchains": [
            "GCC_ARM"
        ],
        "macros_add": [
            "MBED_SPLIT_HEAP"
        ],
        "device_has": [
            "RTC",
            "USTICKER",
            "ANALOGIN",
            "ANALOGOUT",
            "CAN",
            "DEBUG_AWARENESS",
            "EMAC",
            "I2C",
            "I2CSLAVE",
            "INTERRUPTIN",
            "PORTIN",
            "PORTINOUT",
            "PORTOUT",
            "PWMOUT",
            "SERIAL",
            "SERIAL_FC",
            "SLEEP",
            "SPI",
            "SPISLAVE",
            "FLASH",
            "MPU",
            "USBDEVICE",
            "WATCHDOG",
            "RESET_REASON"
        ],
		
        a // <-- This is an intentional error
		
        "release_versions": [
            "5"
        ],
        "bootloader_supported": true,
        "config": {
            "us-ticker-timer": {
                "help": "Chooses which timer (0-3) to use for us_ticker.c",
                "value": 3
            },
            "lpc17xx-xtal-freq": {
                help: "Frequency of external crystal or clock source connected to the XTAL pins. Frequency in MHz must be an integer factor of 24 (e.g. 12MHz, 6MHz, and 1MHz are OK but 5MHz is not).",
                value: 12000000
            },
            "lpc17xx-core-clk-120mhz": {
                help: "If true, the core will be clocked at 120MHz. Otherwise, it will be clocked at 96MHz. This is only officially supported with LPC1759/69 chips, but can work with others as an overclock.",
                value: false
            }
        },
        "overrides": {
            "network-default-interface-type": "ETHERNET",
        },
        "supported_c_libs": {
            "arm": [
                "std", "small"
            ],
            "gcc_arm": [
                "std", "small"
            ]
        },
        "supported_application_profiles": [
            "full", "bare-metal"
        ],
        "is_mcu_family_target": true
    }
}

As you may have noticed, this file has an extra "a" randomly in the middle. Now suppose I try to parse it:

python -c "import pyjson5; pyjson5.decode_io(open('test.json5', 'r'))"

I get the following exception back:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import pyjson5; pyjson5.decode_io(open('test.json5', 'r'))
                    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "src/_exports.pyx", line 286, in pyjson5.pyjson5.decode_io
  File "src/_decoder.pyx", line 913, in pyjson5.pyjson5._decode_callback
  File "src/_decoder.pyx", line 815, in pyjson5.pyjson5._decode_all
pyjson5.pyjson5.Json5IllegalCharacter: ("Expected b'colon' near 1013, found U+0022", {'MCU_LPC17XX': {'inherits': ['LPCTarget'], 'public': False, 'core': 'Cortex-M3', 'extra_labels_add': ['NXP', 'LPC17XX', 'NXP_EMAC'], 'supported_toolchains': ['GCC_ARM'], 'macros_add': ['MBED_SPLIT_HEAP'], 'device_has': ['RTC', 'USTICKER', 'ANALOGIN', 'ANALOGOUT', 'CAN', 'DEBUG_AWARENESS', 'EMAC', 'I2C', 'I2CSLAVE', 'INTERRUPTIN', 'PORTIN', 'PORTINOUT', 'PORTOUT', 'PWMOUT', 'SERIAL', 'SERIAL_FC', 'SLEEP', 'SPI', 'SPISLAVE', 'FLASH', 'MPU', 'USBDEVICE', 'WATCHDOG', 'RESET_REASON']}}, '"')

There are three major issues with this error message that mean it's hard for users to parse when determining what's wrong with their JSON file.

1. It says "near 1013", which I understand to mean that it's near the 1013th byte in the input file. However, there aren't convenient ways for users to take that and find the line where the error occurred.
2. It says "found U+0022", so I have to get out an ASCII table to determine that this is a " character. Ideally this would be converted as part of the error message.
3. It prints the entire minified JSON file, up to the point the error occurred, to the console. Some of our JSON files are 10,000 lines ling, so this is a great way to absolutely explode the user's terminal if they type something wrong near the end of the file.

I'd love for the error to instead look like:

pyjson5.pyjson5.Json5IllegalCharacter: "Line 48: Expected colon, found ' " '"

That would make it way easier to track down where the problem is when editing the file.

[Kijewski]

Thank you for providing an example!

Yeah, is quite hard to read. I think I did it this way, because I could not figure out how to properly subclass an Exception. I will give it a try, if I can make the message more readable!