Skip to main content

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-inCategoryReturn TypeDescription
keyboardIObs_tRead a line from stdin
printIO—Output values to stdout
saveIO—Write a bitstream to file
loadIObs_tRead a bitstream from file
lenStringuint32_tBitstream length in bits
absMathuint32_tAbsolute value
minMathuint32_tMinimum of two values
maxMathuint32_tMaximum of two values
powMathuint32_tBase raised to exponent
makeMemoryobjectAllocate an object
freeMemory—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-inReason
loadExpects a string path via .data field
lenOperates on bitstream .len property
printOutputs 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);

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:

EnglishLocalized 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​

  • keyboard on EOF: Returns an empty bitstream (data=NULL, len=0). Programs should check len before using the result.
  • save with empty data: Writes a zero-byte file.
  • load from non-existent file: Triggers a runtime error (the underlying fopen returns NULL).
  • len on uninitialized bs: Returns 0 (the .len field is zero-initialized).
  • abs of minimum int64: abs(-9223372036854775808) wraps around (the most negative int64 has no positive counterpart) — consistent with C behavior.
  • auto conversion on non-numeric strings: raml_bs_to_uint32("hello") returns 0 (atol returns 0 on non-numeric input).