Uses: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: Uses
| Old | New | Line | |
|---|---|---|---|
| 1 | + | The `uses` clause of a Pascal module imports exported [[Identifier|identifiers]] from another module. It was introduced by [[UCSD Pascal]] and virtually every modern Pascal [[Compiler|compiler]], including [[FPC]], supports it, if no other mechanism is available. | |
| 2 | + | ||
| 3 | + | `Uses` is a [[Reserved word|reserved word]]. | |
| 4 | + | ||
| 5 | + | ## usage | |
| 6 | + | ||
| 7 | + | ### location | |
| 8 | + | ||
| 9 | + | Every Pascal module – i. e. [[Program|program]], `unit`, or `library` – can have at most one `uses` clause per section. It has to appear right after the section headings. Section headings are `interface` and `implementation` in a `unit`. A `program` does not have any explicit section headings, thus the `uses` clause appears immediately after the `program` header, but still after any [[global compiler directives]] as some may alter the `uses` clause. | |
| 10 | + | ||
| 11 | + | ### syntax | |
| 12 | + | ||
| 13 | + | The `uses` clause consists of the word `uses`, followed by a [[Comma|comma]]-separated list of module names, which is terminated by a [[;|semicolon]]. The modules listed in the clause have to be capable of *exporting* identifiers, that means a `program` name may not appear in the list. Usually [[Unit|unit]] names are listed in the clause. The module name of the module, that is about to be defined, can not appear in the list. Example: | |
| 14 | + | ||
| 15 | + | ``` pascal | |
| 16 | + | uses | |
| 17 | + | math, sysUtils, baseUnix; | |
| 18 | + | ``` | |
| 19 | + | ||
| 20 | + | Furthermore, each identifier may be followed by [[In|in]] and a string literal overriding the automatic lookup mechanism. The following will look for a `unit` named `foo` in the file `bar.pas`: | |
| 21 | + | ||
| 22 | + | ``` pascal | |
| 23 | + | uses | |
| 24 | + | foo in 'bar.pas'; | |
| 25 | + | ``` | |
| 26 | + | ||
| 27 | + | ### access and shadowing | |
| 28 | + | ||
| 29 | + | This makes identifiers exported by the listed modules, for units that means identifiers declared in the `interface` section, known in the current module. Either the fully-qualified identifier which is prefixed by the module name, and just the identifier’s stem can be used to refer to the same identifier. For instance, [`math.ceil`](https://www.freepascal.org/docs-html/rtl/math/ceil.html) as well as just `ceil` refer to the same function (unless in the current module `ceil` has been defined otherwise). | |
| 30 | + | ||
| 31 | + | However, two or more units listed in the `uses` clause might declare the same identifier. Then, only the identifier declared by the unit later in the list can be referred to using the short notation. Identifiers declared by earlier units in the `uses` clause can only be accessed via fully-qualified identifiers. A [[With|with-clause]] may alleviate this situation. | |
| 32 | + | ||
| 33 | + | ### loading and unloading | |
| 34 | + | ||
| 35 | + | At program start, all [[Initialization|initialization]] statement blocks, if any, are processed in the order the units were listed in – possibly recursively. At program termination, all [[Finalization|finalization]] are processed *in the reverse order*. | |
| 36 | + | ||
| 37 | + | If initialization fails, only units that have been initialized so far are finalized. The main block of a program is not executed at all. Confer also [FPC issue 0036754](https://gitlab.com/freepascal.org/fpc/source/-/issues/0036754). | |
| 38 | + | ||
| 39 | + | ### special units | |
| 40 | + | ||
| 41 | + | In FPC the [[System unit|unit system]] is implicitly included by every program. It is wrong to explicitly list it in the `uses` clause. Inclusion of the `system` unit can be disabled by using the `‑Us` compiler switch. This switch indicates/ought to indicate, that a/the system unit is about to be compiled. | |
| 42 | + | ||
| 43 | + | ## see also | |
| 44 | + | ||
| 45 | + | - [[Namespaces|namespaces]] | |
| 46 | + | - [§ “Unit dependencies” in the *Free Pascal reference guide*](https://www.freepascal.org/docs-html/ref/refse114.html) | |
| 47 | + | ||
| 48 | + | --- | |
| 49 | + | *From the Free Pascal wiki, page "Uses", as it stood on 2022-01-28 after a change by Kai Burghardt, 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).* |