From 3b4e89d96afe203bb0e8b5b331bb30d1193d0831 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 14:13:00 +0000 Subject: Document supported pseudocode with section 7 language manuals Co-Authored-By: Claude Fable 5.1 --- doc/build.md | 2 +- doc/cpsc.1.md | 87 +++++++++++++++++++++++ doc/cpsc.md | 107 ----------------------------- doc/install.md | 2 +- doc/language/cpsc-function-asc.7.md | 28 ++++++++ doc/language/cpsc-function-chr.7.md | 28 ++++++++ doc/language/cpsc-function-eof.7.md | 34 +++++++++ doc/language/cpsc-function-is_num.7.md | 28 ++++++++ doc/language/cpsc-function-lcase.7.md | 28 ++++++++ doc/language/cpsc-function-left.7.md | 27 ++++++++ doc/language/cpsc-function-length.7.md | 27 ++++++++ doc/language/cpsc-function-mid.7.md | 28 ++++++++ doc/language/cpsc-function-num_to_str.7.md | 27 ++++++++ doc/language/cpsc-function-right.7.md | 27 ++++++++ doc/language/cpsc-function-str_to_num.7.md | 28 ++++++++ doc/language/cpsc-function-ucase.7.md | 28 ++++++++ doc/language/cpsc-keyword-and.7.md | 28 ++++++++ doc/language/cpsc-keyword-call.7.md | 31 +++++++++ doc/language/cpsc-keyword-class.7.md | 43 ++++++++++++ doc/language/cpsc-keyword-closefile.7.md | 29 ++++++++ doc/language/cpsc-keyword-declare.7.md | 40 +++++++++++ doc/language/cpsc-keyword-div.7.md | 28 ++++++++ doc/language/cpsc-keyword-for.7.md | 35 ++++++++++ doc/language/cpsc-keyword-function.7.md | 41 +++++++++++ doc/language/cpsc-keyword-if.7.md | 35 ++++++++++ doc/language/cpsc-keyword-input.7.md | 31 +++++++++ doc/language/cpsc-keyword-mod.7.md | 29 ++++++++ doc/language/cpsc-keyword-not.7.md | 27 ++++++++ doc/language/cpsc-keyword-openfile.7.md | 37 ++++++++++ doc/language/cpsc-keyword-or.7.md | 28 ++++++++ doc/language/cpsc-keyword-output.7.md | 32 +++++++++ doc/language/cpsc-keyword-procedure.7.md | 43 ++++++++++++ doc/language/cpsc-keyword-readfile.7.md | 34 +++++++++ doc/language/cpsc-keyword-repeat.7.md | 34 +++++++++ doc/language/cpsc-keyword-type.7.md | 53 ++++++++++++++ doc/language/cpsc-keyword-while.7.md | 34 +++++++++ doc/language/cpsc-keyword-writefile.7.md | 30 ++++++++ doc/language/cpsc-language-overview.7.md | 100 +++++++++++++++++++++++++++ 38 files changed, 1249 insertions(+), 109 deletions(-) create mode 100644 doc/cpsc.1.md delete mode 100644 doc/cpsc.md create mode 100644 doc/language/cpsc-function-asc.7.md create mode 100644 doc/language/cpsc-function-chr.7.md create mode 100644 doc/language/cpsc-function-eof.7.md create mode 100644 doc/language/cpsc-function-is_num.7.md create mode 100644 doc/language/cpsc-function-lcase.7.md create mode 100644 doc/language/cpsc-function-left.7.md create mode 100644 doc/language/cpsc-function-length.7.md create mode 100644 doc/language/cpsc-function-mid.7.md create mode 100644 doc/language/cpsc-function-num_to_str.7.md create mode 100644 doc/language/cpsc-function-right.7.md create mode 100644 doc/language/cpsc-function-str_to_num.7.md create mode 100644 doc/language/cpsc-function-ucase.7.md create mode 100644 doc/language/cpsc-keyword-and.7.md create mode 100644 doc/language/cpsc-keyword-call.7.md create mode 100644 doc/language/cpsc-keyword-class.7.md create mode 100644 doc/language/cpsc-keyword-closefile.7.md create mode 100644 doc/language/cpsc-keyword-declare.7.md create mode 100644 doc/language/cpsc-keyword-div.7.md create mode 100644 doc/language/cpsc-keyword-for.7.md create mode 100644 doc/language/cpsc-keyword-function.7.md create mode 100644 doc/language/cpsc-keyword-if.7.md create mode 100644 doc/language/cpsc-keyword-input.7.md create mode 100644 doc/language/cpsc-keyword-mod.7.md create mode 100644 doc/language/cpsc-keyword-not.7.md create mode 100644 doc/language/cpsc-keyword-openfile.7.md create mode 100644 doc/language/cpsc-keyword-or.7.md create mode 100644 doc/language/cpsc-keyword-output.7.md create mode 100644 doc/language/cpsc-keyword-procedure.7.md create mode 100644 doc/language/cpsc-keyword-readfile.7.md create mode 100644 doc/language/cpsc-keyword-repeat.7.md create mode 100644 doc/language/cpsc-keyword-type.7.md create mode 100644 doc/language/cpsc-keyword-while.7.md create mode 100644 doc/language/cpsc-keyword-writefile.7.md create mode 100644 doc/language/cpsc-language-overview.7.md (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index ca1c30a..ce87eb6 100644 --- a/doc/build.md +++ b/doc/build.md @@ -185,7 +185,7 @@ export PATH="$PWD/build/deps/root/opt/llvm@18/bin:$PATH" ## Manual -The quick reference is in [cpsc.md](cpsc.md). Pandoc is required only for the +The quick reference is in [cpsc.1.md](cpsc.1.md). Pandoc is required only for the `doc`, installation and release targets. Recommended local downloads follow; an existing system Pandoc works with the same manual-generation command. diff --git a/doc/cpsc.1.md b/doc/cpsc.1.md new file mode 100644 index 0000000..228fd66 --- /dev/null +++ b/doc/cpsc.1.md @@ -0,0 +1,87 @@ +% CPSC(1) + +# NAME + +cpsc - compile and run CIE pseudocode + +# SYNOPSIS + +**cpsc** [**-r**] [**-o** *output*] *source* + +**cpsc** **-h** + +# DESCRIPTION + +Compile one pseudocode source file to LLVM IR. Options may appear before or after the source path. Source input from stdin is not supported. + +Without **-o** or **-r**, replace the source filename's extension with `.ir` and save the output beside the source file. + +# OPTIONS + +**-h** +: Print only the documentation entry point: `man 1 cpsc` on Unix/macOS, or Start Menu > cpsc > cpsc Help on Windows. Return successfully without compiling, even when other arguments are present. + +**-o** *output* +: Save IR to the specified path. May be specified only once. With **-r**, keep this file even if execution fails. + +**-r** +: Run the compiled program with the runner selected at build time (see EXECUTION MODES). Without **-o**, do not save permanent IR. The program inherits stdin, stdout and stderr; `INPUT` can read terminal or piped input. + +# EXECUTION MODES + +The executable has one of the following execution modes, selected when it was built. All modes can compile to LLVM IR; the mode determines whether and how **-r** runs the program. + +**PATH** +: Run `lli` from PATH. If it cannot be found, **-r** fails before compilation or output writing. Without **-o**, write temporary IR and delete it afterward, including on execution failure. + +**EMBEDDED** +: Run the statically linked LLVM engine inside `cpsc`, without looking for `lli` in PATH. Without **-o**, execute the module in memory. Users do not need LLVM or `lli` installed; the executable may still depend on the operating system's C runtime libraries. + +**NONE** +: Reject **-r** with an error before compilation or output writing. Compilation to IR remains available. + +# EXAMPLES + +Compile and save `test.ir` beside `test.cps`: + +```sh +cpsc test.cps +``` + +Choose the output path: + +```sh +cpsc test.cps -o result.ir +``` + +Run without saving permanent IR: + +```sh +cpsc test.cps -r +``` + +Save IR and run it: + +```sh +cpsc test.cps -r -o result.ir +``` + +# EXIT STATUS + +**0** +: Compilation succeeded, or **-h** printed the documentation entry point. + +**1** +: An argument, file, compilation or execution-engine error occurred, including missing input, when PATH mode cannot find `lli` or NONE mode receives **-r**. + +With **-r**, return the executed program's exit status. In PATH mode, failure to launch `lli` or a child-process crash returns 1. + +# NOTES + +Compiler diagnostics go to stderr. Failed compilation does not write IR. Successful compilation overwrites an existing output file, but an output path that refers to the source file (including a symbolic or hard link) is rejected. + +Missing input, including invoking `cpsc` without arguments, reports `cpsc: fatal error: no input files`. Ordinary lexical, syntax and semantic errors use `error:`; failures that prevent compilation, such as file I/O errors, use `fatal error:`. Compilation and argument failures end with one `compilation terminated.` line. Execution-stage failures do not print that line. + +# SEE ALSO + +[cpsc-language-overview(7)](language/cpsc-language-overview.7.md) describes supported syntax and links to the keyword and built-in function manuals. diff --git a/doc/cpsc.md b/doc/cpsc.md deleted file mode 100644 index 8a57a63..0000000 --- a/doc/cpsc.md +++ /dev/null @@ -1,107 +0,0 @@ -% CPSC(1) - -# NAME - -cpsc - compile and run CIE pseudocode - -# SYNOPSIS - -**cpsc** [**-r**] [**-o** *output*] *source* - -**cpsc** **-h** - -# DESCRIPTION - -Compile one pseudocode source file to LLVM IR. Options may appear before or after the source path. Source input from stdin is not supported. - -Without **-o** or **-r**, replace the source filename's extension with `.ir` and save the output beside the source file. - -# OPTIONS - -**-h** -: Print only the documentation entry point: `man 1 cpsc` on Unix/macOS, or Start Menu > cpsc > cpsc Help on Windows. Return successfully without compiling, even when other arguments are present. - -**-o** *output* -: Save IR to the specified path. May be specified only once. With **-r**, keep this file even if execution fails. - -**-r** -: Run the compiled program with the runner selected at build time (see EXECUTION MODES). Without **-o**, do not save permanent IR. The program inherits stdin, stdout and stderr; `INPUT` can read terminal or piped input. - -# EXECUTION MODES - -The executable has one of the following execution modes, selected when it was built. All modes can compile to LLVM IR; the mode determines whether and how **-r** runs the program. - -**PATH** -: Run `lli` from PATH. If it cannot be found, **-r** fails before compilation or output writing. Without **-o**, write temporary IR and delete it afterward, including on execution failure. - -**EMBEDDED** -: Run the statically linked LLVM engine inside `cpsc`, without looking for `lli` in PATH. Without **-o**, execute the module in memory. Users do not need LLVM or `lli` installed; the executable may still depend on the operating system's C runtime libraries. - -**NONE** -: Reject **-r** with an error before compilation or output writing. Compilation to IR remains available. - -# EXAMPLES - -Compile and save `test.ir` beside `test.cps`: - -```sh -cpsc test.cps -``` - -Choose the output path: - -```sh -cpsc test.cps -o result.ir -``` - -Run without saving permanent IR: - -```sh -cpsc test.cps -r -``` - -Save IR and run it: - -```sh -cpsc test.cps -r -o result.ir -``` - -# CLASSES - -Declare classes at top level. Every field must explicitly specify `PUBLIC` or -`PRIVATE`, without `DECLARE`: - -```text -CLASS Person - PUBLIC Name : STRING - PRIVATE Age : INTEGER -ENDCLASS - -DECLARE p : Person -p.Name <- "Alice" -OUTPUT p.Name -``` - -Classes use record value semantics: zero initialization, whole-value copying, -arrays, pointers and ordinary function/procedure parameters. Private fields cannot -be read, written or addressed externally; they are still initialized and copied -with the whole value. Record `TYPE` fields remain implicitly public and cannot -specify access levels. Class methods, constructors, destructors, `NEW` and -`INHERITS` are not supported. Array fields remain unsupported in both records and -classes. - -# EXIT STATUS - -**0** -: Compilation succeeded, or **-h** printed the documentation entry point. - -**1** -: An argument, file, compilation or execution-engine error occurred, including missing input, when PATH mode cannot find `lli` or NONE mode receives **-r**. - -With **-r**, return the executed program's exit status. In PATH mode, failure to launch `lli` or a child-process crash returns 1. - -# NOTES - -Compiler diagnostics go to stderr. Failed compilation does not write IR. Successful compilation overwrites an existing output file, but an output path that refers to the source file (including a symbolic or hard link) is rejected. - -Missing input, including invoking `cpsc` without arguments, reports `cpsc: fatal error: no input files`. Ordinary lexical, syntax and semantic errors use `error:`; failures that prevent compilation, such as file I/O errors, use `fatal error:`. Compilation and argument failures end with one `compilation terminated.` line. Execution-stage failures do not print that line. diff --git a/doc/install.md b/doc/install.md index f1746e5..8101684 100644 --- a/doc/install.md +++ b/doc/install.md @@ -1,6 +1,6 @@ # Installing and packaging cpsc -To build from source, follow [build.md](build.md). For command-line usage, see [cpsc.md](cpsc.md). Run build commands from the project root; package installation commands run from the extracted package directory. +To build from source, follow [build.md](build.md). For command-line usage, see [cpsc.1.md](cpsc.1.md). Run build commands from the project root; package installation commands run from the extracted package directory. ## Linux installation diff --git a/doc/language/cpsc-function-asc.7.md b/doc/language/cpsc-function-asc.7.md new file mode 100644 index 0000000..0600599 --- /dev/null +++ b/doc/language/cpsc-function-asc.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-ASC(7) + +# NAME + +cpsc-function-asc - find a character's byte code + +# SYNOPSIS + +```text +ASC(character : CHAR) RETURNS INTEGER +ASC(text : STRING) RETURNS INTEGER +``` + +# DESCRIPTION + +Return the unsigned byte code of the character, or of the first byte of a +string. Use a nonempty string; for ASCII characters this is the ASCII code. + +# EXAMPLE + +```text +OUTPUT ASC('A') +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-chr(7)](cpsc-function-chr.7.md). + diff --git a/doc/language/cpsc-function-chr.7.md b/doc/language/cpsc-function-chr.7.md new file mode 100644 index 0000000..5062468 --- /dev/null +++ b/doc/language/cpsc-function-chr.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-CHR(7) + +# NAME + +cpsc-function-chr - convert a byte code to text + +# SYNOPSIS + +```text +CHR(code : INTEGER) RETURNS STRING +``` + +# DESCRIPTION + +Convert the low eight bits of code to a one-byte string. +The result is STRING, not CHAR. Use ASCII codes 1 to 127 for +ordinary text; code 0 produces an empty string. + +# EXAMPLE + +```text +OUTPUT CHR(65) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-asc(7)](cpsc-function-asc.7.md). + diff --git a/doc/language/cpsc-function-eof.7.md b/doc/language/cpsc-function-eof.7.md new file mode 100644 index 0000000..721e667 --- /dev/null +++ b/doc/language/cpsc-function-eof.7.md @@ -0,0 +1,34 @@ +% CPSC-FUNCTION-EOF(7) + +# NAME + +cpsc-function-eof - test for the end of a text file + +# SYNOPSIS + +```text +EOF(filename : STRING) RETURNS BOOLEAN +``` + +# DESCRIPTION + +Return true when no further characters remain in a file opened FOR READ. +The test does not consume the next character. Testing an unopened file or +a file in the wrong mode terminates execution. + +# EXAMPLE + +```text +DECLARE Line : STRING +OPENFILE "notes.txt" FOR READ +WHILE NOT EOF("notes.txt") DO + READFILE "notes.txt", Line + OUTPUT Line +ENDWHILE +CLOSEFILE "notes.txt" +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md). + diff --git a/doc/language/cpsc-function-is_num.7.md b/doc/language/cpsc-function-is_num.7.md new file mode 100644 index 0000000..de37b71 --- /dev/null +++ b/doc/language/cpsc-function-is_num.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-IS_NUM(7) + +# NAME + +cpsc-function-is_num - test whether text represents a number + +# SYNOPSIS + +```text +IS_NUM(text : STRING) RETURNS BOOLEAN +``` + +# DESCRIPTION + +Return true for a nonempty string fully consumed by the runtime's +numeric conversion. Leading whitespace is accepted; trailing whitespace +or other trailing text is rejected. + +# EXAMPLE + +```text +OUTPUT IS_NUM("12.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). + diff --git a/doc/language/cpsc-function-lcase.7.md b/doc/language/cpsc-function-lcase.7.md new file mode 100644 index 0000000..f6ca334 --- /dev/null +++ b/doc/language/cpsc-function-lcase.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-LCASE(7) + +# NAME + +cpsc-function-lcase - convert text to lower case + +# SYNOPSIS + +```text +LCASE(text : STRING) RETURNS STRING +``` + +# DESCRIPTION + +Return a copy with letters converted to lower case. Unlike guide section 5.5's +CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII +text for predictable character conversion. + +# EXAMPLE + +```text +OUTPUT LCASE("HELLO") +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-ucase(7)](cpsc-function-ucase.7.md). + diff --git a/doc/language/cpsc-function-left.7.md b/doc/language/cpsc-function-left.7.md new file mode 100644 index 0000000..b4542d6 --- /dev/null +++ b/doc/language/cpsc-function-left.7.md @@ -0,0 +1,27 @@ +% CPSC-FUNCTION-LEFT(7) + +# NAME + +cpsc-function-left - extract the beginning of a string + +# SYNOPSIS + +```text +LEFT(text : STRING, count : INTEGER) RETURNS STRING +``` + +# DESCRIPTION + +Return up to count bytes from the beginning. Counts larger than the string +length return the whole string; negative counts return an empty string. + +# EXAMPLE + +```text +OUTPUT LEFT("Hello", 2) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md). + diff --git a/doc/language/cpsc-function-length.7.md b/doc/language/cpsc-function-length.7.md new file mode 100644 index 0000000..a7f6acf --- /dev/null +++ b/doc/language/cpsc-function-length.7.md @@ -0,0 +1,27 @@ +% CPSC-FUNCTION-LENGTH(7) + +# NAME + +cpsc-function-length - find a string's length + +# SYNOPSIS + +```text +LENGTH(text : STRING) RETURNS INTEGER +``` + +# DESCRIPTION + +Return the number of bytes before the string terminator. String operations +are byte-based, so this is not a Unicode character count. + +# EXAMPLE + +```text +OUTPUT LENGTH("Hello") +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md). + diff --git a/doc/language/cpsc-function-mid.7.md b/doc/language/cpsc-function-mid.7.md new file mode 100644 index 0000000..3a6bc71 --- /dev/null +++ b/doc/language/cpsc-function-mid.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-MID(7) + +# NAME + +cpsc-function-mid - extract part of a string + +# SYNOPSIS + +```text +MID(text : STRING, start : INTEGER, count : INTEGER) RETURNS STRING +``` + +# DESCRIPTION + +Return up to count bytes starting at the one-based position start. +Positions below 1 clamp to 1; positions beyond the end return an empty string. +The count clamps to the available bytes; negative counts return an empty string. + +# EXAMPLE + +```text +OUTPUT MID("ABCDEFGH", 2, 3) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-right(7)](cpsc-function-right.7.md), [cpsc-function-length(7)](cpsc-function-length.7.md). + diff --git a/doc/language/cpsc-function-num_to_str.7.md b/doc/language/cpsc-function-num_to_str.7.md new file mode 100644 index 0000000..30dc39b --- /dev/null +++ b/doc/language/cpsc-function-num_to_str.7.md @@ -0,0 +1,27 @@ +% CPSC-FUNCTION-NUM_TO_STR(7) + +# NAME + +cpsc-function-num_to_str - convert a number to text + +# SYNOPSIS + +```text +NUM_TO_STR(number : INTEGER or REAL) RETURNS STRING +``` + +# DESCRIPTION + +Format INTEGER as signed decimal text and REAL with six digits after the +decimal point. + +# EXAMPLE + +```text +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). + diff --git a/doc/language/cpsc-function-right.7.md b/doc/language/cpsc-function-right.7.md new file mode 100644 index 0000000..ae9114b --- /dev/null +++ b/doc/language/cpsc-function-right.7.md @@ -0,0 +1,27 @@ +% CPSC-FUNCTION-RIGHT(7) + +# NAME + +cpsc-function-right - extract the end of a string + +# SYNOPSIS + +```text +RIGHT(text : STRING, count : INTEGER) RETURNS STRING +``` + +# DESCRIPTION + +Return up to count bytes from the end. Use a nonnegative count. +Counts larger than the string length return the whole string. + +# EXAMPLE + +```text +OUTPUT RIGHT("Hello", 2) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-left(7)](cpsc-function-left.7.md), [cpsc-function-mid(7)](cpsc-function-mid.7.md). + diff --git a/doc/language/cpsc-function-str_to_num.7.md b/doc/language/cpsc-function-str_to_num.7.md new file mode 100644 index 0000000..6128a13 --- /dev/null +++ b/doc/language/cpsc-function-str_to_num.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-STR_TO_NUM(7) + +# NAME + +cpsc-function-str_to_num - convert text to a real number + +# SYNOPSIS + +```text +STR_TO_NUM(text : STRING) RETURNS REAL +``` + +# DESCRIPTION + +Return REAL, including for integer-looking text. Conversion can stop at +trailing text; invalid text returns zero. Use IS_NUM first when the whole +string must be a valid number. + +# EXAMPLE + +```text +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). + diff --git a/doc/language/cpsc-function-ucase.7.md b/doc/language/cpsc-function-ucase.7.md new file mode 100644 index 0000000..dd44892 --- /dev/null +++ b/doc/language/cpsc-function-ucase.7.md @@ -0,0 +1,28 @@ +% CPSC-FUNCTION-UCASE(7) + +# NAME + +cpsc-function-ucase - convert text to upper case + +# SYNOPSIS + +```text +UCASE(text : STRING) RETURNS STRING +``` + +# DESCRIPTION + +Return a copy with letters converted to upper case. Unlike guide section 5.5's +CHAR-to-CHAR signature, cpsc accepts text and returns STRING. Use ASCII +text for predictable character conversion. + +# EXAMPLE + +```text +OUTPUT UCASE("Hello") +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-function-lcase(7)](cpsc-function-lcase.7.md). + diff --git a/doc/language/cpsc-keyword-and.7.md b/doc/language/cpsc-keyword-and.7.md new file mode 100644 index 0000000..6b98abf --- /dev/null +++ b/doc/language/cpsc-keyword-and.7.md @@ -0,0 +1,28 @@ +% CPSC-KEYWORD-AND(7) + +# NAME + +cpsc-keyword-and - combine conditions with logical AND + +# SYNOPSIS + +```text +left AND right +``` + +# DESCRIPTION + +Return BOOLEAN: true when both operands are true. Both operands are +evaluated; AND does not short-circuit. AND binds more tightly than OR +and less tightly than comparisons. Use parentheses for clarity. + +# EXAMPLE + +```text +OUTPUT (3 > 2) AND (4 > 1) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). + diff --git a/doc/language/cpsc-keyword-call.7.md b/doc/language/cpsc-keyword-call.7.md new file mode 100644 index 0000000..b17b3f4 --- /dev/null +++ b/doc/language/cpsc-keyword-call.7.md @@ -0,0 +1,31 @@ +% CPSC-KEYWORD-CALL(7) + +# NAME + +cpsc-keyword-call - invoke a procedure + +# SYNOPSIS + +```text +CALL name(arguments) +``` + +# DESCRIPTION + +Invoke a previously declared procedure with its parameters. Empty argument +lists may be written `CALL name()` or `CALL name`. +Use function calls in expressions to obtain their results. + +# EXAMPLE + +```text +PROCEDURE Hello() + OUTPUT "Hello" +ENDPROCEDURE +CALL Hello() +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md). + diff --git a/doc/language/cpsc-keyword-class.7.md b/doc/language/cpsc-keyword-class.7.md new file mode 100644 index 0000000..7ff32ba --- /dev/null +++ b/doc/language/cpsc-keyword-class.7.md @@ -0,0 +1,43 @@ +% CPSC-KEYWORD-CLASS(7) + +# NAME + +cpsc-keyword-class - define a class with public and private fields + +# SYNOPSIS + +```text +CLASS name + PUBLIC field : type + PRIVATE field : type +ENDCLASS +``` + +# DESCRIPTION + +Declare a class at top level with at least one field. Every field explicitly +requires PUBLIC or PRIVATE, without DECLARE. This differs from guide +section 10's default-public rule. ENDCLASS closes the declaration. + +Classes use record value semantics: zero initialization, whole-value copying, +arrays, pointers, and ordinary function/procedure parameters. Only PUBLIC +fields can be accessed externally. PRIVATE fields still initialize and copy +with the whole value. Methods, constructors, destructors, NEW, INHERITS, +and array fields are unsupported. + +# EXAMPLE + +```text +CLASS Person + PUBLIC Name : STRING + PRIVATE Age : INTEGER +ENDCLASS +DECLARE PersonValue : Person +PersonValue.Name <- "Alice" +OUTPUT PersonValue.Name +``` + +# 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). + diff --git a/doc/language/cpsc-keyword-closefile.7.md b/doc/language/cpsc-keyword-closefile.7.md new file mode 100644 index 0000000..b986b86 --- /dev/null +++ b/doc/language/cpsc-keyword-closefile.7.md @@ -0,0 +1,29 @@ +% CPSC-KEYWORD-CLOSEFILE(7) + +# NAME + +cpsc-keyword-closefile - close a text file + +# SYNOPSIS + +```text +CLOSEFILE filename +``` + +# DESCRIPTION + +Close the file associated with this filename string and release its open-file +slot. Closing a filename that is not open terminates execution. + +# EXAMPLE + +```text +OPENFILE "notes.txt" FOR WRITE +WRITEFILE "notes.txt", "Done" +CLOSEFILE "notes.txt" +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md), [cpsc-keyword-writefile(7)](cpsc-keyword-writefile.7.md). + diff --git a/doc/language/cpsc-keyword-declare.7.md b/doc/language/cpsc-keyword-declare.7.md new file mode 100644 index 0000000..887ae12 --- /dev/null +++ b/doc/language/cpsc-keyword-declare.7.md @@ -0,0 +1,40 @@ +% CPSC-KEYWORD-DECLARE(7) + +# NAME + +cpsc-keyword-declare - declare variables and arrays + +# SYNOPSIS + +```text +DECLARE name : type +DECLARE name : ARRAY[lower:upper, ...] OF type +``` + +# DESCRIPTION + +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. + +ARRAY bounds are inclusive and may be expressions; multiple ranges create +multiple dimensions. Access elements with `name[index, ...]`. Bounds are +checked at run time. Whole-array assignment is unsupported. Declare arrays +before using them; arrays declared inside a control-flow block stay in that +block. + +# EXAMPLE + +```text +DECLARE Count : INTEGER +DECLARE Names : ARRAY[1:3] OF STRING +Count <- 2 +Names[Count] <- "Alice" +OUTPUT Names[Count] +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-type(7)](cpsc-keyword-type.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md), [cpsc-keyword-output(7)](cpsc-keyword-output.7.md). + diff --git a/doc/language/cpsc-keyword-div.7.md b/doc/language/cpsc-keyword-div.7.md new file mode 100644 index 0000000..78715e1 --- /dev/null +++ b/doc/language/cpsc-keyword-div.7.md @@ -0,0 +1,28 @@ +% CPSC-KEYWORD-DIV(7) + +# NAME + +cpsc-keyword-div - perform integer division + +# SYNOPSIS + +```text +left DIV right +``` + +# DESCRIPTION + +Both operands must be INTEGER. Return the quotient truncated toward zero. +A zero divisor terminates execution. DIV has the same precedence as +multiplication. Use `/` for division returning REAL. + +# EXAMPLE + +```text +OUTPUT 7 DIV 2 +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-mod(7)](cpsc-keyword-mod.7.md). + diff --git a/doc/language/cpsc-keyword-for.7.md b/doc/language/cpsc-keyword-for.7.md new file mode 100644 index 0000000..201a492 --- /dev/null +++ b/doc/language/cpsc-keyword-for.7.md @@ -0,0 +1,35 @@ +% CPSC-KEYWORD-FOR(7) + +# NAME + +cpsc-keyword-for - iterate over an integer range + +# SYNOPSIS + +```text +FOR variable <- start TO finish [STEP increment] + statements +NEXT variable +``` + +# DESCRIPTION + +The loop variable must already be declared INTEGER. Both endpoints are +inclusive. STEP defaults to 1; use a negative value to count down. +STEP is evaluated once, while the finish expression is evaluated each +iteration. NEXT must name the same variable. Use a nonzero STEP. +TO, STEP, and NEXT belong to this syntax. + +# EXAMPLE + +```text +DECLARE Index : INTEGER +FOR Index <- 3 TO 1 STEP -1 + OUTPUT Index +NEXT Index +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-while(7)](cpsc-keyword-while.7.md). + diff --git a/doc/language/cpsc-keyword-function.7.md b/doc/language/cpsc-keyword-function.7.md new file mode 100644 index 0000000..c37754c --- /dev/null +++ b/doc/language/cpsc-keyword-function.7.md @@ -0,0 +1,41 @@ +% CPSC-KEYWORD-FUNCTION(7) + +# NAME + +cpsc-keyword-function - define a function that returns a value + +# SYNOPSIS + +```text +FUNCTION name(parameters) RETURNS type + statements + RETURN expression +ENDFUNCTION +``` + +# DESCRIPTION + +Call a function in an expression as `name(arguments)`. A call may precede its +top-level definition. RETURNS specifies the result type; omitting it defaults +to INTEGER. RETURN supplies a value of that type. Whole-array results are +unsupported. + +Parameters use `name : type`, optionally prefixed by BYVAL. BYVAL is the +default; BYREF is forbidden for functions (guide section 8.3). +Array parameters accept `ARRAY OF type` (one dimension) or +`ARRAY[lower:upper, ...] OF type` (integer literal bounds). +BYVAL arrays are copied. RETURNS, RETURN, BYVAL, and ENDFUNCTION belong here. + +# EXAMPLE + +```text +FUNCTION Double(Value : INTEGER) RETURNS INTEGER + RETURN Value * 2 +ENDFUNCTION +OUTPUT Double(4) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md). + diff --git a/doc/language/cpsc-keyword-if.7.md b/doc/language/cpsc-keyword-if.7.md new file mode 100644 index 0000000..9f14959 --- /dev/null +++ b/doc/language/cpsc-keyword-if.7.md @@ -0,0 +1,35 @@ +% CPSC-KEYWORD-IF(7) + +# NAME + +cpsc-keyword-if - choose between branches + +# SYNOPSIS + +```text +IF condition THEN + statements +ELSE + statements +ENDIF +``` + +# DESCRIPTION + +Execute the THEN branch when the condition is true, otherwise the optional +ELSE branch. Blocks may be nested. THEN, ELSE, and ENDIF belong to this syntax. + +# EXAMPLE + +```text +IF 3 > 2 THEN + OUTPUT "yes" +ELSE + OUTPUT "no" +ENDIF +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md). + diff --git a/doc/language/cpsc-keyword-input.7.md b/doc/language/cpsc-keyword-input.7.md new file mode 100644 index 0000000..f31731f --- /dev/null +++ b/doc/language/cpsc-keyword-input.7.md @@ -0,0 +1,31 @@ +% CPSC-KEYWORD-INPUT(7) + +# NAME + +cpsc-keyword-input - read a value from standard input + +# SYNOPSIS + +```text +INPUT variable +``` + +# DESCRIPTION + +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. + +# EXAMPLE + +```text +DECLARE Name : STRING +INPUT Name +OUTPUT Name +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-output(7)](cpsc-keyword-output.7.md). + diff --git a/doc/language/cpsc-keyword-mod.7.md b/doc/language/cpsc-keyword-mod.7.md new file mode 100644 index 0000000..cb437a4 --- /dev/null +++ b/doc/language/cpsc-keyword-mod.7.md @@ -0,0 +1,29 @@ +% CPSC-KEYWORD-MOD(7) + +# NAME + +cpsc-keyword-mod - find the integer division remainder + +# SYNOPSIS + +```text +left MOD right +``` + +# DESCRIPTION + +Both operands must be INTEGER. Return the remainder after division truncated +toward zero; a nonzero remainder has the dividend's sign. +A zero divisor terminates execution. MOD has the same precedence as +multiplication. + +# EXAMPLE + +```text +OUTPUT 7 MOD 2 +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-div(7)](cpsc-keyword-div.7.md). + diff --git a/doc/language/cpsc-keyword-not.7.md b/doc/language/cpsc-keyword-not.7.md new file mode 100644 index 0000000..5bb1c18 --- /dev/null +++ b/doc/language/cpsc-keyword-not.7.md @@ -0,0 +1,27 @@ +% CPSC-KEYWORD-NOT(7) + +# NAME + +cpsc-keyword-not - negate a condition + +# SYNOPSIS + +```text +NOT expression +``` + +# DESCRIPTION + +Return BOOLEAN with the opposite truth value. NOT is a unary operator; +parenthesize comparisons, for example `NOT (Count = 0)`. + +# EXAMPLE + +```text +OUTPUT NOT (3 = 2) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-or(7)](cpsc-keyword-or.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). + diff --git a/doc/language/cpsc-keyword-openfile.7.md b/doc/language/cpsc-keyword-openfile.7.md new file mode 100644 index 0000000..a13b3f4 --- /dev/null +++ b/doc/language/cpsc-keyword-openfile.7.md @@ -0,0 +1,37 @@ +% CPSC-KEYWORD-OPENFILE(7) + +# NAME + +cpsc-keyword-openfile - open a text file + +# SYNOPSIS + +```text +OPENFILE filename FOR READ +OPENFILE filename FOR WRITE +OPENFILE filename FOR APPEND +``` + +# DESCRIPTION + +The filename is a STRING expression. READ opens an existing file for reading; +WRITE creates or truncates a file; APPEND writes at the end, creating the file +if needed. READ, WRITE, APPEND, and this use of FOR belong here. + +At most 16 files may be open at once. Use the same filename string for +subsequent operations. Reopening an open filename, failed opens, and wrong-mode +operations terminate execution with a fatal diagnostic. RANDOM is reserved +but unsupported. + +# EXAMPLE + +```text +OPENFILE "notes.txt" FOR WRITE +WRITEFILE "notes.txt", "Hello" +CLOSEFILE "notes.txt" +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md), [cpsc-keyword-writefile(7)](cpsc-keyword-writefile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md). + diff --git a/doc/language/cpsc-keyword-or.7.md b/doc/language/cpsc-keyword-or.7.md new file mode 100644 index 0000000..7fca628 --- /dev/null +++ b/doc/language/cpsc-keyword-or.7.md @@ -0,0 +1,28 @@ +% CPSC-KEYWORD-OR(7) + +# NAME + +cpsc-keyword-or - combine conditions with logical OR + +# SYNOPSIS + +```text +left OR right +``` + +# DESCRIPTION + +Return BOOLEAN: true when either operand is true. Both operands are +evaluated; OR does not short-circuit. OR binds less tightly than AND +and comparisons. + +# EXAMPLE + +```text +OUTPUT (3 < 2) OR (4 > 1) +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-and(7)](cpsc-keyword-and.7.md), [cpsc-keyword-not(7)](cpsc-keyword-not.7.md), [cpsc-keyword-if(7)](cpsc-keyword-if.7.md). + diff --git a/doc/language/cpsc-keyword-output.7.md b/doc/language/cpsc-keyword-output.7.md new file mode 100644 index 0000000..9ee2133 --- /dev/null +++ b/doc/language/cpsc-keyword-output.7.md @@ -0,0 +1,32 @@ +% CPSC-KEYWORD-OUTPUT(7) + +# NAME + +cpsc-keyword-output - print values to standard output + +# SYNOPSIS + +```text +OUTPUT expression, ... +``` + +# DESCRIPTION + +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. + +# EXAMPLE + +```text +DECLARE Score : INTEGER +Score <- 10 +OUTPUT "Score: ", Score +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-input(7)](cpsc-keyword-input.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md). + diff --git a/doc/language/cpsc-keyword-procedure.7.md b/doc/language/cpsc-keyword-procedure.7.md new file mode 100644 index 0000000..b2e6108 --- /dev/null +++ b/doc/language/cpsc-keyword-procedure.7.md @@ -0,0 +1,43 @@ +% CPSC-KEYWORD-PROCEDURE(7) + +# NAME + +cpsc-keyword-procedure - define a procedure and parameter modes + +# SYNOPSIS + +```text +PROCEDURE name(parameters) + statements +ENDPROCEDURE +``` + +# DESCRIPTION + +Invoke with CALL. Parameters use `name : type`, optionally prefixed by +BYVAL or BYREF. The default is BYVAL (copy); BYREF modifies the caller's +variable and requires an exact type match. Scalar BYREF arguments must be +plain variables. A mode remains in effect for following parameters until +another mode is specified. + +Arrays accept `ARRAY OF type` or `ARRAY[lower:upper, ...] OF type`; +explicit bounds must be integer literals. BYVAL copies the array; BYREF +shares it. Bare RETURN can exit a procedure before a block terminator; +RETURN with a value is invalid. BYVAL, BYREF, RETURN, and ENDPROCEDURE +belong here. Calls may precede top-level definitions. + +# EXAMPLE + +```text +PROCEDURE Increment(BYREF Value : INTEGER) + Value <- Value + 1 +ENDPROCEDURE +DECLARE Count : INTEGER +CALL Increment(Count) +OUTPUT Count +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md), [cpsc-keyword-function(7)](cpsc-keyword-function.7.md). + diff --git a/doc/language/cpsc-keyword-readfile.7.md b/doc/language/cpsc-keyword-readfile.7.md new file mode 100644 index 0000000..71cd3db --- /dev/null +++ b/doc/language/cpsc-keyword-readfile.7.md @@ -0,0 +1,34 @@ +% CPSC-KEYWORD-READFILE(7) + +# NAME + +cpsc-keyword-readfile - read a line from a text file + +# SYNOPSIS + +```text +READFILE filename, variable +``` + +# DESCRIPTION + +Read one line from a file opened FOR READ, removing the line ending. +The target must be a plain, previously declared STRING variable. +Guard reads with EOF; reading past the end terminates execution. + +# EXAMPLE + +```text +DECLARE Line : STRING +OPENFILE "notes.txt" FOR READ +WHILE NOT EOF("notes.txt") DO + READFILE "notes.txt", Line + OUTPUT Line +ENDWHILE +CLOSEFILE "notes.txt" +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md), [cpsc-function-eof(7)](cpsc-function-eof.7.md). + diff --git a/doc/language/cpsc-keyword-repeat.7.md b/doc/language/cpsc-keyword-repeat.7.md new file mode 100644 index 0000000..42fdd2d --- /dev/null +++ b/doc/language/cpsc-keyword-repeat.7.md @@ -0,0 +1,34 @@ +% CPSC-KEYWORD-REPEAT(7) + +# NAME + +cpsc-keyword-repeat - repeat until a condition is true + +# SYNOPSIS + +```text +REPEAT + statements +UNTIL condition +``` + +# DESCRIPTION + +Test after each iteration, so the body runs at least once. +Stop when the condition becomes true. UNTIL belongs to this syntax. + +# EXAMPLE + +```text +DECLARE Count : INTEGER +Count <- 0 +REPEAT + Count <- Count + 1 + OUTPUT Count +UNTIL Count = 3 +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-while(7)](cpsc-keyword-while.7.md), [cpsc-keyword-for(7)](cpsc-keyword-for.7.md). + diff --git a/doc/language/cpsc-keyword-type.7.md b/doc/language/cpsc-keyword-type.7.md new file mode 100644 index 0000000..d630403 --- /dev/null +++ b/doc/language/cpsc-keyword-type.7.md @@ -0,0 +1,53 @@ +% CPSC-KEYWORD-TYPE(7) + +# NAME + +cpsc-keyword-type - define enumerations, pointers, and records + +# SYNOPSIS + +```text +TYPE name = (value, ...) +TYPE name = ^type +TYPE name + DECLARE field : type +ENDTYPE +``` + +# DESCRIPTION + +Define types at top level. Enumeration values have globally reserved names; +OUTPUT prints their zero-based ordinals. Enumerations support comparisons +with the same type and addition/subtraction of INTEGER offsets; invalid +ordinals terminate execution. + +A prefix caret takes an address (`^variable`); a suffix caret dereferences +a pointer (`pointer^`). Pointee types must match exactly, even where guide +section 4.2's example mixes types. Pointers start null; dereferencing null +terminates execution. There is no NULL literal. Avoid pointers to local +variables after the function returns. + +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. + +# EXAMPLE + +```text +TYPE Point + DECLARE X : INTEGER + DECLARE Y : INTEGER +ENDTYPE +TYPE PointPtr = ^Point +DECLARE Position : Point +DECLARE Pointer : PointPtr +Pointer <- ^Position +Pointer^.X <- 3 +OUTPUT Position.X +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md), [cpsc-keyword-class(7)](cpsc-keyword-class.7.md). + diff --git a/doc/language/cpsc-keyword-while.7.md b/doc/language/cpsc-keyword-while.7.md new file mode 100644 index 0000000..e6707b4 --- /dev/null +++ b/doc/language/cpsc-keyword-while.7.md @@ -0,0 +1,34 @@ +% CPSC-KEYWORD-WHILE(7) + +# NAME + +cpsc-keyword-while - repeat while a condition is true + +# SYNOPSIS + +```text +WHILE condition DO + statements +ENDWHILE +``` + +# DESCRIPTION + +Test before each iteration; the body may run zero times. +DO and ENDWHILE belong to this syntax. + +# EXAMPLE + +```text +DECLARE Count : INTEGER +Count <- 1 +WHILE Count <= 3 DO + OUTPUT Count + Count <- Count + 1 +ENDWHILE +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-repeat(7)](cpsc-keyword-repeat.7.md), [cpsc-keyword-for(7)](cpsc-keyword-for.7.md). + diff --git a/doc/language/cpsc-keyword-writefile.7.md b/doc/language/cpsc-keyword-writefile.7.md new file mode 100644 index 0000000..a00be5e --- /dev/null +++ b/doc/language/cpsc-keyword-writefile.7.md @@ -0,0 +1,30 @@ +% CPSC-KEYWORD-WRITEFILE(7) + +# NAME + +cpsc-keyword-writefile - write a line to a text file + +# SYNOPSIS + +```text +WRITEFILE filename, expression +``` + +# DESCRIPTION + +Write one value as text followed by a newline. Open the file FOR WRITE or +APPEND first. Exactly one data expression is accepted; join strings with +`&` when needed. Records, classes, and pointers are unsupported as data. + +# EXAMPLE + +```text +OPENFILE "notes.txt" FOR APPEND +WRITEFILE "notes.txt", "Score: " & NUM_TO_STR(10) +CLOSEFILE "notes.txt" +``` + +# SEE ALSO + +[cpsc-language-overview(7)](cpsc-language-overview.7.md), [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md), [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md), [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md). + diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md new file mode 100644 index 0000000..8adf362 --- /dev/null +++ b/doc/language/cpsc-language-overview.7.md @@ -0,0 +1,100 @@ +% CPSC-LANGUAGE-OVERVIEW(7) + +# NAME + +cpsc-language-overview - supported cpsc pseudocode syntax + +# DESCRIPTION + +Keywords and built-in function names are uppercase and case-sensitive. +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. + +Precedence, from highest to lowest: unary operators, `* / DIV MOD`, +`+ - &`, comparisons, AND, OR. Parentheses override precedence. + +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. + +# KEYWORDS + +- [cpsc-keyword-declare(7)](cpsc-keyword-declare.7.md): declare variables and arrays. +- [cpsc-keyword-input(7)](cpsc-keyword-input.7.md): read a value from standard input. +- [cpsc-keyword-output(7)](cpsc-keyword-output.7.md): print values to standard output. +- [cpsc-keyword-if(7)](cpsc-keyword-if.7.md): choose between branches. +- [cpsc-keyword-while(7)](cpsc-keyword-while.7.md): repeat while a condition is true. +- [cpsc-keyword-repeat(7)](cpsc-keyword-repeat.7.md): repeat until a condition is true. +- [cpsc-keyword-for(7)](cpsc-keyword-for.7.md): iterate over an integer range. +- [cpsc-keyword-function(7)](cpsc-keyword-function.7.md): define a function that returns a value. +- [cpsc-keyword-procedure(7)](cpsc-keyword-procedure.7.md): define a procedure and parameter modes. +- [cpsc-keyword-call(7)](cpsc-keyword-call.7.md): invoke a procedure. +- [cpsc-keyword-openfile(7)](cpsc-keyword-openfile.7.md): open a text file. +- [cpsc-keyword-readfile(7)](cpsc-keyword-readfile.7.md): read a line from a text file. +- [cpsc-keyword-writefile(7)](cpsc-keyword-writefile.7.md): write a line to a text file. +- [cpsc-keyword-closefile(7)](cpsc-keyword-closefile.7.md): close a text file. +- [cpsc-keyword-type(7)](cpsc-keyword-type.7.md): define enumerations, pointers, and records. +- [cpsc-keyword-class(7)](cpsc-keyword-class.7.md): define a class with public and private fields. +- [cpsc-keyword-and(7)](cpsc-keyword-and.7.md): combine conditions with logical AND. +- [cpsc-keyword-or(7)](cpsc-keyword-or.7.md): combine conditions with logical OR. +- [cpsc-keyword-not(7)](cpsc-keyword-not.7.md): negate a condition. +- [cpsc-keyword-div(7)](cpsc-keyword-div.7.md): perform integer division. +- [cpsc-keyword-mod(7)](cpsc-keyword-mod.7.md): find the integer division remainder. + +Closing and auxiliary keywords are documented with their main constructs: +THEN/ELSE/ENDIF with IF; DO/ENDWHILE with WHILE; UNTIL with REPEAT; +TO/STEP/NEXT with FOR; RETURN/RETURNS/BYVAL/BYREF and function/procedure +closing keywords with FUNCTION/PROCEDURE; READ/WRITE/APPEND with OPENFILE; +ARRAY/OF and INTEGER/REAL/BOOLEAN/CHAR/STRING with DECLARE; +ENDTYPE with TYPE; PUBLIC/PRIVATE/ENDCLASS with CLASS. +TRUE/FALSE are BOOLEAN literals. + +# BUILT-IN FUNCTIONS + +- [cpsc-function-length(7)](cpsc-function-length.7.md): find a string's length. +- [cpsc-function-mid(7)](cpsc-function-mid.7.md): extract part of a string. +- [cpsc-function-left(7)](cpsc-function-left.7.md): extract the beginning of a string. +- [cpsc-function-right(7)](cpsc-function-right.7.md): extract the end of a string. +- [cpsc-function-lcase(7)](cpsc-function-lcase.7.md): convert text to lower case. +- [cpsc-function-ucase(7)](cpsc-function-ucase.7.md): convert text to upper case. +- [cpsc-function-asc(7)](cpsc-function-asc.7.md): find a character's byte code. +- [cpsc-function-chr(7)](cpsc-function-chr.7.md): convert a byte code to text. +- [cpsc-function-is_num(7)](cpsc-function-is_num.7.md): test whether text represents a number. +- [cpsc-function-num_to_str(7)](cpsc-function-num_to_str.7.md): convert a number to text. +- [cpsc-function-str_to_num(7)](cpsc-function-str_to_num.7.md): convert text to a real number. +- [cpsc-function-eof(7)](cpsc-function-eof.7.md): test for the end of a text file. + +# UNSUPPORTED FEATURES + +CASE OF, CONSTANT, DATE, SET types and DEFINE, random-file operations +(RANDOM/SEEK/GETRECORD/PUTRECORD), INT, RAND, INPUT into array elements or +fields, string escapes, whole-array assignment or return, array fields, +and class methods/constructors/destructors/inheritance (NEW/INHERITS/SUPER). + +The individual pages note relevant differences from the Cambridge 2026 +pseudocode guide. This manual describes the compiler's current support. + +# EXAMPLE + +```text +DECLARE Count : INTEGER +Count <- 2 +IF Count > 0 THEN + OUTPUT "Count: " & NUM_TO_STR(Count) +ENDIF +``` + +# SEE ALSO + +[cpsc(1)](../cpsc.1.md). + -- cgit v1.3.1-4-g156e