From caa88a9b36d9e1dfae40ecb31aee05bc2891fa17 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 27 Oct 2026 14:07:24 +0000 Subject: docs(preprocessor): document switches and library regions Add manuals and aliases for all five PP directives, replace the retired #LIB page, and update compiler and shared-editor architecture notes. Co-Authored-By: Claude Opus 5.5 --- doc/language/keyword/cpsc-keyword-lib.7.md | 31 ---------------- doc/language/keyword/cpsc-keyword-pp_define.7.md | 45 ++++++++++++++++++++++++ doc/language/keyword/cpsc-keyword-pp_ifdef.7.md | 45 ++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 31 deletions(-) delete mode 100644 doc/language/keyword/cpsc-keyword-lib.7.md create mode 100644 doc/language/keyword/cpsc-keyword-pp_define.7.md create mode 100644 doc/language/keyword/cpsc-keyword-pp_ifdef.7.md (limited to 'doc/language/keyword') diff --git a/doc/language/keyword/cpsc-keyword-lib.7.md b/doc/language/keyword/cpsc-keyword-lib.7.md deleted file mode 100644 index 46af0a4..0000000 --- a/doc/language/keyword/cpsc-keyword-lib.7.md +++ /dev/null @@ -1,31 +0,0 @@ -% CPSC-KEYWORD-LIB(7) - -# NAME - -cpsc-keyword-lib - mark a library compilation unit - -# SYNOPSIS - -```text -#LIB -``` - -# DESCRIPTION - -A line-leading `#` (optionally preceded by whitespace) begins a compiler directive. Only `#LIB` is supported. It marks the entire source file as library code. Compile-time diagnostics retain library locations; runtime checks use the line of the first call from user code into library code, including methods, operators, automatic constructors/destructors and EXTERN calls. Library-to-library calls preserve that line. Directives are not comments. - -C++ library objects may read `extern "C" int __cps_user_line`, print `[Fatal] line N: reason` to stderr and throw an anonymous integer exception for pseudocode TRY/CATCH. The global is shared by the program and is not thread-local. - -# EXAMPLE - -```text -#LIB -PROCEDURE Check() - DECLARE A : ARRAY[1:1] OF INTEGER - OUTPUT A[2] -ENDPROCEDURE -``` - -# SEE ALSO - -[cpsc-keyword-include(7)](cpsc-keyword-include.7.md), [cpsc-keyword-try(7)](cpsc-keyword-try.7.md). diff --git a/doc/language/keyword/cpsc-keyword-pp_define.7.md b/doc/language/keyword/cpsc-keyword-pp_define.7.md new file mode 100644 index 0000000..f48148c --- /dev/null +++ b/doc/language/keyword/cpsc-keyword-pp_define.7.md @@ -0,0 +1,45 @@ +% CPSC-KEYWORD-PP_DEFINE(7) + +# NAME + +cpsc-keyword-pp_define, cpsc-keyword-pp_undef - define and remove preprocessor switches + +# SYNOPSIS + +```text +PP_DEFINE name +PP_UNDEF name +``` + +# DESCRIPTION + +PP_DEFINE and PP_UNDEF are compiler extensions processed before ordinary source code is tokenized. Each directive occupies its own line, optionally preceded by whitespace and followed by a // comment. Names contain ASCII letters, digits and underscores, starting with a letter or underscore. Directive keywords are uppercase; switch names are case-sensitive, unlike ordinary pseudocode identifiers. + +PP_DEFINE enables a switch and PP_UNDEF removes it. Defining an already defined switch or removing an undefined switch has no effect. Switches have no values, do not replace source text and use a namespace separate from ordinary identifiers. Extra arguments are errors. There are no command-line switch options. + +Each source file starts with no switches defined. Definitions take effect in source order and continue until removed or the file ends, including across function boundaries. INCLUDE imports symbols from independently preprocessed files; switches never pass between files. Definitions in a disabled conditional region have no effect. See [cpsc-keyword-pp_ifdef(7)](cpsc-keyword-pp_ifdef.7.md) for conditional compilation. + +The special switch __LIB marks subsequent source positions as library code. PP_UNDEF __LIB restores ordinary code behavior for subsequent positions; both directives may appear inside a function. Runtime checks in ordinary code report their own source line. Checks in library code use the shared user call line: calls from ordinary code update it, while calls from library code preserve it. This also covers methods, operators, EXTERN calls and automatic construction or destruction. Templates retain the modes at their original definition positions. Compile-time diagnostics always retain their original source file and line. The former #LIB syntax is rejected. + +C++ library objects may read `extern "C" int __cps_user_line`, print `[Fatal] line N: reason` to stderr and throw an anonymous integer exception for pseudocode TRY/CATCH. The global is shared by the program and is not thread-local. + +# EXAMPLE + +```text +PP_DEFINE __LIB +PROCEDURE Check() + DECLARE A : ARRAY[1:1] OF INTEGER + OUTPUT A[2] +ENDPROCEDURE +PP_UNDEF __LIB + +TRY + CALL Check() // The library bounds check reports this call's line. +CATCH + OUTPUT "Bounds error caught" +ENDTRY +``` + +# SEE ALSO + +[cpsc-keyword-pp_ifdef(7)](cpsc-keyword-pp_ifdef.7.md), [cpsc-keyword-include(7)](cpsc-keyword-include.7.md), [cpsc-keyword-try(7)](cpsc-keyword-try.7.md). diff --git a/doc/language/keyword/cpsc-keyword-pp_ifdef.7.md b/doc/language/keyword/cpsc-keyword-pp_ifdef.7.md new file mode 100644 index 0000000..b84645d --- /dev/null +++ b/doc/language/keyword/cpsc-keyword-pp_ifdef.7.md @@ -0,0 +1,45 @@ +% CPSC-KEYWORD-PP_IFDEF(7) + +# NAME + +cpsc-keyword-pp_ifdef, cpsc-keyword-pp_ifndef, cpsc-keyword-pp_endif - conditionally compile source regions + +# SYNOPSIS + +```text +PP_IFDEF name + source lines +PP_ENDIF + +PP_IFNDEF name + source lines +PP_ENDIF +``` + +# DESCRIPTION + +PP_IFDEF, PP_IFNDEF and PP_ENDIF are compiler extensions processed before lexing and parsing. PP_IFDEF includes its region when the named switch is defined; PP_IFNDEF includes it when the switch is undefined. Both require exactly one switch name. Each must have a matching PP_ENDIF, which takes no arguments. Conditions may nest, and a region is included only when all enclosing conditions are enabled. There is no PP_ELSE or condition-expression syntax. + +Directives occupy their own lines, optionally preceded by whitespace and followed by // comments. Keywords and switch names are case-sensitive. Switches belong to each file independently and change in source order through [cpsc-keyword-pp_define(7)](cpsc-keyword-pp_define.7.md). + +Disabled ordinary source is not lexed, parsed or compiled, and its PP_DEFINE and PP_UNDEF directives have no effect. Conditional nesting is still checked, including inside disabled regions. Directive lines and disabled source preserve original line numbering for diagnostics. Preprocessor conditions do not introduce ordinary scopes or add indentation in the VS Code plugin or Bundle. + +# EXAMPLE + +```text +PP_DEFINE Debug +PP_IFDEF Debug +OUTPUT "Debug enabled" +PP_IFNDEF Quiet +OUTPUT "Verbose debug output" +PP_ENDIF +PP_ENDIF +PP_UNDEF Debug +PP_IFNDEF Debug +OUTPUT "Debug disabled" +PP_ENDIF +``` + +# SEE ALSO + +[cpsc-keyword-pp_define(7)](cpsc-keyword-pp_define.7.md), [cpsc-language-overview(7)](../cpsc-language-overview.7.md). -- cgit v1.3.1-4-g156e