RC - Retoor's C Interpreter

RC is a lightweight, recursive-descent C interpreter written in C. It executes a subset of C code directly without compilation, supporting essential language features including control flow, functions, pointers, and an extensive standard library.

Features

Language Support

Data Types

  • Integers (long)
  • Doubles (floating-point numbers)
  • Character pointers (char*)
  • Pointer operations (address-of &, dereference *)
  • Array declarations and indexing

Control Flow

  • if/else statements
  • while loops (including infinite loops)
  • break and continue statements
  • Comparison operators: ==, !=, <, >, <=, >=
  • Logical operators: &&, ||

Functions

  • User-defined functions with parameters
  • Return values
  • Recursive function calls
  • Native C function bindings

Operators

  • Arithmetic: +, -, *, /
  • Unary: -, &, *
  • String concatenation with +
  • Python-style slicing: str[start:end]

Standard Library

Math Functions

  • sqrt(x) - Square root
  • pow(base, exp) - Exponentiation
  • abs(x) - Absolute value
  • sin(x), cos(x), tan(x) - Trigonometric functions
  • floor(x), ceil(x) - Rounding functions

Double Type Functions

  • int_to_double(i) - Convert int to double
  • double_to_int(d) - Convert double to int
  • double_add(a, b), double_sub(a, b) - Double arithmetic
  • double_mul(a, b), double_div(a, b) - Double arithmetic
  • printf with %f format for doubles

String Functions

  • strpos(haystack, needle) - Find substring position
  • substr(str, start, length) - Extract substring
  • upper(str), lower(str) - Case conversion
  • strip(str) - Remove whitespace
  • replace(str, old, new) - Replace substring
  • startswith(str, prefix) - Prefix check
  • endswith(str, suffix) - Suffix check
  • strlen(str) - String length

File I/O

  • fopen(filename, mode) - Open a file
  • fclose(file) - Close a file
  • fread(file, buffer, size) - Read from file
  • fwrite(file, buffer, size) - Write to file
  • fgets(file, max_size) - Read a line
  • fputs(file, string) - Write a string
  • feof(file) - Check end of file
  • ftell(file), fseek(file, offset, whence) - File positioning
  • fremove(filename), frename(old, new) - File operations
  • SEEK_SET, SEEK_CUR, SEEK_END constants

Async I/O (Multi-threaded)

  • async_fread(file, buffer, size) - Async file read
  • async_fwrite(file, buffer, size) - Async file write
  • async_recv(socket, buffer, len, flags) - Async socket receive
  • async_send(socket, buffer, len, flags) - Async socket send
  • async_wait(handle) - Wait for async operation to complete
  • async_poll(handle) - Check if async operation is complete
  • async_result(handle) - Get result of completed async operation

Socket Programming

  • socket(), bind(), listen(), accept()
  • send(), recv(), close()
  • AF_INET, SOCK_STREAM constants

String Slicing

char *str = "Hello World";
char *slice = str[0:5];  // "Hello"

Building

make            # Build the interpreter
make clean      # Remove build artifacts
make help       # Show all available commands

The build process creates:

  • bin/rc - The interpreter executable
  • build/ - Object files (incremental compilation)

Usage

Execute RC programs with the .rc extension:

./bin/rc program.rc

Or use make targets:

make test                  # Run all tests
make run-feature-test      # Run specific test
make run-http-simple       # Run simple HTTP server example

Example Programs

Simple Program

int main() {
    int x = 10;
    int y = 20;
    printf("Sum: %d\n", x + y);
    return 0;
}

String Manipulation

int main() {
    char *text = "Hello World";
    char *upper_text = upper(text);
    char *slice = text[0:5];

    printf("Original: %s\n", text);
    printf("Uppercase: %s\n", upper_text);
    printf("Sliced: %s\n", slice);

    return 0;
}

HTTP Server Examples

Simple HTTP Server (examples/http_simple.rc) Single-connection HTTP server that accepts one request and exits.

Persistent HTTP Server (examples/http_persistent.rc) HTTP server with request counter that continuously accepts connections.

Multi-Connection HTTP Server (examples/http_multi.rc) HTTP server that handles up to 100 consecutive connections.

Project Structure

rc/
├── src/                    # Source code
│   ├── main.c             # Entry point
│   ├── tokenizer.c/h      # Lexical analysis
│   ├── parser.c/h         # Expression parsing
│   ├── interpreter.c/h    # Statement execution
│   ├── native_functions.c/h  # Native bindings
│   ├── string_utils.c/h   # String utilities
│   ├── globals.c          # Global variables
│   └── types.h            # Type definitions
├── tests/                 # Test programs (.rc)
├── examples/              # Example programs (.rc)
├── build/                 # Compiled objects
└── bin/                   # Executable (rc)

Architecture

Tokenizer

Converts source code into tokens, handling keywords, identifiers, literals, and operators. Supports line comments (//) and escape sequences in strings.

Parser

Recursive-descent parser with operator precedence:

  • factor() - Literals, variables, function calls
  • unary() - Unary operators (-, &, *)
  • term() - Multiplication, division
  • add() - Addition, subtraction, string concatenation
  • relational() - Comparison operators
  • expression() - Assignments and top-level expressions

Interpreter

Direct execution model without intermediate bytecode. Uses a virtual memory array for stack and variables, with separate string pool for dynamic strings.

Native Functions

Extensible system for binding C functions. Current bindings include math operations, string manipulation, and socket programming.

Limitations

  • Memory model uses long cells (not byte-accurate)
  • No support for structs, unions, or enums as user types
  • Limited type system (int, double, and char*)
  • Double arithmetic requires explicit helper functions
  • No preprocessor directives
  • Error messages show token index rather than line/column
  • Pointer arithmetic works on virtual memory addresses
  • Maximum 100 concurrent async operations

Testing

The project includes comprehensive test suites:

  • feature_test.rc - Core language features
  • endless_loop_test.rc - Loop constructs
  • math_test.rc - Mathematical operations
  • string_test.rc - String concatenation
  • string_manip_test.rc - Advanced string manipulation

Run all tests:

make test

Run individual tests:

make run-feature-test
make run-math-test
make run-string-manip

Implementation Details

Virtual Machine Model

  • Single memory array (10,000 long cells) for stack and variables
  • Stack pointer (sp) and base pointer (bp) manage activation records
  • Global register (ax) for return values and control flow
  • Separate string pool (100KB) for concatenated strings

Memory Management

  • Stack-based allocation for local variables
  • String pool for dynamic string operations
  • Automatic overflow detection

Function Calls

  • Stack-based activation records
  • Parameter passing via memory array
  • Return address tracking
  • Support for recursion

License

This project is provided as-is for educational and research purposes.