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::)

Strada strings carry an internal UTF-8 flag mirroring Perl's SVf_UTF8. When the flag is set, the character built-ins (length, substr, index, rindex, reverse, split, sprintf widths, regex) count Unicode codepoints; when clear, the string is raw bytes. Pure-ASCII strings are character-oriented implicitly. chr(N) for N in 0–127 emits one ASCII byte; for N ≥ 128 it UTF-8-encodes the codepoint and sets the flag (matching use utf8). The byte-level core::byte_* family is available when you need raw byte access for binary protocols.

The flag is set by chr(N>127), the utf8::nfc/nfd/nfkc/nfkd normalizers, and non-ASCII literals in a use utf8 source, and propagates contagiously through concatenation, join, sprintf, and s///. The utf8::* functions below are validation/no-op helpers — they report on the flag rather than transcoding bytes.

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

The plain use statement auto-detects a precompiled sibling artifact (.o preferred over .so) next to the .strada source, with an mtime freshness check. Falls back to source inlining when the artifact is stale or missing.

use lib "lib";
use JSON;                       # picks up lib/JSON.o (or .so) if present

# Explicit forms — useful when no .strada is alongside the artifact:
import_lib "JSON.so";          # Runtime loading (dlopen)
import_object "Utils.o";       # Static linking
import_archive "DataLib.a";   # Static linking with bundled runtime

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

Library Compilation

Compile Strada modules as reusable artifacts:

./strada -M lib/JSON.strada         # module-only JSON.o (recommended)
./strada -M lib/                    # recursive: every .strada → sibling .o
./strada --object-full mylib.strada -o mylib.o  # bundle deps (legacy)
./strada --shared mylib.strada -o mylib.so      # shared object (.so)
./strada --static-lib mylib.strada -o mylib.a   # static archive (includes runtime)

Declaring extern-C Link Deps (link_lib)

A module that wraps a C library advertises its -l deps so consumers don't have to:

package DBI;
link_lib "sqlite3";
link_lib "mysqlclient";
# ... when something does `use DBI;`, the strada driver adds -lsqlite3 -lmysqlclient automatically.

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 function profiling
./strada -p program.strada
./program  # Prints profiling report on exit

# Compile with line-level profiling
./strada --full-profile program.strada
./program                                    # Writes strada-prof.out
strada-proftext strada-prof.out              # Text report
strada-profhtml strada-prof.out profhtml/    # HTML report

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

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