Difference between revisions of "$include"

From Free Pascal wiki
(Insertion of certain information: Made title accurate - it is not just date info!)
(expand information)
Line 1: Line 1:
 
{{Template:{{ROOTPAGENAME}}}}
 
{{Template:{{ROOTPAGENAME}}}}
 
The [[Compiler directive|compiler directive]] <syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> is used to:
 
The [[Compiler directive|compiler directive]] <syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> is used to:
 
 
* read and parse a file, virtually inserting its contents at the location the directive was encountered,
 
* read and parse a file, virtually inserting its contents at the location the directive was encountered,
 
* insert compiler information, or
 
* insert compiler information, or
 
* insert the value of an environment variable.
 
* insert the value of an environment variable.
  
The <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight>, case-''sensitive'', is shorthand for the same directive.
+
The <syntaxhighlight lang="pascal" inline>{$I}</syntaxhighlight> directive, case-''sensitive'', is shorthand for the same directive.
  
 
== Sourcing files ==
 
== Sourcing files ==
 
 
Further tokens can be read from a file using the <syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> directive to virtually substitute the file’s contents for the directive.
 
Further tokens can be read from a file using the <syntaxhighlight lang="pascal" inline>{$include}</syntaxhighlight> directive to virtually substitute the file’s contents for the directive.
A file to be substituted for the directive is specified like this <syntaxhighlight lang="pascal" inline>{$include magic.pas}</syntaxhighlight>.
+
A file to be substituted for the directive is specified like this <syntaxhighlight lang="pascal" inline>{$include magic.pas}</syntaxhighlight>.
The suffix <syntaxhighlight lang="text" inline>.pas</syntaxhighlight> or <syntaxhighlight lang="text" inline>.pp</syntaxhighlight> can be omitted.
 
 
 
The special file name [[Asterisk|<syntaxhighlight lang="bash" inline>*</syntaxhighlight>]] will attempt to include a file of the current module’s name.
 
  
 
Files are searched for in the following order:
 
Files are searched for in the following order:
 
 
# at the path specified;
 
# at the path specified;
 
# in the directory containing the current source file;
 
# in the directory containing the current source file;
 
# in all include file paths. (<syntaxhighlight lang="bash" inline>-Fi</syntaxhighlight> or <syntaxhighlight lang="bash" inline>-I</syntaxhighlight> compiler parameters.)
 
# in all include file paths. (<syntaxhighlight lang="bash" inline>-Fi</syntaxhighlight> or <syntaxhighlight lang="bash" inline>-I</syntaxhighlight> compiler parameters.)
  
Not finding a specified file constitutes a fatal error.
+
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)
 +
# <syntaxhighlight lang="text" inline>.inc</syntaxhighlight>
 +
# <syntaxhighlight lang="text" inline>.pp</syntaxhighlight>
 +
# <syntaxhighlight lang="text" inline>.pas</syntaxhighlight>
 +
# (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 [[Asterisk|<syntaxhighlight lang="bash" inline>*</syntaxhighlight>]] 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:
 +
<syntaxhighlight lang="pascal" inline>{$include *.dat}</syntaxhighlight> will look for a file bearing same name as the source file, but the suffix (if applicable) will be replaced by (or augmented with) <syntaxhighlight lang="text" inline>.dat</syntaxhighlight>.
 +
The suffix is the ''last'' component of a file name separated by a [[period|<syntaxhighlight lang="bash" inline>.</syntaxhighlight> (dot)]] (thus <syntaxhighlight lang="pascal" inline>{$I *.foo.bar.dat}</syntaxhighlight> is effectively the same as <syntaxhighlight lang="pascal" inline>{$I *.dat}</syntaxhighlight>).
 +
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 or starts with a percent sign, the file name needs to be surrounded by [['|<syntaxhighlight lang="pascal" inline>'</syntaxhighlight> (typewriter quotes)]].
 +
 
 +
Not finding a specified file constitutes a [[compile-time error|fatal error]].
  
 
== Insertion of certain information ==
 
== Insertion of certain information ==
 
 
The compiler can be instructed to insert certain information at a specific spot.
 
The compiler can be instructed to insert certain information at a specific spot.
 
For that, a word is surrounded by [[Percent sign|<syntaxhighlight lang="pascal" inline>%</syntaxhighlight>]] like in <syntaxhighlight lang="pascal" inline>{$include %internalVariable%}</syntaxhighlight>.
 
For that, a word is surrounded by [[Percent sign|<syntaxhighlight lang="pascal" inline>%</syntaxhighlight>]] like in <syntaxhighlight lang="pascal" inline>{$include %internalVariable%}</syntaxhighlight>.
Line 56: Line 67:
  
 
== 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''

Revision as of 23:45, 17 January 2021

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 or starts with a percent sign, the file name needs to be surrounded by ' (typewriter quotes).

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 date of invocation of the compiler
    • {$include %date%} expands to a string of the form 'YYYY/mm/dd', e. g. '2021/05/14'.
    • {$include %dateYear%} expands to '2021'. (Available since FPC trunk revision 38329)
    • {$include %dateMonth%} expands to '05'. (Available since FPC trunk revision 38329)
    • {$include %dateDay%} expands to '14'. (Available since FPC trunk revision 38329)
    • {$include %time%} expands to a string of the form 'HH:MM:SS', e. g. '22:48:42'.
    • {$include %timeHour%} expands to '22'. (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)

See also