Difference between revisions of "$include"
(→Sourcing files: fix some imprecision regarding file names starting with a % sign) |
(→Insertion of certain information: add historical remark about fpcsubst [since it’s still out there]) |
||
(3 intermediate revisions by the same user not shown) | |||
Line 33: | Line 33: | ||
If a file name contains blank characters, the file name needs to be surrounded by [['|<syntaxhighlight lang="pascal" inline>'</syntaxhighlight> (typewriter quotes)]]. | If a file name contains blank characters, the file name needs to be surrounded by [['|<syntaxhighlight lang="pascal" inline>'</syntaxhighlight> (typewriter quotes)]]. | ||
− | If a file name starts with a percent sign, you must either use straight quotes as in the case of blanks, or specify an absolute or relative path like <syntaxhighlight lang="pascal" inline>{$I ./%wage.pas}</syntaxhighlight> (on UNIX-like platforms <syntaxhighlight lang="bash" inline>./</syntaxhighlight> denotes the “current directory”). | + | If a file name starts with a percent sign or asterisk, you must either use straight quotes as in the case of blanks, or specify an absolute or relative path like <syntaxhighlight lang="pascal" inline>{$I ./%wage.pas}</syntaxhighlight> (on UNIX-like platforms <syntaxhighlight lang="bash" inline>./</syntaxhighlight> denotes the “current directory”). |
Not finding a specified file constitutes a [[compile-time error|fatal error]]. | Not finding a specified file constitutes a [[compile-time error|fatal error]]. | ||
Line 57: | Line 57: | ||
* compiler information | * compiler information | ||
** <syntaxhighlight lang="pascal" inline>{$include %FPCVersion%}</syntaxhighlight> expands to the version number of the used [[FPC]], e. g. <syntaxhighlight lang="pascal" inline>'3.0.4'</syntaxhighlight>. | ** <syntaxhighlight lang="pascal" inline>{$include %FPCVersion%}</syntaxhighlight> expands to the version number of the used [[FPC]], e. g. <syntaxhighlight lang="pascal" inline>'3.0.4'</syntaxhighlight>. | ||
− | * regarding date of | + | * regarding time/date of processing the directive |
− | ** <syntaxhighlight lang="pascal" inline>{$include %date%}</syntaxhighlight> expands to a string of the form <syntaxhighlight lang="pascal" inline>'YYYY/mm/dd'</syntaxhighlight>, e. g. <code class="mw-highlight"><span class="s">'{{CURRENTYEAR}}/{{CURRENTMONTH}}/{{ | + | ** <syntaxhighlight lang="pascal" inline>{$include %date%}</syntaxhighlight> expands to a string of the form <syntaxhighlight lang="pascal" inline>'YYYY/mm/dd'</syntaxhighlight>, e. g. <code class="mw-highlight"><span class="s">'{{CURRENTYEAR}}/{{CURRENTMONTH}}/{{CURRENTDAY2}}'</span></code>. |
** <syntaxhighlight lang="pascal" inline>{$include %dateYear%}</syntaxhighlight> expands to <code class="mw-highlight"><span class="s">'{{CURRENTYEAR}}'</span></code>. (Available since FPC trunk revision 38329) | ** <syntaxhighlight lang="pascal" inline>{$include %dateYear%}</syntaxhighlight> expands to <code class="mw-highlight"><span class="s">'{{CURRENTYEAR}}'</span></code>. (Available since FPC trunk revision 38329) | ||
** <syntaxhighlight lang="pascal" inline>{$include %dateMonth%}</syntaxhighlight> expands to <code class="mw-highlight"><span class="s">'{{CURRENTMONTH}}'</span></code>. (Available since FPC trunk revision 38329) | ** <syntaxhighlight lang="pascal" inline>{$include %dateMonth%}</syntaxhighlight> expands to <code class="mw-highlight"><span class="s">'{{CURRENTMONTH}}'</span></code>. (Available since FPC trunk revision 38329) | ||
Line 66: | Line 66: | ||
** <syntaxhighlight lang="pascal" inline>{$include %timeMinute%}</syntaxhighlight> expands to the minute part of <syntaxhighlight lang="pascal" inline>{$I %time%}</syntaxhighlight>. (Available since FPC trunk revision 38329) | ** <syntaxhighlight lang="pascal" inline>{$include %timeMinute%}</syntaxhighlight> expands to the minute part of <syntaxhighlight lang="pascal" inline>{$I %time%}</syntaxhighlight>. (Available since FPC trunk revision 38329) | ||
** <syntaxhighlight lang="pascal" inline>{$include %timeSecond%}</syntaxhighlight> expands to the seconds part of <syntaxhighlight lang="pascal" inline>{$I %time%}</syntaxhighlight>. (Available since FPC trunk revision 38329) | ** <syntaxhighlight lang="pascal" inline>{$include %timeSecond%}</syntaxhighlight> expands to the seconds part of <syntaxhighlight lang="pascal" inline>{$I %time%}</syntaxhighlight>. (Available since FPC trunk revision 38329) | ||
+ | |||
+ | Historical remark: | ||
+ | Previously ''some'' information like <syntaxhighlight lang="pascal" inline>{$include %FPCVersion%}</syntaxhighlight> and <syntaxhighlight lang="pascal" inline>{$include %date%}</syntaxhighlight> could be included with the long deprecated utility {{gitlab|repository|FPC|3.3.1/utils/fpcsubst.pp|<syntaxhighlight lang="pascal" inline>fpcsubst</syntaxhighlight>}}, a macro preprocessor program. | ||
== See also == | == See also == | ||
* [https://www.freepascal.org/docs-html/prog/progsu40.html § “include file”] and [https://www.freepascal.org/docs-html/prog/progsu41.html § “include compiler info”] in the ''Free Pascal programmer’s guide'' | * [https://www.freepascal.org/docs-html/prog/progsu40.html § “include file”] and [https://www.freepascal.org/docs-html/prog/progsu41.html § “include compiler info”] in the ''Free Pascal programmer’s guide'' |
Latest revision as of 16:30, 4 October 2022
│
Deutsch (de) │
English (en) │
The compiler directive {$include}
is used to:
- read and parse a file, virtually inserting its contents at the location the directive was encountered,
- insert compiler information, or
- insert the value of an environment variable.
The {$I}
directive, case-sensitive, is shorthand for the same directive.
Sourcing files
Further tokens can be read from a file using the {$include}
directive to virtually substitute the file’s contents for the directive.
A file to be substituted for the directive is specified like this {$include magic.pas}
.
Files are searched for in the following order:
- at the path specified;
- in the directory containing the current source file;
- in all include file paths. (
-Fi
or-I
compiler parameters.)
When specifying a file name, a file type hint suffix can be omitted. If you omit a suffix, the following suffixes are tried out:
- none, meaning the exact name as specified (without any suffix)
.inc
.pp
.pas
- (trailing dot stripped)
This strategy applies to every directory in the search path as described above, and the first match is taken.
For Delphi compatibility, the special file name *
will attempt to include a file of the current file’s base name.
The suffix is supplemented as described above.
You can, however, specify a (different) suffix too:
{$include *.dat}
will look for a file bearing same name as the source file, but the suffix (if applicable) will be replaced by (or augmented with) .dat
.
The suffix is the last component of a file name separated by a .
(dot) (thus {$I *.foo.bar.dat}
is effectively the same as {$I *.dat}
).
Note, if you are reading a file via a symbolic link, the supplied unresolved name is the source code file’s name, not the target file name.
If a file name contains blank characters, the file name needs to be surrounded by '
(typewriter quotes).
If a file name starts with a percent sign or asterisk, you must either use straight quotes as in the case of blanks, or specify an absolute or relative path like {$I ./%wage.pas}
(on UNIX-like platforms ./
denotes the “current directory”).
Not finding a specified file constitutes a fatal error.
Insertion of certain information
The compiler can be instructed to insert certain information at a specific spot.
For that, a word is surrounded by %
like in {$include %internalVariable%}
.
This directive always inserts strings (except {$include %lineNum%}
).
A set of predefined variables are consulted first. If there is no predefined variable of a given name, the value of the environment variable of the given name is tried to be retrieved.
If this process fails, an empty string is inserted in order to provide a consistent behavior.
The set of predefined variables are (case-insensitive):
- location information
{$include %currentRoutine%}
expands to the current routine’s name. (available since FPC trunk revision 30873; FPC 3.2.0){$include %file%}
expands to the file’s name the directive is found in.{$include %line%}
expands to the line number (starting at 1) where the directive is found at.{$include %lineNum%}
is the same as{$I %line%}
but of an integer type.
- target information
- compiler information
{$include %FPCVersion%}
expands to the version number of the used FPC, e. g.'3.0.4'
.
- regarding time/date of processing the directive
{$include %date%}
expands to a string of the form'YYYY/mm/dd'
, e. g.'2024/05/07'
.{$include %dateYear%}
expands to'2024'
. (Available since FPC trunk revision 38329){$include %dateMonth%}
expands to'05'
. (Available since FPC trunk revision 38329){$include %dateDay%}
expands to'7'
. (Available since FPC trunk revision 38329){$include %time%}
expands to a string of the form'HH:MM:SS'
, e. g.'00:13:42'
.{$include %timeHour%}
expands to'00'
. (Available since FPC trunk revision 38329){$include %timeMinute%}
expands to the minute part of{$I %time%}
. (Available since FPC trunk revision 38329){$include %timeSecond%}
expands to the seconds part of{$I %time%}
. (Available since FPC trunk revision 38329)
Historical remark:
Previously some information like {$include %FPCVersion%}
and {$include %date%}
could be included with the long deprecated utility fpcsubst
, a macro preprocessor program.
See also
- § “include file” and § “include compiler info” in the Free Pascal programmer’s guide