Difference between revisions of "$include"

From Lazarus wiki
Jump to navigationJump to search
m (→‎Insertion of certain information: `{$include %date%}` emits a zero-padded day number therefore the MediaWiki magic word {{CURRENTDAY2}} has to be used)
(→‎Insertion of certain information: add historical remark about fpcsubst [since it’s still out there])
 
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 15: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:

  1. at the path specified;
  2. in the directory containing the current source file;
  3. 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:

  1. none, meaning the exact name as specified (without any suffix)
  2. .inc
  3. .pp
  4. .pas
  5. (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
    • {$include %FPCTargetCPU%} expands to the target’s CPU name, e. g. 'x86_64'.
    • {$include %FPCTargetOS%} expands to the target’s OS name, e. g. 'Linux'.
  • 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. '2022/12/05'.
    • {$include %dateYear%} expands to '2022'. (Available since FPC trunk revision 38329)
    • {$include %dateMonth%} expands to '12'. (Available since FPC trunk revision 38329)
    • {$include %dateDay%} expands to '5'. (Available since FPC trunk revision 38329)
    • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. '11:50:42'.
    • {$include %timeHour%} expands to '11'. (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