A new and improved lldb_bson.py

[vector-of-bool]

This PR rewrites the lldb_bson.py Python module for use in the LLDB debugger. The prior version supported simple inspection of BSON data as its equivalent JSON encoding, but this was often cumbersome and difficult to read.

This new module allows traversing and watching document elements (with arbitrary nesting), as well as introspection on element values. In VSCode, this also enables jump-to-memory on individual elements.

The new lldb_bson.py is large, and shares very little with the original (it also no longer requires the Python driver to be installed, and only uses the standard library). I've done my best to annotate and comment it as well as possible, for future non-Pythonic maintainers.

Viewing document elements in the VSCode variables tab

Viewing document content from the LLDB CLI

Introspection of a BSON binary and a BSON datetime

Decoding a Decimal128 value

Adding a watch expression in VSCode with CodeLLDB

[vector-of-bool]

Added review requests, but mostly curious to see if this "(only) works on my machine" and what may need to be tweaked to work in different environments/LLDBs.

[kkloberdanz]

Long time GDB user, but I haven't used lldb before. How does one use this script with lldb?

[eramongodb]

@kkloberdanz I got it up and running using the VS Code Debugging and CodeLLDB User Manual as reference.

@vector-of-bool At the moment there does not seem to be a way to distinguish int32 fields from int64 fields by their type:

Can we display integral fields in a manner similar to what is done for the datetime field such that this distinction can be made, e.g. something like the following?

[content]: document (4 elements)
 ['int32']: int32: 100
 ['int64']: int64: 100
 ['double']: 100.0
 ['date']: datetime: "1969-12-31T18:00:00.100000"

[kkloberdanz]

Thanks! Would anyone know off hand if there is a way to use this from the lldb CLI?

[vector-of-bool]

I've tweaked the summary strings to show the type info in a similar manner to what is displayed on the Mongo CLI (e.g. NumberInt, NumberLong)

@kkloberdanz you should be able to import it with: command script import lldb_bson.py

[kevinAlbs]

Fantastic. This seems very helpful for inspecting BSON while debugging.

I did not review the implementation but checked the output by debugging the /bson/iter/init_from_data_at_offset test, which includes a BSON document with all types.

Here is the launch.json I used:

{
    "name": "test-libmongoc",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/cmake-build/src/libmongoc/test-libmongoc",
    "args": [
        "--no-fork",
        "--match",
        "/bson/iter/init_from_data_at_offset"
    ],
    "stopAtEntry": false,
    "cwd": "${workspaceFolder}",
    "setupCommands": [
        {
            "text": "command script import ${workspaceFolder}/lldb_bson.py"
        }
    ],
    "environment": [],
    "externalConsole": false,
    "MIMode": "lldb"
}

LGTM with documentation updated.

[kevinAlbs]

Update the LLDB documentation, since it may no longer be correct.