Skip to content

Commit dcd64e5

Browse files
ashenBladeashenBlade
committed
docs: remove redundant info for variable handling from README
There are too many gifs showing how extension works, but actually even 1 is enough, so only 1 gif (with overview) is left in variable section. Also, some sections are rearranged: formatting section goes after variables as it's second important feature.
1 parent 67df493 commit dcd64e5

File tree

9 files changed

+104
-192
lines changed

9 files changed

+104
-192
lines changed

‎README.md‎

Lines changed: 87 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -2,173 +2,70 @@
22

33
![Logo](resources/logo.png)
44

5-
This is a Visual Studio Code extension to assist PostgreSQL source code
6-
developers. It allows to investigate `Node *` variables to obtain it's real type
7-
based on `NodeTag` and provide some other utilities.
5+
This is a Visual Studio Code extension to assist PostgreSQL source code developers:
86

9-
## Features
10-
11-
More info you can find in documentation for [`PG Variables` view](docs/pg_variables.md).
12-
13-
### Investigate real type of `Node *`
14-
15-
While debugging you can observe variables of `Node *` type with it's real type.
16-
They appear in separate action view.
17-
18-
![Overview of extension](resources/overview.gif)
19-
20-
It behaves like Debug->Variables view, but no colorization (limitations of VS
21-
Code Extension framework) and automatically detects real type of `Node *`
22-
variables.
23-
24-
### Show contents of containers
25-
26-
Extension support showing contents of containers: `List` (including `Oid`, `TransactionId`, `int` and non-Node types) and `Bitmapset`.
27-
28-
![List * expansion](resources/list.gif)
29-
30-
`Bitmapset` elements are displayed:
31-
32-
- `$elements$` - elements of set (array of integers)
33-
- `$length$` - number of entries in set
34-
35-
![Bitmapset expansion](resources/bitmapset.gif)
36-
37-
Also, there is support for C-arrays (like `PlannerInfo->simple_rel_array`) - array is displayed using it's length.
38-
39-
![Array special member](resources/array-special-member.gif)
40-
41-
Currently, there are 36 registered array members, but you can add your own using [pgsql_hacker_helper.json](#pgsql_hacker_helperjson) configuration file.
42-
43-
Another containers - Hash Tables. There is support for both `HTAB *` and `simplehash` (from `lib/simplehash.h`) - you can see their elements in separate `$elements$` member.
44-
45-
![TIDBitmap simplehash elements](resources/simplehash.gif)
46-
47-
> NOTE: most `HTAB *` stored in `static` variables, so they are not shown in variables UI
48-
>
49-
> NOTE2: simplehashes have limitation due to compiler unused symbol pruning optimization (more in [configuration file documentation](./docs/config_file.md))
50-
51-
### Show where Bitmapset references
52-
53-
`Bitmapset` and `Relids` often store indexes of other elements in other places.
54-
Extension knows 53 such elements. I.e. `PlannerInfo->all_relids` or `RelOptInfo->eclass_indexes`.
55-
56-
![Bitmapset references](resources/bitmapset-refs.gif)
57-
58-
### Show Expr in their text representation
59-
60-
In members of `Expr` nodes you can see their text representation.
61-
I.e. for `OpExpr` you will see something like `a.x = 1`.
62-
This works for most of `Exprs`, except *bulky* (`SubPlan`, `Case`, ...).
63-
64-
![Show Exprs text representation](./resources/expr_repr.gif)
65-
66-
Also, there are shortcuts for: `EquivalenceMember`, `RestrictInfo` and `TargetEntry`.
67-
Their expressions are displayed right after their member, so you will not have to keep opening and closing variables to see what's inside.
68-
A quick glance will make it clear what's inside!
7+
- Exploring Postgres variables (`Node *`, container types, etc...)
8+
- Format code with `pgindent`
699

70-
![Expressions of equivalence members displayed immediately](./resources/ec_members_exprs.png)
71-
72-
> NOTE: not all and not always `Expr`s will be displayed.
73-
> Some of subtypes just not supported (i.e. `SubPlan` or `Case`).
74-
> Also, for displaying representation it's required to have range table.
75-
> In such cases placeholder is displayed.
76-
77-
### Dump `Node *`
78-
79-
In PostgreSQL there is `pprint(Node *)` which dumps passed Node variable to
80-
stdout with pretty printing it. Using 'Dump Node to log' option in variable
81-
context menu you also will be able to do so.
82-
83-
![call pprint](resources/dump.gif)
84-
85-
Also, you can dump `Node *` into newly created document and work with it as text file.
86-
There is `Dump Node to document` option in variable context menu.
87-
88-
### Formatting
89-
90-
Extension uses `pgindent` for formatting C code. It integrates with VS Code
91-
extension and available with `Format Document` or `Ctrl + Shift + I` shortcut
92-
(or another key binding if overridden).
93-
94-
To enable this set formatter for C in settings (i.e. `.vscode/settings.json`
95-
for workspace):
96-
97-
```json
98-
{
99-
"[c]": {
100-
"editor.defaultFormatter": "ash-blade.postgresql-hacker-helper"
101-
}
102-
}
103-
```
104-
105-
Or specify formatter manually using `Format Document With...`. Select
106-
`PostgreSQL Hacker Helper` in pick up box.
107-
108-
![Formatter work](resources/formatter-work.gif)
109-
110-
Feature supported for PostgreSQL starting from 10 version.
10+
## Features
11111

112-
> This feature using tools from `src/tools`. If they are unavailable extension
113-
> will try to build or download them.
114-
>
115-
> Primary tool required is `pg_bsd_indent` - extension will try to build it.
116-
> For this `pg_config` is used, but if extension fails to find it you will be
117-
> prompted to enter path to it.
12+
### Postgres Variables
11813

119-
Using command `PgSQL: Show diff preview for PostgreSQL formatter` you can
120-
preview changes made by formatter.
14+
Extension provides assistance with postgres variables:
12115

122-
Also, you can add your custom `typedefs.list` files and extension will use it
123-
during formatting. For more info check [documentation](docs/config_file.md#custom-typedefslist-files).
16+
- View `Node *` variables with real type according to `NodeTag`
17+
- Get the contents of container types: `List *`, `HTAB *`, `Bitmapset *`
18+
- Render `Expr` nodes by the original expression
12419

125-
### Extension bootstrapping
20+
> More info you can find in documentation for [`PG Variables` view](docs/pg_variables.md).
12621
127-
Extension can help with creation of basic PostgreSQL extension files: Makefile,
128-
control file, source files (C, SQL) and tests.
22+
Extension creates separate view in debug section - `PG Variables`. It contains postgres variables - extended with knowledge of source code.
12923

130-
Just run command `Bootstrap extension` and enter initial values (extension
131-
name, description, required files). Extension will be created inside `contrib`
132-
directory.
24+
![Overview of extension](resources/overview.gif)
13325

134-
## Customization
26+
- `Node *` variables casted to types according to `NodeTag`
27+
- Container types show their elements:
28+
- `List *` (with support for scalars)
29+
- `HTAB *`
30+
- simplehash (`lib/simplehash.h`)
31+
- `Bitmapset *`
32+
- Render `Expr` nodes by the original expression
33+
- `Bitmapset *` elements (numbers) store references to which they point, i.e. `Relids` will store `RelOptInfo` and `RangeTable` references
34+
- `List *` can support custom pointer types (not `Node *` types)
35+
- Some scalar types are rendered in more convenient way, i.e. `XLogRecPtr` displayed in `File/Offset` form - not integer
13536

136-
### pgsql_hacker_helper.json
37+
### Configuration file
13738

138-
This is a configuration file for extension.
139-
It stored inside `.vscode` directory in your repository - `.vscode/pgsql_hacker_helper.json`. You can use config file to extend built-in capabilities if there is no support for something yet.
39+
Extension has configuration file - `.vscode/pgsql_hacker_helper.json`.
40+
Main purpose is to allow to define container elements custom types, i.e. when you are developing a contrib.
14041

14142
Example json:
14243

14344
```json
14445
{
145-
"version": 5,
146-
"specialMembers": {
147-
"array": [
148-
{
149-
"typeName": "PlannerInfo",
150-
"memberName": "simple_rel_array",
151-
"lengthExpression": "simple_rel_array_size"
152-
},
153-
{
154-
"typeName": "RelOptInfo",
155-
"memberName": "partexprs",
156-
"lengthExpression": "part_scheme->partnatts"
157-
},
158-
{
159-
"typeName": "GatherMergeState",
160-
"memberName": "gm_slots",
161-
"lengthExpression": "nreaders + 1"
162-
}
163-
]
164-
},
46+
"arrays": [
47+
{
48+
"typeName": "PlannerInfo",
49+
"memberName": "simple_rel_array",
50+
"lengthExpression": "simple_rel_array_size"
51+
},
52+
{
53+
"typeName": "RelOptInfo",
54+
"memberName": "partexprs",
55+
"lengthExpression": "part_scheme->partnatts"
56+
},
57+
{
58+
"typeName": "GatherMergeState",
59+
"memberName": "gm_slots",
60+
"lengthExpression": "nreaders + 1"
61+
}
62+
],
16563
"aliases": [
16664
{
16765
"alias": "PlannerRef",
16866
"type": "PlannerInfo *"
16967
}
17068
],
171-
"typedefs": "my.typedefs.file",
17269
"customListTypes": [
17370
{
17471
"type": "char *",
@@ -190,29 +87,59 @@ Example json:
19087
"prefix": "userdata",
19188
"type": "UserDataHashEntry *"
19289
}
193-
]
90+
],
91+
"typedefs": "my.typedefs.file"
19492
}
19593
```
19694

19795
Features:
19896

199-
- 3 *array* special members (pointer field used as array) - `"typeName"->"memberName"` will be shown with length `"typeName"->"lengthExpression"`, not as simple pointers.
200-
201-
- `PlannerRef` - custom user typedef for `PlannerInfo *`.
202-
97+
- 3 array members (pointer field used as array) - `"typeName"->"memberName"` will be shown with length `"typeName"->"lengthExpression"`, not as simple pointers.
98+
- `PlannerRef` - custom user typedef for `PlannerInfo *` (used to correctly handle types).
20399
- `UserData->knownNames` is a `List *` that contains pointer elements not `Node *`, but `char *` (`List` of strings).
204100
Variable `chunks` in function `ProcessFileChunks` is a `List` that contains pointer elements not `Node *`, but `struct FileChunks *`.
205-
206-
- User provided custom `typedefs` list (used by formatter).
207-
208101
- `List *UserData->knownNames` contains pointers to `char *` (not Node), and variable `List *chunks` in function `ProcessFileChunks()` contains pointers to `struct FileChunks` (not Node)
209-
210102
- Hash Table member `HTAB *hashtable` of struct `ParentStruct` contains entries of type `HashTableEntry *`
211-
212103
- Simplehash struct `hashtable_hash` contains entries of type `UserDataHashEntry *`.
104+
- User provided custom `typedefs` list (used by formatter).
213105

214106
For more info check [configuration file documentation](./docs/config_file.md).
215107

108+
### Formatting
109+
110+
Extension uses `pgindent` for formatting C code. It integrates with VS Code extension and available with `Format Document` or `Ctrl + Shift + I` shortcut (or another key binding if overridden). Or you can just specify formatter manually using `Format Document With...` - select `PostgreSQL Hacker Helper` in pick up box.
111+
112+
![Formatter work](resources/formatter-work.gif)
113+
114+
Feature supported for PostgreSQL starting from 10 version.
115+
116+
> This feature using tools from `src/tools`. If they are unavailable extension will try to build or download them.
117+
>
118+
> Primary tool required is `pg_bsd_indent` - extension will try to build it.
119+
> For this `pg_config` is used, but if extension fails to find it you will be prompted to enter path to it.
120+
121+
Using command `PgSQL: Show diff preview for PostgreSQL formatter` you can
122+
preview changes made by formatter.
123+
124+
Also, you can add your custom `typedefs.list` files and extension will use it during formatting (`"typedefs"`). For more info check [documentation](docs/config_file.md#custom-typedefslist-files).
125+
126+
### Dump `Node *`
127+
128+
In PostgreSQL there is `pprint(Node *)` which dumps passed Node variable to
129+
stdout with pretty printing it. Using 'Dump Node to log' option in variable
130+
context menu you also will be able to do so.
131+
132+
![call pprint](resources/dump.gif)
133+
134+
Also, you can dump `Node *` into newly created document and work with it as text file.
135+
There is `Dump Node to document` option in variable context menu.
136+
137+
### Extension bootstrapping
138+
139+
Extension can help with creation of basic PostgreSQL extension files: Makefile, control file, source files (C, SQL) and tests.
140+
141+
Just run command `Bootstrap extension` and enter initial values (extension name, description, required files). Extension will be created inside `contrib` directory.
142+
216143
## Extension Settings
217144

218145
There are 4 settings:
@@ -246,12 +173,10 @@ There are 4 settings:
246173

247174
- If not specified, it will be searched in `*SrcPath*/src/tools` directory.
248175
- If specified, and failed to run extension will try to build it.
249-
NOTE: If required, it will be downloaded and built.
250176

251177
## Compatibility
252178

253179
Compatibility is ensured using testing. Minimal supported versions are **PostgreSQL 9.6** and **VS Code 1.70**.
254-
But actually it can support PostgreSQL down to 8.0 and VS Code 1.30, but testing is not done due to large test matrix - for these versions testing is done manually.
255180

256181
There are 2 supported debugger extensions: [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) and [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).
257182
Extension always tested on *latest version of debugger* and do not tries to be compatible with old ones due to *possible* large/breaking changes in behavior (most features implemented using hacks).
@@ -264,9 +189,11 @@ For using formatter minimal supported version Postgres is `10`.
264189
Directory [`./src/test`](./src/test) contains multiple staff for extension testing.
265190
You can read [README](./src/test/README.md) to look at testing process.
266191

267-
In short, only variable expansion is tested using large test matrix: PG Version x VS Code Version x Debugger.
192+
For variables testing is performed using matrix: PG Version x VS Code Version x Debugger.
268193
Each dimension contains all supported values: 9 (PG Versions) x 4 (VS Code Versions) x 2 (Debuggers) = 72 tests in total.
269194

195+
For formatting testing is performed using matrix: PG Version x VS Code Version (36 tests in total).
196+
270197
## Known Issues
271198

272199
Known issues:
@@ -277,8 +204,8 @@ Known issues:
277204
but these files may be not created (./configure or make not run). I assume by
278205
time of debugging start files will be created, so extension catch them and process.
279206
- Sometimes formatting can misbehave. This is due to `pg_bsd_indent` internal
280-
logic. If formatting is not applied try run command again. If file after
281-
formatting is a mess this can be due to errors in logic.
207+
logic. If formatting is not applied check logs of an extension - it may contain
208+
error messages.
282209
- Some operations require data to be allocated (usually, for function invocation).
283210
For this, `palloc` and `pfree` are used. So if you are debugging memory subsystem
284211
you may want to disable extension, because it may affect debugging process.

0 commit comments

Comments
 (0)