CAIE Code (cpc)

the CAIE Pseudocode Interpreter

中文 | English

Installation and Update

Online Version

Installation Preliminaries

Have python3 installed on your computer.

It is suggested to use pypy3 to achieve the best efficiency.

Have git installed on your computer. If you do not know what git is, see https://git-scm.com/downloads.

For macOS users ensure you installed Command Line Tools for Xcode.

cargo if you want to compile manually

Installation

For macOS users, you can install directly using following scripts:

curl -fsSL https://atcrea.tech/cpc.sh | sh

For those who want to install with Visual Studio Code as well as its extension, you can use the following script:
curl -fsSL https://atcrea.tech/cpc.sh | sh -s -- --with-vsc

For other users...

Clone the project to your computer using git clone https://github.com/iewnfod/CAIE_Code.git.
Enter the project folder: cd CAIE_Code.
The executable programs are in bin/ folder. You may directly run or consider adding bin/ to your PATH.
If you want to compile manually:

macOS: run build.sh
Windows: run build.ps1

If you want to see the manual page from man command, you should consider link the manual file man/cpc.1 to your MANPATH.

For example(Linux): sudo ln -f ./man/cpc.1 /your/man/path.
If you cannot execute the complied files, please submit the problems on our issue page.

Update

If you followed the instructions and used git or PKG to install cpc, you can update easily using cpc -u.
An auto-update feature is introduced after dc0cd71 to automatically detect updates once a week.
Otherwise, you should manually re-install the whole project.

Usage

cpc [filepath] [options]

It runs the entire file if filepath is provided, otherwise, it enters playground mode.

Options

Mnemonic	Option	Description
`-c`	`--config`	To set configs of this interpreter
`-d`	`--document`	To show the official document
`-h`	`--help`	To show the help page
`-k`	`--keywords`	To show all the keywords
`-m`	`--migrate`	To migrate `.p` files to `.cpc` in a specified directory
`-n`	`--notification`	To show notification published by developer (only if this is not expired)
`-p`	`--parse`	To show parse information during running
`-t`	`--time`	To show the time for the script to run
`-u`	`--update`	To update the version
`-v`	`--version`	To show the version of this interpreter
`-gt`	`--get-tree`	To show the tree of the program after being parsed
`-lc`	`--list-configs`	To list all the configs of the interpreter
`-ne`	`--no-error`	To remove all error messages
`-rc`	`--reset-configs`	To reset all the configs of the interpreter
`-init`	`--init-requirements`	To install all dependences

Config

remote
- github: Use GitHub as the update source. This source is always the latest.
- gitee: Use Gitee as the update source, which might be slower than Github.
branch
- stable: Updates are slow, but the most stable.
- nightly: This branch will update once a day. Early adopters can try this branch, please actively report the issue.
- dev: The latest version of CPC may contain many untested functions.
This setting needs to be run cpc -u once for it to take effect.

In a developer mod, your remote will not be changed by config and the branch will be locked in dev.
auto-update
- true：Enable auto update.
- false：Disable auto update.
last-auto-update All non-negative real numbers are accepted and automatically updated by the system.
interval-update All non-negative integers, in seconds, are accepted as the automatic update interval.
recursion-limit(rl) all integer number as the recursion depth limit of the interpreter.
integrity-protection
- true: Enable integrity protection.
- false: Disable integrity protection.
Integrity Protection prevent any accidental or malicious modification of the interpreter.

This protection will be automatically disabled in developer mode.
dev
- true: Enable developer mode.
- false: Disable developer mode.
Developer Options
- dev.simulate-update
  - true: Enable simulation updates
  - false: Disable simulation updates

FAQs

Import Error

Please try to install all Python packages manually using pip install -r requirements.txt

Import Error after I manually installed packages

The program will automatically detect pypy3 when available and use it to interpret pseudocode because it has better efficiency.

If you have pypy3 installed you should install manually using pypy3 -m pip install -r requirements.txt

Incorrect <up>, <down>, <left>, <right> key actions when in playground mode

You should retry pip install readline or pip install gnureadline.

OSError when launching

Enter the directory of this project, and run

rm -rf .cpc_history
cpc -u

Efficiency test

Test Environment

machine: 2020 MacBook Pro
processor: Apple M1
RAM: 8GB
Cores: 8 (4 efficient, 4 performance)
OS: macOS 14.1.1 (23B81)
Python version: PyPy 3.9.16

Basic Tests

assignment: 1200w/s

DECLARE a : INTEGER
FOR i <- 1 TO 12000000
    a <- i
NEXT i

explicit conversion and assignment: 760w/s

DECLARE a : STRING
FOR i <- 1 TO 7600000
    a <- STRING(i)
NEXT i

implicit conversion and assignment: 1000w/s

DECLARE a : STRING
FOR i <- 1 TO 10000000
    a <- i
NEXT i

print to terminal: 65w/s

FOR i <- 1 TO 650000
    OUTPUT i
NEXT i

Computation Tests

generating 100k randoms and shell sorting: about 3.5s

Standards

Basic Standards

use camelCase naming
use .cpc as the file suffix
use utf-8 encoding
all reserved words are in upper case
the program is case-sensitive
use // to comment code

Features

Most syntax follows the pseudocode standard of CAIE.

However, indentation is suggested but not compulsory.

Each statement following CASE statement must end with a ;, semicolon.

Basic Data Types

The following items give the DATATYPE, its description, and the default value set when defined in brackets.

INTEGER integer, whole number (0)
```
1
2
123
-123
```
REAL float-point number (0.0)
```
1.1
0.1
-12.1233
```
CHAR one single character ('')
```
'1'
'!'
'd'
```
STRING string ("")
```
"Hello"
"World"
"!"
```
BOOLEAN boolean (FALSE)
```
TRUE
FALSE
```
DATE date (current date)
```
25/07/2023
10/12/2012
```

None is a null datatype returned by some special functions. it should not be used in normal coding and cannot be declared.

Syntax Definitions

Variables and constants

Declare variables

DECLARE <identifier> : <data type>
DECLARE <identifier> : ARRAY [<lower>:<upper>, ...] OF <data type>

Declare constants
```
CONSTANT <identifier> = <value>
```

Assignment

<identifier> <- <value>
<identifier>[<index>, ...] <- <value>

Pseudocode uses <- instead of =.

I/O
- Input
```
INPUT <identifier>
```
- Output
```
OUTPUT <value>, ...
```
Operations
- + addition
- - subtraction
- * multiplication
- / division
- > greater than
- >= greater than or equal to
- < smaller than
- <= smaller than or equal to
- = equal (NOT AN ASSIGNMENT STATEMENT)
- <> not equal
- & conglomerate strings
- MOD modulus, find the remainder
- DIV integer division
Logic operations
- AND
- OR
- NOT

Conditional statements

IF statements

IF <condition> THEN
    <statements>
ENDIF

IF <condition> THEN
    <statements>
ELSE
    <statements>
ENDIF

CASE statements

IMPORTANT: official standards do not have semicolons ; here

CASE OF <identifier>
    <value> : <statements>;
    <value> : <statements>;
    ...
    OTHERWISE : <statements>;
ENDCASE

Loop statements

FOR loop

FOR <identifier> <- <value> TO <value>
    <statements>
NEXT <identifier>

REPEAT loop

REPEAT
    <statements>
UNTIL <condition>

WHILE loop

WHILE <condition>
    <statements>
ENDWHILE

functions
- functions without a return value (procedure)
```
PROCEDURE <identifier> ()
    <statements>
ENDPROCEDURE

PROCEDURE <identifier> (<param> : <data type>, ...)
    <statements>
ENDPROCEDURE
```
- call a procedure
```
CALL <identifier> ()

CALL <identifier> (<value>, ...)
```
- functions with return values
```
FUNCTION <identifier> RETURNS <data type>
    <statements>
    RETURN <value>
ENDFUNCTION

FUNCTION <identifier> (<param> : <data type>, ...) RETURNS <data type>
    <statements>
    RETURN <value>
ENDFUNCTION
```
- call a function with return values
```
<identifier> ()

<identifier> (<value>, ...)
```
- Before the parameters of those sub-routines, you can use BYREF or BYVAL to force the program to pass those parameters by reference or by-value respectively. If no BYREF nor BYVAL is given, the program will follow the prior parameter. If the program cannot find a clear indication it will, by default pass parameters by value.
  - If you explicitly define the data types of the array passed BYVAL the program will implicitly convert to the designated data type; the program will not convert data types when passed BYREF.
  - BYREF : pass the reference of a variable
  - BYVAL : pass a copy of the variable

File I/O

open a file
```
OPENFILE <file path> FOR <file mode>
```
read a file
```
READFILE <file path>, <variable>
```
write to a file
```
WRITEFILE <file path>, <data>
```
close a file
```
CLOSEFILE <file path>
```
locate in the file
```
SEEK <file path>, <address>
```
File Mode
1. READ
2. WRITE
3. APPEND
4. RANDOM

Self-defined data types
- enumerate type
```
TYPE <identifier> = (<identifier>, ...)
```
- pointer type
```
TYPE <identifier> = ^<data type>
```
- records(classes)
In this case, the program will not check the data types when assigning a variable of this type to another. The program will assign the other variable as the reference for this one. TYPE <identifier> <statements> ENDTYPE

Object Oriented Programme

define an object

CLASS <identifier>
    PUBLIC PROCEDURE NEW (<params>)
        <statements>
    ENDPROCEDURE
    <statements>
ENDCLASS

private or public variable

PRIVATE <identifier> : <type>
PUBLIC <identifier> : <type>

private or public procedure and function

PRIVATE PROCEDURE <identifier> (<params>)
    <statements>
ENDPROCEDURE

PUBLIC PROCEDURE <identifier> (<params>)
    <statements>
ENDPROCEDURE

PRIVATE FUNCTION <identifier> (<params>) RETURNS <type>
    <statements>
ENDFUNCTION

PUBLIC FUNCTION <identifier> (<params>) RETURNS <type>
    <statements>
ENDFUNCTION

create an object
```
NEW <identifier> (<values>)
```

If you do not sign a variable or procedure or function explicitly, it will be public by default.

Special Syntax of CPC Interpreter

delete a variable or constant on RAM
```
DELETE <identifier>
```
do nothing
```
PASS
```
import CPC files
```
IMPORT <expression>
```
expression here should be a string within double quotes. There is no isolation between the imported file and the main file. Identifiers may collide. It is suggested to use the Import function to import a package instead.
```
CONSTANT <identifier> = Import("<path to import file>")
```

Built-in Functions from CAIE Standard

LEFT(ThisString : STRING, x : INTEGER) RETURNS STRING
```
$ LEFT("ABCDEFGH", 3)
"ABC"
```
RIGHT(ThisString : STRING, x : INTEGER) RETURNS STRING
```
$ RIGHT("ABCDEFGH", 3)
"FGH"
```
LENGTH(ThisString : STRING) RETURNS INTEGER
```
$ LENGTH("Happy Days")
10
```
MID(ThisString : STRING, x : INTEGER, y : INTEGER) RETURNS STRING
```
$ MID("ABCDEFGH", 2, 3)
"BCD"
```
LCASE(ThisChar : CHAR) RETURNS CHAR

Decrapricated since 2023 $ LCASE('W') 'w'

UCASE(ThisChar : CHAR) RETURNS CHAR

Decrapricated since 2023 $ UCASE('h') 'H'

TO_UPPER(x : <datatype>) RETURNS <datatype>

may be CHAR or STRING

  $ TO_UPPER("hello")
  "HELLO"

  $ TO_UPPER('a')
  'A'

TO_LOWER(x : <datatype>) RETURNS <datatype>