Language Feature Matrix¶
This matrix is the user-facing support index for native-language features. It points each feature to its user guide, evidence, and limitations. Start with C Support for the complete C workflow, or the User Guide for the broader Fortran workflow.
A row may claim support only when the linked evidence proves that behavior in the current repository. Runtime wrapper support requires compiled, imported, and called wrapper tests. Parser or semantic support alone is listed as inspection-only or partial support.
At A Glance¶
PRIK wraps Fortran and C code. Fortran supports the broader language surface; C wrappers support target-probed primitive functions and authored pointer, array, and string contracts. C Support defines that exact C boundary.
| Capability | Fortran | C |
|---|---|---|
| Primitive arguments and results | Supported for all documented kinds | Supported for target-probed arithmetic and C99 complex types, including void results |
| NumPy arrays | Supported with documented rank, shape, layout, stride, and mutation contracts | Supported for ranks 1–15 with primitive non-Boolean elements and C-contiguous storage |
| Strings | Supported for scalars and fixed-width arrays | Supported for rank-zero inputs and caller-owned storage |
| Procedures and API shaping | Functions, subroutines, modules, state, optional arguments, generics, and defined operators | Externally linked functions, output and status projection, renaming, argument reordering, and dtype/rank overloads |
| Pointers and managed storage | Allocatable arrays are supported; pointer arrays are partially supported | One-level primitive pointer parameters support scalar addresses, rank-zero storage, projected results, and arrays |
| Callbacks | Supported for immediate call-scoped use | Unsupported |
| User-defined types and global state | Scalar derived types support fields, methods, constructors, and finalizers; arrays of derived types remain unsupported | struct, union, and global-state wrappers are unsupported |
The detailed rows below add the owning docs, evidence, and exact limitation for each feature. Each status group separates Fortran, C, and shared capabilities where they apply.
Status Meanings¶
| Status | Meaning |
|---|---|
| Supported | The documented subset has current runtime or inspection evidence. |
| Partially supported | A useful subset is implemented and tested, but important related forms are blocked or deferred. |
| Unsupported | PRIK intentionally blocks the form or has no safe wrapper contract for it yet. |
Supported Runtime Features¶
Fortran¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
| Primitive scalar and array calls | Supported | Data types, arrays, functions, subroutines | Scalar runtime evidence, array runtime evidence | Native scalar arguments require exact NumPy dtypes where documented. |
| Generic procedure interfaces | Supported | Generic interfaces | Generic interface tests | Defined operators and assignment are tracked separately. |
| Defined operators and assignment overloads | Supported | Defined operators | Defined operator tests | Supported operators are those covered by the wrapper guide and runtime tests. |
| Output arguments and multiple results | Supported | Subroutine projection | Calls and results tests, function result tests | Tuple ordering and caller-provided array behavior follow the wrapper guide. |
| Optional arguments | Supported | Optional arguments | Optional argument tests | Unsupported optional combinations fail during wrapper planning. |
| Allocatable array handles, descriptor arguments, and owned results | Supported | Allocatables | Allocatable runtime tests, scalar-derived matrix tests | Array module/field handles borrow their owner; result handles own persistent descriptor storage. Wrapper-owned scalar-derived allocatables use typed holders; module scalar allocatables use reversible move_alloc transactions for compatible dummies. |
| Pointer scalar projections and array handles | Partially supported | Pointers | Pointer handle tests, pointer policy tests, scalar-derived matrix tests | Descriptor arguments, module/field handles, strided views, wrapper-owned pointer-array results and outputs, scalar-derived pointer holders, and module pointer reassociation transactions are supported. Target deallocation and writable reassociation remain policy-gated. |
| Array-valued function results | Supported | Array results | Array result tests | Ownership and dtype/shape behavior are limited to documented array result forms. |
| NumPy array argument contracts | Supported | Arrays | Array contract tests, multidimensional tests | Wrong dtype, rank, shape, contiguity, alignment, or mutability is rejected. |
| Derived-type scalar boundaries and methods | Supported | Derived types | Derived boundary tests, method tests | Derived-type arrays and some polymorphic forms are not included. |
| Default and keyword constructors with finalizers | Supported | Constructors and finalizers | Constructor/finalizer tests, borrowed finalizer tests | Construction commits ownership only after initialization; borrowed wrappers never run an owning finalizer. |
| Generic constructor interfaces and overloaded runtime initialization | Supported | Constructors | Edited class surface tests, class policy tests | Candidates require distinguishable completed Python signatures; incomplete or ambiguous sets are blocked before emission. |
| Module variables, constants, saved state, and common-block procedure state | Supported | Wrapping modules | Module state tests, scalar-derived matrix tests, common-block tests | Common-block storage is not exported as Python variables. Rank-zero derived module objects use direct, scoped, allocation-transaction, or pointer-transaction handoff selected before lowering. character module state is supported in every form: a declared-length scalar reads and writes as str at exactly its declared byte width, an allocatable or pointer scalar reads as a detached str or None, and arrays reach Python as fixed-width bytes. Only declared-length non-descriptor scalars are writable by assignment; descriptor scalars are read-only snapshots for numeric and character state alike, and arrays are mutated in place through their view or handle rather than rebound. |
| Fortran enum constants | Supported | Enumerations | Enum runtime tests, enum semantic tests, enum diagnostics | No Python Enum or IntEnum classes are generated. |
| Scalar character arguments, results, and fields | Supported | Strings | Character argument tests, edge-case tests | Character arrays use fixed-width NumPy bytes dtype. Scalar character allocatable and pointer values are supported for intent(in), intent(out), intent(inout), and function results, at deferred (len=:) and declared (len=n) length; a mutable dummy returns the value the procedure left behind, or None. PRIK frees the target it allocated for the call while it can still prove that identity, but never a target the procedure reassociated or the library owns; a procedure that returns a fresh allocation each call leaks unless it frees its own. |
| Character arrays and caller-supplied deferred-length character storage | Supported | Strings | Character edge tests | Character arrays use fixed-width NumPy bytes dtype, whose width each accessor reports from the Fortran declaration; Unicode/object arrays are unsupported. Scalar character allocatable and pointer values work for every intent and as function results. A mutable pointer dummy that the native procedure reassociates without deallocating orphans the target the adapter allocated for that call. A deferred-length character(len=:), allocatable module array does not build under GNU Fortran 11.4, which raises an internal compiler error on that declaration. |
| Scalar kind coverage | Supported | Data types | Scalar kind tests | Real and complex storage wider than the target's long double is blocked; real(10) and C long double map to NumPy longdouble. All logical kinds are supported and adapt to one-byte NumPy Booleans at the boundary. |
| Multi-source builds, Makefiles, verbose mode, and output placement | Supported | Building the shared library | Multi-source tests, compiler verbose tests | Wrapped project sources compile in dependency order derived from their module/use graph, falling back to the given order when a compiled source was not parsed. PRIK does not discover sources you did not name, prebuilt module paths, or external libraries. |
| Visibility, naming, keyword escaping, and collision policy | Supported | Generic interfaces | Visibility/naming tests | Strict mode rejects names that default mode can normalize. |
| Immediate call-scoped Python callbacks | Supported | Callbacks | Callback plan tests, scalar callback tests, array callback tests, combined shape tests | Direct wrapper-plan generation supports entering-thread callbacks only. Stored, optional, asynchronous, or cross-thread callbacks are unsupported. |
| Runtime error projection, GIL policy, recursion, OpenMP path, and GNU ABI checks | Supported | Error handling | Status projection runtime, status and GIL lowering, recursion tests, OpenMP tests, ABI tests | OpenMP and ABI evidence is compiler/platform-specific; callers still own native synchronization. |
| Fortran source wrapper builds | Supported | Building the shared library | Build modes, runtime ABI | Implemented for ordered Fortran source inputs. |
value arguments and existing bind(C) procedures |
Supported | Data types | value and bind(C) tests |
Existing bind(C) support is deliberately ABI-guarded. |
Opaque bind(C) and sequence derived-type layout through accessors |
Supported | Derived types | Derived layout tests | C struct layout access is not enabled. |
C¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
| Primitive scalar calls | Supported | Build a scalar C function | C scalar runtime | Covers target-probed arithmetic and C99 complex scalars, including void results. Public NumPy dtypes remain canonical while the native boundary preserves exact C scalar identities. |
| One-level primitive pointer parameters | Supported | Choose the pointer contract | Pointer contracts | Covers scalar addresses, rank-zero storage, projected results, and C-contiguous arrays. Pointer results, multi-level pointers, and nullable or ownership-sensitive pointers remain unsupported. |
| NumPy array arguments | Supported | Author a contract for pointers and arrays | Pointer contracts | Covers ranks 1–15 with primitive non-Boolean elements and C-contiguous storage. PRIK validates dtype, rank, shape, layout, and writeability before the call. |
| Rank-zero C strings | Supported | Pass C strings | String contracts | Covers string inputs and caller-owned rank-zero storage. Arrays of strings remain unsupported. |
| Output, status, naming, and overload projection | Supported | Rename and reorder arguments, return several outputs, raise Python exceptions, overload sets | Projection and overload evidence, hidden-output and status evidence | Covers hidden outputs, status projection, symbol renaming, argument reordering, typed literals, derived lengths and shapes, and overload sets distinguishable by dtype and rank. |
| C source, header, and semantic-contract builds | Supported | Build and inspect APIs | C build pipeline, collision forwarder | Supports ordinary compiler preprocessing, including standard includes and macros, plus explicit native dependencies. A selected collision adapter isolates a binding-header name conflict; it is not an ABI fallback. |
Inspection And Contract Support¶
Fortran¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
Fortran parse, semantic IR, and .pyi inspection |
Supported | CLI commands | Fortran parser fixtures, Fortran semantic tests | Inspection support does not by itself prove runtime wrapper support. |
Semantic .pyi wrapper builds from explicit native artifacts |
Partially supported | Editing .pyi contracts |
format and authoritative-input tests, multi-source contract tests, native build plan tests | Source/generated/modified multi-source package parity is covered. Support is limited to contract forms with linked build evidence; no general parity claim is made for every source-supported Fortran feature. |
| Scalar inheritance and polymorphic dispatch | Partially supported | Inheritance and polymorphic input | Inheritance tests | Abstract types wrap as non-instantiable Python base classes and deferred bindings resolve through the caller's concrete type. Polymorphic results, mutable dummies, arrays, allocatable/pointer scalars, and class(*) are blocked. |
| Assumed-size, assumed-rank, and lower-bound array contracts | Partially supported | Arrays | Assumed-rank tests | Assumed type and derived-type arrays remain blocked. Character arrays require fixed-width NumPy bytes dtype. |
C¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
C parse, semantic IR, and .pyi inspection |
Partially supported | C Support | C parser fixtures, C semantic tests | Parser coverage is broader than the supported C wrapper subset; parser acceptance is not a runtime-support claim. |
Shared¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
| Generated wrapper API documentation | Partially supported | Editing .pyi contracts |
Documentation reference checks, semantic contract tests | Published guides cover the shared generated surface; automatic per-symbol reference generation has not been selected. |
Unsupported Or Blocked Forms¶
PRIK normally blocks these before code generation and reports the boundary and the reason, rather than emitting a wrapper that could lose precision, corrupt memory, or outlive its native storage. Parameterized derived types are the documented diagnostic-stage exception below.
Fortran¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
| Unproved pointer lifetime and ownership-changing operations | Unsupported | Pointer safety | Pointer policy tests, pointer runtime tests | Native targets must outlive every handle use; allocation, target deallocation, resize, and writable reassociation require explicit completed policy. |
| Persistent callbacks and procedure pointers | Unsupported | Callback limitations | Callback policy tests, scalar callback tests | Callbacks are valid only during the wrapped call. |
| Advanced multi-source dependency discovery and external-library integration | Unsupported | Multiple source files | Multi-source tests | PRIK does not discover sources you did not name, prebuilt module search paths, or external libraries. Dependency ordering among the sources it parses is supported. |
| Blocked array forms | Unsupported | Arrays | Array semantic tests, diagnostics | Assumed type type(*), arrays of derived types, and character arrays not representable as fixed-width bytes need missing runtime contracts. |
| Unsupported polymorphic forms | Unsupported | Inheritance limits | Inheritance tests | Results, mutable dummies, arrays, polymorphic allocatable/pointer scalars, and class(*) are blocked. Abstract types and deferred bindings are supported. |
| Ambiguous or incomplete constructor overload sets | Unsupported | Constructor limitations | Constructor semantic tests, class-plan validation tests | Candidates must have distinguishable exact runtime signatures and compatible native-owner lifecycles. A Fortran interface <typename> is wrapped as the type's overloaded constructor. |
| Parameterized derived types | Unsupported | Fortran support boundaries | Parameterized-declaration parsing | The parser preserves the declaration and its parameter expressions, but wrapper semantics do not model type parameters. A build can currently reach compiler probing and surface a raw compiler diagnostic instead of a PRIK diagnostic. |
Real and complex storage wider than the target long double |
Unsupported | Datatype limits | Scalar kind tests | PRIK compares the compiler-measured mantissa against the target's long double instead of trusting storage size, which alone cannot separate x87 extended precision from IEEE binary128. real(16) is blocked on an x87 target; real(10) and C long double are supported. |
C¶
| Feature | Status | User docs | Evidence | Limitations |
|---|---|---|---|---|
| Callbacks and function pointers | Unsupported | C Support | C policy blockers, prebuild callback rejection | C callback and function-pointer parameters may be parsed, but wrapper policy rejects them before planning. |
| Aggregates, global state, and enum constants | Unsupported | C Support | Aggregate, global-state, and enum rejection | struct and union wrappers, native global state, and enum constants are not exposed by C wrappers. |
| Variadics, local symbols, qualifiers, and calling conventions | Unsupported | C Support | C policy blockers, prebuild qualifier and declaration rejection | Variadic functions, static symbols, volatile or _Atomic values, and unsupported calling conventions fail before wrapper planning. |
| Pointer results and ownership-sensitive pointers | Unsupported | C Support | Pointer policy blockers, prebuild raw-address rejection | Pointer results, multi-level pointers, raw or nullable pointers, and APIs with retained or ownership-sensitive pointers are unsupported. |
| Unsupported C array and string forms | Unsupported | C Support | Array policy blockers, string contract blockers | Arrays of strings, Boolean arrays, native C array declarators, ranks outside 1–15, and non-C-contiguous arrays are unsupported. |