Built-in Functions

Complete reference for all built-in functions.

Output Functions

String Functions

String Repetition Operator (x)

The x operator repeats a string a given number of times. It has the same precedence as *, /, and %.

my str $dashes = "-" x 40;
say($dashes);  # "----------------------------------------"

my str $ab = "ab" x 3;
say($ab);  # "ababab"

# Useful for formatting
say("=" x 60);
say("  Report Title");
say("=" x 60);

Transliteration (tr///, y///)

The tr/// operator (alias y///) performs character-by-character transliteration. Unlike s///, it does not use regex — it maps individual characters from one set to another.

Flags

my str $text = "Hello World";

# ROT13
$text =~ tr/A-Za-z/N-ZA-Mn-za-m/;
say($text);  # "Uryyb Jbeyq"

# Lowercase to uppercase
my str $upper = "hello";
$upper =~ tr/a-z/A-Z/;
say($upper);  # "HELLO"

# Delete digits
my str $nodigits = "abc123def456";
$nodigits =~ tr/0-9//d;
say($nodigits);  # "abcdef"

# Squeeze repeated spaces
my str $spaced = "hello    world";
$spaced =~ tr/ / /s;
say($spaced);  # "hello world"

# Return modified copy (original unchanged)
my str $original = "hello";
my str $copy = ($original =~ tr/a-z/A-Z/r);
say($original);  # "hello" (unchanged)
say($copy);      # "HELLO"

Examples

my str $s = "  Hello World  ";
say(strlen($s));           # 15
say(trim($s));             # "Hello World"
say(substr($s, 2, 5));    # "Hello"
say(uc($s));               # "  HELLO WORLD  "
say(index($s, "World"));  # 8

my array @parts = split(" ", trim($s));
say(join("-", @parts));   # "Hello-World"

Array Functions

splice() in Detail

The splice() function removes elements from an array and optionally replaces them. It returns an array of the removed elements.

my array @data = (10, 20, 30, 40, 50);

# Remove 2 elements starting at index 1
my array @removed = splice(@data, 1, 2);
# @removed = (20, 30), @data = (10, 40, 50)

# Replace 1 element at index 1 with two new elements
my array @arr = ("a", "b", "c", "d");
my array @repl = ("X", "Y");
splice(@arr, 1, 1, @repl);
# @arr = ("a", "X", "Y", "c", "d")

# Insert without removing (len = 0)
my array @list = (1, 2, 5);
my array @insert = (3, 4);
splice(@list, 2, 0, @insert);
# @list = (1, 2, 3, 4, 5)

Array Memory Management

my array @data[1000];  # Pre-allocate for 1000 elements
for (my int $i = 0; $i < 1000; $i++) {
    push(@data, $i);  # No reallocation needed
}

Array Transformations (map, grep, sort)

Strada supports Perl-style block expressions for powerful array transformations. The special variable $_ contains the current element.

Map Examples

my array @nums = (1, 2, 3, 4, 5);

# Transform each element (double)
my array @doubled = map { $_ * 2 } @nums;
# Result: (2, 4, 6, 8, 10)

# Transform to strings
my array @strings = map { "Value: " . $_ } @nums;

Map with Fat Arrow (Creating Hashes)

The classic Perl idiom for building lookup hashes works in Strada:

my array @fruits = ("apple", "banana", "cherry");

# Create a lookup hash - the Perl way!
my hash %lookup = map { $_ => 1 } @fruits;
# %lookup is now {"apple" => 1, "banana" => 1, "cherry" => 1}

# Fast membership testing
if (exists($lookup{"apple"})) {
    say("Found apple!");
}

The fat arrow $_ => value creates a key-value pair. When assigned to a hash variable, these pairs become hash entries.

Grep Examples

my array @nums = (1, 2, 3, 4, 5, 6);

# Keep only even numbers
my array @evens = grep { $_ % 2 == 0 } @nums;
# Result: (2, 4, 6)

# Keep values greater than 3
my array @big = grep { $_ > 3 } @nums;
# Result: (4, 5, 6)

Sort Examples

my array @nums = (5, 2, 8, 1, 9);

# Sort ascending (numeric) - use spaceship operator
my array @asc = sort { $a <=> $b } @nums;
# Result: (1, 2, 5, 8, 9)

# Sort descending
my array @desc = sort { $b <=> $a } @nums;
# Result: (9, 8, 5, 2, 1)

# Default sort (alphabetical)
my array @alpha = sort @names;

Chaining Operations

my array @data = (5, 2, 8, 1, 9, 3, 7);

# Filter, transform, and sort in one pipeline
my array @result = sort { $a <=> $b } map { $_ * 10 } grep { $_ > 3 } @data;
# Result: (50, 70, 80, 90)

Hash Functions

each() Iterator

The each() function returns the next key-value pair from a hash as a two-element array [key, value]. When all pairs have been returned, it returns an empty array. The iterator resets when all entries have been traversed.

my hash %config = ();
$config{"host"} = "localhost";
$config{"port"} = 8080;
$config{"debug"} = 1;

# Iterate with each()
my array @pair = each(%config);
while (scalar(@pair) > 0) {
    say($pair[0] . " = " . $pair[1]);
    @pair = each(%config);
}
# Output (order may vary):
#   host = localhost
#   port = 8080
#   debug = 1

my hash %cache[500];  # Pre-allocate for ~500 entries

# Or set default for all new hashes:
core::hash_default_capacity(1000);

Type Functions

File I/O Functions

select() — Default Filehandle

The select() function sets the default output filehandle. After calling select($fh), all print() and say() calls without an explicit filehandle will write to $fh instead of stdout.

my scalar $fh = core::open("output.log", "w");

# Redirect print/say to the file
select($fh);
say("This goes to output.log");
print("So does this");

# Restore stdout (pass undef or no argument)
select(undef);
say("Back to stdout");

core::close($fh);

Diamond Operator <$fh>

The diamond operator reads lines from a filehandle or socket. Context determines behavior:

Filehandle I/O

Say and print work with filehandles as the first argument:

In-Memory I/O

Read from and write to strings using standard file handle operations. All I/O functions work transparently with in-memory handles.

# Read from a string
my scalar $fh = core::open_str("line1\nline2\n", "r");
my str $line = <$fh>;  # "line1"

# Write to a string buffer
my scalar $wfh = core::open_str("", "w");
say($wfh, "hello");
my str $result = core::str_from_fh($wfh);  # "hello\n"

# Reference-style (variable updated on close)
my str $output = "";
my scalar $wfh2 = core::open(\$output, "w");
say($wfh2, "data");
core::close($wfh2);  # $output = "data\n"

Math Functions (math::)

System Functions (core::)

Process Control

Environment

File System

Time

Debugging

Call Context (Dynamic Return Type)

Networking

SSL/TLS (ssl::)

Secure socket connections via OpenSSL. Build with: cd lib/ssl && make

SSL Example

my int $conn = ssl::connect("example.com", 443);
ssl::write($conn, "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
my str $response = ssl::read($conn, 4096);
ssl::close($conn);

# Or use the convenience function:
my str $page = ssl::http_get("example.com", 443, "/");

UTF-8 Introspection (utf8::)

Perl-compatible UTF-8 introspection functions. In Strada, all strings are stored as raw bytes (typically UTF-8). There is no separate "UTF-8 flag" like Perl.

UTF-8 Example

my str $text = "Hello";
say(utf8::is_utf8($text));    # 1 (ASCII is valid UTF-8)
say(utf8::downgrade($text)); # "Hello" (ASCII-only, succeeds)

# Safe downgrade with fail_ok
my scalar $result = utf8::downgrade($text, 1);
if (!defined($result)) {
    say("Contains non-ASCII");
}

Signals

Dynamic Loading (FFI)

FFI Example

# Load a Strada shared library
my int $lib = core::dl_open("./mylib.so");
my int $fn = core::dl_sym($lib, "my_function");
my scalar $result = core::dl_call_sv($fn, [$arg1, $arg2]);

Library Imports

For cleaner library imports, use import_lib, import_object, or import_archive:

use lib "lib";
import_lib "JSON.so";         # Runtime loading (dlopen)
import_object "Utils.o";      # Static linking
import_archive "DataLib.a";  # Static linking with bundled runtime

# Functions are now available with namespace syntax:
my str $json = JSON::encode(\%data);
my hash %data = JSON::decode($json);

Library Compilation

Compile Strada programs as libraries:

./strada --shared mylib.strada      # Creates mylib.so
./strada --object mylib.strada      # Creates mylib.o
./strada --static-lib mylib.strada  # Creates mylib.a (includes runtime)

C Interop (__C__ Blocks)

Embed raw C code directly in Strada programs using __C__ blocks:

Top-Level Blocks

For includes, globals, and C helper functions:

__C__ {
    #include <math.h>
    #include <openssl/ssl.h>

    static SSL_CTX *g_ctx = NULL;

    static int helper(int a, int b) {
        return a + b;
    }
}

Statement-Level Blocks

Inline C code inside functions with access to Strada variables:

func my_sqrt(num $x) num {
    __C__ {
        double val = strada_to_num(x);
        return strada_new_num(sqrt(val));
    }
}

Key C Functions

Opaque Handle Pattern

Store C pointers in Strada int variables (64-bit):

func open_connection(str $host) int {
    __C__ {
        char *h = strada_to_str(host);
        SSL *conn = connect_ssl(h);
        free(h);
        // Store pointer as int
        return strada_new_int((int64_t)(intptr_t)conn);
    }
}

func close_connection(int $handle) void {
    __C__ {
        // Retrieve pointer from int
        SSL *conn = (SSL*)(intptr_t)strada_to_int(handle);
        SSL_free(conn);
        return &strada_undef;
    }
}

JSON Functions

Package Syntax

Example

package Calculator;

func add(int $a, int $b) int { return $a + $b; }

func compute(int $x, int $y) int {
    return ::add($x, $y);  # Calls Calculator_add
}

Moose-Style OOP Keywords

Strada provides a declarative OOP system inspired by Perl's Moose. See the OOP page for full details and examples.

my scalar $obj = MyClass::new("name", "value", "age", 30);

core:: Namespace Alias

The core:: namespace is the preferred way to call system functions. It is an alias for the older sys:: namespace. The compiler normalizes core:: to sys:: at compile time, so there is zero overhead. Both namespaces work interchangeably.

Use whichever namespace feels more natural. core:: is recommended for new code as it reads more clearly as "core language functionality."

# These are equivalent:
my int $pid = core::fork();
my int $pid = sys::fork();

my str $home = core::getenv("HOME");
my str $home = sys::getenv("HOME");

my int $now = core::time();
my int $now = sys::time();

Miscellaneous

local() — Dynamic Scoping

The local() function provides dynamic scoping for our (package-global) variables. It saves the current value and automatically restores it when the enclosing scope exits. This is useful for temporarily overriding globals without affecting the rest of the program.

our int $verbose = 0;

func debug_section() void {
    local($verbose) = 1;  # Temporarily set to 1
    do_work();               # $verbose is 1 here
    # $verbose automatically restored to 0 on scope exit
}

func do_work() void {
    if ($verbose) {
        say("Doing work...");  # Prints when called from debug_section
    }
}

func main() int {
    do_work();        # $verbose is 0, nothing printed
    debug_section(); # $verbose is temporarily 1 inside
    do_work();        # $verbose is 0 again
    return 0;
}

tie/untie/tied — Tied Hashes

The tie mechanism binds a hash variable to a class, allowing custom behavior for hash operations. When a hash is tied, all accesses (read, write, delete, exists, iteration) are dispatched to methods in the tied class.

TIEHASH Methods

The tied class must implement these methods:

Example: Case-Insensitive Hash

package CIHash;

func TIEHASH() scalar {
    my hash %self = ();
    $self{"data"} = {};
    return bless(\%self, "CIHash");
}

func FETCH(scalar $self, str $key) scalar {
    return $self->{"data"}->{lc($key)};
}

func STORE(scalar $self, str $key, scalar $val) void {
    $self->{"data"}->{lc($key)} = $val;
}

package main;

func main() int {
    my hash %h = ();
    tie(%h, "CIHash");

    $h{"Name"} = "Alice";   # Calls CIHash::STORE
    say($h{"name"});         # Calls CIHash::FETCH -> "Alice"
    say($h{"NAME"});         # "Alice" (case insensitive)

    untie(%h);              # Unbind from class
    return 0;
}

Compiler Flags

The Strada compiler (stradac) and wrapper (strada) support these flags:

Examples

# Compile and run
./strada -r program.strada

# Compile with debugging
./strada -g program.strada

# Compile with profiling
./strada -p program.strada
./program  # Prints profiling report on exit

# Check for warnings
./strada -w program.strada

# Create shared library
./strada --shared mylib.strada  # Creates mylib.so