From 63109537383fa58c6a1db95f275d6b5de63b0015 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 28 Oct 2026 13:41:26 +0000 Subject: docs(overload): document default return selection Co-Authored-By: Claude Opus 5.5 --- AGENTS/CONVENTIONS/CALLS.md | 2 +- AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md | 2 +- AGENTS/PITFALLS/core-language.md | 4 +-- AGENTS/PITFALLS/overload-template-operator.md | 12 +++++-- AGENTS/SUBSYSTEMS/FUNCTIONS.md | 10 ++++-- doc/language/cpsc-language-overview.7.md | 3 +- .../function/cpsc-function-num_to_str.7.md | 7 ++-- .../function/cpsc-function-str_to_num.7.md | 14 +++++--- doc/language/keyword/cpsc-keyword-default.7.md | 42 ++++++++++++++++++++++ doc/language/keyword/cpsc-keyword-function.7.md | 2 +- doc/language/keyword/cpsc-keyword-operator.7.md | 2 +- doc/language/keyword/cpsc-keyword-overload.7.md | 6 ++-- doc/language/keyword/cpsc-keyword-procedure.7.md | 2 +- doc/language/keyword/cpsc-keyword-template.7.md | 2 +- plugin/AGENTS/ARCH.md | 5 +-- 15 files changed, 89 insertions(+), 26 deletions(-) create mode 100644 doc/language/keyword/cpsc-keyword-default.7.md diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md index 55b3647..df3d61d 100644 --- a/AGENTS/CONVENTIONS/CALLS.md +++ b/AGENTS/CONVENTIONS/CALLS.md @@ -29,7 +29,7 @@ bridge C void* and nominal pseudocode pointer types. prototypes are pre-registered too. - OVERLOAD link names append canonical parameter types, plus `:ReturnKey` for non-VOID results (NEW and OPERATOR<- excepted); ordinary names except MAIN get no mangling. - An expression's expected result type filters overloads when present. Overload sets, + An expression's expected result type filters overloads when present. Without a result context, a DEFAULT return resolves return-only ambiguity within one name and canonical parameter signature. Overload sets, visibility filtering and exact selection: [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution). - `emitPrototype` rejects builtin and enum names. Ordinary non-EXTERN, non-OVERLOAD diff --git a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md index 6c869cf..79f1a88 100644 --- a/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md +++ b/AGENTS/CONVENTIONS/TEMPLATES_AND_OPERATORS.md @@ -45,7 +45,7 @@ Part of [Load-bearing conventions](../CONVENTIONS.md). Basic call resolution is - Both getExprTypeInfo and emission must consult this resolver with the expression's result context before hardcoded builtin result types. A strict context requires the overload's return type to match exactly; a cast only prefers it; without a context, - return-only-distinct candidates are ambiguous. Returns may be any supported function + return-only-distinct candidates need a unique DEFAULT return. Defaults never resolve parameter-signature or global/member ties. Returns may be any supported function result, including non-BOOLEAN comparisons/logic. emitCoercedExpr still rejects a direct STRING to BOOLEAN conversion; CASE requires BOOLEAN comparisons. - Operators use shared argument marshalling and exception-aware calls. Member diff --git a/AGENTS/PITFALLS/core-language.md b/AGENTS/PITFALLS/core-language.md index 5018fb3..05793e7 100644 --- a/AGENTS/PITFALLS/core-language.md +++ b/AGENTS/PITFALLS/core-language.md @@ -32,8 +32,8 @@ source, most also by compiling and running test programs. - **`/` always yields REAL** (double FDiv), even for two INTEGERs; integer division is DIV/MOD only. - CHR returns CHAR, not STRING; CHR(0) is a NUL CHAR that converts to a one-byte STRING. - - STR_TO_NUM always returns REAL and shares parseNumber (strtod, full consumption, overflow rejected, only `0-9 . e E + -` after leading whitespace, so no nan/inf/hex) with IS_NUM and INPUT REAL (`__cps_parse_real` in InputGen.cc); change them together. - - NUM_TO_STR keeps the full signed i64 range for INTEGER; REAL uses the shortest + - STR_TO_NUM defaults to REAL and shares parseNumber (strtod, full consumption, overflow rejected, only `0-9 . e E + -` after leading whitespace, so no nan/inf/hex) with IS_NUM and INPUT REAL (`__cps_parse_real` in InputGen.cc); change them together. Its INTEGER overload applies INT to the parsed REAL, inheriting REAL rounding and truncating toward zero with a range check. + - NUM_TO_STR defaults to STRING; its CHAR overload uses the same text and requires length 1. It keeps the full signed i64 range for INTEGER; REAL uses the shortest round-trip text (realText in string.cc), byte-identical to OUTPUT's IR helper in OutputGen.cc (`__cps_output_real`); change both together. C_DOUBLE output keeps `%f`. - **`getExprTypeInfo` returns nullptr** for expressions it can't classify (null-check diff --git a/AGENTS/PITFALLS/overload-template-operator.md b/AGENTS/PITFALLS/overload-template-operator.md index f4a52ad..909e5f7 100644 --- a/AGENTS/PITFALLS/overload-template-operator.md +++ b/AGENTS/PITFALLS/overload-template-operator.md @@ -13,7 +13,11 @@ Part of the [pitfalls index](../PITFALLS.md). functions still coerce arguments. A known expected result type (assignment, BYVAL argument, RETURN, condition, subscript, CASE comparison) must match the overload's return type exactly; `(T) x` only prefers T and otherwise converts. Without a - context, return-only-distinct candidates are ambiguous. + context, return-only-distinct candidates need one DEFAULT return or remain ambiguous. + DEFAULT never resolves competing parameter signatures. +- Each name and canonical parameter signature permits only one DEFAULT return, + including across invisible units; different parameter signatures may each have + their own. Only non-VOID OVERLOAD functions accept RETURNS DEFAULT. - Call visibility filters the set, but duplicate signatures (parameters and return type) conflict across all inputs. MAIN and builtins cannot be overloaded. - NEW supports overloads; DECLARE, fields and arrays needing default construction @@ -33,7 +37,8 @@ Part of the [pitfalls index](../PITFALLS.md). - Packs are final non-array parameters and expand only in call/constructor argument lists; pack fields are rejected, including in variadic classes. - Unsupported: non-type parameters, SIZEOF..., member/operator templates, - specialization, bare injected class name, pointer-alias templates. Pointer-linked + specialization, bare injected class name, pointer-alias templates, DEFAULT + returns (including methods in class templates). Pointer-linked generic containers remain unsupported; use fixed fields or other supported value layouts. - Class instances follow ordinary constructor rules, so a parameterized NEW alone does @@ -53,7 +58,8 @@ Part of the [pitfalls index](../PITFALLS.md). - Exact matching considers visible globals and left-class members together, and the result type joins the match when the context supplies one; ties are errors, including private/public ties. Without a context, return-only-distinct candidates - are ambiguous; casts only prefer their target type. + need a unique DEFAULT return or remain ambiguous; defaults do not resolve + global/member ties, and casts only prefer their target type. - Comparison and logic result types are declared, not assumed BOOLEAN; a strict BOOLEAN context requires an overload returning BOOLEAN. CASE comparisons must return BOOLEAN. AND/OR overloads evaluate both operands. diff --git a/AGENTS/SUBSYSTEMS/FUNCTIONS.md b/AGENTS/SUBSYSTEMS/FUNCTIONS.md index 134ee8b..9555f1d 100644 --- a/AGENTS/SUBSYSTEMS/FUNCTIONS.md +++ b/AGENTS/SUBSYSTEMS/FUNCTIONS.md @@ -29,8 +29,14 @@ internal __cps_main). overload-set map (`FunctionGen::getOverloads`, filtered by unit visibility). - `resolveCall` selects exact static parameter types/ranks for OVERLOAD. When the call site has an expected result type, the candidate must also return exactly that type; - a cast only prefers it. Without a context, return-only-distinct candidates are - ambiguous. A single ordinary definition keeps implicit conversions. + a cast only prefers it. Without a context, return-only-distinct candidates use + the unique DEFAULT return, otherwise they are ambiguous. A single ordinary definition keeps implicit conversions. +- `RETURNS DEFAULT type` records IsDefaultReturn on PrototypeAST and FuncSig. + Only non-VOID OVERLOAD functions support it; templates reject it. Registration + rejects two defaults for one name and ParamKey across all input units. + FunctionGen::selectDefaultReturn is shared by call and operator resolution; it + only resolves candidates with the same name and ParamKey, preserving parameter + ambiguity and global/member ties. Defaults do not affect link names. - Parameter keys exclude return types, modes and bounds; the separate ReturnKey holds the declared result (PROCEDURE is VOID). Equivalent C aliases use CIdentity. Duplicate signatures require both keys to match, even across invisible units. diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md index 559a58d..da4d821 100644 --- a/doc/language/cpsc-language-overview.7.md +++ b/doc/language/cpsc-language-overview.7.md @@ -10,7 +10,7 @@ Keywords are uppercase and case-sensitive. Ordinary identifiers, including built Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`, `<=`, and `>=`. Standard-library 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. OVERLOAD definitions may also differ by return type: a context that requires a result type selects the matching return type, while a cast only prefers it. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md) and [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.7.md). STRING cannot be implicitly converted to BOOLEAN. Typing is strict: arithmetic and unary minus accept only INTEGER and REAL, a comparison needs operands of the same type (or INTEGER with REAL), and BOOLEAN, CHAR and INTEGER never convert into one another implicitly (only INTEGER converts to REAL). Use ASC and CHR to move between CHAR and INTEGER. CHAR and STRING do convert implicitly: a CHAR becomes a one-character STRING in `&`, in comparisons, in assignment, in argument passing and in RETURN, and a STRING becomes a CHAR in assignment, argument passing and RETURN (for example `c <- MID(s, i, 1)`); a STRING whose length is not 1 is a runtime error that TRY/CATCH can catch. REAL never converts to INTEGER implicitly; use INT. +User-defined types can overload operators with OVERLOAD FUNCTION OPERATOR; expressions then use the declared result type. OVERLOAD definitions may also differ by return type: a context that requires a result type selects the matching return type, while a cast only prefers it. `RETURNS DEFAULT type` selects a default when context cannot choose among return-only overloads. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.7.md) and [cpsc-keyword-overload(7)](keyword/cpsc-keyword-overload.7.md). STRING cannot be implicitly converted to BOOLEAN. Typing is strict: arithmetic and unary minus accept only INTEGER and REAL, a comparison needs operands of the same type (or INTEGER with REAL), and BOOLEAN, CHAR and INTEGER never convert into one another implicitly (only INTEGER converts to REAL). Use ASC and CHR to move between CHAR and INTEGER. CHAR and STRING do convert implicitly: a CHAR becomes a one-character STRING in `&`, in comparisons, in assignment, in argument passing and in RETURN, and a STRING becomes a CHAR in assignment, argument passing and RETURN (for example `c <- MID(s, i, 1)`); a STRING whose length is not 1 is a runtime error that TRY/CATCH can catch. REAL never converts to INTEGER implicitly; use INT. Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence. @@ -47,6 +47,7 @@ PP_DEFINE and PP_UNDEF control file-local, case-sensitive preprocessor switches. - [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-default(7)](keyword/cpsc-keyword-default.7.md): choose a default return type for an overload. - [cpsc-keyword-template(7)](keyword/cpsc-keyword-template.7.md): define function, procedure and class templates with type packs. - [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/function/cpsc-function-num_to_str.7.md b/doc/language/function/cpsc-function-num_to_str.7.md index 8e895ee..9d9c071 100644 --- a/doc/language/function/cpsc-function-num_to_str.7.md +++ b/doc/language/function/cpsc-function-num_to_str.7.md @@ -7,13 +7,16 @@ cpsc-function-num_to_str - convert a number to text # SYNOPSIS ```text -NUM_TO_STR(number : INTEGER or REAL) RETURNS STRING +NUM_TO_STR(number : INTEGER or REAL) RETURNS DEFAULT STRING +NUM_TO_STR(number : INTEGER or REAL) RETURNS CHAR ``` # DESCRIPTION Provided by the standard string library, loaded and linked by default. +The function table in the 9618 winter 2025 insert allows INTEGER or REAL input and STRING or CHAR output. Context selects the result type; the compiler's DEFAULT extension selects STRING when context supplies none. CHAR results use the same formatting as STRING results and must contain exactly one character, otherwise a catchable runtime error is raised. Thus INTEGER 7 can return '7', but INTEGER 12 and REAL 7.0 cannot return CHAR. + Format INTEGER as signed decimal text and REAL in the same shortest round-trip form that OUTPUT prints. The text is the shortest decimal text that reads back as the same value (as Python's `repr`): fixed notation with at least one fractional digit when 1e-4 <= |x| < 1e16 (`2.0`, `87.5`, `0.0001`), otherwise scientific notation with an exponent of at least two digits (`1e-07`, `1.5e-07`, `1e+16`); special values print as `-0.0`, `inf`, `-inf` and `nan`. # EXAMPLE @@ -24,4 +27,4 @@ OUTPUT NUM_TO_STR(42), " ", NUM_TO_STR(3.5) # SEE ALSO -[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). +[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-default(7)](../keyword/cpsc-keyword-default.7.md), [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md). diff --git a/doc/language/function/cpsc-function-str_to_num.7.md b/doc/language/function/cpsc-function-str_to_num.7.md index a9d008b..6351ec9 100644 --- a/doc/language/function/cpsc-function-str_to_num.7.md +++ b/doc/language/function/cpsc-function-str_to_num.7.md @@ -2,20 +2,24 @@ # NAME -cpsc-function-str_to_num - convert text to a real number +cpsc-function-str_to_num - convert text to a number # SYNOPSIS ```text -STR_TO_NUM(text : STRING) RETURNS REAL -STR_TO_NUM(text : CHAR) RETURNS REAL +STR_TO_NUM(text : STRING) RETURNS DEFAULT REAL +STR_TO_NUM(text : CHAR) RETURNS DEFAULT REAL +STR_TO_NUM(text : STRING) RETURNS INTEGER +STR_TO_NUM(text : CHAR) RETURNS INTEGER ``` # DESCRIPTION Provided by the standard string library, loaded and linked by default. -Return REAL, including for integer-looking text. The whole string must be consumed. Invalid text and trailing junk throw a catchable exception reading `STR_TO_NUM: '' is not a number`, and overflowing values throw `STR_TO_NUM: '' is out of the REAL range`. Underflow is accepted. Use IS_NUM first to check numeric text without throwing for invalid input. +The function table in the 9618 winter 2025 insert allows STRING or CHAR input and REAL or INTEGER output. The compiler selects the return type from context and defaults to REAL, including for integer-looking text. The INTEGER version parses as REAL and applies INT, truncating toward zero with the existing INTEGER range check; it inherits REAL rounding. For example, assigning STR_TO_NUM("-23.45") to an INTEGER gives -23. DEFAULT selection and this truncation policy are compiler extensions. + +The whole string must be consumed. Invalid text and trailing junk throw a catchable exception reading `STR_TO_NUM: '' is not a number`, and REAL overflow throws `STR_TO_NUM: '' is out of the REAL range`. Underflow is accepted. INTEGER overflow uses INT's range error. Use IS_NUM first to check numeric text without throwing for invalid input; it does not check INTEGER range. # EXAMPLE @@ -25,4 +29,4 @@ OUTPUT STR_TO_NUM("12.5") # SEE ALSO -[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-function-is_num(7)](cpsc-function-is_num.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). +[cpsc-language-overview(7)](../cpsc-language-overview.7.md), [cpsc-keyword-default(7)](../keyword/cpsc-keyword-default.7.md), [cpsc-function-int(7)](cpsc-function-int.7.md), [cpsc-function-is_num(7)](cpsc-function-is_num.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). diff --git a/doc/language/keyword/cpsc-keyword-default.7.md b/doc/language/keyword/cpsc-keyword-default.7.md new file mode 100644 index 0000000..0e9ed9b --- /dev/null +++ b/doc/language/keyword/cpsc-keyword-default.7.md @@ -0,0 +1,42 @@ +% CPSC-KEYWORD-DEFAULT(7) + +# NAME + +cpsc-keyword-default - select a default return type for an overload + +# SYNOPSIS + +```text +OVERLOAD FUNCTION name(parameters) RETURNS DEFAULT type + statements +ENDFUNCTION +``` + +# DESCRIPTION + +DEFAULT is a reserved compiler extension, absent from the CIE guide. Place it between RETURNS and the result type on a non-VOID OVERLOAD FUNCTION. Global functions, class methods and operator functions support it. Templates, including methods of class templates, do not support DEFAULT returns. + +When the surrounding context requires a result type, selection still requires that exact return type. Without a required result type, a unique parameter match is selected normally; if matches differ only by return type, the DEFAULT version is selected. Without a default, such a call remains ambiguous. A cast first prefers its target return type, then may select the default and convert its result. DEFAULT does not resolve competing parameter signatures or global/member operator ties. + +Each case-insensitive name and canonical parameter signature may have at most one DEFAULT return, including across separate input files. Parameter count, types and array rank distinguish these groups; BYREF/BYVAL and array bounds do not. Different parameter signatures may each have a default. Defaults participate only when visible to the caller, and ordinary access checks still apply after selection. + +The standard library marks STR_TO_NUM's REAL results and NUM_TO_STR's STRING results as defaults. Their other return types are selected by context. + +# EXAMPLE + +```text +OVERLOAD FUNCTION Score(Value : INTEGER) RETURNS DEFAULT REAL + RETURN 2.5 +ENDFUNCTION +OVERLOAD FUNCTION Score(Value : INTEGER) RETURNS INTEGER + RETURN 3 +ENDFUNCTION +OUTPUT Score(1) // 2.5 +DECLARE Number : INTEGER +Number <- Score(1) +OUTPUT Number // 3 +``` + +# SEE ALSO + +[cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-operator(7)](cpsc-keyword-operator.7.md), [cpsc-function-str_to_num(7)](../function/cpsc-function-str_to_num.7.md), [cpsc-function-num_to_str(7)](../function/cpsc-function-num_to_str.7.md). diff --git a/doc/language/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md index 8a5e37b..fbeb15b 100644 --- a/doc/language/keyword/cpsc-keyword-function.7.md +++ b/doc/language/keyword/cpsc-keyword-function.7.md @@ -25,7 +25,7 @@ A FUNCTION inside CLASS defines a member function, called as `Object.Method(argu As a compiler extension, a top-level `FUNCTION MAIN RETURNS INTEGER` with no parameters supplies the program entry point. MAIN is case insensitive and cannot coexist with top-level executable statements in any input file. Its INTEGER result, truncated to 32 bits, is returned as the process exit status. An uncaught exception prints the generic termination message and returns 1. A PROCEDURE MAIN or a MAIN with parameters or a non-INTEGER result is an error. The usual default INTEGER result type also applies when RETURNS is omitted. -Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types. Calls then require exact argument types and, where the surrounding context requires a result type, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types. Calls then require exact argument types and, where the surrounding context requires a result type, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). `RETURNS DEFAULT type` marks the result to select when context cannot choose among return-only overloads; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). # EXAMPLE diff --git a/doc/language/keyword/cpsc-keyword-operator.7.md b/doc/language/keyword/cpsc-keyword-operator.7.md index e18a5e5..6c29370 100644 --- a/doc/language/keyword/cpsc-keyword-operator.7.md +++ b/doc/language/keyword/cpsc-keyword-operator.7.md @@ -31,7 +31,7 @@ Binary operators are `+ - * / DIV MOD & = <> < <= > >= AND OR`. Unary operators 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. The selected method must be accessible: PRIVATE never causes a public fallback. Included units provide operators using the ordinary INCLUDE visibility rules. -Return types also distinguish operator overloads. When the context requires a result type (assignment, RETURN, condition, CASE comparison, subscript and similar positions), only definitions returning exactly that type match; if the operands match but no result does, the error is `No matching overload for OPERATOR +(T, U) returning R`. A cast `(R) expr` only prefers R and otherwise selects by operands before converting. Without an expected result type, such as OUTPUT or an operand of another operator, a unique operand match is selected and definitions that differ only by return type are ambiguous. +Return types also distinguish operator overloads. When the context requires a result type (assignment, RETURN, condition, CASE comparison, subscript and similar positions), only definitions returning exactly that type match; if the operands match but no result does, the error is `No matching overload for OPERATOR +(T, U) returning R`. A cast `(R) expr` only prefers R and otherwise selects by operands before converting. Without an expected result type, such as OUTPUT or an operand of another operator, a unique operand match is selected; definitions that differ only by return type need a `RETURNS DEFAULT type` declaration to avoid ambiguity. DEFAULT follows the same rules as ordinary functions and does not resolve global/member operator ties; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). 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 a BOOLEAN context requires an overload returning BOOLEAN. CASE comparisons follow the same result-type rule and must return BOOLEAN. A VOID result may be discarded through an explicit call but cannot be used as a value. diff --git a/doc/language/keyword/cpsc-keyword-overload.7.md b/doc/language/keyword/cpsc-keyword-overload.7.md index 2e2a101..1f7a0a4 100644 --- a/doc/language/keyword/cpsc-keyword-overload.7.md +++ b/doc/language/keyword/cpsc-keyword-overload.7.md @@ -24,13 +24,13 @@ ENDCLASS OVERLOAD is a compiler extension, absent from the CIE guide. Put it immediately before FUNCTION or PROCEDURE, after PUBLIC or PRIVATE when an access keyword is present. OVERLOAD is reserved. Every definition sharing a case-insensitive name must specify OVERLOAD. Global functions, procedures, class methods and NEW constructors support it; MAIN and built-in functions do not. -Signatures differ by parameter count, parameter types, array rank, or return type. BYREF versus BYVAL and declared array bounds do not distinguish signatures. A PROCEDURE counts as returning VOID, so it can coexist with a FUNCTION having the same parameter list; a call that cannot determine a result type is then ambiguous. Nominal user types remain distinct; equivalent native C type aliases identify the same type. +Signatures differ by parameter count, parameter types, array rank, or return type. BYREF versus BYVAL and declared array bounds do not distinguish signatures. A PROCEDURE counts as returning VOID, so it can coexist with a FUNCTION having the same parameter list; a call that cannot determine a result type is then ambiguous unless the function specifies a DEFAULT return. Nominal user types remain distinct; equivalent native C type aliases identify the same type. Calls require an exact match to the arguments' static types. No implicit conversion is used to select an overload, even when only one OVERLOAD definition exists. Array arguments must be whole array variables with matching element types and rank. After selection, ordinary parameter-mode, array-bound and access checks apply. Functions without OVERLOAD retain their ordinary argument conversions and their implicit result conversions. When the context requires a known result type, the selected overload must return exactly that type. This applies to assignment targets, BYVAL arguments, RETURN values, conditions, FOR bounds, subscripts and CASE comparisons. If the arguments match but no overload returns the required type, the error is `No matching overload for Name(T1, T2) returning T`. A cast `(T) expr` is weaker: it first prefers an overload returning T, then uses ordinary parameter selection and converts the result to T. -Without an expected result type (for example OUTPUT, an operand of another operator or comparison, a CASE selector, a CALL statement, or an argument passed to another OVERLOAD call), a unique parameter match is selected. If several candidates share the same parameter list and differ only by return type, the call is ambiguous. +Without an expected result type (for example OUTPUT, an operand of another operator or comparison, a CASE selector, a CALL statement, or an argument passed to another OVERLOAD call), a unique parameter match is selected. If several candidates share the same parameter list and differ only by return type, select the one marked `RETURNS DEFAULT type`; without a default, the call is ambiguous. Each name and canonical parameter signature may have only one default, including across input files. DEFAULT does not resolve parameter ambiguity or override a required result type; see [cpsc-keyword-default(7)](cpsc-keyword-default.7.md). Overloads may be defined in separate input files. A caller sees only its own and included units' definitions. Duplicate signatures fail across all inputs, even when neither unit includes the other; two definitions are duplicates only when both their parameters and their return types match. See [cpsc-keyword-include(7)](cpsc-keyword-include.7.md). @@ -53,4 +53,4 @@ OUTPUT Area(2.0) # SEE ALSO -[cpsc-keyword-template(7)](cpsc-keyword-template.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). +[cpsc-keyword-default(7)](cpsc-keyword-default.7.md), [cpsc-keyword-template(7)](cpsc-keyword-template.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). diff --git a/doc/language/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md index 2b251b5..30946e1 100644 --- a/doc/language/keyword/cpsc-keyword-procedure.7.md +++ b/doc/language/keyword/cpsc-keyword-procedure.7.md @@ -20,7 +20,7 @@ Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; explicit bou A PROCEDURE inside CLASS defines a member procedure, called as `Object.Method(arguments)` or `CALL Object.Method(arguments)`. It follows the same parameter rules and modifies the receiver. Within a method, `this` refers directly to the current object; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). -Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types; a procedure counts as returning VOID. A CALL statement has no expected result type, so a procedure and a function with the same parameters are ambiguous there. Other calls require exact argument types and, when a result type is required, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Prefix a definition with OVERLOAD to share its name with other explicitly marked definitions having different parameters or return types; a procedure counts as returning VOID. A CALL statement has no expected result type, so a procedure and a function with the same parameters are ambiguous there unless the function has a DEFAULT return. Other calls require exact argument types and, when a result type is required, an exact return type; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). # EXAMPLE diff --git a/doc/language/keyword/cpsc-keyword-template.7.md b/doc/language/keyword/cpsc-keyword-template.7.md index ca158c8..afa9cba 100644 --- a/doc/language/keyword/cpsc-keyword-template.7.md +++ b/doc/language/keyword/cpsc-keyword-template.7.md @@ -33,7 +33,7 @@ When multiple function or procedure definitions share a name, every definition, Use a class instance such as `Box` wherever a type name is accepted, including nested instances such as `Box>`. Supply all class type arguments explicitly; variadic CLASS templates are allowed, and their methods may use the class's pack parameters. Pack fields such as `Values : Rest...` are rejected. Constructors, ownership and destruction follow ordinary CLASS rules. In particular, a declaration without constructor arguments needs a matching parameterless NEW when constructors exist; see [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). -Non-type parameters, SIZEOF..., member templates, operator templates, specialization and pointer-alias templates are unsupported. Within a class template, write the full instance type rather than the bare class name. Pointer-linked generic containers remain unsupported because pointer-alias templates are unavailable. +Non-type parameters, SIZEOF..., member templates, operator templates, specialization and pointer-alias templates are unsupported. DEFAULT return declarations are also unsupported in templates, including methods of class templates. Within a class template, write the full instance type rather than the bare class name. Pointer-linked generic containers remain unsupported because pointer-alias templates are unavailable. Source template lists cannot be empty: `<>` is the inequality token. Nested closing `>>` works as two tokens. Separate `<` from a following `-` and `>` from a following `=` to avoid the `<-` and `>=` tokens. Expression lookahead treats `A < B, C > (D)` as a template call; parenthesize comparisons to avoid this ambiguity. diff --git a/plugin/AGENTS/ARCH.md b/plugin/AGENTS/ARCH.md index 69040af..a2d4240 100644 --- a/plugin/AGENTS/ARCH.md +++ b/plugin/AGENTS/ARCH.md @@ -114,9 +114,10 @@ only a subset of its syntax: TextMate injection, including nested declaration expressions. Comments, strings, fields outside methods and top-level code do not receive this scope. - Highlighting covers CASE/ENDCASE/OTHERWISE, CLASS/ENDCLASS/PUBLIC/PRIVATE, - CONSTANT, TEMPLATE, OVERLOAD/OPERATOR, EXTERN declarations, INCLUDE_OBJ - and ellipses using C++ scopes. OVERLOAD borrows a declaration modifier and + CONSTANT, TEMPLATE, OVERLOAD/DEFAULT/OPERATOR, EXTERN declarations, INCLUDE_OBJ + and ellipses using C++ scopes. OVERLOAD and DEFAULT borrow a declaration modifier and INCLUDE_OBJ borrows #include. + RETURNS DEFAULT preserves result type highlighting, including nested types. These rules do not add indentation support for the corresponding constructs. SET, DATE and random-file operations remain unsupported by the compiler. - PP_DEFINE/PP_UNDEF/PP_IFDEF/PP_IFNDEF/PP_ENDIF highlight only at line start, -- cgit v1.3.1-4-g156e