Using CPP and HEADER Keywords for direct C++ Integration

[jarroddavis68]

🚀 Direct C++ Integration - New cpp and header Keywords

Version: JetPascal 0.2.0+

📢 Overview

We're excited to announce two powerful new language features that give you direct control over C++ code generation in JetPascal:

1. cpp...end blocks - Emit raw C++ code exactly as written
2. header declarations - Control which C++ headers get included

These features bridge the gap between high-level Pascal syntax and low-level C++ control, giving you the best of both worlds.

🎯 Purpose & Design Goals

Why Direct C++ Emission?

JetPascal transpiles Pascal to C++, but sometimes you need to:

• Use C++ library features not yet wrapped in Pascal
• Optimize critical code with hand-tuned C++
• Interface with existing C++ code directly
• Prototype features before adding full Pascal support
• Leverage C++23 features like std::print, std::format, etc.

Instead of forcing you to edit generated C++ files (which get overwritten on recompile), JetPascal now lets you embed C++ directly in your Pascal source.

Why Manual Header Control?

The compiler automatically includes common headers, but you might need:

• Third-party library headers (<raylib.h>, <SDL2/SDL.h>)
• Standard library features not yet auto-detected (<iostream>, <vector>)
• Fine-grained control over what gets included
• Platform-specific headers (<windows.h>, <unistd.h>)

🔧 The cpp...end Block

Syntax

cpp
  // Raw C++ code here
  // Emitted exactly as written
end;

Key Features

✅ Exact Emission - Whitespace, indentation, everything preserved
✅ No Processing - JetPascal doesn't parse or validate the C++ code
✅ Line Directives - Automatic #line directives for debugging
✅ Access to Context - Can reference Pascal variables in scope

Where You Can Use It

cpp blocks work anywhere statements are allowed:

✅ Inside Program Main Block

program Example;
begin
  WriteLn('Pascal code');
  
  cpp
    std::cout << "C++ code" << std::endl;
  end;
  
  WriteLn('Back to Pascal');
end.

✅ Inside Functions/Procedures

function Calculate(): Integer;
begin
  Result := 0;
  
  cpp
    // Directly manipulate Result
    Result = 42;
  end;
end;

✅ Inside Any Begin..End Block

if condition then
begin
  cpp
    // C++ code in conditional block
    std::cout << "Condition was true!" << std::endl;
  end;
end;

Important Rules

⚠️ Avoid using end keyword - The block terminates at the first end keyword
⚠️ Headers are your responsibility - Use header directive to include what you need
⚠️ C++ compiler catches errors - Syntax errors show up at C++ compile time

Examples

Example 1: Using STL Containers

program STLExample;

header '<iostream>';
header '<vector>';

begin
  WriteLn('Creating vector in C++...');
  
  cpp
    std::vector<int> numbers = {1, 2, 3, 4, 5};
    for (auto n : numbers) {
      std::cout << n << " ";
    }
    std::cout << std::endl;
  end;
  
  WriteLn('Done!');
end.

Example 2: Performance-Critical Code

function FastCalculation(const AData: Pointer; const ASize: Integer): Double;
begin
  cpp
    // Hand-optimized C++ for critical loop
    auto* data = static_cast<double*>(AData);
    double sum = 0.0;
    for (int i = 0; i < ASize; ++i) {
      sum += data[i] * data[i];
    }
    return sum / ASize;
  end;
end;

Example 3: Platform-Specific Code

procedure ShowConsole();
begin
  cpp
    #ifdef _WIN32
      ShowWindow(GetConsoleWindow(), SW_SHOW);
    #else
      // Linux/Mac: console always visible
    #endif
  end;
end;

📦 The header Directive

Syntax

header '<system_header>';   // System header with angle brackets
header '"user_header.h"';   // User header with quotes

Key Features

✅ Automatic Deduplication - Same header listed multiple times? No problem
✅ Sorted Output - Headers emitted in consistent order
✅ Top of File - Always placed at the beginning of generated C++

Where You Can Use It

header directives work in two places:

✅ At Compilation Unit Level

program Example;

header '<iostream>';
header '<vector>';
header '"mylib.h"';

begin
  // Your code here
end.

unit MyUnit;

interface
  header '<string>';
  
  function Test(): string;

implementation
  header '<sstream>';
  
  function Test(): string;
  begin
    // Implementation
  end;

end.

library MyLib;

header '<windows.h>';

function LibFunc(): Integer; cdecl;
begin
  Result := 42;
end;

exports
  LibFunc;

end.

✅ Inside Begin..End Blocks

begin
  header '<cmath>';
  
  cpp
    double result = std::sqrt(144.0);
  end;
end.

Format Validation

The header directive is strict about format:

✅ Valid:

header '<iostream>';      // System header
header '"myheader.h"';    // User header

❌ Invalid:

header 'iostream';        // Missing angle brackets
header 'myheader.h';      // Missing quotes
header '<iostream';       // Unclosed bracket

Examples

Example 1: Multiple Headers

program MultiHeader;

header '<iostream>';
header '<vector>';
header '<algorithm>';
header '<string>';

begin
  WriteLn('Headers included!');
end.

Example 2: Third-Party Libraries

program RaylibGame;

header '<raylib.h>';

begin
  cpp
    InitWindow(800, 600, "My Game");
    while (!WindowShouldClose()) {
      BeginDrawing();
      ClearBackground(BLACK);
      DrawText("Hello, Raylib!", 190, 200, 20, WHITE);
      EndDrawing();
    }
    CloseWindow();
  end;
end.

Example 3: Conditional Headers

program PlatformHeaders;

cpp
  #ifdef _WIN32
end;

header '<windows.h>';

cpp
  #else
end;

header '<unistd.h>';

cpp
  #endif
end;

begin
  WriteLn('Platform-specific headers included');
end.

🔄 How They Work Together

Generated C++ Output

Pascal Source:

program Example;

header '<iostream>';
header '<vector>';

var
  X: Integer;

begin
  X := 42;
  
  WriteLn('Before C++');
  
  cpp
    std::cout << "X = " << X << std::endl;
    std::vector<int> nums = {1, 2, 3};
  end;
  
  WriteLn('After C++');
end.

Generated C++ (simplified):

// Generated by JetPascal Compiler
// Requires: C++23 or later

#include "runtime.h"
#include <iostream>
#include <string>
#include <vector>

int main(int argc, char* argv[])
{
  jp::internal::SetCommandLine(argc, argv);
  jp::internal::InitializeConsole();

  int X;
  X = 42;
  
  std::println("Before C++");
  
  #line 14 "Example.pas"
    std::cout << "X = " << X << std::endl;
    std::vector<int> nums = {1, 2, 3};
  
  std::println("After C++");
  
  return 0;
}

The Pipeline

1. Parse - JetPascal parses header and cpp tokens
2. Register - Headers collected in master list (deduplicated)
3. Emit - Pascal code transpiled to C++, cpp blocks copied verbatim
4. Inject - Headers inserted at top of file
5. Compile - Zig compiles the final C++ to executable

💡 Best Practices

DO:

✅ Use header to declare all C++ dependencies
✅ Keep cpp blocks small and focused
✅ Add comments explaining what the C++ code does
✅ Test C++ code separately if it's complex
✅ Use cpp blocks for prototyping new features

DON'T:

❌ Put end keyword inside C++ code (terminates the block)
❌ Forget to include required headers
❌ Write entire programs in cpp blocks (defeats the purpose!)
❌ Assume Pascal variables have specific C++ names (check generated code)
❌ Rely on implementation details of the transpiler

🎓 Use Cases

1. Library Integration

Quickly wrap C/C++ libraries before full Pascal bindings exist.

2. Performance Tuning

Hand-optimize critical inner loops while keeping the rest in Pascal.

3. Feature Prototyping

Try out C++23 features before adding them to the Pascal language.

4. Platform-Specific Code

Embed platform-specific APIs without complex conditional compilation.

5. Debugging

Insert debug prints or breakpoints in generated C++ code.

6. Interfacing with Existing Codebases

Call into existing C++ code without writing full binding layers.

📝 Technical Notes

Semicolon Handling

• At program level: header directive consumes its own semicolon
• Inside begin..end: Parent block consumes the semicolon
• cpp blocks: No semicolon after end (treated as statement)

Line Directives

cpp blocks automatically emit #line directives:

#line 15 "MyProgram.pas"
    std::cout << "C++ code" << std::endl;

This ensures:

• C++ compiler errors point to correct Pascal source line
• Debuggers show the right source location
• Stack traces reference Pascal files

Header Deduplication

Headers are automatically deduplicated and sorted:

header '<iostream>';
header '<vector>';
header '<iostream>';  // Duplicate - ignored

Generates:

#include <iostream>
#include <string>
#include <vector>

🚦 Status & Compatibility

Status: ✅ Fully Implemented
Since: JetPascal 0.2.0
Tested: Programs, Units, Libraries
Platform: All supported targets (native, cross-compile)

🤝 Feedback Welcome!

These features are brand new! We'd love to hear:

• How are you using cpp and header?
• What problems are they solving for you?
• What additional features would make them more useful?
• Any bugs or unexpected behavior?

Drop your thoughts in the comments below! 👇

Happy Coding! 🚀

JetPascal™ - Accelerate Your Code!