Difference between revisions of "Uses"

From Lazarus wiki
Jump to navigationJump to search
m
m (→‎syntax: fix spelling mistake)
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The '''uses''' statement is a [[declaration]] by a [[Pascal]] [[Program|program]] that it will invoke or use certain [[Procedure|procedures]], [[Function|functions]], [[object]]s, [[Const|const]]ants, [[Var|var]]iables and other items which are defined or declared in the specified [[Unit|unit]].
+
{{Uses}}
  
Every pascal program and unit has an automatic implied uses statement of
+
The <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> 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.
  
USES System;
+
<syntaxhighlight lang="pascal" inline>Uses</syntaxhighlight> is a [[Reserved word|reserved word]].
  
except in the case where a compiler [[parameter]] allows a unit to exclude a reference to the [[System]] unit. (One example of this would be if one was recompiling the System unit, it would be necessary for it not to invoke itself.)
+
== usage ==
 +
=== location ===
 +
Every Pascal module – i. e. [[Program|<syntaxhighlight lang="pascal" inline>program</syntaxhighlight>]], <syntaxhighlight lang="pascal" inline>unit</syntaxhighlight>, or <syntaxhighlight lang="pascal" inline>library</syntaxhighlight> – can have at most one <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause per section.
 +
It has to appear right after the section headings.
 +
Section headings are <syntaxhighlight lang="pascal" inline>interface</syntaxhighlight> and
 +
<syntaxhighlight lang="pascal" inline>implementation</syntaxhighlight> in a <syntaxhighlight lang="pascal" inline>unit</syntaxhighlight>.
 +
A <syntaxhighlight lang="pascal" inline>program</syntaxhighlight> does not have any explicit section headings, thus the <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause appears immediately after the <syntaxhighlight lang="pascal" inline>program</syntaxhighlight> header, but still after any [[global compiler directives]] as some may alter the <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause.
 +
 
 +
=== syntax ===
 +
The <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause consists of the word <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight>, 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 <syntaxhighlight lang="pascal" inline>program</syntaxhighlight> name may not appear in the list.
 +
Usually [[Unit|<syntaxhighlight lang="pascal" inline>unit</syntaxhighlight>]] 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:
 +
<syntaxhighlight lang="pascal">
 +
uses
 +
math, sysUtils, baseUnix;
 +
</syntaxhighlight>
 +
Furthermore, each identifier may be followed by [[In|<syntaxhighlight lang="pascal" inline>in</syntaxhighlight>]] and a string literal overriding the automatic lookup mechanism.
 +
The following will look for a <syntaxhighlight lang="pascal" inline>unit</syntaxhighlight> named <syntaxhighlight lang="pascal" inline>foo</syntaxhighlight> in the file <syntaxhighlight lang="text" inline>bar.pas</syntaxhighlight>:
 +
<syntaxhighlight lang="pascal">
 +
uses
 +
foo in 'bar.pas';
 +
</syntaxhighlight>
 +
 
 +
=== access and shadowing ===
 +
This makes identifiers exported by the listed modules, for units that means identifiers declared in the <syntaxhighlight lang="pascal" inline>interface</syntaxhighlight> 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, {{Doc|package=RTL|unit=math|identifier=ceil|text=<syntaxhighlight lang="pascal" inline>math.ceil</syntaxhighlight>}} as well as just <syntaxhighlight lang="pascal" inline>ceil</syntaxhighlight> refer to the same function (unless in the current module <syntaxhighlight lang="pascal" inline>ceil</syntaxhighlight> has been defined otherwise).
 +
 
 +
However, two or more units listed in the <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> 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 <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause can only be accessed via fully-qualified identifiers.
 +
A [[With|<syntaxhighlight lang="pascal" inline>with</syntaxhighlight>-clause]] may alleviate this situation.
 +
 
 +
=== loading and unloading ===
 +
At program start, all [[Initialization|<syntaxhighlight lang="pascal" inline>initialization</syntaxhighlight>]] statement blocks, if any, are processed in the order the units were listed in – possibly recursively.
 +
At program termination, all [[Finalization|<syntaxhighlight lang="pascal" inline>finalization</syntaxhighlight>]] are processed ''in the reverse order''.
 +
 
 +
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 {{gitlab|issue|FPC|0036754}}.
 +
 
 +
=== special units ===
 +
In FPC the [[System unit|unit <syntaxhighlight lang="pascal" inline>system</syntaxhighlight>]] is implicitly included by every program.
 +
It is wrong to explicitly list it in the <syntaxhighlight lang="pascal" inline>uses</syntaxhighlight> clause.
 +
Inclusion of the <syntaxhighlight lang="pascal" inline>system</syntaxhighlight> unit can be disabled by using the <syntaxhighlight lang="text" inline>‑Us</syntaxhighlight> compiler switch.
 +
This switch indicates/ought to indicate, that a/the system unit is about to be compiled.
 +
 
 +
== see also ==
 +
* [[Namespaces|namespaces]]
 +
* [https://www.freepascal.org/docs-html/ref/refse114.html § “Unit dependencies” in the ''Free Pascal reference guide'']

Latest revision as of 02:08, 28 January 2022

Deutsch (de) English (en) español (es) suomi (fi) français (fr) 日本語 (ja)

The uses clause of a Pascal module imports exported identifiers from another module. It was introduced by UCSD Pascal and virtually every modern Pascal compiler, including FPC, supports it, if no other mechanism is available.

Uses is a reserved word.

usage

location

Every Pascal module – i. e. 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.

syntax

The uses clause consists of the word uses, followed by a 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 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:

uses
	math, sysUtils, baseUnix;

Furthermore, each identifier may be followed by in and a string literal overriding the automatic lookup mechanism. The following will look for a unit named foo in the file bar.pas:

uses
	foo in 'bar.pas';

access and shadowing

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 as well as just ceil refer to the same function (unless in the current module ceil has been defined otherwise).

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-clause may alleviate this situation.

loading and unloading

At program start, all initialization statement blocks, if any, are processed in the order the units were listed in – possibly recursively. At program termination, all finalization are processed in the reverse order.

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.

special units

In FPC the 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.

see also