From c63584c388ea6acb7ad2f244376ae005536b6838 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Sat, 24 Oct 2026 18:09:43 +0000 Subject: docs(overload): document return-type selection across keyword pages Co-Authored-By: Claude Opus 5.5 --- doc/cpsc.1.md | 2 +- doc/language/cpsc-language-overview.7.md | 2 +- doc/language/keyword/cpsc-keyword-class.7.md | 2 +- doc/language/keyword/cpsc-keyword-function.7.md | 2 +- doc/language/keyword/cpsc-keyword-include.7.md | 2 +- doc/language/keyword/cpsc-keyword-overload.7.md | 2 +- doc/language/keyword/cpsc-keyword-procedure.7.md | 2 +- doc/language/keyword/cpsc-keyword-template.7.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/cpsc.1.md b/doc/cpsc.1.md index c0dd4f0..caa829c 100644 --- a/doc/cpsc.1.md +++ b/doc/cpsc.1.md @@ -16,7 +16,7 @@ Compile one or more pseudocode source files to a native executable, or to textua Without **-o**, save beside the entry source file, replacing its extension with `.exe` on Windows or `.out` elsewhere for an executable, or `.ll` for IR. With **-r** alone, run without saving a file. -Each input is a compilation unit. Use top-level `INCLUDE "lib.cps"` to import another input's exported definitions, including its transitive imports. Paths are relative to the including source; every included file must also appear on the command line. Repeated includes and include cycles are harmless. Giving the same input twice, including symbolic or hard links, is an error. Duplicate definitions across files are errors even if the files do not include each other; distinct parameter signatures may share a name when every definition specifies OVERLOAD. +Each input is a compilation unit. Use top-level `INCLUDE "lib.cps"` to import another input's exported definitions, including its transitive imports. Paths are relative to the including source; every included file must also appear on the command line. Repeated includes and include cycles are harmless. Giving the same input twice, including symbolic or hard links, is an error. Duplicate definitions across files are errors even if the files do not include each other; distinct signatures, differing in parameters or return type, may share a name when every definition specifies OVERLOAD. Exactly one file may contain top-level executable statements (including top-level DECLARE). Alternatively, define a parameterless `FUNCTION MAIN RETURNS INTEGER` in one file and have no top-level executable statements anywhere. Builds containing only definitions and no MAIN fail with `error: no main program`. GLOBAL blocks declare shared primitive variables. INCLUDE, GLOBAL and MAIN entry points are compiler extensions beyond the Cambridge guide. diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md index 914126e..fcdb4b5 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. Identifiers, including built-in funct 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. See [cpsc-keyword-operator(7)](keyword/cpsc-keyword-operator.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. 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. diff --git a/doc/language/keyword/cpsc-keyword-class.7.md b/doc/language/keyword/cpsc-keyword-class.7.md index ebeb98e..dffd4a1 100644 --- a/doc/language/keyword/cpsc-keyword-class.7.md +++ b/doc/language/keyword/cpsc-keyword-class.7.md @@ -26,7 +26,7 @@ object <- NEW ClassName(arguments) # DESCRIPTION -Declare a class at top level with at least one field or method. Fields and methods are public by default; PUBLIC or PRIVATE may be specified for each member. Fields do not use DECLARE. ENDCLASS closes the declaration. Fields and methods share a case-insensitive member namespace; fields and methods cannot share a name. Methods with distinct parameter signatures may share a name when every definition is prefixed with OVERLOAD, after any access keyword; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Declare a class at top level with at least one field or method. Fields and methods are public by default; PUBLIC or PRIVATE may be specified for each member. Fields do not use DECLARE. ENDCLASS closes the declaration. Fields and methods share a case-insensitive member namespace; fields and methods cannot share a name. Methods with distinct signatures, differing in parameters or return type, may share a name when every definition is prefixed with OVERLOAD, after any access keyword; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). Call methods as `Object.Method(arguments)` in expressions or as standalone statements, or use `CALL Object.Method(arguments)`. A receiver may be a variable, array element, nested field, or pointer dereference. Class-valued function and method results also support method calls, such as `Make().Get()`, using a temporary receiver. Direct field access, indexing and dereferencing on call results remain unsupported. Calls may precede definitions; methods may call later methods or recurse. Parameters and return values follow the ordinary FUNCTION and PROCEDURE rules. diff --git a/doc/language/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md index d49a07d..8a5e37b 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 parameter signatures. Calls then require exact argument types; 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). # EXAMPLE diff --git a/doc/language/keyword/cpsc-keyword-include.7.md b/doc/language/keyword/cpsc-keyword-include.7.md index 95ff953..0f3e3d0 100644 --- a/doc/language/keyword/cpsc-keyword-include.7.md +++ b/doc/language/keyword/cpsc-keyword-include.7.md @@ -14,7 +14,7 @@ INCLUDE "path.cps" INCLUDE is a compiler extension, allowed only at top level. Resolve the path relative to the including source's directory. The included file must also be given on the command line; symbolic and hard links identify the same file. -Import functions, procedures, types (including enum values), classes and methods, top-level constants and GLOBAL variables. Imports are transitive. Repeated includes and cycles are harmless: INCLUDE imports symbols rather than copying statements. A file always sees its own definitions. Using an unimported definition produces the usual unknown or undefined name error. Definitions must be unique across all input files, even when they are not imported. Explicit OVERLOAD definitions may share a name across files when their parameter signatures differ; callers see only visible overloads. See [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +Import functions, procedures, types (including enum values), classes and methods, top-level constants and GLOBAL variables. Imports are transitive. Repeated includes and cycles are harmless: INCLUDE imports symbols rather than copying statements. A file always sees its own definitions. Using an unimported definition produces the usual unknown or undefined name error. Definitions must be unique across all input files, even when they are not imported. Explicit OVERLOAD definitions may share a name across files when their signatures differ, including by return type; callers see only visible overloads. See [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). Imported constants are visible from the start of the including unit. A unit's own constants retain their ordinary declaration-order visibility. Top-level DECLARE variables are entry-program locals and are not exported. Pass all inputs together; there is no separate object-file compilation mode. diff --git a/doc/language/keyword/cpsc-keyword-overload.7.md b/doc/language/keyword/cpsc-keyword-overload.7.md index 6a50e5a..2e2a101 100644 --- a/doc/language/keyword/cpsc-keyword-overload.7.md +++ b/doc/language/keyword/cpsc-keyword-overload.7.md @@ -2,7 +2,7 @@ # NAME -cpsc-keyword-overload - explicitly overload functions, procedures and constructors +cpsc-keyword-overload - explicitly overload functions, procedures, methods and constructors # SYNOPSIS diff --git a/doc/language/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md index 6d46fb2..2b251b5 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 parameter signatures. Calls then require exact argument types; 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. 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 95dee8c..ca158c8 100644 --- a/doc/language/keyword/cpsc-keyword-template.7.md +++ b/doc/language/keyword/cpsc-keyword-template.7.md @@ -29,7 +29,7 @@ Function calls deduce types from parameters typed `T` or `ARRAY OF T`; bounded a A final parameter `Others : Rest...` expands into one parameter per pack type, possibly none. It cannot be an ARRAY parameter. Write `Others...` only in argument lists of function or method calls, NEW or DECLARE constructors. A bare pack value is invalid. In type argument lists, `Rest...` forwards the current type pack. Explicit pack arguments constrain a prefix; deduction can supply the remaining types. -When multiple function or procedure definitions share a name, every definition, including ordinary definitions, must specify OVERLOAD. Selection prefers an exact ordinary definition, then a non-variadic template, then a variadic template. Two matches at the same level are ambiguous; no further template ordering is performed. Explicit template arguments select only templates. Normal BYREF, array-bound and access checks apply after selection; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). +When multiple function or procedure definitions share a name, every definition, including ordinary definitions, must specify OVERLOAD. Selection prefers an exact ordinary definition, then a non-variadic template, then a variadic template. Expected result types filter ordinary definitions but do not participate in template selection, which still matches substituted parameter types only. Two matches at the same level are ambiguous; no further template ordering is performed. Explicit template arguments select only templates. Normal BYREF, array-bound and access checks apply after selection; see [cpsc-keyword-overload(7)](cpsc-keyword-overload.7.md). 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). -- cgit v1.3.1-4-g156e