🪷 Lotus

Lotus Documentation

Complete reference documentation for the Lotus programming language. These guides cover language features, standard library, coding style, and compiler details.

📚 Essential Guides

🔤 Language Reference

Type System

// Integer types
int, int8, int16, int32, int64
uint, uint8, uint16, uint32, uint64

// Floating point
float

// Boolean
bool

// String
string

// Pointer
int* ptr   // Postfix asterisk

Variable Declaration

// Type-first declarations
int count = 42;
string message = "Hello";
bool flag = true;

// Pointers
int* buffer = malloc(sizeof(int) * 10);

// Constants (compile-time)
const int MAX_SIZE = 1000;
const string VERSION = "1.0.0";

Functions

// Function definition with return type
fn int add(int a, int b) {
    ret a + b;
}

// Function call
int result = add(5, 3);

Control Flow

// if/else
if condition {
    // body
} else {
    // body
}

// while loop
while condition {
    // body
}

// for loop
for int i = 0; i < 10; i = i + 1 {
    // body
}

📦 Standard Library Modules

io - Input/Output

use "io";

println("Hello, World!");
printf("Number: %d\n", 42);
printf("String: %s\n", "Lotus");

Functions: print, println, printf, fprintf, sprint, sprintf, sprintln

Printf verbs: %d (int), %s (string), %x (hex), %b (binary), %o (octal), %c (char), %q (quoted string), %v (generic)

mem - Memory Management

use "mem";

int* buffer = malloc(sizeof(int) * 10);
free(buffer);

Functions: malloc(size), free(ptr), sizeof(type)

math - Mathematical Operations

use "math";

int abs_val = abs(-42);
int max_val = max(10, 20);
int min_val = min(10, 20);
int r = sqrt(81);
int p = pow(2, 10);

Implemented: abs, min, max, sqrt, pow, floor, ceil, round, gcd, lcm

str - String Operations

use "str";

int length = len("Lotus");
string both = concat("Lo", "tus");
int cmp = compare("a", "b");
string copy_of_name = copy("Lotus");

Implemented: len, concat, compare, copy, indexOf, contains, startsWith, endsWith

num - Numeric Conversions

use "num";

int64 big = toInt64(42);
uint8 small = toUint8(255);
bool ok = toBool(1);

Functions: toInt8, toUint8, toInt16, toUint16, toInt32, toUint32, toInt64, toUint64, toBool

hash - Hashing

use "hash";

int djb = djb2("Hello");
int fnv = fnv1a("Hello", 5);
int crc = crc32("Hello", 5);
int mur = murmur("Hello", 5, 42);

Functions: djb2(string), fnv1a(ptr,len), crc32(ptr,len), murmur(ptr,len,seed), sha256(ptr,len,out), md5(ptr,len,out)

collections - Data Structures

use "collections";

int* arr = array_int_new(16);
array_int_push(arr, 10);
int n = array_int_len(arr);
int idx = binary_search_int(arr, n, 10);

Includes: dynamic arrays, stacks, queues, deques, heaps, hash maps, hash sets; helpers like binary_search_int

net - Networking (low-level)

use "net";

int fd = socket(2, 1, 0); // AF_INET, SOCK_STREAM
int ok = connect_ipv4(fd, 0x7F000001, 8080); // 127.0.0.1:8080
send(fd, "hi", 2);
close(fd);

Functions: socket, connect_ipv4, send, recv, close

http - HTTP Client

use "http";

// Simplified GET
int status = get("example.com", 80, "/", null, null, null, null);

Functions: get(host, port, path, headers..., out_buf)

🎯 Compiler Usage

Command-line Flags

lotus [flags] <file>

Flags:
  -S              Generate assembly/IR only
  -o FILE         Output file name (default: a.out)
  -run            Compile and run immediately
  -v              Verbose output
  -version        Show compiler version
  -h, -help       Show help message

LLVM Backend (default):
  --emit-llvm     Output LLVM IR instead of binary
  -O0, -O1, -O2, -O3   Optimization levels
  --target=ARCH   Target architecture (x86, arm, riscv, wasm)

Legacy GCC Backend:
  --gcc           Use GCC assembly backend instead of LLVM

Examples

# Compile to binary (uses LLVM by default)
lotus program.lts

# Compile with optimization
lotus -O2 program.lts

# Generate LLVM IR
lotus --emit-llvm program.lts -o program.ll

# Cross-compile for ARM
lotus --target=arm program.lts

# Use legacy GCC backend
lotus --gcc program.lts

# Compile and run
lotus -run program.lts

# Verbose compilation
lotus -v program.lts

🔧 Advanced Topics

Assembly Output

Generate and inspect x86-64 assembly:

lotus -S -o program.s program.lts
cat program.s

Extending the Standard Library

See STDLIB_IMPLEMENTATION.md for details on adding new modules and functions.

Architecture

Lotus uses a multi-phase compiler with LLVM backend:

Source Code
    ↓
Tokenizer (Lexical Analysis)
    ↓
Parser (Syntax Analysis)
    ↓
LLVM Code Generator (IR Generation)
    ↓
LLVM Optimizer (O0-O3)
    ↓
LLVM Backend (x86/ARM/RISC-V/WASM)
    ↓
Binary Executable

Legacy GCC backend (--gcc flag) uses:

Source Code → Tokenizer → Parser → x86-64 Assembly → GCC → Binary

📖 Quick Links

• GitHub Repository
• Full Documentation Files
• Code Examples
• Getting Started Guide