Namespaces: what changed

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

Old	New		Line
1	1		Since [[FPC New Features 3.0\|FPC 3.0.0]] unit namespaces with dots are supported.
2	2
3	3		## Namespaces in FPC
4	4
5	5		This page contains proposals and ideas, which could lead to the a better implementation of namespaces that what Delphi currently has. These ideas may or may not work, that's the whole point of this wiki page. Throw ideas around until we find something that could work.
6	6
7	7		## Why?
8	8
9	9		Namespaces are not perfect, but they do work, and they do greatly reduce the chances for Unit name or Class name conflicts. Other languages and frameworks (Java, .NET, C++ etc) have already seen the problem and introduced namespace support.
10	10
11	11		How visible is the unit name conflict problem? Just think, how many projects are there that use the unit names (or would like to use these common names):
12	12
13		-	~~` constants.pas`\~~
14		-	~~` utils.pas`\~~
15		-	~~` etc...`~~
	13	+	```text
	14	+	constants.pas
	15	+	utils.pas
	16	+	etc...
	17	+	```
16	18
17	19		Extremely common names, and are really good names for what they contain (they describe the purpose of the unit clearly), so why can't we use them in our projects? Namespaces will resolve such problem.
18	20
19	21		- To reduce the chances of conflicting unit names
20	22		- Allow developers to use ideal names for units without the worry of conflicting unit names with the FPC compiler or other component libraries. eg: constants.pas or utils.pas or strutils.pas
21	23		- No need for cryptic 2 or 3 letter prefixes to unit names.
22	24
23	25		## Interested Parties
24	26
25	27		- Graeme Geldenhuys
26	28		- Marcos Douglas
27	29
28	30		## Usage Examples
29	31
30	32		Please add any new ideas to the end of the list.
31	33
32	34		### Suggestion 1 - "dotted unit name notation"
33	35
34	36		Use the same style as implemented in Delphi 2009 onwards.
35	37
36	38		#### Pros
37	39
38	40		- Extends the syntax in Pascal where units are already namespaces (disambiguating two names by prefixing the unit name)
39	41		- Similar to the Ada approach of packages, much more robust than namespaces
40	42		- Delphi compatible
41	43
42	44		#### Cons
43	45
44	46		- The force rather long unit names. eg: freepascal.rtl.classes.pas
45	47		- Unit names now contain a '.' character which doesn't make them truly valid identifiers.
46	48		- Ambiguities could appear, but they are rather easy to overcome with a simple language rule. Object Pascal already have many language rules, this will just be a new one. See the following Mantis report for details: [Mantis report 14439](http://bugs.freepascal.org/view.php?id=14439)
47	49
48	50		### Suggestion 2 - new keyword & new compiler parameter
49	51
50	52		This idea works similar to Compiler Defines. They can be applied to a unit, or to a project as a whole. Add a new keyword namespace \<value\> to the Object Pascal language that gets added to the unit line of a source file. Also add a new -namespace=\<value\> compiler parameter to apply a namespace to a whole project
51	53
52	54		#### Example
53	55
54		-	~~` // per unit`\~~
55		-	~~` unit utils namespace companyxyz;`\~~
56		-	~~` uses`\~~
57		-	~~` ...`\~~
58		-	~~` end.`~~
	56	+	``` pascal
	57	+	// per unit
	58	+	unit utils namespace companyxyz;
	59	+	uses
	60	+	...
	61	+	end.
	62	+	```
59	63
60	64		...or applied at compile time to all units being compiled.
61	65
62		-	~~` // our sample unit - as normal, nothing new`\~~
63		-	~~` unit utils;`\~~
64		-	~~` uses`\~~
65		-	~~` ...`\~~
66		-	~~` end.`~~
	66	+	``` pascal
	67	+	// our sample unit - as normal, nothing new
	68	+	unit utils;
	69	+	uses
	70	+	...
	71	+	end.
	72	+	```
67	73
68		-	~~` $ fpc -namespace=companyxyz utils.pas constants.pas ...`~~
	74	+	```text
	75	+	$ fpc -namespace=companyxyz utils.pas constants.pas ...
	76	+	```
69	77
70	78		... if a conflict occurs, then you reference the unit with the full namespace.
71	79
72		-	~~` uses`\~~
73		-	~~` companyxyz.utils; // because unit names must be valid identifier and thus,`\~~
74		-	~~` // can't contain dots, when the compiler sees this, it knows`\~~
75		-	~~` // companyxyz. is a namespace reference.`~~
	80	+	``` pascal
	81	+	uses
	82	+	companyxyz.utils; // because unit names must be valid identifier and thus,
	83	+	// can't contain dots, when the compiler sees this, it knows
	84	+	// companyxyz. is a namespace reference.
	85	+	```
76	86
77	87		#### Pros
78	88
79	89		- Namespaces can be applied per unit or for a whole project. The unit specific namespace takes preference compared to the namespace declared as a compiler parameter.
80	90
81		-	~~` unit buttons namespace fpgui;`\~~
82		-	~~` uses`\~~
83		-	~~` Classes`\~~
84		-	~~` ...`\~~
85		-	~~` end.`~~
	91	+	``` pascal
	92	+	unit buttons namespace fpgui;
	93	+	uses
	94	+	Classes
	95	+	...
	96	+	end.
	97	+	```
86	98
87	99		- Namespaces can be applied via the compiler command line parameter so no need to modify each individual unit.
88	100
89		-	~~` fpc -namespace=fpgui buttons.pas groupbox.pas panel.pas`~~
	101	+	```text
	102	+	fpc -namespace=fpgui buttons.pas groupbox.pas panel.pas
	103	+	```
90	104
91	105		- Least amount of intrusion to existing code.
92	106		- Unit names still stay short
93	107		- Unit names are still valid identifiers (unlike the "dotted" notation of Delphi).
94	108		- If no explicit namespace is declared in the unit, or per compiler parameter, then in automatically get added to the "global" namespace, and works like FPC and Delphi prior to v2009.
95	109		- The usage of the namespace is only required when you get a unit name conflict. All other times, simply using the unit name as-is will suffice.
96	110		- When a unit references a unit in a uses clause without the namespace, then the following search priority is taken.
97	111		- "global" (or undefined) namespaces take preference. For example the RTL in FPC will not be compiled with a namespace to get higher priority. So if a project also contains a SysUtils.pas unit, the RTL's SysUtils will take preference, and the developer will have to introduce a project wide namespace.
98	112		- Then units part of a project.
99	113		- Then units defined in a namespace.
100	114
101		-	~~`// our project also has a SysUtils unit, but because RTL already has one, we`\~~
102		-	~~`// must define a namespace for it.`\~~
103		-	~~`unit SysUtils namespace myproject;`\~~
104		-	~~`uses`\~~
105		-	~~` ...`\~~
106		-	~~`end.`\~~
107		-	~~` `\~~
108		-	~~`unit mytools;`\~~
109		-	~~`uses`\~~
110		-	~~` SysUtils, // from the RTL`\~~
111		-	~~` myproject.SysUtils, // from this project / the myproject namespace.`\~~
112		-	~~` Classes;`~~
	115	+	``` pascal
	116	+	// our project also has a SysUtils unit, but because RTL already has one, we
	117	+	// must define a namespace for it.
	118	+	unit SysUtils namespace myproject;
	119	+	uses
	120	+	...
	121	+	end.
	122	+
	123	+	unit mytools;
	124	+	uses
	125	+	SysUtils, // from the RTL
	126	+	myproject.SysUtils, // from this project / the myproject namespace.
	127	+	Classes;
	128	+	```
113	129
114	130		#### Cons
115	131
116	132		- In corner cases, some ambiguities could appear (if the developer doesn't understand the preferences of namespaces).
117	133		- The name of a common RTL unit (e.g: sysutils) can be redefined. And while being fully qualified in the uses-clause "myproject.SysUtils", it could occur unqualified in the source (if only the one SysUtils was used): "SysUtils.Foo" or "SysUtils.Exception" (Exception could be redefined in myproject)
118	134
119	135
120	136		This would be confusing to any reader (other than the original author). As reading "SysUtils" will always trigger the assumption RTL
121	137
122	138		- how will the compiler know what file contains myprojects.sysutils ? It will have to index all files in the search path on every compiler start. The Java solution solves at least that, check all classpath roots for a fixed directory. ( for x in classpaths do check(x+'/myproject/sysutils').
123	139
124	140		### Suggestion 3 - directory layout
125	141
126	142		Similar to what JAVA does, by using the directory hierarchy to define the namespace.
127	143
128	144		#### Pros
129	145
130	146		- Keeps the unit names short, while still mapping the full namespace qualified name directly to a path name
131	147
132	148		- Only need a single search path to include all packages, since each package is automatically mapped to its own subdirectory
133	149
134	150		#### Cons
135	151
136	152		- I see lots of issues with this idea because FPC supports multiple search and library paths per project. So this is probably the crappiest idea. :-)
137	153
138	154		### Mapping Namespace to each search path
139	155
140	156		Each installed "package" (set of units) usually resides in a directory, and has it's own /lib or units folder for pre-compiled ppu.
141	157
142	158		This directory is added to the list of search paths.
143	159
144	160		#### Definitions / Proposals
145	161
146	162		- Terms used:
147	163
148	164		:* Package: A collection of units, grouped in one directory. (Since FPC as no real packages yet)
149	165
150	166
151	167
152	168		Examples: RTL, FCL, LCL, SynEdit, CodeTools, RxLib, ....
153	169
154	170		- Notes:
155	171
156	172		:* Unit names:
157	173
158	174
159	175
160	176		It is not encouraged to call a unit Utils. It should still be attempted to use names with a likelihood for uniqueness (such as RxUtils). The described proposal is a last resort to resolve remaining conflicts
161	177
162	178		#### Adding / Creating a Namespace / SearchPath-Alias
163	179
164	180
165	181		Current Situation; Any package used in a project must be known to FPC at compile time of the project. that is archived by adding an -Fu to either the command-line or fpc.cfg file
166	182
167	183		- Proposal 1: Extending -Fu
168	184
169	185
170	186		Allowing to specify Namespace/SearchPath-Alias together with the Path in the -Fu (or alternative a new directive -FU)
171	187
172	188		Since there is no char, that can not already be part of a directory name in a path, -Fu cannot easily be extended, so that an alias would always be detected.
173	189
174	190		Using -FU would tell the compiler, that an alias is always expected. The alias always ends at the first occurence of the separator char. e.g -FU LCL : /path/to/lcl (spaces are for readability =\> real directive, would not have spaces)
175	191
176	192		- Proposal 2: Adding a default namespace to the Lazarus *.lpk file (Lazarus would add it to the -FU)
177	193
178	194
179	195		This would be set by the supplier of the package, e.g when downloading rxlib, the people who are in charg of rxlib, would have set the default to "rxlib"
180	196
181	197		This can create conflicts in namespace,. but the user can easily change the default
182	198
183	199
184	200		If the user changes the default, and hiscode refers to the changed default, he must change the default on all installations where he uses this.
185	201
186	202		Maybe the ability override defaults, in the project settings instead should be discussed? Separate discussin...
187	203
188	204		- Proposal 3: Adding a default namespace inside one/each unit of the package (using a namespace directive, after the unit declaration)
189	205
190	206
191	207
192	208		Instead of a namespace in -FU or lpk; a namespace can be defined inside the unit(s)
193	209
194	210		Because there is no package file, this would be needed in every unit. (alternatively a unit with special name (e.g equal to the last directory name in the path ?)
195	211
196	212		Example
197	213
198	214
199	215		Unit Utils; Namespace 'RxLib'; \[1\]
200	216
201	217		Cons: As there currently is no package concept, this would be required for each unit, here would be no way to ensure all units in the path have the same (a consistent) Namespace.
202	218
203	219		Multiple namespaces in one packages may not be desirable .
204	220
205	221		- Mixing of Proposals:
206	222
207	223
208	224
209	225		-Fu (1, 2) and namespace (3) can work in parallel, -FU takes priority.
210	226
211	227		- Multiply Namespace: Needed ?
212	228
213	229		- Project overrides for conflicting Namespaces: Todo
214	230
215	231		#### The "uses" clause
216	232
217	233		- Proposal 1: using "in"
218	234
219	235
220	236
221	237		uses Utils in RxLib;
222	238
223	239
224	240		Note ther e are no quotes around the namespace, this disambiguates it from a directory of the same name, present in the project folder.
225	241
226	242		uses Utils in RxLib alias RxUtils, utils in LCL alias LCLUtils;
227	243
228	244		uses Utils in RxLib as RxUtils, utils in LCL as LCLUtils;
229	245
230	246
231	247		alias (or as / to be decided) can be used, if several units of the same name exist across several namespaces, and should all be imported.
232	248
233	249		- If no alias is given the unit is known by it's own name
234	250		- If an alias is given the unit is known by the alias, and the alias only
235	251
236	252		No 2 units must resolve to the same name
237	253
238	254		- It may be proposed, that if 2 units Utils exists, both must be aliased. Even though, if only one was aliased, they would have different names already.
239	255
240	256
241	257		But that might lead to unnecessary changes in a unit if a unit name is already used to distinguish types like in the following example:
242	258
243		-	~~`uses`\~~
244		-	~~` Windows, Graphics; // both have a type TBitmap`\~~
	259	+	``` pascal
	260	+	uses
	261	+	Windows, Graphics; // both have a type TBitmap
245	262
246		-	~~`(...)`\~~
	263	+	(...)
247	264
248		-	~~`var`\~~
249		-	~~` b1: TBITMAP; // from Windows`\~~
250		-	~~` b2: Graphics.TBitmap; // Note: for this example I assume that the first unit "wins". If FPC handles this different, then please exchange the unit in the uses clause ^^`~~
	265	+	var
	266	+	b1: TBITMAP; // from Windows
	267	+	b2: Graphics.TBitmap; // Note: for this example I assume that the first unit "wins". If FPC handles this different, then please exchange the unit in the uses clause ^^
	268	+	```
251	269
252	270
253	271
254	272		Assuming there are more usages of "Graphics.TBitmap" in that unit the addition of another Graphics unit would lead to unnecessary changes if both units must be aliased:
255	273
256		-	~~`uses`\~~
257		-	~~` Windows, Graphics in LCL, Graphics in SomeGraphicsPkg as SomeGraphics;`\~~
258		-	~~` // Note: I just picked one of the syntaxes for this example`~~
	274	+	``` pascal
	275	+	uses
	276	+	Windows, Graphics in LCL, Graphics in SomeGraphicsPkg as SomeGraphics;
	277	+	// Note: I just picked one of the syntaxes for this example
	278	+	```
259	279
260	280		- Proposal 2: Using "." (dot)
261	281
262	282
263	283
264	284		uses RxLib.Utils;
265	285
266	286		uses RxLib.Utils as RxUtils;
267	287
268	288		- Proposal 3: Using alternatively "as"/"alias" syntax
269	289
270	290
271	291
272	292		uses RxUtils=RxLib.Utils;
273	293
274	294		uses RxUtils(RxLib.Utils);
275	295
276	296		#### References in the code
277	297
278	298		In the code the unit can only be referenced by it's alias (or it's own name, if it was not aliased.
279	299
280	300		Namespace qualifiers should not be allowed in the code
281	301
282	302		Namespace qualifiers in the code can cause ambiguity, since a unit and a name of the same namespace can exist. See [Mantis report 14439](http://bugs.freepascal.org/view.php?id=14439)
283	303
284	304		Namespace qualifiers are not native pascal. Keeping their effect as low as possible (quarantined to the "uses" clause, maybe the "unit" declaration) would be desirable
285	305
286	306		#### Pros
287	307
288	308		#### Cons
289	309
290	310		### Suggestion 123 - all together
291	311
292	312		#### Proposal
293	313
294	314		Use dotted unit names with additional keywords and mapped to directory layout.
295	315
296	316		#### Example
297	317
298	318		E.g. the current classes unit would become freepascal.rtl.classes.pas
299	319
300	320		But you can also store it in a directory freepascal/rtl/classes.pas or freepascal.rtl/classes.pas to avoid cluttering a directory with a lot of files and long names.
301	321
302	322		When using it, you can use a new keyword to not write the full name for every unit.
303	323
304	324		E.g.
305	325
306		-	~~` uses with freepascal.rtl do begin classes, sysutils end, with lazarus.lcl do begin ... end, ...;`~~
	326	+	``` pascal
	327	+	uses with freepascal.rtl do begin classes, sysutils end, with lazarus.lcl do begin ... end, ...;
	328	+	```
307	329
308	330		or allow multiple uses
309	331
310		-	~~` with freepascal.rtl do uses classes, syutils;`\~~
311		-	~~` with lazarus.lcl do uses ...`\~~
312		-	~~` ...`~~
	332	+	``` pascal
	333	+	with freepascal.rtl do uses classes, syutils;
	334	+	with lazarus.lcl do uses ...
	335	+	...
	336	+	```
313	337
314	338		#### Pros
315	339
316	340		- Combines the pros of each suggestion(see above)
317	341
318	342		#### Cons
319	343
320	344		- uses with needs to be repeated in every unit + some extra keywords (WITH, DO BEGIN.. END). Savings not that great, unless you really need a lot of units from one namespace. But since FPC/Delphi allows multiple classes per unit, this will be not the case as often as in e.g. C# or Java.
321	345
322	346		## see also
323	347
324	348		- [§ “Namespaces: Dotted Units” in the Free Pascal reference guide](https://www.freepascal.org/docs-html/ref/refse112.html)
325	349
326	350		---
327	351		From the Free Pascal wiki, page "Namespaces", as it stood on 2020-08-03 after a change by BrainChemistry, 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).
328	352		Category: Proposals

Back to history