Built-ins and IO
Raml provides a small set of built-in keywords and functions for IO, string operations, and math.
Overview
This section covers the built-ins at a glance — enough to use them in programs.
Quick Reference
| Built-in | Category | Return Type | Description |
|---|---|---|---|
keyboard | IO | bs_t | Read a line from stdin |
print | IO | — | Output values to stdout |
save | IO | — | Write a bitstream to file |
load | IO | bs_t | Read a bitstream from file |
len | String | uint32_t | Bitstream length in bits |
abs | Math | uint32_t | Absolute value |
min | Math | uint32_t | Minimum of two values |
max | Math | uint32_t | Maximum of two values |
pow | Math | uint32_t | Base raised to exponent |
make | Memory | object | Allocate an object |
free | Memory | — | Deallocate heap memory |
Common Patterns
:start:
// Read input
name = keyboard
// Print output
print "hello" name
// File IO
data = "hello world"
save "output.bin" data
loaded = load "output.bin"
// Bitstream length
l = len loaded
// Math
m = max 3 7
p = pow 2 8
Reference
IO Keywords
keyboard
Reads a line from standard input and returns it as a bs_t (bitstream):
:start:
input = keyboard
print "you typed" input
The returned value is a bitstream containing the input string data.
print
Outputs values to standard output. Items are space-separated and a newline is appended:
print "hello" 42 "world"
// Output: hello 42 world
Print can also output object contents by calling the object's implicit print method:
counter:
value
functions:
prints:
print "counter" value
:start:
c = make counter 5
print c // calls counter_prints(&c)
save
Writes a bitstream to a file:
data = "hello world"
save "output.bin" data
The path string is extracted from the bitstream's .data field.
load
Reads a bitstream from a file and returns it:
data = load "input.bin"
print "loaded" data
Returns a bs_t. The path is extracted from the bitstream's .data field.
Built-in Functions
len expr
Returns the length of a bitstream in bits:
bs s = "hello"
l = len s // l = 40 (5 bytes * 8 bits)
abs x
Returns the absolute value:
a = abs (0 - 42) // a = 42
min a b
Returns the smaller of two values:
m = min 3 7 // m = 3
max a b
Returns the larger of two values:
m = max 3 7 // m = 7
pow base exp
Returns base raised to the power of exp:
p = pow 2 8 // p = 256
Automatic Type Conversion
When bs (bitstream) variables are passed as arguments to methods or functions expecting numeric types, they are automatically converted to uint32_t:
:start:
move = keyboard // move is bs_t
b:set move player // move converted to uint32_t
This conversion is performed via raml_bs_to_uint32() in the generated C code.
Excluded built-ins (expect bs_t arguments directly):
| Built-in | Reason |
|---|---|
load | Expects a string path via .data field |
len | Operates on bitstream .len property |
print | Outputs bitstream content directly |
Deep Dive
This section covers the runtime implementation, type conversion internals, and edge cases.
Runtime Implementation
The built-ins map to C runtime functions. Here are the key signatures:
// Bitstream type
typedef struct {
uint8_t* data; // pointer to raw bytes
size_t len; // length in bytes
} bs_t;
// IO
bs_t raml_keyboard(void);
void raml_print(bs_t val); // print single value
void raml_print_bs(bs_t s); // print bitstream
void raml_print_int(uint64_t n); // print integer
void raml_save(bs_t path, bs_t data);
bs_t raml_load(bs_t path);
// Bitstream operations
bs_t raml_make_bs(const char* s); // create from C string
bs_t raml_bs_concat(bs_t a, bs_t b); // concatenate
uint32_t raml_bs_to_uint32(bs_t bs); // convert to integer
size_t raml_bs_length(bs_t bs); // get length
// Math
uint64_t raml_abs(int64_t x);
uint64_t raml_min(uint64_t a, uint64_t b);
uint64_t raml_max(uint64_t a, uint64_t b);
uint64_t raml_pow(uint64_t base, uint64_t exp);
// Memory
void* raml_alloc(size_t size);
void raml_free(void* ptr);
Print Statement Codegen
The print statement is translated to a sequence of typed print calls. Each argument generates a call appropriate to its type:
print "loop" i 3.14
Generates:
raml_print_bs(_string_0); // "loop" as bs_t
raml_print_int(i); // integer variable
raml_print_int(3); // integer literal (decimal truncated)
Print over objects: When print obj is used on an object, the codegen calls the object's prints method (which must exist). The signature is void obj_prints(struct obj_t* self).
Bitstream Auto-Conversion Internals
When a bs_t is passed to a function expecting a numeric type, the codegen wraps it with raml_bs_to_uint32():
// Raml: b:set move player
// C codegen:
board_set(&b, raml_bs_to_uint32(move), player);
The raml_bs_to_uint32 function parses the bitstream data as a decimal string:
uint32_t raml_bs_to_uint32(bs_t bs) {
if (!bs.data || bs.len == 0) return 0;
// Copy to null-terminated string and parse
char* buf = malloc(bs.len + 1);
memcpy(buf, bs.data, bs.len);
buf[bs.len] = '\0';
uint32_t result = (uint32_t)atol(buf);
free(buf);
return result;
}
Keyword Localization Integration
Built-in keywords are localized via keywords.raml.lang files. The following built-in names are localizable:
| English | Localized Example (Arabic) |
|---|---|
print | اطبع |
keyboard | لوحة_المفاتيح |
save | احفظ |
load | حمل |
len | طول |
make | اصنع |
free | احذف |
The localization is a lexer-level substitution — the parser never sees the localized names.
Edge Cases
keyboardon EOF: Returns an empty bitstream (data=NULL, len=0). Programs should checklenbefore using the result.savewith empty data: Writes a zero-byte file.loadfrom non-existent file: Triggers a runtime error (the underlyingfopenreturns NULL).lenon uninitializedbs: Returns 0 (the.lenfield is zero-initialized).absof minimum int64:abs(-9223372036854775808)wraps around (the most negative int64 has no positive counterpart) — consistent with C behavior.autoconversion on non-numeric strings:raml_bs_to_uint32("hello")returns 0 (atol returns 0 on non-numeric input).