Sign in Join
Wiki copytemporary

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

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

Title: IDE Window: Ide Options - Backend Value Converter

OldNewLine
1+# About Backend-Converters
2+
3+
4+Backend-Converters are plugins for the debugger backend. They can be used to enhance/alter the display of specific values.
5+
6+As they are executed in the backend, they can fetch additional information and include this in the resulting watch data.
7+
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+
10+For a Backend-Converters to be used, it must be associated with the type-name of the watched data.
11+
12+# Configuration
13+
14+## Add / Remove
15+
16+Will add/remove entries to/from the list on top of the Window. Those entries can then be selected and configured.
17+
18+## "Enabled" Checkbox
19+
20+Each entry in the list has a checkbox.
21+
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+- 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+
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+
27+## Name
28+
29+Change the name of the Backend-Converters
30+
31+## Action
32+
33+Select a registered Backend-Converters
34+
35+## Match types by name
36+
37+Each line can contain a type-name or pattern.
38+
39+The following is recognized:
40+
41+- "TFoo" exact typename (case insensitive)
42+- "*oo", "TF*", "T*o" an asterisk matches zero, one or more chars
43+- "is:TFoo" must be an object, and must inherit from TFoo. (also accepts "is:TF*")
44+
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+
47+## Other ...
48+
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+
51+# How/When is a converter applied to a watch
52+
53+For each watch that the debugger backend processes, it follows the steps below
54+
55+- Evaluate the watch
56+- Check settings in the watch properties
57+
58+
59+The following setting are available
60+
61+- Default:
62+
63+
64+
65+All "Enabled" converters will be considered.
66+
67+Converters from the project are first considered, the Converters from the global IDE config
68+
69+Both list will be processed from top to bottom, until the first match is found.
70+
71+- No Converter:
72+
73+
74+
75+The watch will not be processed
76+
77+- \<NAME\>:
78+
79+
80+
81+Only the selected converter \<NAME\> will be considered (if it matches in the below)
82+
83+The converter will be considered even if it is not "Enabled"
84+
85+- For each converter from the first step, the "Match types by name" settings are checked
86+
87+:* The type-name of evaluated result will be checked
88+
89+
90+
91+If the type-name matches, the converter will be called.
92+
93+Even if that converter then fails or rejects:\
94+No further converter will be considered. No checks on nested (array/struct) values will be performed.
95+
96+# Per Project settings
97+
98+Additional settings can be made on a per Project basis: [[IDE Window: Project Options - Value Converter]]
99+
100+# Example Backend-Converters
101+
102+Those only work with LazDebuggerFp.
103+
104+## "Convert variant to value type"
105+
106+Convert variants to their value.
107+
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+
110+- The converter simply shows the value. E.g. just the integer, or string.
111+- The converter can not add typeinfo. E.g. enum are stored as integer, and as integer they are displayed
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+
114+## CallSysVarToLStr
115+
116+This only works for variant data (including custom variants).
117+
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+
120+## JsonForDebug
121+
122+Calls a user defined function (default "JSonForDebug") in the debugged process.
123+
124+The function must support exactly the following parameters.
125+
126+` procedure JsonForDebug(`\
127+`   const Value;   // or  :Pointer;  `\
128+`   var TypeName: AnsiString;`\
129+`   out JsonResultText: AnsiString`\
130+` );`
131+
132+The result text will be returned as watch representation. If it is valid JSon, the IDE will allow to expand/unfold entries.
133+
134+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+
136+---
137+*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+Category: Debugging

Back to history