From 5a67f4e3833c2acca4a351f5dd613bc08f04bfc0 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Sun, 18 Oct 2026 06:11:42 +0000 Subject: feat(operators): document overloads and cover remaining operator forms Add fixed cases for every supported operator, imported global and member operators, CASE comparisons, and declared result type errors. Document syntax, exact matching, access rules and temporary receiver lifetimes. Co-Authored-By: Claude Opus 5.5 --- doc/language/cpsc-language-overview.7.md | 5 ++- doc/language/keyword/cpsc-keyword-operator.7.md | 59 +++++++++++++++++++++++++ doc/language/keyword/cpsc-keyword-overload.7.md | 2 + 3 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 doc/language/keyword/cpsc-keyword-operator.7.md (limited to 'doc/language') diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md index 2e2a393..a66ce69 100644 --- a/doc/language/cpsc-language-overview.7.md +++ b/doc/language/cpsc-language-overview.7.md @@ -8,7 +8,9 @@ cpsc-language-overview - supported cpsc pseudocode syntax Keywords are uppercase and case-sensitive. Identifiers, including built-in function names, are case insensitive. Indentation is for readability; blocks use explicit closing keywords. Identifiers begin with a letter and continue with letters, digits, or underscores. -Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`, `<=`, and `>=`. STRING comparisons compare contents, case-sensitively. Use `+`, `-`, `*`, and `/` for arithmetic; `/` always returns REAL. Use `&` to join strings. +Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`, `<=`, and `>=`. Built-in STRING comparisons compare contents, case-sensitively. Use `+`, `-`, `*`, and `/` for arithmetic; built-in `/` always returns REAL. Use `&` to join strings. + +User-defined types can overload operators with OVERLOAD FUNCTION OPERATOR; expressions then use the declared result type. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md). STRING cannot be implicitly converted to BOOLEAN. Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence. @@ -38,6 +40,7 @@ Multi-file builds use the compiler extensions INCLUDE and GLOBAL. Pass every sou - [cpsc-keyword-for(7)](keyword/cpsc-keyword-for.7.md): iterate over an integer range. - [cpsc-keyword-function(7)](keyword/cpsc-keyword-function.7.md): define a function that returns a value. - [cpsc-keyword-procedure(7)](keyword/cpsc-keyword-procedure.7.md): define a procedure and parameter modes. +- [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md): overload unary and binary operators. - [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.7.md): explicitly overload functions, procedures and constructors. - [cpsc-keyword-call(7)](keyword/cpsc-keyword-call.7.md): invoke a procedure. - [cpsc-keyword-openfile(7)](keyword/cpsc-keyword-openfile.7.md): open a text file. diff --git a/doc/language/keyword/cpsc-keyword-operator.7.md b/doc/language/keyword/cpsc-keyword-operator.7.md new file mode 100644 index 0000000..5ba3999 --- /dev/null +++ b/doc/language/keyword/cpsc-keyword-operator.7.md @@ -0,0 +1,59 @@ +% CPSC-KEYWORD-OPERATOR(7) + +# NAME + +cpsc-keyword-operator - overload unary and binary operators + +# SYNOPSIS + +```text +OVERLOAD FUNCTION OPERATOR+(left : T, right : U) RETURNS R + statements +ENDFUNCTION +CLASS T + OVERLOAD FUNCTION OPERATOR+(right : U) RETURNS R + statements + ENDFUNCTION + OVERLOAD FUNCTION OPERATOR-() RETURNS R + statements + ENDFUNCTION +ENDCLASS +``` + +# DESCRIPTION + +OPERATOR is a compiler extension, absent from the CIE guide. Declare operators with OVERLOAD FUNCTION, at top level or inside CLASS. OPERATOR is reserved; whitespace before the operator is optional. Parentheses are required. Parameters and return values follow FUNCTION rules: parameters default to BYVAL, BYREF is forbidden, and omitting RETURNS defaults to INTEGER. Whole-array operands and array results are unsupported. + +Binary operators are `+ - * / DIV MOD & = <> < <= > >= AND OR`. Unary operators are `- NOT`. A global binary definition takes two parameters and a unary definition takes one; at least one parameter must be a record, class or enum. A pointer alias alone does not qualify. A member binary definition takes one explicit parameter and a unary definition takes none; this supplies the left or sole operand. PUBLIC and PRIVATE precede OVERLOAD as for other methods. + +Operands match exact static types, without implicit conversions, following OVERLOAD rules. For example, an INTEGER operand does not match a REAL parameter. Visible global definitions and methods of the left operand's class participate together; multiple matching candidates are an error. The selected method must be accessible: PRIVATE never causes a public fallback. Included units provide operators using the ordinary INCLUDE visibility rules. Return types do not distinguish overloads. + +The expression has the selected function's declared return type. Comparisons and logic may return any supported function result type: a comparison returning STRING can be printed or assigned to STRING, but cannot be implicitly used as BOOLEAN. CASE comparisons must return BOOLEAN. A VOID result may be discarded through an explicit call but cannot be used as a value. + +Operators keep their existing precedence, operand count and associativity. Operands are evaluated once, from left to right; overloaded AND and OR evaluate both operands. Operators are independent: defining = does not define <>, and operands are never swapped to find a match. A matching overload takes precedence over the built-in operation; otherwise the existing built-in rules apply. + +Member operators on variables, fields, array elements and pointer dereferences modify the original receiver. Class-valued expressions can also receive operator calls, supporting chains such as `(A + B) + C`. A temporary receiver follows the compiler's existing function-scoped object cleanup rules, rather than C++ full-expression lifetimes. Copies and return values retain the ordinary class value semantics. + +Explicit calls use `OPERATOR+(A, B)` for global definitions and `A.OPERATOR+(B)` for members. They also work as statements, optionally prefixed with CALL, to discard results. As with ordinary method calls, explicit member access on a function result is unsupported. Assignment, indexing, function-call, address-of and dereference operators cannot be overloaded. + +# EXAMPLE + +```text +CLASS Box + Value : INTEGER + OVERLOAD FUNCTION OPERATOR+(Right : INTEGER) RETURNS Box + DECLARE Result : Box + Result.Value <- Value + Right + RETURN Result + ENDFUNCTION +ENDCLASS +DECLARE Item : Box +DECLARE Sum : Box +Item.Value <- 3 +Sum <- (Item + 2) + 4 +OUTPUT Sum.Value +``` + +# SEE ALSO + +[cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-include(7)](cpsc-keyword-include.7.md). diff --git a/doc/language/keyword/cpsc-keyword-overload.7.md b/doc/language/keyword/cpsc-keyword-overload.7.md index f7df69f..21ba7b7 100644 --- a/doc/language/keyword/cpsc-keyword-overload.7.md +++ b/doc/language/keyword/cpsc-keyword-overload.7.md @@ -32,6 +32,8 @@ Overloads may be defined in separate input files. A caller sees only its own and Methods use the same rules; fields and methods cannot share a name. Constructor calls select NEW by their explicit arguments. DECLARE without arguments, class-valued fields and array elements select a parameterless NEW; if NEW exists but has no matching parameterless overload, compilation fails. PRIVATE checks apply to the selected method or constructor. +Operator definitions use OVERLOAD FUNCTION OPERATOR followed by the operator symbol or keyword. They support global and member forms with exact operand types; see [cpsc-keyword-operator(7)](cpsc-keyword-operator.7.md). + # EXAMPLE ```text -- cgit v1.3.1-4-g156e