docs(language): document native C types and explicit casts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

8 files changed, 62 insertions, 0 deletions

diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md
index 5c327b0..e729a6b 100644
--- a/doc/language/cpsc-language-overview.7.md
+++ b/doc/language/cpsc-language-overview.7.md
@@ -12,6 +12,8 @@ Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`,
 
 Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence.
 
+Parenthesized type casts, such as (C_INT)Number, have unary precedence. C_INT, C_CHAR, C_STRING and C_DOUBLE are native C aliases; TYPE name = C_TYPE("...") imports other supported C base types and pointers. Conversions between C and pseudocode types must be explicit. These are compiler extensions; see [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md).
+
 Literals include integers, decimal real numbers, TRUE/FALSE, strings in double quotes, and single-byte characters in single quotes. Negative numbers use unary minus. There are no string or character escape sequences. Comments begin with `//` and continue to the end of the line.
 
 Declare variables before use. See DECLARE for built-in types and arrays, TYPE for records/enumerations/pointers, and CLASS for public/private fields.
@@ -36,6 +38,7 @@ The compiler extensions TRY/CATCH/ENDTRY and THROW support anonymous exceptions
 - [cpsc-keyword-writefile(7)](keyword/cpsc-keyword-writefile.7.md): write a line to a text file.
 - [cpsc-keyword-closefile(7)](keyword/cpsc-keyword-closefile.7.md): close a text file.
 - [cpsc-keyword-type(7)](keyword/cpsc-keyword-type.7.md): define enumerations, pointers, and records.
+- [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md): import native C types and explicitly cast values.
 - [cpsc-keyword-class(7)](keyword/cpsc-keyword-class.7.md): define a class with public and private fields.
 - [cpsc-keyword-and(7)](keyword/cpsc-keyword-and.7.md): combine conditions with logical AND.
 - [cpsc-keyword-or(7)](keyword/cpsc-keyword-or.7.md): combine conditions with logical OR.
diff --git a/doc/language/keyword/cpsc-keyword-c_type.7.md b/doc/language/keyword/cpsc-keyword-c_type.7.md
new file mode 100644
index 0000000..5b8ebd3
--- /dev/null
+++ b/doc/language/keyword/cpsc-keyword-c_type.7.md
@@ -0,0 +1,46 @@
+% CPSC-KEYWORD-C_TYPE(7)
+
+# NAME
+
+cpsc-keyword-c_type - import a native C type as a pseudocode alias
+
+# SYNOPSIS
+
+```text
+TYPE name = C_TYPE("C type expression")
+(type) expression
+```
+
+# DESCRIPTION
+
+C_TYPE and parenthesized casts are compiler extensions. C_TYPE requires a string literal and appears only on the right side of a top-level TYPE declaration. C_INT, C_CHAR, C_STRING and C_DOUBLE are predefined aliases for int, char, char* and double. Imported aliases for the same C type are interchangeable, including BYREF arguments and array parameters; the original pseudocode TYPE rules remain nominal.
+
+Supported base types are _Bool; char, signed char and unsigned char; signed and unsigned short, int, long and long long; and float, double and long double. Legal C combinations such as unsigned, signed int and unsigned long int are accepted. Type spelling is case-sensitive. void is allowed for pointer pointees and function return types, but not variables, fields or parameters. Multiple pointer stars may precede or follow the base type: `"**char"` and `"char**"` are equivalent. Whitespace is allowed. Mixed star placement, const/volatile, structs, unions, C typedef names, array types, function pointers, complex types and compiler-specific types are unsupported.
+
+C widths, char signedness and floating-point formats come from the compiler's build platform. Generated programs must use the same platform ABI; cross-target compilation and EXTERN declarations are not implemented. INTEGER remains signed 64-bit, CHAR remains an unsigned byte, and REAL remains double precision. In particular, C_CHAR need not have CHAR's signedness.
+
+A cast has unary precedence and converts its following operand. Declare a type alias before using its name in a cast. Numeric, character and boolean values can be explicitly converted between pseudocode and C types. STRING can be cast to char* and back, and C pointer types can be cast to other C pointer types. Pointer/integer casts and casts involving the original pseudocode enums, records or pointer types are unsupported. Casts are values, not assignable locations.
+
+C/pseudocode assignment, argument passing and mixed arithmetic require an explicit cast, including ordinary literals: use n <- (C_INT)1 and n + (C_INT)1. Different C scalar types use C++ numeric conversions, integer promotions and usual arithmetic conversions. BYREF requires the same type and performs no conversion. Comparisons and logical operations return BOOLEAN. The / operator always performs real division and returns REAL, including with two C integer operands; DIV and MOD accept C integers after promotion. C values used directly as IF/WHILE conditions need a cast to BOOLEAN.
+
+C scalar values support INPUT and OUTPUT. Plain char prints and reads a character; signed char and unsigned char use numeric input/output. _Bool uses the existing TRUE/FALSE output and numeric input. C pointers start null and support prefix ^ for address-of, suffix ^ for dereference, and = or <> between the same C pointer type. Dereferencing null throws; void pointers cannot be dereferenced. Pointer arithmetic and direct pointer INPUT/OUTPUT are unsupported. To print a C string, cast it to STRING. STRING/char* casts share the original buffer without allocation; a null char* becomes an empty STRING. Pointer validity and writable storage remain the caller's responsibility.
+
+# EXAMPLE
+
+```text
+TYPE NativeInt = C_TYPE("int")
+TYPE NativeIntPtr = C_TYPE("*int")
+DECLARE Number : NativeInt
+DECLARE Pointer : NativeIntPtr
+DECLARE Text : C_STRING
+Number <- (C_INT)42
+Pointer <- ^Number
+Pointer^ <- Number + (C_INT)1
+Text <- (C_STRING)"Result"
+OUTPUT (STRING)Text, ": ", Number
+OUTPUT Number / (C_INT)2
+```
+
+# SEE ALSO
+
+[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-input(7)](cpsc-keyword-input.7.md), [cpsc-keyword-output(7)](cpsc-keyword-output.7.md).
diff --git a/doc/language/keyword/cpsc-keyword-declare.7.md b/doc/language/keyword/cpsc-keyword-declare.7.md
index dcaa8ce..f92471e 100644
--- a/doc/language/keyword/cpsc-keyword-declare.7.md
+++ b/doc/language/keyword/cpsc-keyword-declare.7.md
@@ -15,6 +15,8 @@ DECLARE name : ARRAY[lower:upper, ...] OF type
 
 Declare one variable per statement. Built-in types are INTEGER (signed 64-bit), REAL, BOOLEAN, CHAR (one byte), and STRING. User-defined TYPE and CLASS names are also accepted. Variables start with zero, FALSE, an empty string, or a zero-initialized user-defined value.
 
+C_INT, C_CHAR, C_STRING and C_DOUBLE are native C aliases for int, char, char* and double. C_TYPE can introduce aliases for other supported C base types and pointers. C values start with zero or null; assignment from pseudocode types requires an explicit cast. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md).
+
 ARRAY bounds are inclusive and may be expressions; multiple ranges create multiple dimensions. Access elements with `name[index, ...]`. Bounds are checked at run time; an invalid index throws an exception that TRY/CATCH can handle. Whole-array assignment is unsupported. Declare arrays before using them; arrays declared inside a control-flow block stay in that block.
 
 # EXAMPLE
diff --git a/doc/language/keyword/cpsc-keyword-div.7.md b/doc/language/keyword/cpsc-keyword-div.7.md
index af2443d..4ff774e 100644
--- a/doc/language/keyword/cpsc-keyword-div.7.md
+++ b/doc/language/keyword/cpsc-keyword-div.7.md
@@ -14,6 +14,8 @@ left DIV right
 
 Both operands must be INTEGER. Return the quotient truncated toward zero. A zero divisor throws an exception that TRY/CATCH can handle. DIV has the same precedence as multiplication. Use `/` for division returning REAL.
 
+Two C integer operands are also accepted, using C++ integer promotions and signed/unsigned conversion rules. Mixing C and pseudocode operands requires an explicit cast. The / operator still returns REAL for C operands. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md).
+
 # EXAMPLE
 
 ```text
diff --git a/doc/language/keyword/cpsc-keyword-input.7.md b/doc/language/keyword/cpsc-keyword-input.7.md
index 7bc1c73..c1ec905 100644
--- a/doc/language/keyword/cpsc-keyword-input.7.md
+++ b/doc/language/keyword/cpsc-keyword-input.7.md
@@ -14,6 +14,8 @@ INPUT variable
 
 Read into a previously declared INTEGER, REAL, BOOLEAN, CHAR, or STRING variable. STRING input reads one whitespace-delimited word. The target must be a plain variable; array elements and record/class fields are unsupported, unlike the wider INPUT syntax in guide section 5.1.
 
+Native C scalar variables are also supported, using their actual widths and signedness. Plain C char reads a character; signed/unsigned char read numbers. C _Bool reads a number and stores whether it is nonzero. C pointers, including C_STRING, cannot be INPUT targets. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md).
+
 # EXAMPLE
 
 ```text
diff --git a/doc/language/keyword/cpsc-keyword-mod.7.md b/doc/language/keyword/cpsc-keyword-mod.7.md
index 45267e2..0fa3e04 100644
--- a/doc/language/keyword/cpsc-keyword-mod.7.md
+++ b/doc/language/keyword/cpsc-keyword-mod.7.md
@@ -14,6 +14,8 @@ left MOD right
 
 Both operands must be INTEGER. Return the remainder after division truncated toward zero; a nonzero remainder has the dividend's sign. A zero divisor throws an exception that TRY/CATCH can handle. MOD has the same precedence as multiplication.
 
+Two C integer operands are also accepted, using C++ integer promotions and signed/unsigned conversion rules. A signed result follows truncation toward zero; an unsigned result uses unsigned division. Mixing C and pseudocode operands requires an explicit cast. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md).
+
 # EXAMPLE
 
 ```text
diff --git a/doc/language/keyword/cpsc-keyword-output.7.md b/doc/language/keyword/cpsc-keyword-output.7.md
index 90d4e82..3f90959 100644
--- a/doc/language/keyword/cpsc-keyword-output.7.md
+++ b/doc/language/keyword/cpsc-keyword-output.7.md
@@ -14,6 +14,8 @@ OUTPUT expression, ...
 
 Print expressions from left to right without automatic separators, then add a newline. Strings print their contents; BOOLEAN prints TRUE or FALSE. Whole arrays and partially indexed arrays print their elements one per line; a final array adds no extra newline. Records, classes, and pointers cannot be printed directly.
 
+C scalars print with their native type's format and C argument promotions. Plain char prints a character, other C integers print numbers, and _Bool prints TRUE or FALSE. C_STRING is a pointer: cast it to STRING to print its contents. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md).
+
 # EXAMPLE
 
 ```text
diff --git a/doc/language/keyword/cpsc-keyword-type.7.md b/doc/language/keyword/cpsc-keyword-type.7.md
index cdc41ff..ea9e098 100644
--- a/doc/language/keyword/cpsc-keyword-type.7.md
+++ b/doc/language/keyword/cpsc-keyword-type.7.md
@@ -9,6 +9,7 @@ cpsc-keyword-type - define enumerations, pointers, and records
 ```text
 TYPE name = (value, ...)
 TYPE name = ^type
+TYPE name = C_TYPE("C type expression")
 TYPE name
     DECLARE field : type
 ENDTYPE
@@ -22,6 +23,8 @@ A prefix caret takes an address (`^variable`); a suffix caret dereferences a poi
 
 Records contain one or more DECLARE fields and end with ENDTYPE. Access fields with a dot. Whole records copy by value; array fields are unsupported. Distinct user-defined type names remain distinct types. SET/DEFINE are reserved but unsupported.
 
+C_TYPE imports a native C type as an alias. Unlike the original enumerations, records and pointer declarations, C aliases with the same underlying C type are interchangeable. See [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md) for supported types and explicit casts.
+
 # EXAMPLE
 
 ```text