Definition

Include file handling and resolution for the fpx Fortran preprocessor

This module implements robust and standard-compliant processing of #include directives with full support for:

Both forms: #include "file.h" (local/user) and #include <file.h> (system)
Proper search order: quotes search source dir first, angle brackets skip source dir
Relative paths resolved against the directory of the parent source file
Search in user-defined include directories (globalincludedir)
Search in system PATH environment variable directories
Fallback to current working directory
Proper error reporting with file name and line number context
Recursion safety through integration with the main preprocessor loop
Seamless integration via the abstract preprocess procedure pointer

The routine correctly strips quotes or angle brackets, performs path resolution, checks file existence, opens the file, and recursively invokes the main preprocessing engine on the included content using the same macro environment.

Search Order

For #include "file":

Directory of the parent source file
Directories specified by -I or -Y options (globalincludedir)
Directories in INCLUDE environment variable
Current working directory

For #include <file>:

Directories specified by -I or -Y options (globalincludedir)
Directories in INCLUDE environment variable
Current working directory

Examples

Include a local header from the same directory using quotes:
#include

!> fpx will look for ./config.h relative to the current source file first
Include a system header using angle brackets:
#include <stdlib.h>

!> fpx will skip the source directory and search -I paths, then PATH
Using from the driver program (adding include paths):
global%includedir = ['/usr/include', './include', './headers']

call preprocess('main.F90', 'main.f90')

!> All #include <...> will search these directories in order
Verbose error reporting when a file is not found:
$ fpx -v src/utils.F90

Error: Cannot find include file 'missing.h' at src/utils.F90:27

Data Types
interface	read_unit
	Abstract interface for the main preprocessing routine (used for recursion) Allows handle_include to recursively call the top-level preprocess_unit routine without creating circular module dependencies. More...

Methods

◆ get_system_paths()

character(:) function, dimension(:), allocatable get_system_paths

private

Get system include paths from PATH environment variable Returns an array of directory paths found in PATH.

Returns: Array of path strings, empty if PATH not set

Remarks

Definition at line 238 of file include.f90.

◆ handle_include()

recursive subroutine, public handle_include	(	character(*), intent(in)	input,
		integer, intent(in)	ounit,
		character(*), intent(in)	parent_file,
		integer, intent(in)	iline,
		procedure(read_unit)	preprocess,
		type(macro), dimension(:), intent(inout), allocatable	macros,
		character(*), intent(in)	token )

Process a include directive encountered during preprocessing Resolves the include file name (quoted or angle-bracketed), searches for the file using standard C preprocessor rules:

Quoted includes search: parent directory, -I paths, PATH, cwd
Angle bracket includes search: -I paths, PATH, cwd (skips parent directory) Opens the file and recursively preprocesses its contents into the output unit.

Parameters

[in]	input	Full line containing the include directive
[in]	ounit	Output unit where preprocessed content is written
[in]	parent_file	Path of the file containing the include
[in]	iline	Line number in parent file (for error messages)
[in]	preprocess	Procedure pointer to the main line-by-line preprocessor
[in,out]	macros	Current macro table (shared across recursion levels)
[in]	token	Usually 'INCLUDE' – the directive keyword