Codetools: what changed

Revision 4 to 5. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# What are the codetools?
2	2
3	3		Codetools is a Lazarus package providing tools to parse, explore, edit and refactor Pascal sources. The codetools have been packaged in their own module and are licensed under GPL. Many examples showing how to use the codetools in your own programs can be found under components/codetools/examples.
4	4
5	5		svn:
6	6
7	7		- Lazarus: <http://svn.freepascal.org/svn/lazarus/trunk>
8	8		- Only CodeTools: <http://svn.freepascal.org/svn/lazarus/trunk/components/codetools>
9	9
10	10		# Using the codetools without the IDE
11	11
12	12		You can use the codetools without the IDE. This can be used to test a new tool. An easy example is
13	13
14		-	~~```~~
	14	+	```text
15	15		<lazarusdir>/components/codetools/examples/methodjumping.lpi
16	16		```
17	17
18	18		To test find declaration, the codetools need to parse sources. Especially the RTL and FCL sources. The examples use the following environment variables:
19	19
20	20		- FPCDIR: path to the FPC sources, the default is ~/freepascal/fpc.
21	21		- PP: path to the compiler executable (/usr/bin/fpc or /usr/bin/ppc386 or C:\lazarus\ppc386.exe). The codetools need to ask the compiler for the settings. The default is to search for 'fpc' via the PATH variable.
22	22		- FPCTARGETOS: tell the codetools to scan for another operating system (cross compiling). For example: linux, freebsd, darwin, win32, win64, wince
23	23		- FPCTARGETCPU: when scanning for another CPU. For example: i386, powerpc, x86_64, arm, sparc
24	24		- LAZARUSDIR: path of the lazarus sources. Only needed if you want to scan them.
25	25
26	26		FPC is a very complex project with lots of search paths, include files and macros. The codetools need to know all these paths and macros in order to parse this jungle. To setup all this easily the codetools contain predefined templates for FPC, Lazarus, Delphi and Kylix source directories. See for a find declaration example
27	27
28		-	~~```~~
	28	+	```text
29	29		<lazarusdir>/components/codetools/examples/finddeclaration.lpi
30	30		```
31	31
32	32		Because the FPC sources contain multiple versions of some units, and the FPC sources change often, the codetools do not use a fixed table of paths, but rather scan the whole FPC directory structure on first use, applying a set of rules specifying what is the correct source for the current TargetOS and TargetCPU. This scan may take a while depending on your disk speed. All examples save the result in codetools.config, so that the next time Lazarus is started this possibly lengthy scan is skipped.
33	33
34	34		Whenever the FPC sources are changed or a unit is renamed, just delete the codetools.config file. The Lazarus IDE has its own config file and does a rescan whenever the compiler executable changes (or when the user forces a 'Tools \> Rescan FPC source directory').
35	35
36	36		## Defining search paths and macros
37	37
38	38		Important: Codetools assumes that you have multiple directories with different compiler settings, e.g. the FPC sources have different search paths than your sources. You can have FPC, Delphi and pas2js directories - all at the same time.
39	39
40	40		The codetools uses "define templates" to generate search paths and macros. Define templates are trees of rules.
41	41
42	42		### Example: Expand IncPath for a directory and/or its sub directories
43	43
44	44		The following demo demonstrate various ways to expand the IncPath for a directory and/or its sub directories:
45	45
46	46		``` pascal
47	47		program SetIncludePath;
48	48
49	49		{$mode objfpc}{$H+}
50	50
51	51		uses
52	52		SysUtils, CodeToolManager, DefineTemplates, LazFileUtils;
53	53
54	54		var
55	55		Directory: String;
56	56		DirectoryTemplate: TDefineTemplate;
57	57		IncPathTemplate: TDefineTemplate;
58	58		SubDirectory: String;
59	59		begin
60	60		// create a template for the current directory
61	61		// all child nodes of this template are only valid for this directory.
62	62		Directory:=ExpandFileNameUTF8(GetCurrentDirUTF8);
63	63		DirectoryTemplate:=TDefineTemplate.Create('Current working directory',
64	64		'Example template for current working directory','',Directory,da_Directory);
65	65
66	66		// Example 1:
67	67		// Add a sub template to extend the include search path #IncPath
68	68		// only for the current directory, not its sub directories.
69	69		// Note: 'myincludes' is a relative path, so it won't work for sub directories.
70	70		IncPathTemplate:=TDefineTemplate.Create('Add myincludes to the IncPath',
71	71		'Add myincludes to the include search path',
72	72		IncludePathMacroName, // variable name: #IncPath
73	73		IncludePathMacro+';myincludes' // new value: $(#IncPath);myincludes
74	74		,da_Define // da_Define extends the IncPath only for this directory
75	75		);
76	76		DirectoryTemplate.AddChild(IncPathTemplate);
77	77
78	78		// Example 2:
79	79		// Add a sub template to extend the include search path #IncPath
80	80		// with an absolute path for the current directory and all its sub directories.
81	81		// Note: '/tmp/myincludes' is an absolute path, so works for sub directories.
82	82		IncPathTemplate:=TDefineTemplate.Create('Add /tmp/myincludes to the IncPath',
83	83		'Add /tmp/myincludes to the include search path',
84	84		IncludePathMacroName, // variable name: #IncPath
85	85		IncludePathMacro+';'+SetDirSeparators('/tmp/myincludes') // new value: $(#IncPath);/tmp/myincludes
86	86		,da_DefineRecurse // da_DefineRecuse extends the IncPath for this directory and all sub directories
87	87		);
88	88		DirectoryTemplate.AddChild(IncPathTemplate);
89	89
90	90		// Example 3:
91	91		// Using the #DefinePath macro you can use the current directory to create absolute paths.
92	92		IncPathTemplate:=TDefineTemplate.Create('Add ./myincludes to the IncPath',
93	93		'Add ./myincludes to the include search path',
94	94		IncludePathMacroName, // variable name: #IncPath
95	95		IncludePathMacro+';'+DefinePathMacro+'/myincludes' // new value: $(#IncPath);$(#DefinePath)/myincludes
96	96		,da_DefineRecurse // da_DefineRecuse extends the IncPath for this directory and all sub directories
97	97		);
98	98		DirectoryTemplate.AddChild(IncPathTemplate);
99	99
100	100		// add the directory template to the tree
101	101		CodeToolBoss.DefineTree.Add(DirectoryTemplate);
102	102
103	103		writeln('Directory="',Directory,'"',
104	104		' IncPath="',CodeToolBoss.GetIncludePathForDirectory(Directory),'"');
105	105		SubDirectory:=AppendPathDelim(Directory)+'sub';
106	106		writeln('SubDirectory="',SubDirectory,'"',
107	107		' IncPath="',CodeToolBoss.GetIncludePathForDirectory(SubDirectory),'"');
108	108		end.
109	109		```
110	110
111	111		### Example: Expand global UnitPath
112	112
113	113		Here is an example how to extend the global (all directories) unit search path and query the unit path of one directory. This might be useful for single minded command line tools.
114	114
115	115		``` pascal
116	116		uses
117	117		Classes, SysUtils, CodeToolManager, DefineTemplates, FileProcs;
118	118
119	119		var
120	120		Directory: String;
121	121		UnitPathTemplate: TDefineTemplate;
122	122		begin
123	123		// add a sub template to extend the include search path #UnitPath.
124	124		UnitPathTemplate:=TDefineTemplate.Create(
125	125		'Add myunits to the UnitPath', // optional: an arbitrary name of the template, useful for finding it later
126	126		'Add /tmp/myunits to the unit search path', // optional: a description
127	127		UnitPathMacroName, // variable name: #UnitPath
128	128		UnitPathMacro+';/tmp/myunits' // new value: $(#UnitPath);/tmp/myunits
129	129		,da_DefineRecurse
130	130		);
131	131		// add the unit path template to the tree
132	132		CodeToolBoss.DefineTree.Add(UnitPathTemplate);
133	133
134	134		Directory:=ExpandFileNameUTF8(GetCurrentDirUTF8);
135	135		writeln('Directory="',Directory,'"',
136	136		' UnitPath="',CodeToolBoss.GetUnitPathForDirectory(Directory),'"');
137	137		end.
138	138		```
139	139
140	140		## Define Template Macros
141	141
142	142		Macros defined by define templates are used by the Pascal parser. The Codetools have functions to query the Free Pascal Compiler for its macros and convert them to define templates. This is done by CodeToolBoss.Init(Options); which you can find in many examples.
143	143
144	144		Additionally there some predefined macros, which start with a hash (#). See unit definetemplates for the full list. Here are some important ones:
145	145
146	146		``` pascal
147	147		ExternalMacroStart = '#';
148	148		// Standard macros
149	149		DefinePathMacroName = ExternalMacroStart+'DefinePath'; // the current directory
150	150		UnitPathMacroName = ExternalMacroStart+'UnitPath'; // unit search path separated by semicolon (same as given to FPC)
151	151		IncludePathMacroName = ExternalMacroStart+'IncPath'; // include file search path separated by semicolon (same as given to FPC)
152	152		SrcPathMacroName = ExternalMacroStart+'SrcPath'; // unit source search path separated by semicolon (not given to FPC)
153	153		```
154	154
155	155		For example the IncludePathMacroName is \#IncPath and is used to define the include file search path. Keep in mind that macro values depend on the directory.
156	156
157	157		Define templates values can contain macros. The macro has to be enclosed in dollar and brackets: \$(macro).
158	158
159	159		In the above example the value was '\$('+IncludePathMacroName+');/tmp/myincludes', which is '\$(#IncPath);/tmp/myincludes', which executes to the old include search path plus ';/tmp/myincludes', which means a path is appended. For readability you can use the constant IncludePathMacro instead of '\$('+IncludePathMacroName+')':
160	160
161	161		``` pascal
162	162		DefinePathMacro = '$('+DefinePathMacroName+')'; // the path of the define template
163	163		UnitPathMacro = '$('+UnitPathMacroName+')';
164	164		IncludePathMacro = '$('+IncludePathMacroName+')';
165	165		SrcPathMacro = '$('+SrcPathMacroName+')';
166	166		```
167	167
168	168		## Define Template Actions
169	169
170	170		A define template has a name, an optional description, a variable, a value and an action. The name and description are optional. The meaning of variable and value depends on the action. You can add define templates as children of define templates - creating a tree of define templates. You can see many examples for define templates in the Lazarus' dialog Tools / CodeTools Defines Editor.
171	171
172	172		- da_Block - Used for grouping templates. When the block is executed all children are executed.
173	173		- da_Directory - Use this to define all rules of a directory. If this is a root directory set Value to the full expanded directory path (use function CleanAndExpandDirectory). If this is a sub directory (parent template is a directory) Value is the sub path. Can contain macros. Children are only executed if directory fits.
174	174		- da_Define - sets a macro (Variable) value (Value) of the current directory. The value can contain macros. Note that when a macro value is set to empty string it is still defined, that means{\$IFDEF variable}will still result intrue''. Children are not executed.
175	175		- da_Undefine - clears a macro (Variable) of the current directory. {\$IFDEF macro} results in false. Children are not executed.
176	176		- da_DefineRecurse - as da_Define, but for current directory and sub directories.
177	177		- da_UndefineRecurse - as da_Undefine, but for current directory and sub directories.
178	178		- da_UndefineAll - clear all macro values.
179	179		- da_IfDef - if macro Variable is defined then execute children and skip following da_Else and da_ElseIf.
180	180		- da_IfNDef - if macro Variable is not defined then execute children and skip following da_Else and da_ElseIf.
181	181		- da_If,daElseIf - if the boolean expression Value executes to true then execute children and skip following da_Else and da_ElseIf. Value can contain macros.
182	182		- da_Else - When this template is executed then execute all children.
183	183
184	184		## How to extend the include path of a directory
185	185
186	186		See the example lazarus/components/codetools/examples/setincludepath.lpr. It demonstrates the use of relative paths, absolute paths, how to use the DefinePathMacro and the difference between da_Define and da_DefineRecurse.
187	187
188	188		# Using the codetools in the IDE with the IDEIntf
189	189
190	190		See \<lazarusdir\>/examples/idequickfix/quickfixexample.lpk package. It demonstrates:
191	191
192	192		- How to write an IDE package. When you install this package it will register a Quick Fix item in the IDE.
193	193		- How to write a Quick Fix item for the compiler message: 'Parameter "Sender" not used'
194	194		- How to use the codetools to:
195	195		- parse a unit
196	196		- convert Filename, Line, and Column data into a codetools source position
197	197		- find a codetools node at a cursor position
198	198		- find a procedure node, and the begin..end node
199	199		- create a nice insertion position for a statement at the beginning of the begin..end block
200	200		- obtain line indentation information so that a new line will work in a sub-procedure as well
201	201		- insert code using the codetools
202	202
203	203		# Codetools rules for FPC sources
204	204
205	205		When the codetools searches the source of a fpc ppu it uses a set of rules. You can write your own rules, but normally you will use the standard rules, which are defined in the include file components/codetools/fpcsrcrules.inc. You can test the rules with the command line utility: components/codetools/examples/testfpcsrcunitrules.lpi.
206	206
207	207		## Usage of testfpcsrcunitrules
208	208
209	209		Usage: lazarus/components/codetools/examples/testfpcsrcunitrules -h
210	210
211	211		-c <compiler file name>, --compiler=<compiler file name>
212	212		Default is to use environment variable PP.
213	213		If this is not set, search for fpc
214	214
215	215		-T <target OS>, --targetos=<target OS>
216	216		Default is to use environment variable FPCTARGET.
217	217		If this is not set, use the default of the compiler.
218	218
219	219		-P <target CPU>, --targetcpu=<target CPU>
220	220		Default is to use environment variable FPCTARGETCPU.
221	221		If this is not set, use the default of the compiler.
222	222
223	223		-F <FPC source directory>, --fpcsrcdir=<FPC source directory>
224	224		Default is to use environment variable FPCDIR.
225	225		There is no default.
226	226
227	227		-u <unit name>, --checkunit=<unit name>
228	228		Write a detailed report about this unit.
229	229
230	230		## Example for testfpcsrcunitrules
231	231
232	232		Open the testfpcsrcunitrules.lpi in the IDE and compile it. Then run the utility in a terminal/console:
233	233
234		-	~~```~~
	234	+	```text
235	235		./testfpcsrcunitrules -F ~/fpc/sources/2.5.1/fpc/
236	236		```
237	237
238	238		This will tell you which compiler is used, which compiler executes, which config files were tested and parsed, and it warns you about duplicate units in the FPC search path and about duplicated unit source files. Note: This example caches results in the file codetools.config. You should delete codetools.config when you update the compiler or your fpc.cfg file.
239	239
240	240		## Duplicate source files
241	241
242	242		You find out that the codetools opens for target wince/arm the wrong source of the unit mmsystem. Run the tool with the -u parameter:
243	243
244	244		./testfpcsrcunitrules -F ~/fpc/2.5.1/fpc/ -T wince -P arm -u mmsystem
245	245
246	246		This will give you a detailed report where this unit was found and what score each source file got. For example:
247	247
248	248		``` pascal
249	249		Unit report for mmsystem
250	250		WARNING: mmsystem is not in PPU search path
251	251		GatherUnitsInFPCSources UnitName=mmsystem File=packages/winunits-base/src/mmsystem.pp Score=11
252	252		GatherUnitsInFPCSources UnitName=mmsystem File=packages/winceunits/src/mmsystem.pp Score=11 => duplicate
253	253		```
254	254
255	255		This means there are two source files with the same score, so the codetools took the first. The last one in winceunits is for target wince and the first one is for win32 and win64.
256	256
257	257		Now open the rules file fpcsrcrules.inc.
258	258
259	259		Rules work like this:
260	260
261	261		``` pascal
262	262		Score:=10;
263	263		Targets:='wince';
264	264		Add('packages/winceunits');
265	265		```
266	266
267	267		The Add adds a rule for all files beginning with 'packages/winceunits' that adds a score of 10 to all these files. The Targets is a comma separated list of target operating systems and/or target processors. For example Targets='wince,linux,i386' means: apply this rules to TargetOS wince or linux and to all TargetCPU i386.
268	268
269	269		# How the codetools parses sources differently from the compiler
270	270
271	271		A compiler is optimized to parse code linearly and to load needed units and include files as soon as it parses a uses section or a directive. The codetools are optimized to parse only certain code sections. For example jumping from the method declaration to the method body only needs the unit and its include files. When a codetool searches a declaration it searches backwards. That means it starts searching in the local variables, then upwards from the implementation. When it finds a uses section it searches the identifiers in the interface section of the units. When the identifier is found it stops. The result and some intervening steps are cached. Because it often only needs to parse a few interface sections it finds an individual identifier very quickly.
272	272
273	273		The codetools do not parse a source in a single step (as the compiler does) but in several steps, which depend on what the current codetool needs:
274	274
275	275		- First a source file is loaded in a TCodeBuffer. The IDE uses this step to change the encoding to UTF8. The files are kept in memory and only reloaded if the modification date changes or if a file is manually reverted. There are several tools and functions which work directly on the buffer.
276	276		- The next step is to parse the unit (or include file). A unit must be parsed from the beginning, so the codetools tries to find the main file, the first file of a unit. It does that by looking for a directive in the first line like {%MainUnit ../lclintf.pp}. If that does not exist, it searches in the includelink cache. The IDE saves this cache to disk, so the IDE learns over time.
277	277		- After finding the main file a TCodeTool is created and a TLinkScanner parses the source. It handles compiler directives, such as include directives and conditional directives. The scanner can be given a range, so it might, for instance, parse only a unit's interface. The scanner creates the clean source. The clean source is put together from all include files, having been stripped of code in the else part of conditional directives, which is skipped. It also creates a list of links which map the clean source to the real source files. The clean source is now Pascal containing no else code. Note: there are also tools designed to scan a single source for all directives. These tools create a tree of directives.
278	278		- After creating the clean source a TCodeTool parses it and creates a tree of TCodeTreeNode. It can also be given a range. This parser skips a few parts, for example class members, begin..end blocks and parameter lists. Many tools don't need them. These sub nodes are created on demand. A TCodeTreeNode has a range StartPos..EndPos which are clean positions, that means positions in the clean source. There are only nodes for the important parts. Creating nodes for every detail would need more memory than the source itself and is seldom needed. There are plenty of functions to find out the details. For example if a function has the 'cdecl' calling convention.
279	279		- When searching for an identifier the search stores the base types it finds and creates caches for all identifiers in the interface section.
280	280
281	281		Every level has its own caches, which need to be checked and updated before calling a function. Many high level functions accessible via the CodeToolBoss do that automatically. For others it is the responsibility of the caller.
282	282
283	283		Example for:
284	284
285	285		unit1.pas:
286	286
287	287		``` pascal
288	288		unit Unit1;
289	289		{$I settings.inc}
290	290		interface
291	291		uses
292	292		{$IFDEF Flag}
293	293		unix,
294	294		{$ELSE}
295	295		windows,
296	296		{$ENDIF}
297	297		Classes;
298	298		```
299	299
300	300		settings.inc:
301	301
302	302		``` pascal
303	303		{%MainUnit unit1.pas}
304	304		{$DEFINE Flag}
305	305		```
306	306
307	307		clean source:
308	308
309	309		``` pascal
310	310		unit Unit1;
311	311		{$I settings.inc}{%MainUnit unit1.pas}
312	312		{$DEFINE Flag}
313	313		interface
314	314		uses
315	315		{$IFDEF Flag}
316	316		unix,
317	317		{$ELSE}{$ENDIF}
318	318		Classes;
319	319		```
320	320
321	321		Hint: To easily parse a unit and build the nodes, use CodeToolBoss.Explore.
322	322
323	323		# Tool, Node, LinkScanner
324	324
325	325		## Tool
326	326
327	327		A tool is a TCodeTool. For Pascal files every unit, program and package gets its own TCodeTool. These are automatically created by the CodetoolBoss when parsing sources. A tool has a Scanner (TLinkScanner) and a Root (TCodeTreeNode), which is the root node of the tree of Pascal nodes of the module (e.g. unit).
328	328
329	329		## LinkScanner
330	330
331	331		Every TCodeTool creates a TLinkScanner to scan the files and creates the CleanedSrc, which is the parsed unit source, include files included and code in skipped \$IF directives removed. When only the unit interface was parsed, the CleanedSrc may not be complete. TLinkScanner is not shared between TCodeTools. There is a 1:1 mapping between TLinkScanner and TCodeTool.
332	332
333	333		## Node
334	334
335	335		- A TCodeTreeNode is part of a tree of such nodes. The root node is stored in a TCodeTool.Root. Nodes are not shared between tool. Every node is associated with exactly one TCodeTool.
336	336		- When a function returns a Node, it always returns the associated Tool as well.
337	337		- Node.StartPos/EndPos are positions 1-based in the Scanner.CleanedSrc.
338	338		- To get from the cleaned postion to the file, line, column use Tool.CleanPosToCaret(Node.StartPos,xyp).
339	339
340	340		# CleanPos and CursorPos
341	341
342	342		There are several methods to define a position in the codetools.
343	343
344	344		The codetools Absolute position is related to the source as a continuous string starting at character 1. For example a TCodeBuffer holds the file contents as a single string in its Source property. Caret or cursor positions are given as X,Y where X is the column number and Y the line number. Each value (X and Y) starts at 1. A TCodeBuffer provides the member functions LineColToPosition and AbsoluteToLineCol'' to convert between (X,Y) values and the Absolute codetools position. When working with multiple source files (such as a unit which may contain several include files), the clean position relates to the absolute position in the stripped codeSrc. Here Src is a string whose clean positions start at 1. Cursor positions are specified as TCodeXYPosition (Code,X,Y). A TCodeTool provides the functionsCaretToCleanPosandCleanPosToCaret''' to convert between them.
345	345
346	346		# Inserting, deleting, replacing - the TSourceChangeCache
347	347
348	348		When making changes to the source code of a unit (or its include files) you should use the CodetoolBoss.SourceChangeCache instead of altering the source directly.
349	349
350	350		- Simple usage: Connect, Replace, Replace, ... Apply. See below.
351	351		- You can use cleanpos as given by the node tree OR you can use direct position in a file.
352	352		- You can use Replace to insert and delete, which automatically calls events, so connected editors are notified of changes.
353	353		- It can automatically insert needed spaces, line breaks or empty lines in front or behind each Replace. For example you define that there should be an empty line in front. The SourceChangeCache checks what is inserted and how much space there is already and will insert needed space.
354	354		- It checks if the replaced/deleted span is writable.
355	355		- You can do multiple Replaces and you control when they are applied. Keep in mind that inserting code means that the parsed tree becomes invalid and needs rebuilding.
356	356		- Multiple replaces are checked for intersection. For example an insert in the middle of deleted code gives an error.
357	357		- Mutiple insertions at the same place are added FIFO - first at the top.
358	358		- You can combine several functions altering code to one bigger function. See below.
359	359
360	360		## Usage
361	361
362	362		The SourceChangeCache works on a unit, so you need to get a TCodeTool and scan a unit/include file. For example:
363	363
364	364		``` pascal
365	365		// Step 1: load the file and parse it
366	366		Code:=CodeToolBoss.LoadFile(Filename,false,false);
367	367		if Code=nil then
368	368		raise Exception.Create('loading failed '+Filename);
369	369		if not CodeToolBoss.Explore(Code,Tool,false) then
370	370		...;// parse error ...
371	371
372	372		// Step 2: connect the SourceChangeCache
373	373		CodeToolBoss.SourceChangeCache.MainScanner:=Tool.Scanner;
374	374
375	375		// Step 3: use Replace to insert and/or delete code
376	376		// The first two parameters are the needed spaces in front and behind the insertion
377	377		// The FromPos,ToPos defines the deleted/replaced range in CleanPos positions.
378	378		// The NewCode is the string of new code. Use '' for a delete.
379	379		if not CodeToolBoss.SourceChangeCache.Replace(gtNone,gtNone,FromPos,ToPos,NewCode) then
380	380		exit; // e.g. source read only or a former Replace has deleted the place
381	381		...do some more Replace...
382	382
383	383		// Step 4: Apply the changes
384	384		if not CodeToolBoss.SourceChangeCache.Apply then
385	385		exit; // apply was aborted
386	386		```
387	387
388	388		## BeginUpdate/EndUpdate
389	389
390	390		BeginUpdate/EndUpdate delays the Apply. This is useful when combining several code changing functions. For example:
391	391
392	392		You want to scan the unit, add a unit to the interface uses section, and remove the unit from the implementation uses section. The two functions AddUnitToMainUsesSection and RemoveUnitFromUsesSection use Apply, altering the source, so the second function would rescan the unit a second time. But since the two functions are independent of each other (they change different parts of the source) you can combine them and do it with one scan:
393	393
394	394		``` pascal
395	395		// Step 1: parse unit and connect SourceChangeCache
396	396		if not CodeToolBoss.Explore(Code,Tool,false) then
397	397		...;// parse error ...
398	398		CodeToolBoss.SourceChangeCache.MainScanner:=Tool.Scanner;
399	399
400	400		// Step 2: delay Apply
401	401		CodeToolBoss.SourceChangeCache.BeginUpdate;
402	402
403	403		// Step 3: add unit to interface section
404	404		// AddUnitToMainUsesSection would apply and change the code
405	405		// Because of the BeginUpdate the change is not yet done, but stored in the SourceChangeCache
406	406		if not Tool.AddUnitToMainUsesSection('Classes','',CodeToolBoss.SourceChangeCache) then exit;
407	407
408	408		// Step 4: remove unit from implementation section
409	409		// Without the BeginUpdate the RemoveUnitFromUsesSection would rescan the unit
410	410		if Tool.FindImplementationUsesSection<>nil then
411	411		if not Tool.RemoveUnitFromUsesSection(Tool.FindImplementationUsesSection,'Classes',CodeToolBoss.SourceChangeCache) then exit;
412	412
413	413		// Step 5: apply all changes
414	414		if not CodeToolBoss.SourceChangeCache.EndUpdate then
415	415		exit; // apply was aborted
416	416		```
417	417
418	418		BeginUpdate/EndUpdate work with a counter, so if you call BeginUpdate twice you need to call EndUpdate twice. This means you can put the above example in a function and combine that with another function.
419	419
420	420		## Saving changes to disk
421	421
422	422		The above changes are made to the code buffers and the buffers are marked modified. To save the changes to disk, you have to call Save for each modified buffer.
423	423
424	424		- The buffers that will be modified in the next Apply/EndUpdate are in SourceChangeCache.BuffersToModify and BuffersToModifyCount.
425	425		- The events SourceChangeCache.OnBeforeApplyChanges/OnAfterApplyChanges are used by the CodeToolBoss, which connects it to its own OnBeforeApplyChanges/OnAfterApplyChanges. The Lazarus IDE sets these events and automatically opens modified files in the source editor, so all changes go into the undo list of synedit.
426	426
427	427		# Hints/Tips/Guide Lines
428	428
429	429		- BuildTree checks the current state and will only parse if needed. If a former call has parsed the interface and you need the interface again, BuildTree will not do anything. If you need the full unit, only the implementation will be parsed. Nodes are only freed if some files have changed on disk or some settings have changed (initial macros). BuildTree does not check all files on every call. Instead it uses the directory cache of the codetools. So, if nothing has changed it will return very quickly. You should call it before any search operation.
430	430		- Do not call BuildTree after an operation. That is a waste of CPU.
431	431		- BuildTree raises an exception when there are missing include files or syntax errors. You should enclose your code into
432	432
433	433		``` pascal
434	434		try
435	435		Tool.BuildTree(lsrEnd);
436	436		... search ... replace
437	437		except
438	438		on E: Exception do
439	439		CodeToolBoss.HandleException(E);
440	440		end;
441	441		```
442	442
443	443		- After calling SourceChangeCache.Replace (multiple times) the sources (TCodeBuffers) have not changed immediately. You must call SourceChangeCache.Apply to change the sources. This will not save the changes to file.
444	444
445	445		# Test suite
446	446
447	447		The codetools test suite can be found here:
448	448
449		-	~~```~~
	449	+	```text
450	450		lazarus/components/codetools/tests/runtestscodetools
451	451		```
452	452
453	453		Compile it and run it:
454	454
455		-	~~```~~
	455	+	```text
456	456		cd lazarus/components/codetools/tests
457	457		./runtestscodetools
458	458		```
459	459
460	460		# Links
461	461
462	462		- [[Lazarus IDE Tools]] - A tutorial about the built-in tools of the standard IDE
463	463		- [[Cody]] - IDE package adding advanced code tools to the IDE
464	464		- [[Extending the IDE]] - How to write your own codetools plugins for the IDE.
465	465
466	466		---
467	467		From the Free Pascal wiki, page "Codetools", as it stood on 2020-12-31 after a change by Mattias2, 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).
468	468		Category: Components

Back to history