Group language manuals into function and keyword directories

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

12 files changed, 338 insertions, 0 deletions

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).
+