Namespaces: what changed

Revision 1 to 2. 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	13		` constants.pas`\
14	14		` utils.pas`\
15	15		` etc...`
16	16
17	17		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	18
19	19		- To reduce the chances of conflicting unit names
20	20		- 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	21		- No need for cryptic 2 or 3 letter prefixes to unit names.
22	22
23	23		## Interested Parties
24	24
25	25		- Graeme Geldenhuys
26	26		- Marcos Douglas
27	27
28	28		## Usage Examples
29	29
30	30		Please add any new ideas to the end of the list.
31	31
32	32		### Suggestion 1 - "dotted unit name notation"
33	33
34	34		Use the same style as implemented in Delphi 2009 onwards.
35	35
36	36		#### Pros
37	37
38	38		- Extends the syntax in Pascal where units are already namespaces (disambiguating two names by prefixing the unit name)
39	39		- Similar to the Ada approach of packages, much more robust than namespaces
40	40		- Delphi compatible
41	41
42	42		#### Cons
43	43
44	44		- The force rather long unit names. eg: freepascal.rtl.classes.pas
45	45		- Unit names now contain a '.' character which doesn't make them truly valid identifiers.
46	46		- 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	47
48	48		### Suggestion 2 - new keyword & new compiler parameter
49	49
50	50		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	51
52	52		#### Example
53	53
54	54		` // per unit`\
55	55		` unit utils namespace companyxyz;`\
56	56		` uses`\
57	57		` ...`\
58	58		` end.`
59	59
60	60		...or applied at compile time to all units being compiled.
61	61
62	62		` // our sample unit - as normal, nothing new`\
63	63		` unit utils;`\
64	64		` uses`\
65	65		` ...`\
66	66		` end.`
67	67
68	68		` $ fpc -namespace=companyxyz utils.pas constants.pas ...`
69	69
70	70		... if a conflict occurs, then you reference the unit with the full namespace.
71	71
72	72		` uses`\
73	73		` companyxyz.utils; // because unit names must be valid identifier and thus,`\
74	74		` // can't contain dots, when the compiler sees this, it knows`\
75	75		` // companyxyz. is a namespace reference.`
76	76
77	77		#### Pros
78	78
79	79		- 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	80
81	81		` unit buttons namespace fpgui;`\
82	82		` uses`\
83	83		` Classes`\
84	84		` ...`\
85	85		` end.`
86	86
87	87		- Namespaces can be applied via the compiler command line parameter so no need to modify each individual unit.
88	88
89	89		` fpc -namespace=fpgui buttons.pas groupbox.pas panel.pas`
90	90
91	91		- Least amount of intrusion to existing code.
92	92		- Unit names still stay short
93	93		- Unit names are still valid identifiers (unlike the "dotted" notation of Delphi).
94	94		- 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	95		- 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	96		- When a unit references a unit in a uses clause without the namespace, then the following search priority is taken.
97	97		- "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	98		- Then units part of a project.
99	99		- Then units defined in a namespace.
100	100
101	101		`// our project also has a SysUtils unit, but because RTL already has one, we`\
102	102		`// must define a namespace for it.`\
103	103		`unit SysUtils namespace myproject;`\
104	104		`uses`\
105	105		` ...`\
106	106		`end.`\
107	107		` `\
108	108		`unit mytools;`\
109	109		`uses`\
110	110		` SysUtils, // from the RTL`\
111	111		` myproject.SysUtils, // from this project / the myproject namespace.`\
112	112		` Classes;`
113	113
114	114		#### Cons
115	115
116	116		- In corner cases, some ambiguities could appear (if the developer doesn't understand the preferences of namespaces).
117	117		- 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	118
119	119
120	120		This would be confusing to any reader (other than the original author). As reading "SysUtils" will always trigger the assumption RTL
121	121
122	122		- 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	123
124	124		### Suggestion 3 - directory layout
125	125
126	126		Similar to what JAVA does, by using the directory hierarchy to define the namespace.
127	127
128	128		#### Pros
129	129
130	130		- Keeps the unit names short, while still mapping the full namespace qualified name directly to a path name
131	131
132	132		- Only need a single search path to include all packages, since each package is automatically mapped to its own subdirectory
133	133
134	134		#### Cons
135	135
136	136		- 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	137
138	138		### Mapping Namespace to each search path
139	139
140	140		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	141
142	142		This directory is added to the list of search paths.
143	143
144	144		#### Definitions / Proposals
145	145
146	146		- Terms used:
147	147
148	148		:* Package: A collection of units, grouped in one directory. (Since FPC as no real packages yet)
149	149
150	150
151	151
152	152		Examples: RTL, FCL, LCL, SynEdit, CodeTools, RxLib, ....
153	153
154	154		- Notes:
155	155
156	156		:* Unit names:
157	157
158	158
159	159
160	160		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	161
162	162		#### Adding / Creating a Namespace / SearchPath-Alias
163	163
164	164
165	165		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	166
167	167		- Proposal 1: Extending -Fu
168	168
169	169
170	170		Allowing to specify Namespace/SearchPath-Alias together with the Path in the -Fu (or alternative a new directive -FU)
171	171
172	172		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	173
174	174		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	175
176	176		- Proposal 2: Adding a default namespace to the Lazarus *.lpk file (Lazarus would add it to the -FU)
177	177
178	178
179	179		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	180
181	181		This can create conflicts in namespace,. but the user can easily change the default
182	182
183	183
184	184		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	185
186	186		Maybe the ability override defaults, in the project settings instead should be discussed? Separate discussin...
187	187
188	188		- Proposal 3: Adding a default namespace inside one/each unit of the package (using a namespace directive, after the unit declaration)
189	189
190	190
191	191
192	192		Instead of a namespace in -FU or lpk; a namespace can be defined inside the unit(s)
193	193
194	194		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	195
196	196		Example
197	197
198	198
199	199		Unit Utils; Namespace 'RxLib'; \[1\]
200	200
201		-	~~<b>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.</b>~~
	201	+	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	202
203		-	~~<b>Multiple namespaces in one packages may not be desirable .</b>~~
	203	+	Multiple namespaces in one packages may not be desirable .
204	204
205	205		- Mixing of Proposals:
206	206
207	207
208	208
209	209		-Fu (1, 2) and namespace (3) can work in parallel, -FU takes priority.
210	210
211	211		- Multiply Namespace: Needed ?
212	212
213	213		- Project overrides for conflicting Namespaces: Todo
214	214
215	215		#### The "uses" clause
216	216
217	217		- Proposal 1: using "in"
218	218
219	219
220	220
221	221		uses Utils in RxLib;
222	222
223	223
224	224		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	225
226	226		uses Utils in RxLib alias RxUtils, utils in LCL alias LCLUtils;
227	227
228	228		uses Utils in RxLib as RxUtils, utils in LCL as LCLUtils;
229	229
230	230
231	231		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	232
233	233		- If no alias is given the unit is known by it's own name
234	234		- If an alias is given the unit is known by the alias, and the alias only
235	235
236	236		No 2 units must resolve to the same name
237	237
238	238		- 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	239
240	240
241	241		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	242
243	243		`uses`\
244	244		` Windows, Graphics; // both have a type TBitmap`\
245		-	\
	245	+
246	246		`(...)`\
247		-	\
	247	+
248	248		`var`\
249	249		` b1: TBITMAP; // from Windows`\
250	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 ^^`
251	251
252	252
253	253
254	254		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	255
256	256		`uses`\
257	257		` Windows, Graphics in LCL, Graphics in SomeGraphicsPkg as SomeGraphics;`\
258	258		` // Note: I just picked one of the syntaxes for this example`
259	259
260	260		- Proposal 2: Using "." (dot)
261	261
262	262
263	263
264	264		uses RxLib.Utils;
265	265
266	266		uses RxLib.Utils as RxUtils;
267	267
268	268		- Proposal 3: Using alternatively "as"/"alias" syntax
269	269
270	270
271	271
272	272		uses RxUtils=RxLib.Utils;
273	273
274	274		uses RxUtils(RxLib.Utils);
275	275
276	276		#### References in the code
277	277
278	278		In the code the unit can only be referenced by it's alias (or it's own name, if it was not aliased.
279	279
280		-	~~<b>Namespace qualifiers should not be allowed in the code</b>~~
	280	+	Namespace qualifiers should not be allowed in the code
281	281
282	282		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	283
284	284		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	285
286	286		#### Pros
287	287
288	288		#### Cons
289	289
290	290		### Suggestion 123 - all together
291	291
292	292		#### Proposal
293	293
294	294		Use dotted unit names with additional keywords and mapped to directory layout.
295	295
296	296		#### Example
297	297
298	298		E.g. the current classes unit would become freepascal.rtl.classes.pas
299	299
300	300		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	301
302	302		When using it, you can use a new keyword to not write the full name for every unit.
303	303
304	304		E.g.
305	305
306	306		` uses with freepascal.rtl do begin classes, sysutils end, with lazarus.lcl do begin ... end, ...;`
307	307
308	308		or allow multiple uses
309	309
310	310		` with freepascal.rtl do uses classes, syutils;`\
311	311		` with lazarus.lcl do uses ...`\
312	312		` ...`
313	313
314	314		#### Pros
315	315
316	316		- Combines the pros of each suggestion(see above)
317	317
318	318		#### Cons
319	319
320	320		- 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	321
322	322		## see also
323	323
324	324		- [§ “Namespaces: Dotted Units” in the Free Pascal reference guide](https://www.freepascal.org/docs-html/ref/refse112.html)
325	325
326	326		---
327	327		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	328		Category: Proposals

Back to history