From ff121fcbb461a4d8f768e87128facf32e6272889 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 14:25:59 +0000 Subject: Group language manuals into function and keyword directories Co-Authored-By: Claude Fable 5.1 --- AGENTS/ARCH.md | 13 +++-- cmake/Manual.cmake | 2 +- cmake/Release.cmake | 19 +++++-- doc/build.md | 6 +- doc/install.md | 7 ++- 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 | 66 +++++++++++----------- doc/language/function/cpsc-function-asc.7.md | 28 +++++++++ doc/language/function/cpsc-function-chr.7.md | 28 +++++++++ doc/language/function/cpsc-function-eof.7.md | 34 +++++++++++ doc/language/function/cpsc-function-is_num.7.md | 28 +++++++++ doc/language/function/cpsc-function-lcase.7.md | 28 +++++++++ doc/language/function/cpsc-function-left.7.md | 27 +++++++++ doc/language/function/cpsc-function-length.7.md | 27 +++++++++ doc/language/function/cpsc-function-mid.7.md | 28 +++++++++ .../function/cpsc-function-num_to_str.7.md | 27 +++++++++ doc/language/function/cpsc-function-right.7.md | 27 +++++++++ .../function/cpsc-function-str_to_num.7.md | 28 +++++++++ doc/language/function/cpsc-function-ucase.7.md | 28 +++++++++ doc/language/keyword/cpsc-keyword-and.7.md | 28 +++++++++ doc/language/keyword/cpsc-keyword-call.7.md | 31 ++++++++++ doc/language/keyword/cpsc-keyword-class.7.md | 43 ++++++++++++++ doc/language/keyword/cpsc-keyword-closefile.7.md | 29 ++++++++++ doc/language/keyword/cpsc-keyword-declare.7.md | 40 +++++++++++++ doc/language/keyword/cpsc-keyword-div.7.md | 28 +++++++++ doc/language/keyword/cpsc-keyword-for.7.md | 35 ++++++++++++ doc/language/keyword/cpsc-keyword-function.7.md | 41 ++++++++++++++ doc/language/keyword/cpsc-keyword-if.7.md | 35 ++++++++++++ doc/language/keyword/cpsc-keyword-input.7.md | 31 ++++++++++ doc/language/keyword/cpsc-keyword-mod.7.md | 29 ++++++++++ doc/language/keyword/cpsc-keyword-not.7.md | 27 +++++++++ doc/language/keyword/cpsc-keyword-openfile.7.md | 37 ++++++++++++ doc/language/keyword/cpsc-keyword-or.7.md | 28 +++++++++ doc/language/keyword/cpsc-keyword-output.7.md | 32 +++++++++++ doc/language/keyword/cpsc-keyword-procedure.7.md | 43 ++++++++++++++ doc/language/keyword/cpsc-keyword-readfile.7.md | 34 +++++++++++ doc/language/keyword/cpsc-keyword-repeat.7.md | 34 +++++++++++ doc/language/keyword/cpsc-keyword-type.7.md | 53 +++++++++++++++++ doc/language/keyword/cpsc-keyword-while.7.md | 34 +++++++++++ doc/language/keyword/cpsc-keyword-writefile.7.md | 30 ++++++++++ install.ps1 | 28 ++++++--- install.sh | 7 ++- 74 files changed, 1147 insertions(+), 1121 deletions(-) delete mode 100644 doc/language/cpsc-function-asc.7.md delete mode 100644 doc/language/cpsc-function-chr.7.md delete mode 100644 doc/language/cpsc-function-eof.7.md delete mode 100644 doc/language/cpsc-function-is_num.7.md delete mode 100644 doc/language/cpsc-function-lcase.7.md delete mode 100644 doc/language/cpsc-function-left.7.md delete mode 100644 doc/language/cpsc-function-length.7.md delete mode 100644 doc/language/cpsc-function-mid.7.md delete mode 100644 doc/language/cpsc-function-num_to_str.7.md delete mode 100644 doc/language/cpsc-function-right.7.md delete mode 100644 doc/language/cpsc-function-str_to_num.7.md delete mode 100644 doc/language/cpsc-function-ucase.7.md delete mode 100644 doc/language/cpsc-keyword-and.7.md delete mode 100644 doc/language/cpsc-keyword-call.7.md delete mode 100644 doc/language/cpsc-keyword-class.7.md delete mode 100644 doc/language/cpsc-keyword-closefile.7.md delete mode 100644 doc/language/cpsc-keyword-declare.7.md delete mode 100644 doc/language/cpsc-keyword-div.7.md delete mode 100644 doc/language/cpsc-keyword-for.7.md delete mode 100644 doc/language/cpsc-keyword-function.7.md delete mode 100644 doc/language/cpsc-keyword-if.7.md delete mode 100644 doc/language/cpsc-keyword-input.7.md delete mode 100644 doc/language/cpsc-keyword-mod.7.md delete mode 100644 doc/language/cpsc-keyword-not.7.md delete mode 100644 doc/language/cpsc-keyword-openfile.7.md delete mode 100644 doc/language/cpsc-keyword-or.7.md delete mode 100644 doc/language/cpsc-keyword-output.7.md delete mode 100644 doc/language/cpsc-keyword-procedure.7.md delete mode 100644 doc/language/cpsc-keyword-readfile.7.md delete mode 100644 doc/language/cpsc-keyword-repeat.7.md delete mode 100644 doc/language/cpsc-keyword-type.7.md delete mode 100644 doc/language/cpsc-keyword-while.7.md delete mode 100644 doc/language/cpsc-keyword-writefile.7.md create mode 100644 doc/language/function/cpsc-function-asc.7.md create mode 100644 doc/language/function/cpsc-function-chr.7.md create mode 100644 doc/language/function/cpsc-function-eof.7.md create mode 100644 doc/language/function/cpsc-function-is_num.7.md create mode 100644 doc/language/function/cpsc-function-lcase.7.md create mode 100644 doc/language/function/cpsc-function-left.7.md create mode 100644 doc/language/function/cpsc-function-length.7.md create mode 100644 doc/language/function/cpsc-function-mid.7.md create mode 100644 doc/language/function/cpsc-function-num_to_str.7.md create mode 100644 doc/language/function/cpsc-function-right.7.md create mode 100644 doc/language/function/cpsc-function-str_to_num.7.md create mode 100644 doc/language/function/cpsc-function-ucase.7.md create mode 100644 doc/language/keyword/cpsc-keyword-and.7.md create mode 100644 doc/language/keyword/cpsc-keyword-call.7.md create mode 100644 doc/language/keyword/cpsc-keyword-class.7.md create mode 100644 doc/language/keyword/cpsc-keyword-closefile.7.md create mode 100644 doc/language/keyword/cpsc-keyword-declare.7.md create mode 100644 doc/language/keyword/cpsc-keyword-div.7.md create mode 100644 doc/language/keyword/cpsc-keyword-for.7.md create mode 100644 doc/language/keyword/cpsc-keyword-function.7.md create mode 100644 doc/language/keyword/cpsc-keyword-if.7.md create mode 100644 doc/language/keyword/cpsc-keyword-input.7.md create mode 100644 doc/language/keyword/cpsc-keyword-mod.7.md create mode 100644 doc/language/keyword/cpsc-keyword-not.7.md create mode 100644 doc/language/keyword/cpsc-keyword-openfile.7.md create mode 100644 doc/language/keyword/cpsc-keyword-or.7.md create mode 100644 doc/language/keyword/cpsc-keyword-output.7.md create mode 100644 doc/language/keyword/cpsc-keyword-procedure.7.md create mode 100644 doc/language/keyword/cpsc-keyword-readfile.7.md create mode 100644 doc/language/keyword/cpsc-keyword-repeat.7.md create mode 100644 doc/language/keyword/cpsc-keyword-type.7.md create mode 100644 doc/language/keyword/cpsc-keyword-while.7.md create mode 100644 doc/language/keyword/cpsc-keyword-writefile.7.md diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index e551c8f..cb2e6a3 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -117,7 +117,7 @@ timestamp (`yyyy-mm-dd-hh-mm-ss`) followed by its short ID. Git is only required for packaging; recipients can install the extracted archive using just the script. The Windows `install.ps1` installs `cpsc.exe`, `doc/cpsc.html` and -`doc/language/*.html` for the current user under `%LOCALAPPDATA%\Programs\cpsc` (or `-Prefix`). It appends that directory +`doc/language/**/*.html` for the current user under `%LOCALAPPDATA%\Programs\cpsc` (or `-Prefix`). It appends that directory to the user PATH without copying the combined process PATH, and creates a per-user Start Menu help shortcut. `-SourceDir` selects the artifact directory; `DESTDIR` staging is unsupported on Windows. The script is compatible with @@ -125,8 +125,8 @@ Windows PowerShell 5.1; its Windows actions have only been reviewed statically. The `doc` target uses CMake's `WIN32` target-platform detection: Windows generates standalone HTML with inline styles at `build/doc/cpsc.html`; other platforms generate `build/doc/cpsc.1`. The section 1 source is `doc/cpsc.1.md`; section 7 sources are -`doc/language/cpsc-*.7.md`. `doc` builds every page, preserving the language -subdirectory, as `.7` on Unix or `.html` on Windows. Sources are discovered with +`doc/language/**/*.7.md`. `doc` builds every page, preserving the language +category subdirectories, as `.7` on Unix or `.html` on Windows. Sources are discovered with CONFIGURE_DEPENDS; per-page commands regenerate only changed pages. `cmake/ManualLinks.lua` renders cross-references as man names or local HTML links. Windows `mingw32-make -C build install` builds the HTML manual and invokes @@ -135,7 +135,7 @@ Windows `mingw32-make -C build install` builds the HTML manual and invokes directory above; explicit prefixes are preserved. Unix still invokes `install.sh`. The release target explicitly passes the configured Windows flag to `cmake/Release.cmake`, since a standalone CMake script otherwise describes the -host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/*.html`, `install.ps1` and +host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and `LICENSE` as `build/cpsc-VERSION-Windows-ARCH.zip` using CMake's default Deflate compression. Unix retains `.tar.xz`, the POSIX installer and the man pages. Linux smoke tests can configure an isolated build with `-DWIN32=TRUE` to exercise @@ -183,8 +183,9 @@ they are pure data with virtual destructors only — no codegen/visitor methods. ## Language manuals `doc/cpsc.1.md` documents the command-line interface. Short language manuals live -in `doc/language/` as `cpsc-keyword-NAME.7.md`, `cpsc-function-NAME.7.md`, and -`cpsc-language-overview.7.md`; filenames are lowercase and preserve underscores. +in `doc/language/keyword/` as `cpsc-keyword-NAME.7.md` and +`doc/language/function/` as `cpsc-function-NAME.7.md`; the overview remains +`doc/language/cpsc-language-overview.7.md`. Filenames are lowercase and preserve underscores. Document auxiliary/closing keywords with the main construct, not in separate pages. Keep examples small and describe actual compiler support, noting relevant differences from the 2026 Cambridge guide in `reference/`. All project text is diff --git a/cmake/Manual.cmake b/cmake/Manual.cmake index 689c91e..17a8e77 100644 --- a/cmake/Manual.cmake +++ b/cmake/Manual.cmake @@ -6,7 +6,7 @@ endif() configure_file("${CMAKE_CURRENT_LIST_DIR}/GenerateManual.cmake.in" "${CMAKE_CURRENT_BINARY_DIR}/GenerateManual.cmake" @ONLY) -file(GLOB cpsc_language_sources CONFIGURE_DEPENDS +file(GLOB_RECURSE cpsc_language_sources CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/doc/language/cpsc-*.7.md") set(cpsc_manual_sources "${CMAKE_CURRENT_SOURCE_DIR}/doc/cpsc.1.md" ${cpsc_language_sources}) diff --git a/cmake/Release.cmake b/cmake/Release.cmake index 59a1d79..66c2e2b 100644 --- a/cmake/Release.cmake +++ b/cmake/Release.cmake @@ -21,7 +21,7 @@ if(CPSC_WINDOWS) set(cpsc_binary_name cpsc.exe) set(cpsc_installer install.ps1) set(cpsc_manual cpsc.html) - set(cpsc_language_pattern "${CPSC_BINARY_DIR}/doc/language/cpsc-*.html") + set(cpsc_language_extension html) set(cpsc_tar_flags cf) set(cpsc_archive_format zip) else() @@ -29,7 +29,7 @@ else() set(cpsc_binary_name cpsc) set(cpsc_installer install.sh) set(cpsc_manual cpsc.1) - set(cpsc_language_pattern "${CPSC_BINARY_DIR}/doc/language/cpsc-*.7") + set(cpsc_language_extension 7) set(cpsc_tar_flags cJf) set(cpsc_archive_format gnutar) endif() @@ -40,11 +40,18 @@ configure_file("${CPSC_EXECUTABLE}" "${cpsc_package_dir}/${cpsc_binary_name}" CO file(COPY "${CPSC_SOURCE_DIR}/${cpsc_installer}" "${CPSC_SOURCE_DIR}/LICENSE" DESTINATION "${cpsc_package_dir}") file(COPY "${CPSC_BINARY_DIR}/doc/${cpsc_manual}" DESTINATION "${cpsc_package_dir}/doc") -file(GLOB cpsc_language_manuals "${cpsc_language_pattern}") -if(NOT cpsc_language_manuals) - message(FATAL_ERROR "Language manuals are missing; build the doc target first") +# Package the current source set, preserving categories and ignoring stale outputs. +file(GLOB_RECURSE cpsc_language_sources "${CPSC_SOURCE_DIR}/doc/language/cpsc-*.7.md") +if(NOT cpsc_language_sources) + message(FATAL_ERROR "Language manual sources are missing") endif() -file(COPY ${cpsc_language_manuals} DESTINATION "${cpsc_package_dir}/doc/language") +foreach(source IN LISTS cpsc_language_sources) + file(RELATIVE_PATH relative "${CPSC_SOURCE_DIR}/doc/language" "${source}") + string(REGEX REPLACE "\\.7\\.md$" ".${cpsc_language_extension}" relative "${relative}") + get_filename_component(directory "${relative}" DIRECTORY) + file(COPY "${CPSC_BINARY_DIR}/doc/language/${relative}" + DESTINATION "${cpsc_package_dir}/doc/language/${directory}") +endforeach() execute_process( COMMAND "${CMAKE_COMMAND}" -E tar "${cpsc_tar_flags}" "${cpsc_archive}" "--format=${cpsc_archive_format}" "${cpsc_package_name}" diff --git a/doc/build.md b/doc/build.md index ee335fd..4942859 100644 --- a/doc/build.md +++ b/doc/build.md @@ -225,13 +225,13 @@ cmake --build build --target doc ``` CMake selects local Pandoc first, sets its local runtime/data paths as needed, -and falls back to Pandoc in the system PATH. The outputs are `build/doc/cpsc.1` and `build/doc/language/*.7` on Unix, -or `build/doc/cpsc.html` and `build/doc/language/*.html` on Windows. Each page +and falls back to Pandoc in the system PATH. The outputs are `build/doc/cpsc.1` and `build/doc/language/**/*.7` on Unix, +or `build/doc/cpsc.html` and `build/doc/language/**/*.html` on Windows. Each page is regenerated when its source, rendering configuration or downloaded packages change. New language pages are discovered automatically during the build. On Unix, open the command manual with `man ./build/doc/cpsc.1`, or a syntax -page with `man ./build/doc/language/cpsc-keyword-if.7`. On Windows, open the standalone, +page with `man ./build/doc/language/keyword/cpsc-keyword-if.7`. On Windows, open the standalone, offline HTML from PowerShell: ```powershell diff --git a/doc/install.md b/doc/install.md index 9fe660a..d91b059 100644 --- a/doc/install.md +++ b/doc/install.md @@ -78,7 +78,7 @@ make -C build release The output is `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`. `VERSION` uses HEAD's commit time in UTC followed by its short ID: `yyyy-mm-dd-hh-mm-ss-commit`. The version is read each time packaging runs. The package uses the current build's -execution mode and contains `cpsc`, `doc/cpsc.1`, `doc/language/*.7`, `install.sh` and `LICENSE`. +execution mode and contains `cpsc`, `doc/cpsc.1`, `doc/language/**/*.7`, `install.sh` and `LICENSE`. Packaging builds the compiler and manual automatically; it requires Git and Pandoc. Use `EMBEDDED` when recipients should not need LLVM or `lli` at run time. @@ -106,7 +106,7 @@ prefix is preserved. To change it, run You can also call `install.ps1` directly. It installs for the current user without administrator rights. Its source directory must contain `cpsc.exe`, -`doc/cpsc.html` and `doc/language/*.html`: +`doc/cpsc.html` and `doc/language/**/*.html`: ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDir .\build @@ -114,6 +114,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDir The default destination is `%LOCALAPPDATA%\Programs\cpsc`: `cpsc.exe` goes in that directory, the command manual goes in `doc`, and syntax manuals go in +`doc/language/function` and `doc/language/keyword`; the overview stays in `doc/language`. The command manual links to the language overview and its pages. The installer adds the directory to the user PATH and creates Start Menu > cpsc > cpsc Help, which opens the manual in the default browser. Open a new terminal afterward; @@ -134,7 +135,7 @@ cmake --build build --target release This is equivalent to `mingw32-make -C build release`. Windows produces `build/cpsc-VERSION-Windows-ARCH.zip`, using the same UTC commit version as Unix and retaining the configured execution mode. The ZIP contains `cpsc.exe`, -`doc/cpsc.html`, `doc/language/*.html`, `install.ps1` and `LICENSE` under one top-level directory. +`doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and `LICENSE` under one top-level directory. It uses CMake's default Deflate compression and needs no additional compression tool; packaging requires Git and Pandoc, just as on Unix. diff --git a/doc/language/cpsc-function-asc.7.md b/doc/language/cpsc-function-asc.7.md deleted file mode 100644 index 0600599..0000000 --- a/doc/language/cpsc-function-asc.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 5062468..0000000 --- a/doc/language/cpsc-function-chr.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 721e667..0000000 --- a/doc/language/cpsc-function-eof.7.md +++ /dev/null @@ -1,34 +0,0 @@ -% 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 deleted file mode 100644 index de37b71..0000000 --- a/doc/language/cpsc-function-is_num.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index f6ca334..0000000 --- a/doc/language/cpsc-function-lcase.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index b4542d6..0000000 --- a/doc/language/cpsc-function-left.7.md +++ /dev/null @@ -1,27 +0,0 @@ -% 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 deleted file mode 100644 index a7f6acf..0000000 --- a/doc/language/cpsc-function-length.7.md +++ /dev/null @@ -1,27 +0,0 @@ -% 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 deleted file mode 100644 index 3a6bc71..0000000 --- a/doc/language/cpsc-function-mid.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 30dc39b..0000000 --- a/doc/language/cpsc-function-num_to_str.7.md +++ /dev/null @@ -1,27 +0,0 @@ -% 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 deleted file mode 100644 index ae9114b..0000000 --- a/doc/language/cpsc-function-right.7.md +++ /dev/null @@ -1,27 +0,0 @@ -% 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 deleted file mode 100644 index 6128a13..0000000 --- a/doc/language/cpsc-function-str_to_num.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index dd44892..0000000 --- a/doc/language/cpsc-function-ucase.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 6b98abf..0000000 --- a/doc/language/cpsc-keyword-and.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index b17b3f4..0000000 --- a/doc/language/cpsc-keyword-call.7.md +++ /dev/null @@ -1,31 +0,0 @@ -% 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 deleted file mode 100644 index 7ff32ba..0000000 --- a/doc/language/cpsc-keyword-class.7.md +++ /dev/null @@ -1,43 +0,0 @@ -% 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 deleted file mode 100644 index b986b86..0000000 --- a/doc/language/cpsc-keyword-closefile.7.md +++ /dev/null @@ -1,29 +0,0 @@ -% 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 deleted file mode 100644 index 887ae12..0000000 --- a/doc/language/cpsc-keyword-declare.7.md +++ /dev/null @@ -1,40 +0,0 @@ -% 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 deleted file mode 100644 index 78715e1..0000000 --- a/doc/language/cpsc-keyword-div.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 201a492..0000000 --- a/doc/language/cpsc-keyword-for.7.md +++ /dev/null @@ -1,35 +0,0 @@ -% 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 deleted file mode 100644 index c37754c..0000000 --- a/doc/language/cpsc-keyword-function.7.md +++ /dev/null @@ -1,41 +0,0 @@ -% 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 deleted file mode 100644 index 9f14959..0000000 --- a/doc/language/cpsc-keyword-if.7.md +++ /dev/null @@ -1,35 +0,0 @@ -% 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 deleted file mode 100644 index f31731f..0000000 --- a/doc/language/cpsc-keyword-input.7.md +++ /dev/null @@ -1,31 +0,0 @@ -% 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 deleted file mode 100644 index cb437a4..0000000 --- a/doc/language/cpsc-keyword-mod.7.md +++ /dev/null @@ -1,29 +0,0 @@ -% 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 deleted file mode 100644 index 5bb1c18..0000000 --- a/doc/language/cpsc-keyword-not.7.md +++ /dev/null @@ -1,27 +0,0 @@ -% 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 deleted file mode 100644 index a13b3f4..0000000 --- a/doc/language/cpsc-keyword-openfile.7.md +++ /dev/null @@ -1,37 +0,0 @@ -% 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 deleted file mode 100644 index 7fca628..0000000 --- a/doc/language/cpsc-keyword-or.7.md +++ /dev/null @@ -1,28 +0,0 @@ -% 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 deleted file mode 100644 index 9ee2133..0000000 --- a/doc/language/cpsc-keyword-output.7.md +++ /dev/null @@ -1,32 +0,0 @@ -% 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 deleted file mode 100644 index b2e6108..0000000 --- a/doc/language/cpsc-keyword-procedure.7.md +++ /dev/null @@ -1,43 +0,0 @@ -% 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 deleted file mode 100644 index 71cd3db..0000000 --- a/doc/language/cpsc-keyword-readfile.7.md +++ /dev/null @@ -1,34 +0,0 @@ -% 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 deleted file mode 100644 index 42fdd2d..0000000 --- a/doc/language/cpsc-keyword-repeat.7.md +++ /dev/null @@ -1,34 +0,0 @@ -% 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 deleted file mode 100644 index d630403..0000000 --- a/doc/language/cpsc-keyword-type.7.md +++ /dev/null @@ -1,53 +0,0 @@ -% 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 deleted file mode 100644 index e6707b4..0000000 --- a/doc/language/cpsc-keyword-while.7.md +++ /dev/null @@ -1,34 +0,0 @@ -% 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 deleted file mode 100644 index a00be5e..0000000 --- a/doc/language/cpsc-keyword-writefile.7.md +++ /dev/null @@ -1,30 +0,0 @@ -% 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 index 8adf362..7005fa0 100644 --- a/doc/language/cpsc-language-overview.7.md +++ b/doc/language/cpsc-language-overview.7.md @@ -29,27 +29,27 @@ 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. +- [cpsc-keyword-declare(7)](keyword/cpsc-keyword-declare.7.md): declare variables and arrays. +- [cpsc-keyword-input(7)](keyword/cpsc-keyword-input.7.md): read a value from standard input. +- [cpsc-keyword-output(7)](keyword/cpsc-keyword-output.7.md): print values to standard output. +- [cpsc-keyword-if(7)](keyword/cpsc-keyword-if.7.md): choose between branches. +- [cpsc-keyword-while(7)](keyword/cpsc-keyword-while.7.md): repeat while a condition is true. +- [cpsc-keyword-repeat(7)](keyword/cpsc-keyword-repeat.7.md): repeat until a condition is true. +- [cpsc-keyword-for(7)](keyword/cpsc-keyword-for.7.md): iterate over an integer range. +- [cpsc-keyword-function(7)](keyword/cpsc-keyword-function.7.md): define a function that returns a value. +- [cpsc-keyword-procedure(7)](keyword/cpsc-keyword-procedure.7.md): define a procedure and parameter modes. +- [cpsc-keyword-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. +- [cpsc-keyword-readfile(7)](keyword/cpsc-keyword-readfile.7.md): read a line from a text file. +- [cpsc-keyword-writefile(7)](keyword/cpsc-keyword-writefile.7.md): write a line to a text file. +- [cpsc-keyword-closefile(7)](keyword/cpsc-keyword-closefile.7.md): close a text file. +- [cpsc-keyword-type(7)](keyword/cpsc-keyword-type.7.md): define enumerations, pointers, and records. +- [cpsc-keyword-class(7)](keyword/cpsc-keyword-class.7.md): define a class with public and private fields. +- [cpsc-keyword-and(7)](keyword/cpsc-keyword-and.7.md): combine conditions with logical AND. +- [cpsc-keyword-or(7)](keyword/cpsc-keyword-or.7.md): combine conditions with logical OR. +- [cpsc-keyword-not(7)](keyword/cpsc-keyword-not.7.md): negate a condition. +- [cpsc-keyword-div(7)](keyword/cpsc-keyword-div.7.md): perform integer division. +- [cpsc-keyword-mod(7)](keyword/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; @@ -61,18 +61,18 @@ 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. +- [cpsc-function-length(7)](function/cpsc-function-length.7.md): find a string's length. +- [cpsc-function-mid(7)](function/cpsc-function-mid.7.md): extract part of a string. +- [cpsc-function-left(7)](function/cpsc-function-left.7.md): extract the beginning of a string. +- [cpsc-function-right(7)](function/cpsc-function-right.7.md): extract the end of a string. +- [cpsc-function-lcase(7)](function/cpsc-function-lcase.7.md): convert text to lower case. +- [cpsc-function-ucase(7)](function/cpsc-function-ucase.7.md): convert text to upper case. +- [cpsc-function-asc(7)](function/cpsc-function-asc.7.md): find a character's byte code. +- [cpsc-function-chr(7)](function/cpsc-function-chr.7.md): convert a byte code to text. +- [cpsc-function-is_num(7)](function/cpsc-function-is_num.7.md): test whether text represents a number. +- [cpsc-function-num_to_str(7)](function/cpsc-function-num_to_str.7.md): convert a number to text. +- [cpsc-function-str_to_num(7)](function/cpsc-function-str_to_num.7.md): convert text to a real number. +- [cpsc-function-eof(7)](function/cpsc-function-eof.7.md): test for the end of a text file. # UNSUPPORTED FEATURES diff --git a/doc/language/function/cpsc-function-asc.7.md b/doc/language/function/cpsc-function-asc.7.md new file mode 100644 index 0000000..72403a7 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-chr.7.md b/doc/language/function/cpsc-function-chr.7.md new file mode 100644 index 0000000..59b3121 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-eof.7.md b/doc/language/function/cpsc-function-eof.7.md new file mode 100644 index 0000000..3ab2d31 --- /dev/null +++ b/doc/language/function/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)](../keyword/cpsc-keyword-openfile.7.md), [cpsc-keyword-readfile(7)](../keyword/cpsc-keyword-readfile.7.md), [cpsc-keyword-closefile(7)](../keyword/cpsc-keyword-closefile.7.md). + diff --git a/doc/language/function/cpsc-function-is_num.7.md b/doc/language/function/cpsc-function-is_num.7.md new file mode 100644 index 0000000..a85acfe --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-lcase.7.md b/doc/language/function/cpsc-function-lcase.7.md new file mode 100644 index 0000000..c8c7db9 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-left.7.md b/doc/language/function/cpsc-function-left.7.md new file mode 100644 index 0000000..38a703e --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-length.7.md b/doc/language/function/cpsc-function-length.7.md new file mode 100644 index 0000000..9730798 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-mid.7.md b/doc/language/function/cpsc-function-mid.7.md new file mode 100644 index 0000000..66f7294 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-num_to_str.7.md b/doc/language/function/cpsc-function-num_to_str.7.md new file mode 100644 index 0000000..fb4f6fc --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-right.7.md b/doc/language/function/cpsc-function-right.7.md new file mode 100644 index 0000000..9aa10e6 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-str_to_num.7.md b/doc/language/function/cpsc-function-str_to_num.7.md new file mode 100644 index 0000000..341b757 --- /dev/null +++ b/doc/language/function/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/function/cpsc-function-ucase.7.md b/doc/language/function/cpsc-function-ucase.7.md new file mode 100644 index 0000000..6356f48 --- /dev/null +++ b/doc/language/function/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/keyword/cpsc-keyword-and.7.md b/doc/language/keyword/cpsc-keyword-and.7.md new file mode 100644 index 0000000..8df8c56 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-call.7.md b/doc/language/keyword/cpsc-keyword-call.7.md new file mode 100644 index 0000000..e999a8b --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-class.7.md b/doc/language/keyword/cpsc-keyword-class.7.md new file mode 100644 index 0000000..d7ec12f --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-closefile.7.md b/doc/language/keyword/cpsc-keyword-closefile.7.md new file mode 100644 index 0000000..381ae56 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-declare.7.md b/doc/language/keyword/cpsc-keyword-declare.7.md new file mode 100644 index 0000000..7fe1cf6 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-div.7.md b/doc/language/keyword/cpsc-keyword-div.7.md new file mode 100644 index 0000000..6adb23d --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-for.7.md b/doc/language/keyword/cpsc-keyword-for.7.md new file mode 100644 index 0000000..57b5632 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-function.7.md b/doc/language/keyword/cpsc-keyword-function.7.md new file mode 100644 index 0000000..d687ba9 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-if.7.md b/doc/language/keyword/cpsc-keyword-if.7.md new file mode 100644 index 0000000..a934922 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-input.7.md b/doc/language/keyword/cpsc-keyword-input.7.md new file mode 100644 index 0000000..c14fac1 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-mod.7.md b/doc/language/keyword/cpsc-keyword-mod.7.md new file mode 100644 index 0000000..2eceeb5 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-not.7.md b/doc/language/keyword/cpsc-keyword-not.7.md new file mode 100644 index 0000000..0ada425 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-openfile.7.md b/doc/language/keyword/cpsc-keyword-openfile.7.md new file mode 100644 index 0000000..2aa2b44 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-or.7.md b/doc/language/keyword/cpsc-keyword-or.7.md new file mode 100644 index 0000000..4594215 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-output.7.md b/doc/language/keyword/cpsc-keyword-output.7.md new file mode 100644 index 0000000..a1c2d2a --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-procedure.7.md b/doc/language/keyword/cpsc-keyword-procedure.7.md new file mode 100644 index 0000000..d8be9f4 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-readfile.7.md b/doc/language/keyword/cpsc-keyword-readfile.7.md new file mode 100644 index 0000000..8260dd2 --- /dev/null +++ b/doc/language/keyword/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)](../function/cpsc-function-eof.7.md). + diff --git a/doc/language/keyword/cpsc-keyword-repeat.7.md b/doc/language/keyword/cpsc-keyword-repeat.7.md new file mode 100644 index 0000000..b1a73c2 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-type.7.md b/doc/language/keyword/cpsc-keyword-type.7.md new file mode 100644 index 0000000..9dd4c73 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-while.7.md b/doc/language/keyword/cpsc-keyword-while.7.md new file mode 100644 index 0000000..c6d8721 --- /dev/null +++ b/doc/language/keyword/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/keyword/cpsc-keyword-writefile.7.md b/doc/language/keyword/cpsc-keyword-writefile.7.md new file mode 100644 index 0000000..caeafe7 --- /dev/null +++ b/doc/language/keyword/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)](../function/cpsc-function-num_to_str.7.md). + diff --git a/install.ps1 b/install.ps1 index 7d8ccce..e09efb3 100644 --- a/install.ps1 +++ b/install.ps1 @@ -3,7 +3,7 @@ .SYNOPSIS Installs cpsc and its HTML manual for the current user. .DESCRIPTION -Copies cpsc.exe, doc\cpsc.html and doc\language\*.html, creates a help shortcut, and +Copies cpsc.exe, doc\cpsc.html and doc\language HTML pages, creates a help shortcut, and adds the installation directory to the user PATH. No administrator is needed for the default location: %LOCALAPPDATA%\Programs\cpsc. .EXAMPLE @@ -26,7 +26,7 @@ $ErrorActionPreference = 'Stop' if ($Help) { Write-Output 'Usage: install.ps1 [-Prefix DIR] [-SourceDir DIR] [-Help]' Write-Output 'Default destination: %LOCALAPPDATA%\Programs\cpsc' - Write-Output 'Source must contain cpsc.exe, doc\cpsc.html and doc\language\*.html; default: script directory.' + Write-Output 'Source must contain cpsc.exe, doc\cpsc.html and doc\language HTML pages; default: script directory.' return } @@ -75,7 +75,19 @@ try { if (-not (Test-Path -LiteralPath $sourceLanguageDir -PathType Container)) { throw "Missing language manuals: $sourceLanguageDir; build the doc target first." } - $languageManuals = @(Get-ChildItem -LiteralPath $sourceLanguageDir -Filter 'cpsc-*.html' -File) + $sourceOverview = Join-Path $sourceLanguageDir 'cpsc-language-overview.html' + if (-not (Test-Path -LiteralPath $sourceOverview -PathType Leaf)) { + throw "Missing language overview: $sourceOverview; build the doc target first." + } + $languageManuals = @(Get-Item -LiteralPath $sourceOverview) + foreach ($category in @('function', 'keyword')) { + $categoryDir = Join-Path $sourceLanguageDir $category + $categoryManuals = @(Get-ChildItem -LiteralPath $categoryDir -Filter "cpsc-$category-*.html" -File) + if ($categoryManuals.Count -eq 0) { + throw "Missing language manuals: $categoryDir; build the doc target first." + } + $languageManuals += $categoryManuals + } if ($languageManuals.Count -eq 0) { throw "Missing language manuals: $sourceLanguageDir; build the doc target first." } @@ -84,14 +96,14 @@ try { $languageDir = Join-Path $docDir 'language' $targetExe = Join-Path $Prefix 'cpsc.exe' $targetManual = Join-Path $docDir 'cpsc.html' - foreach ($directory in @($Prefix, $docDir, $languageDir)) { + foreach ($directory in @($Prefix, $docDir, $languageDir, (Join-Path $languageDir 'function'), (Join-Path $languageDir 'keyword'))) { if ((Test-Path -LiteralPath $directory) -and -not (Test-Path -LiteralPath $directory -PathType Container)) { throw "Installation directory is occupied by a file: $directory" } } $targetFiles = @($targetExe, $targetManual) + @($languageManuals | ForEach-Object { - Join-Path $languageDir $_.Name + Join-Path $languageDir ($_.FullName.Substring($sourceLanguageDir.Length + 1)) }) foreach ($file in $targetFiles) { if (Test-Path -LiteralPath $file -PathType Container) { @@ -107,7 +119,9 @@ try { $shell = New-Object -ComObject WScript.Shell # Directory.CreateDirectory treats paths literally, including spaces and brackets. - [IO.Directory]::CreateDirectory($languageDir) | Out-Null + foreach ($category in @('function', 'keyword')) { + [IO.Directory]::CreateDirectory((Join-Path $languageDir $category)) | Out-Null + } if ($sourceExe -ine $targetExe) { Copy-Item -LiteralPath $sourceExe -Destination $targetExe -Force } @@ -115,7 +129,7 @@ try { Copy-Item -LiteralPath $sourceManual -Destination $targetManual -Force } foreach ($manual in $languageManuals) { - $destination = Join-Path $languageDir $manual.Name + $destination = Join-Path $languageDir ($manual.FullName.Substring($sourceLanguageDir.Length + 1)) if ($manual.FullName -ine $destination) { Copy-Item -LiteralPath $manual.FullName -Destination $destination -Force } diff --git a/install.sh b/install.sh index fbe98a2..6f0f263 100755 --- a/install.sh +++ b/install.sh @@ -8,7 +8,8 @@ Usage: install.sh [--prefix DIR] [--source-dir DIR] Install cpsc to DIR/bin and its man pages to DIR/share/cpsc/man/man1 and man7. The default prefix is /usr/local. The source directory defaults to the directory containing this script and must contain cpsc, doc/cpsc.1 and -doc/language/*.7. Installation registers the independent manual search path. +doc/language/cpsc-language-overview.7 and doc/language/{function,keyword}/*.7. +Installation registers the independent manual search path. Use --source-dir build when running this script from the source checkout. DESTDIR may be set to stage files without changing host manpath configuration. EOF @@ -46,7 +47,9 @@ source_dir=$(CDPATH= cd -- "$source_dir" && pwd) || die "cannot open source dire || die "missing readable executable: $source_dir/cpsc; build cpsc first" [ -f "$source_dir/doc/cpsc.1" ] && [ -r "$source_dir/doc/cpsc.1" ] \ || die "missing readable manual: $source_dir/doc/cpsc.1; run make doc first" -set -- "$source_dir"/doc/language/cpsc-*.7 +set -- "$source_dir/doc/language/cpsc-language-overview.7" \ + "$source_dir"/doc/language/function/cpsc-function-*.7 \ + "$source_dir"/doc/language/keyword/cpsc-keyword-*.7 [ -f "$1" ] || die "missing language manuals: $source_dir/doc/language; run make doc first" for manual do [ -f "$manual" ] && [ -r "$manual" ] || die "missing readable manual: $manual" -- cgit v1.3.1-4-g156e