Preprocess C preprocessor directives in the input text.

This function handles:

• Macro definitions (#define) and expansion
• Conditional compilation (#if, #ifdef, #ifndef, #elif, #else, #endif)
• File inclusion (#include)
• Diagnostics (#warning, #error)
• Line control (#line)
• Predefined macros (FILE, LINE, DATE, TIME)

Macro expansion

Object-like macros are expanded in the output:

>>> let Done r = preprocess defaultConfig "#define FOO 42\nThe answer is FOO"
>>> T.putStr (resultOutput r)
#line 1 "<input>"

The answer is 42

Function-like macros are also supported:

>>> let Done r = preprocess defaultConfig "#define MAX(a,b) ((a) > (b) ? (a) : (b))\nMAX(3, 5)"
>>> T.putStr (resultOutput r)
#line 1 "<input>"

((3) > (5) ? (3) : (5))

Conditional compilation

Conditional directives control which sections of code are included:

>>> :{
let Done r = preprocess defaultConfig
      "#define DEBUG 1\n#if DEBUG\ndebug mode\n#else\nrelease mode\n#endif"
in T.putStr (resultOutput r)
:}
#line 1 "<input>"


debug mode

Include handling

When an #include directive is encountered, preprocess returns a NeedInclude step. The caller must provide the contents of the included file:

>>> :{
let NeedInclude req k = preprocess defaultConfig "#include \"header.h\"\nmain code"
    Done r = k (Just "-- header content")
in T.putStr (resultOutput r)
:}
#line 1 "<input>"
#line 1 "./header.h"
-- header content
#line 2 "<input>"
main code

If the include file is not found, pass Nothing to emit an error:

>>> :{
let NeedInclude _ k = preprocess defaultConfig "#include \"missing.h\""
    Done r = k Nothing
in do
  T.putStr (resultOutput r)
  mapM_ print (resultDiagnostics r)
:}
#line 1 "<input>"
Diagnostic {diagSeverity = Error, diagMessage = "missing include: missing.h", diagFile = "<input>", diagLine = 1}

Diagnostics

The #warning directive emits a warning:

>>> :{
let Done r = preprocess defaultConfig "#warning This is a warning"
in do
  T.putStr (resultOutput r)
  mapM_ print (resultDiagnostics r)
:}
#line 1 "<input>"

Diagnostic {diagSeverity = Warning, diagMessage = "This is a warning", diagFile = "<input>", diagLine = 1}

The #error directive emits an error and stops preprocessing:

>>> :{
let Done r = preprocess defaultConfig "#error Build failed\nthis line is not processed"
in do
  T.putStr (resultOutput r)
  mapM_ print (resultDiagnostics r)
:}
#line 1 "<input>"

Diagnostic {diagSeverity = Error, diagMessage = "Build failed", diagFile = "<input>", diagLine = 1}

Configuration for the C preprocessor.

Default configuration with sensible defaults.

• configInputFile is set to "<input>"
• configMacros includes DATE and TIME set to the Unix epoch

To customize the date and time macros:

>>> import qualified Data.Map.Strict as M
>>> let cfg = defaultConfig { configMacros = M.fromList [("__DATE__", "\"Mar 15 2026\""), ("__TIME__", "\"14:30:00\"")] }
>>> configMacros cfg
fromList [("__DATE__","\"Mar 15 2026\""),("__TIME__","\"14:30:00\"")]

To add additional macros while keeping the defaults:

>>> import qualified Data.Map.Strict as M
>>> let cfg = defaultConfig { configMacros = M.insert "VERSION" "42" (configMacros defaultConfig) }
>>> M.lookup "VERSION" (configMacros cfg)
Just "42"

A step in the preprocessing process. Either preprocessing is complete (Done) or an #include directive needs to be resolved (NeedInclude).

The result of preprocessing.

Information about a pending #include that needs to be resolved.

The kind of #include directive.

A diagnostic message emitted during preprocessing.

Severity level for diagnostics.