feat: user defined custom list types

ashenBlade · ashenBlade · commit b387e172d886 · 2025-03-08T20:41:36.000+03:00
diff --git a/README.md b/README.md
@@ -23,8 +23,7 @@ variables.
 
 ### Show contents of containers
 
-Extension support showing contents of containers: `List` (including subtypes)
-and `Bitmapset`.
+Extension support showing contents of containers: `List` (including Oid, TransactionId, int and custom user pointer types) and `Bitmapset`.
 
 ![List * expansion](resources/list.gif)
 
@@ -35,13 +34,11 @@ and `Bitmapset`.
 
 ![Bitmapset expansion](resources/bitmapset.gif)
 
-Also, there is support for C-arrays (like `PlannerInfo->simple_rel_array`) - 
-array is displayed using it's length.
+Also, there is support for C-arrays (like `PlannerInfo->simple_rel_array`) - array is displayed using it's length.
 
 ![Planner expansion](resources/planner.gif)
 
-Currently, there are 36 registered array members, but you can add your own
-using [pgsql_hacker_helper.json](#pgsql_hacker_helperjson) configuration file.
+Currently, there are 36 registered array members, but you can add your own using [pgsql_hacker_helper.json](#pgsql_hacker_helperjson) configuration file.
 
 ### Show where Bitmapset references
 
@@ -134,7 +131,7 @@ Example json:
 
 ```json
 {
-    "version": 3,
+    "version": 4,
     "specialMembers": {
         "array": [
             {
@@ -160,13 +157,30 @@ Example json:
             "type": "PlannerInfo *"
         }
     ],
-    "typedefs": "my.typedefs.file"
+    "typedefs": "my.typedefs.file",
+    "customListTypes": [
+        {
+            "type": "char *",
+            "member": ["UserData", "knownNames"]
+        },
+        {
+            "type": "struct FileChunks *",
+            "variable": ["ProcessFileChunks", "chunks"]
+        }
+    ]
 }
 ```
 
-In example 3 array special members - arrays will be shown with specified length,
-not just pointers to arrays start.
-Also, `PlannerRef` - typedef for `PlannerInfo *`.
+Features:
+
+- 3 *array* special members (pointer field used as array) - `"typeName"->"memberName"` will be shown with length `"typeName"->"lengthExpression"`, not as simple pointers.
+
+- `PlannerRef` - custom user typedef for `PlannerInfo *`.
+
+- `UserData->knownNames` is a `List *` that contains pointer elements not `Node *`, but `char *` (`List` of strings).
+Variable `chunks` in function `ProcessFileChunks` is a `List` that contains pointer elements not `Node *`, but `struct FileChunks *`.
+
+- User provided custom `typedefs` list (used by formatter).
 
 For more info check [configuration file documentation](./docs/config_file.md).
 
@@ -218,30 +232,34 @@ Minimal supported version of:
 > It is tested manually and not all use cases might be covered. If you found
 > bug specific to some version please [create issue](https://github.com/ashenBlade/postgres-dev-helper/issues).
 
-Also, extension will target latest VS Code version and try to use the full
-functionality of new versions. So, use latest VS Code versions to get new
-features earlier.
+Also, extension will target latest VS Code version and try to use the full functionality of new versions.
+So, use latest VS Code versions to get new features earlier.
 
 For using formatter minimal supported version Postgres is `10`.
 
+> WARN: I *do not stand* that all extension features will work as expected on all versions
+
 ## Known Issues
 
 Known issues:
 
-- If in pointer variable was garbage, extension will not detect it and expand
-  this variable (may be garbage).
+- If in pointer variable was garbage, extension will not detect it and expand this variable (may be garbage).
+  Usually, this will not lead to fatal errors, just note this.
 - To get NodeTags extension reads all available NodeTag files (from settings),
   but these files may be not created (./configure or make not run). I assume by
-  time of debugging start files will be created, so extension catch them and
-  process.
-- Tested only with [ms-vscode.cpptools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
-  extension. Currently, no support for other DAP adapters (i.e. Code LLDB)
+  time of debugging start files will be created, so extension catch them and process.
+- Works only with [ms-vscode.cpptools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
+  extension. Currently, no support for other DAP adapters (i.e. Code LLDB).
+  Reason: strongly tied to output format of this extension (not only expression evaluation, but stack trace format i.e.)
 - Sometimes formatting can misbehave. This is due to `pg_bsd_indent` internal
   logic. If formatting is not applied try run command again. If file after
   formatting is a mess this can be due to errors in logic.
 - Some operations require data to be allocated (usually, for function invocation).
   For this, `palloc` and `pfree` are used. So if you are debugging memory subsystem
   you may want to disable extension, because it may affect debugging process.
+- Some operations require for some work to be done with system catalog.
+  For example, to get function name using it's Oid. So, system catalog (system cache)
+  can be modified during extension work.
 
 ## Release Notes
 
@@ -386,5 +404,4 @@ Call `pprint(Node *)` on selected variable in `Variables` view.
 
 ## Contributing
 
-Go to [Issues](https://github.com/ashenBlade/postgres-dev-helper/issues) if you
-want to say something: bugs, features, etc...
+Go to [Issues](https://github.com/ashenBlade/postgres-dev-helper/issues) if you want to say something: bugs, features, etc...
diff --git a/dev/release-checklist.md b/dev/release-checklist.md
diff --git a/docs/config_file.md b/docs/config_file.md
@@ -5,10 +5,10 @@ It stored inside `.vscode` folder.
 
 ## Layout
 
-There are 2 versions of config file layout.
-Version is specified using top level `"version"` field.
+There are 4 versions of config file layout.
+Version is specified using `"version"` field.
 
-Current version - 3.
+Current version - 4.
 
 > This file belongs to latest schema version.
 
@@ -156,11 +156,58 @@ Read typedefs file `custom.typedefs.list` in current src path.
 }
 ```
 
-Read global typedefs file stored in temporary directory
+Read global typedefs file stored in temporary directory.
 
 ```json
 {
     "version": 3,
     "typedefs": "/tmp/cached.custom.typedefs.list"
 }
 ```
+
+### Custom `List` types
+
+Usually, `List *` contains nodes (inherits from `Node`), but actually it can contain any pointer.
+Extension treats all `List` as they contain `Node` variables, but you can say that this variable or struct member contains custom type (pointer to it).
+
+This information stored in `customListTypes` member. This is array of objects:
+
+```json
+{
+    "version": 4,
+    "customListTypes": [
+        {
+            "type": "MyCustomType *",
+            "member": ["ParentStruct", "parent_member"]
+        },
+        {
+            "type": "MyCustomType *",
+            "variable": ["ParentFunction", "variable_name"]
+        }
+    ]
+}
+```
+
+Each object contain:
+
+- `type` - fully-qualified type name (that is `struct` or `pointer` should be included) to which pointer will be casted.
+- `member` - pair of struct name and member of this struct. Definition looks like this:
+
+    ```c
+    typedef struct ParentStruct
+    {
+        List *parent_member;
+    } ParentStruct;
+    ```
+
+- `variable` - pair of function name and variable inside it. Definition looks like this:
+
+    ```c
+    void
+    ParentFunction()
+    {
+        List *variable_name;
+    }
+    ```
+
+With this 2 strategies extension detects `List`s with custom types.
diff --git a/docs/pg_variables.md b/docs/pg_variables.md
@@ -92,6 +92,8 @@ Also, there are some Special Node types:
   - `IntList`
   - `OidList`
   - `XidList`
+  
+  Additionally, you can specify custom pointer type in `List`. See [custom `List` types](./config_file.md#custom-list-types) section in configuration file documentation.
 
 - Bitmapset - show elements of set in pseudo-member `$elements$`
 
@@ -200,9 +202,8 @@ this you should update config file like this:
 }
 ```
 
-There are about 36 supported asm. For example, `simple_rel_array` for `PlannerInfo`
+There are about 36 supported ASM. For example, `simple_rel_array` for `PlannerInfo`
 
 ![PlannerInfo->simple_rel_array](../resources/tutorial_array_sm.png)
 
 > For more info about configuration check [documentation](config_file.md)
-
diff --git a/properties.schema.json b/properties.schema.json
@@ -84,13 +84,40 @@
         },
         "version": {
             "type": "integer",
-            "default": 3,
+            "default": 4,
             "enum": [
                 1,
                 2,
-                3
+                3,
+                4
             ],
             "description": "Version of configuration file layout. Managed by extension"
+        },
+        "customListType": {
+            "type": "object",
+            "description": "Description of custom pointer type for specified List",
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "pattern": "\\*$",
+                    "description": "Type to which 'ListCell's will be casted"
+                },
+                "member": {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "description": "Pair of parent struct name and member name inside this struct, identifying this List*"
+                },
+                "variable": {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "description": "Pair of function name and variable name inside this function, identifying this List*"
+                }
+            },
+            "required": [
+                "type"
+            ]
         }
     },
     "oneOf": [
@@ -168,6 +195,41 @@
                     "$ref": "#/definitions/typedefs"
                 }
             }
+        },
+        {
+            "type": "object",
+            "properties": {
+                "version": {
+                    "const": 4,
+                    "$ref": "#/definitions/version"
+                },
+                "specialMembers": {
+                    "type": "object",
+                    "description": "Configurations for special members",
+                    "properties": {
+                        "array": {
+                            "type": "array",
+                            "description": "Special members that represent arrays - separate fields for array and it's length",
+                            "items": {
+                                "$ref": "#/definitions/arraySpecialMemberV2"
+                            }
+                        }
+                    }
+                },
+                "aliases": {
+                    "$ref": "#/definitions/aliasesV2"
+                },
+                "typedefs": {
+                    "$ref": "#/definitions/typedefs"
+                },
+                "customListTypes": {
+                    "type": "array",
+                    "description": "Array of definitions of custom List types",
+                    "items": {
+                        "$ref": "#/definitions/customListType"
+                    }
+                }
+            }
         }
     ],
     "required": [
diff --git a/src/constants.ts b/src/constants.ts
@@ -622,18 +622,15 @@ export function getDisplayedExprs(): string[] {
 }
 
 export function getKnownCustomListPtrs(): ListPtrSpecialMemberInfo[] {
-    const member = (type: string, struct: string, member: string): ListPtrSpecialMemberInfo => {
-        return {
-            type: type + ' *',
-            member: [struct, member]
-        }
-    }
-    const variable = (type: string, func: string, variable: string): ListPtrSpecialMemberInfo => {
-        return {
-            type: type + ' *',
-            variable: [func, variable]
-        }
-    }
+    const member = (type: string, struct: string, member: string): ListPtrSpecialMemberInfo => ({
+        type: type + ' *',
+        member: [struct, member]
+    });
+
+    const variable = (type: string, func: string, variable: string): ListPtrSpecialMemberInfo => ({
+        type: type + ' *',
+        variable: [func, variable]
+    });
 
     return [
         /* contrib/amcheck/verify_heapam.c */
diff --git a/src/extension.ts b/src/extension.ts
