IDE Window: Ide Options - Backend Value Converter: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# About Backend-Converters
2	2
3	3
4	4		Backend-Converters are plugins for the debugger backend. They can be used to enhance/alter the display of specific values.
5	5
6	6		As they are executed in the backend, they can fetch additional information and include this in the resulting watch data.
7	7
8	8		Backend-Converters must be compiled into the Lazarus exe. They can either be included within an existing Debugger-backend, or they can be added by 3rd party packages. Currently only the LazDebuggerFp (FpDebug) supports Backend-Converters.
9	9
10	10		For a Backend-Converters to be used, it must be associated with the type-name of the watched data.
11	11
12	12		# Configuration
13	13
14	14		## Add / Remove
15	15
16	16		Will add/remove entries to/from the list on top of the Window. Those entries can then be selected and configured.
17	17
18	18		## "Enabled" Checkbox
19	19
20	20		Each entry in the list has a checkbox.
21	21
22	22		- If enabled, then the "Match type name" will be checked for each watch that is evaluated. Any data will be processed by the first matching Backend-Converter.
23	23		- If disabled, the converter can be explicitly assigned in the "Watches properties". Watches for which a Backend-Converters is assigned will still check if the type-name matches.
24	24
25	25		For Watches that return structured data or references to other data, and the embedded data is part of the result (e.g. a field of an object), such embedded data will also be checked and converted if matching. If the outer value matches, any embedded data must be included by the Backend-Converters. In this case it is not subject to further conversion.
26	26
27	27		## Name
28	28
29	29		Change the name of the Backend-Converters
30	30
31	31		## Action
32	32
33	33		Select a registered Backend-Converters
34	34
35	35		## Match types by name
36	36
37	37		Each line can contain a type-name or pattern.
38	38
39	39		The following is recognized:
40	40
41	41		- "TFoo" exact typename (case insensitive)
42	42		- "oo", "TF", "T*o" an asterisk matches zero, one or more chars
43	43		- "is:TFoo" must be an object, and must inherit from TFoo. (also accepts "is:TF*")
44	44
45	45		For the outer value of the watch, the "is:" operator will take the type of the instance. For nested values, only the declared type is tested.
46	46
47	47		## Other ...
48	48
49	49		Each converter may have it's own additional settings. If they have additional configuration will be shown at the bottom of the Window.
50	50
51	51		# How/When is a converter applied to a watch
52	52
53	53		For each watch that the debugger backend processes, it follows the steps below
54	54
55	55		- Evaluate the watch
56	56		- Check settings in the watch properties
57	57
58	58
59	59		The following setting are available
60	60
61	61		- Default:
62	62
63	63
64	64
65	65		All "Enabled" converters will be considered.
66	66
67	67		Converters from the project are first considered, the Converters from the global IDE config
68	68
69	69		Both list will be processed from top to bottom, until the first match is found.
70	70
71	71		- No Converter:
72	72
73	73
74	74
75	75		The watch will not be processed
76	76
77	77		- \<NAME\>:
78	78
79	79
80	80
81	81		Only the selected converter \<NAME\> will be considered (if it matches in the below)
82	82
83	83		The converter will be considered even if it is not "Enabled"
84	84
85	85		- For each converter from the first step, the "Match types by name" settings are checked
86	86
87	87		:* The type-name of evaluated result will be checked
88	88
89	89
90	90
91	91		If the type-name matches, the converter will be called.
92	92
93	93		Even if that converter then fails or rejects:\
94	94		No further converter will be considered. No checks on nested (array/struct) values will be performed.
95	95
96	96		# Per Project settings
97	97
98	98		Additional settings can be made on a per Project basis: [[IDE Window: Project Options - Value Converter]]
99	99
100	100		# Example Backend-Converters
101	101
102	102		Those only work with LazDebuggerFp.
103	103
104	104		## "Convert variant to value type"
105	105
106	106		Convert variants to their value.
107	107
108	108		Depending on Dwarf versions variants either show as record with all the available fields, or as record with 2 values "(vtype: 1; xxx: ...)".
109	109
110	110		- The converter simply shows the value. E.g. just the integer, or string.
111	111		- The converter can not add typeinfo. E.g. enum are stored as integer, and as integer they are displayed
112	112		- The converter does not support custom variant types, for that use CallSysVarToLStr. (Unlike CallSysVarToLStr, this converter does not call any functions in the debuggee)
113	113
114	114		## CallSysVarToLStr
115	115
116	116		This only works for variant data (including custom variants).
117	117
118	118		It will invoke the function "VarToLStr()" (from "TVariantManager"). The function will be invoked in the debugged process. The Backend-Converter returns the textual representation given by "VarToLStr()".
119	119
120	120		## JsonForDebug
121	121
122	122		Calls a user defined function (default "JSonForDebug") in the debugged process.
123	123
124	124		The function must support exactly the following parameters.
125	125
126		-	~~` procedure JsonForDebug(`\~~
127		-	~~` const Value; // or :Pointer; `\~~
128		-	~~` var TypeName: AnsiString;`\~~
129		-	~~` out JsonResultText: AnsiString`\~~
130		-	~~` );`~~
	126	+	``` pascal
	127	+	procedure JsonForDebug(
	128	+	const Value; // or :Pointer;
	129	+	var TypeName: AnsiString;
	130	+	out JsonResultText: AnsiString
	131	+	);
	132	+	```
131	133
132	134		The result text will be returned as watch representation. If it is valid JSon, the IDE will allow to expand/unfold entries.
133	135
134	136		If a JSON object has a key matching the "Key for Address", it will be read for the Address column in the watches window. If a JSON object has a key matching the "Key for Typename", it will be read for the type-name column in the inspect window.
135	137
136	138		---
137	139		From the Free Pascal wiki, page "IDE Window: Ide Options - Backend Value Converter", as it stood on 2023-06-11 after a change by Martin, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
138	140		Category: Debugging

Back to history