Add minimal C++ Portal (.prtl) compiler pipeline and CLI

[Copilot]

Portal is defined as a semantic-native AOT systems language with .prtl source and a staged compiler pipeline (lexing → parsing map table → AST → semantic adjustment → optimization → IR → LLVM-ASM hybrid lowering → executable emission).
This PR introduces a compact C++ reference implementation of that pipeline and documents how to build and run it.

• Compiler baseline (portal.cpp)

  • Adds a single-file C++ compiler entrypoint for .prtl programs.
  • Implements:
    • lexical analysis (including Portal-specific tokens like #, ;, --, and // ... ;)
    • parser-map-table style statement parsing with semicolon-terminated boundaries
    • AST representation (Program/Statement)
    • semantic adjuster stage hook
    • optimizer stage (empty-statement cleanup)
    • IR lowering and LLVM-ASM hybrid output-image stage placeholder
  • Produces output artifact alongside input (<input>.prtl.out).

• CLI behavior

  • Supports:
    • portal <file.prtl> for compilation
    • portal --self-test for a built-in pipeline smoke path
  • Enforces .prtl extension for source input.

• Documentation updates (README.md)

  • Replaces placeholder README with concise build/run/self-test instructions.
  • Describes implemented pipeline coverage and scope.

Example usage:

g++ -std=c++20 -O2 -Wall -Wextra -pedantic portal.cpp -o portal
./portal example.prtl
./portal --self-test

Original prompt

Implement this in C++

Portal (.prtl)

Industrial Canonical Edition

Portal is a native-speed Ahead-of-Time systems programming language built around computerized grammar, virtual syntax, universal semantics, and conditional-oriented execution.

File extension:

.prtl

Portal transforms expressive human-structured source code into aggressively optimized native machine execution through a semantic compiler architecture that lowers source into LLVM-ASM hybrid infrastructure before emitting portable executables.

Portal is designed for:

native systems software

runtime engines

rendering infrastructure

parallel execution systems

simulation frameworks

operating-level tooling

high-performance applications

game engines

AI execution environments

machine-oriented orchestration

native desktop platforms

compiler infrastructure

executable automation systems

Portal combines:

strong static typing

machine-oriented execution

semantic-driven compilation

compiler-friendly structure

conditional logic flow

deterministic parsing

modern readable syntax

aggressive optimization

universal interoperability

compile-time abstraction dissolution

semantic inference systems

intrinsic runtime tuning

into one cohesive industrial language architecture.

---

Executive Identity

Portal is a semantic-native systems language.

It is designed around the principle:

“Human-readable structure should become direct machine-executable intent.”

Portal eliminates excessive punctuation, symbolic clutter, and abstraction overhead while preserving full systems-level power and native performance.

Portal programs compile:

.prtl
→ lexical analysis
→ parsing map table
→ AST
→ semantic adjuster
→ optimizer
→ IR
→ LLVM-ASM hybrid lowering
→ code generator
→ portable executable

The compiler architecture is designed to maximize:

optimization visibility

semantic deduction

deterministic execution

native interoperability

compile-time reasoning

executable efficiency

---

Core Language Philosophy

Portal is based on:

Conditional-Oriented Execution

Execution is structured around:

conditional flow

semantic routing

contextual logic

layered resolution

execution legality

flow deduction

Programs are interpreted semantically before they are lowered structurally.

---

Universal Semantics

Portal does not rely solely on token sequences.

Instead, the compiler uses:

semantic interpretation

contextual deduction

parser layering

structural analysis

execution profiling

compiler-side inference

to determine executable meaning.

---

Virtual Syntax

Portal syntax is intentionally flexible internally while remaining deterministic externally.

The language uses:

semantic interpretation

compiler-guided restructuring

contextual matching

structural folding

inference layering

instead of punctuation-heavy grammar models.

---

Metal-Driven Rulesets

Portal’s legality system is machine-oriented.

Rules are determined through:

executable validity

opcode legality

optimizer visibility

memory safety boundaries

target architecture rules

profiling analysis

execution feasibility

---

Typing System

Portal is:

strongly typed

statically typed

compiler-verified

inference-assisted

Typing is explicit where necessary and inferred where safe.

Primitive implementation details remain abstracted beneath the semantic layer.

---

Hidden Primitive Architecture

Portal internally supports primitives such as:

bool

char

int

float

enums

flows

constructs

val

var

init

but their low-level representation is abstracted behind compiler semantics.

The programmer works with expressive structures while the compiler manages primitive realization internally.

---

Syntax Philosophy

Portal intentionally minimizes punctuation.

Symbols only exist where they improve:

compiler determinism

structural clarity

semantic distinction

execution legality

Everything else is handled through:

indentation

semantic grouping

contextual interpretation

parser inference

---

Core Structural Symbols

Comments

Portal comments use:

// comment ;

Comments terminate formally with:

;

This preserves deterministic parsing.

---

Statement Closers

Portal uses:

;

as the authoritative closure marker.

Example:

val health = 400 ;

Benefits:

deterministic token boundaries

parser acceleration

simplified AST segmentation

reduced ambiguity

---

Preprocessors

Portal preprocessors use:

Example:

#link graphics ;
#import renderer ;
#profile aggressive ;

Preprocessors operate at compiler level.

---

Active Indentation

Indentation is semantic.

Indentation directly affects:

scope ownership

parser hierarchy

execution grouping

optimization visibility

semantic layering

Example:

flow combat ;

if enemy.visible ;

    attack enemy ;

else ;

    reposition ;

;

---

Unsafe Regions

Unsafe execution is explicitly marked using:

--

Example:

-- raw.memory.write address value ;

or:

-- inline.asm ;

...