PrismCC Reference

Feature overview for the in-OS subset C compiler and BCVM runtime

Overview

PrismCC compiles a C-like subset into BCVM bytecode packaged in the Prism app format.

Supported Types

Arrays are currently int-only. Local variable limit per function: 64.

Functions and Calls

Preprocessor and Includes

Statements and Control Flow

Expressions and Operators

API Reference

These are the built-ins exposed by PrismCC. Each one below includes what it does and how to call it.

print(expr)

Prints a value and appends a newline. The argument can be int or string.

Use this when you want one call that handles either numeric or text output without choosing a separate function.

print("hello"); print(42);

print_int(expr)

Prints an integer value and appends a newline.

Use this when the value is definitely numeric and you want the output path to be explicit.

int count = 3; print_int(count);

print_color(colorExpr, stringExpr)

Prints a string using a console color selected by the first argument.

Use this for highlighted status output or simple visual emphasis in terminal-style apps.

print_color(2, "success");

read_text()

Reads a text line from input and returns it as a string value.

Use this when you want to prompt through the shell or UI before collecting free-form text.

string name = read_text();

read_text(promptStringExpr)

Shows a prompt string, then reads a line of text and returns it.

Use this when the user should see the question or context before entering input.

string city = read_text("Enter city: ");

input_int()

Reads the current input buffer as an integer value.

Use this when the app expects a numeric response instead of raw text.

int age = input_int();

print_input()

Prints the current input buffer back to the console.

Use this for echoing the user’s last input or debugging interactive flows.

print_input();

input_len()

Returns the length of the current input buffer as an integer.

Use this when you need to check whether the input is empty or to size follow-up logic.

int len = input_len();

input_eq("literal")

Compares the current input buffer against a literal string and returns 1 or 0.

Use this for menu choices, yes/no prompts, and simple command matching.

if (input_eq("yes")) { print("confirmed"); }

string_len(stringExpr)

Returns the length of a string as an integer.

Use this for bounds checks, validation, or any logic that depends on string size.

int size = string_len(name);

string_eq(stringExprA, stringExprB)

Compares two strings and returns 1 when they match, otherwise 0.

Use this when you need exact string matching without manual character-by-character code.

if (string_eq(mode, "debug")) { print("debug mode"); }

file_read(pathStringExpr)

Reads a file and returns its contents as a string.

Use this when you want to load text data from the filesystem into a string value.

string data = file_read("/DATA.TXT");

file_write(pathStringExpr, textStringExpr)

Writes text to a file. In statement form, the status result is discarded.

Use this when you want to replace the file contents with a new string.

file_write("/OUT.TXT", "fresh contents");

file_append(pathStringExpr, textStringExpr)

Appends text to the end of a file. In statement form, the status result is discarded.

Use this for logs, traces, or any output that should accumulate over time.

file_append("/LOG.TXT", "next line");

file_exists(pathStringExpr)

Checks whether a file exists and returns 1 or 0.

Use this before reading or writing when the app needs to branch on file presence.

if (file_exists("/CONFIG.TXT")) { print("config found"); }

set_fullscreen(int enabled)

Enables or disables fullscreen app mode. In fullscreen mode, the VM listens for Esc as a global quit shortcut.

Use this at app start to hide the text cursor and switch to framebuffer-style drawing updates.

set_fullscreen(1); // ... draw loop ... set_fullscreen(0);

draw_pixel(int x, int y, int color)

Draws one pixel at framebuffer coordinates (x, y) using palette color 0..15.

Use this for custom software rendering, pixel art, and basic visual effects.

draw_pixel(100, 80, 12);

app_should_quit()

Returns 1 when a queued quit shortcut event is available, otherwise 0.

Use this inside animation loops to exit cleanly without forcing the global shortcut behavior.

while (app_should_quit() == 0) { // render frame }

app_exit()

Exits the running app immediately and returns control to the shell.

Use this for explicit termination paths such as menu commands or fatal runtime conditions.

if (done == 1) { app_exit(); }

Path strings are passed directly to VFS operations in the VM.

Arrays

Array storage is VM heap backed, and out-of-range access fails VM execution.

Compiler and Runtime Limits

Compiler-side

  • Source size: 32 KiB
  • Code size: 48 KiB
  • Data size: 16 KiB
  • Max locals: 512
  • Max functions: 64
  • Max call patch sites: 256

VM-side

  • Stack entries: 256
  • Call depth: 32
  • Max VM steps per run: 200000
  • Input buffer: 127 chars
  • Heap string slots: 64
  • Heap array slots: 64

Shell Workflow

  1. Write a source file.
  2. Optionally split reusable code into headers and include them.
  3. Compile in PrismOS shell with cc /path/program.c /path/program.app.
  4. Run it with app-run /path/program.app.

cc <input.c> <output.app>

Compiles a PrismCC source file into a Prism app package.

Use this inside the PrismOS shell to turn source code into a runnable BCVM application.

cc /HELLO.C /HELLO.APP

app-run <output.app>

Launches a compiled Prism app on the VM.

Use this after compilation to execute the generated app package.

app-run /HELLO.APP

Small Standard Library (Headers)

Header-only helper library available under /examples/std.

Includes string helpers, math helpers, and IO wrappers that work with the new #include support.

#include "std/prism_string.h" #include "std/prism_math.h" #include "std/prism_io.h"

Structs

Struct values are represented with VM-backed field storage.

Current Known Gaps