pperl

pperl is a next-generation Perl 5 platform written in Rust, targeting Perl 5.42+ compatibility.

Goals

• Auto-Parallelization - Automatic parallel map, grep, for, while loops via Rayon work-stealing
• JIT Compilation - Native code generation via Cranelift for hot loops (up to 76x faster than perl5)
• Pure Perl Viability - Fast enough that XS becomes optional

Architecture Overview

flowchart LR
    subgraph Input
        A[Perl Source]
    end

    subgraph Parser
        B[Lexer] --> C[Parser]
        C --> D[AST]
    end

    subgraph Compiler
        D --> E[Codegen]
        E --> F[OpArena]
    end

    subgraph Runtime
        F --> G[Interpreter]
        G --> H[PP Dispatch]
    end

    subgraph Output
        H --> I[Result]
    end

    A --> B

Quick Start

# Run a script
pperl script.pl

# Run one-liner
pperl -e 'print "Hello, World!\n"'

# Check syntax only
pperl -c script.pl

Compatibility

pperl aims for high compatibility with Perl 5.42+. See Differences from Perl 5 for known incompatibilities.

Platform Support

• Linux only (any architecture)
• No Windows, macOS, or other platforms

Getting Started

Installation

Binaries will be available from a GitHub release page (TBD). That is also where to report issues via the tracker.

First Script

#!/usr/bin/env pperl
print "Hello from PetaPerl!\n";

Command Line Options

See Running Scripts for the full option list.

Notes

• Modern features (say, state, //, signatures) are always enabled — no use feature needed
• XS modules are not supported; native Rust reimplementations are provided for common modules
• -I is not supported; use PERL5LIB environment variable to add include paths

Running Scripts

PetaPerl’s pperl command executes Perl scripts with a familiar interface. Most perl5 options work identically.

Basic Execution

# Run a script
pperl script.pl

# Run with arguments
pperl script.pl arg1 arg2

# Execute one-liner
pperl -e 'say "Hello, World!"'

# Check syntax without running
pperl -c script.pl

Command-Line Options

Perl-Compatible Options

Combined short flags:

pperl -wc script.pl  # Enable warnings + syntax check

PetaPerl-Specific Options

Choosing a Runtime

PetaPerl has two runtime engines. The default PP runtime uses safe, idiomatic Rust and supports JIT compilation and auto-parallelization. The P5 runtime (--p5) is a line-for-line Rust transliteration of perl5’s C interpreter — it matches perl5 performance out of the box but does not support JIT or parallelization.

Use --p5 when you need maximum compatibility with perl5’s edge-case behaviour or baseline performance without JIT. Use the default PP runtime (with JIT enabled) for compute-heavy workloads where parallelization and JIT provide significant speedups.

See Dual Runtime Architecture for technical details.

Performance Options

Caching and Analysis Options

Unsupported perl5 Options

These perl5 flags are not implemented:

Examples

One-Liners

Modern features (say, state, etc.) are always enabled.

# Print hello
pperl -e 'say "Hello!"'

# Process input
echo "hello" | pperl -e 'while (<>) { say uc($_) }'

# Math
pperl -e 'say 2 + 2'

# Generate data
pperl -e 'say join ",", 1..10'

Syntax Checking

# Check single file
pperl -c script.pl
# Output: script.pl syntax OK

# Check with warnings enabled
pperl -wc script.pl

Script Arguments

Arguments after the script name populate @ARGV.

pperl process.pl file1.txt file2.txt

# process.pl
for my $file (@ARGV) {
    say "Processing: $file";
}

Performance Statistics

pperl --stats script.pl

Output:

--- Performance Statistics ---
Wall-clock time: 0.042 seconds
Peak memory (RSS): 12.34 MB (12640 KB)
Ops executed: 1523 (36261 ops/sec)
------------------------------

Execution Tracing

See every op executed (debugging aid).

pperl --trace script.pl

Output shows:

[TRACE] NextState
[TRACE] Const("Hello")
[TRACE] Print

Parser Comparison

Compare native Rust parser output against a perl5-generated JSON op tree (analysis tool).

pperl --compare-bytecode script.pl

Shows differences in generated op trees. Useful for parser validation.

Op Tree Inspection

Dump canonical op tree representation without executing.

pperl --dump-optree script.pl

Shows internal op tree structure:

NextState(file="script.pl", line=1)
  → Const(sv="Hello")
    → Print
      → LeaveSub

Execution Model

Parser Pipeline

Source → Lexer → Parser → AST → Codegen → OpArena → Interpreter

Fast, pure Rust. No perl5 dependency at runtime.

JSON Op Tree Loading (Analysis Only)

Source → perl + B::PetaPerl → JSON → OpArena → Interpreter

For analysis and parser validation, pperl can load a perl5-generated op tree via --from-json or compare it against the native parser via --compare-bytecode. This is not used during normal execution.

Timeouts

By default, pperl has no execution timeout. Use --timeout=SECS to set one:

# No timeout (default)
pperl script.pl

# Set timeout (useful for untrusted code or testing)
pperl --timeout=60 script.pl
pperl --timeout=5 script.pl

The test harness sets its own timeout (default 5 seconds per test). This is separate from the --timeout flag.

Exit Codes

Environment Variables

Example:

export PPERL_MAX_RECURSION=5000
pperl deeply_recursive.pl

export PPERL_CACHE=/tmp/pperl-cache
pperl --cache script.pl

Warnings

Enable warnings with -w or -W:

pperl -w script.pl

Warnings appear on stderr. Currently implemented:

• Use of uninitialized value
• Undefined subroutine call

Standard Streams

# Read stdin
while (my $line = <STDIN>) {
    print "Got: $line";
}

# Write stdout
print "Output\n";
say "Output with newline";

# Write stderr
warn "Warning message\n";

Redirection works normally:

pperl script.pl < input.txt > output.txt 2> errors.txt

Shebang Support

PetaPerl scripts support shebang for direct execution.

#!/usr/bin/env pperl
say "Hello from PetaPerl!";

Make executable and run:

chmod +x script.pl
./script.pl

Module Loading

use strict;
use warnings;
use Data::Dumper;

my $data = { foo => 42 };
print Dumper($data);

Module search path: same as perl5’s @INC. Set PERL5LIB to add directories.

Current limitations:

• XS modules not supported (native modules only)
• Some pragmas (strict, warnings) parsed but not fully enforced
• Pure Perl modules work if they don’t use unsupported features

Differences from perl5

Always-Enabled Features

Modern Perl features are always available (no use feature needed):

• say - print with newline
• state - persistent lexical variables
• // - defined-or operator
• ~~ - smart match (partial)

Default Timeout

pperl has no default timeout (same as perl5). Use --timeout=SECS to set one for untrusted scripts.

Parser

pperl always uses the native Rust parser. There is no runtime fallback to perl5.

Debugging

Syntax Errors

pperl -c script.pl

Reports parse errors with line numbers:

Parse error: Expected ';' after statement
  at script.pl line 42

Runtime Errors

Errors show stack trace:

Runtime error: Undefined subroutine &main::foo
  called at script.pl line 10

Execution Tracing

pperl --trace script.pl

Shows every op executed. Very verbose. Useful for understanding execution flow.

Performance Tips

Benchmarking

time pperl script.pl

Or use --stats for detailed metrics:

pperl --stats script.pl

Performance Characteristics

PetaPerl’s performance varies by workload:

• Interpreter fast paths: Common operations (integer arithmetic, assignment, comparison) run at or near perl5 speed
• JIT-compiled loops: Arithmetic-heavy loops compile to native code via Cranelift, achieving up to 76x faster than perl5
• JIT + parallelization: Embarrassingly parallel workloads on multi-core systems achieve up to 431x faster than perl5 (Mandelbrot 1000x1000)
• String-heavy code: Comparable to perl5 with PvBuf optimizations
• Module loading: Similar to perl5 for Pure Perl modules

Use --no-jit and --no-parallel to isolate interpreter-only performance.

Common Workflows

Script Development

# Edit script
vim script.pl

# Check syntax
pperl -c script.pl

# Run with warnings
pperl -w script.pl

# Debug with tracing (if needed)
pperl --trace script.pl

Testing

# Syntax check all scripts
find . -name '*.pl' -exec pperl -c {} \;

# Run test suite
pperl t/test.pl

Production Deployment

# Run production script (no timeout by default)
pperl production.pl

# Monitor performance
pperl --stats production.pl

Advanced Usage

Loading Op Tree from JSON (Analysis)

For parser validation and analysis:

# JSON format (B::PetaPerl) — reads from stdin
perl -MO=PetaPerl script.pl | pperl --from-json

# Short form
perl -MO=PetaPerl script.pl | pperl -j

This loads a perl5-generated op tree and executes it in the PetaPerl runtime, bypassing the native parser.

Comparing Parsers

Compare native parser output against a perl5-generated op tree:

pperl --compare-bytecode script.pl

Shows structural differences. Exit code 0 = equivalent, 1 = different.

Troubleshooting

“Can’t open perl script”

File doesn’t exist or wrong path.

pperl script.pl  # Must exist

“Undefined subroutine”

Sub not defined or not visible in current scope.

sub greet { say "hi" }
greet();  # OK

greeet();  # Error: Undefined subroutine

“Timeout expired”

Script ran longer than the --timeout value.

pperl --timeout=120 long_script.pl  # Increase timeout
pperl long_script.pl                # No timeout (default)

“Parse error”

Syntax error in script. Use -c to check:

pperl -c script.pl

“Is perl installed and in PATH?”

The --from-json/-j and --compare-bytecode analysis tools require system perl 5.42+ with B::PetaPerl installed. Normal execution does not require perl.

Version Information

pperl -v

Shows brief version and copyright.

pperl -V

Shows detailed configuration:

Summary of PetaPerl configuration:

  PetaPerl:
    version='0.1.0'
    binary='pperl'

  Runtime:
    backend=Rust interpreter + function-pointer dispatch
    jit=Cranelift (for/while loops)
    parallelism=Rayon (auto-parallel map/grep/for/while)

  Perl compatibility:
    parser=native Rust
    perl_required=no (5.42+ optional for --from-json/--compare-bytecode analysis)
    platforms=Linux only

Platform Support

PetaPerl runs on Linux only (any architecture).

Not supported: Windows, macOS, BSD, VMS, etc.

This simplification allows aggressive optimization for Linux-specific features.

Future Enhancements

Planned features:

• Profiling output (--profile)
• Extended JIT coverage (string operations, subroutine inlining)
• Extended parallelization (more loop patterns, pipeline parallelism)

Track progress: https://gl.petatech.eu/petatech/peta-perl

perlvar - PetaPerl Predefined Variables

DESCRIPTION

This document describes the special variables supported by PetaPerl. For full Perl 5 documentation, see perldoc perlvar.

SPECIAL VARIABLES

General Variables

$_ - The Default Variable

The default input and pattern-searching space. Many functions operate on $_ when no argument is given.

for (1, 2, 3) {
    print;      # prints $_ implicitly
}

$_ = "hello";
print length;   # prints 5

Implementation: src/runtime/pp/globals.rs:95

@_ - Subroutine Arguments

Within a subroutine, @_ contains the arguments passed to that subroutine. Modifying elements of @_ modifies the caller’s variables (aliasing).

sub double {
    $_[0] *= 2;    # modifies caller's variable
}

my $x = 5;
double($x);
print $x;          # prints 10

Implementation: src/runtime/pp/sub.rs

Global Special Variables

$0 - Program Name

Contains the name of the program being executed.

print "Running: $0\n";

$$ - Process ID

The process ID of the Perl process running this script.

print "PID: $$\n";

$? - Child Error Status

The status returned by the last pipe close, backtick command, or system() call.

system("false");
print "Exit status: ", $? >> 8, "\n";

$@ - Eval Error

The error message from the last eval that failed.

eval { die "oops" };
print "Error: $@" if $@;

$! - OS Error

When used in numeric context, yields the current value of errno. In string context, yields the corresponding error string.

open(my $fh, '<', '/nonexistent') or print "Error: $!\n";

I/O Variables

$/ - Input Record Separator

The input record separator, newline by default. Setting to undef enables slurp mode.

{
    local $/;           # slurp mode
    my $content = <$fh>;
}

{
    local $/ = "";      # paragraph mode
    while (<$fh>) { ... }
}

$\ - Output Record Separator

Appended to the end of every print. Default is undef (nothing appended).

{
    local $\ = "\n";
    print "line1";      # outputs "line1\n"
    print "line2";      # outputs "line2\n"
}

$, - Output Field Separator

Printed between arguments to print. Default is undef.

{
    local $, = ", ";
    print "a", "b", "c";   # outputs "a, b, c"
}

$" - List Separator

Used when arrays are interpolated into strings. Default is a space.

my @arr = (1, 2, 3);
print "@arr\n";            # outputs "1 2 3"

{
    local $" = ",";
    print "@arr\n";        # outputs "1,2,3"
}

$| - Output Autoflush

If set to nonzero, forces a flush after every write on the currently selected output channel. Default is 0.

$| = 1;    # enable autoflush on STDOUT

$. - Current Line Number

The current line number of the last filehandle read.

while (<$fh>) {
    print "$.: $_";    # prints line number and content
}

$; - Subscript Separator

The subscript separator for multidimensional hash emulation. Default is "\034" (SUBSEP).

$hash{$x, $y} = $value;    # equivalent to $hash{"$x\034$y"}

$^T - Basetime

The time at which the program began running, in seconds since the epoch.

print "Started at: ", scalar localtime($^T), "\n";

$^W - Warning Flag

The current value of the warning switch. Set by -w.

$^W = 1;    # enable warnings

Regular Expression Variables

$& - Match String

The string matched by the last successful pattern match.

"hello world" =~ /wo\w+/;
print $&;      # prints "world"

$` - Prematch String

The string preceding what was matched by the last successful pattern match.

"hello world" =~ /wo\w+/;
print $`;      # prints "hello "

$' - Postmatch String

The string following what was matched by the last successful pattern match.

"hello world!" =~ /wo\w+/;
print $';      # prints "!"

$1, $2, … - Capture Groups

Contain the text matched by capture groups in the last pattern match.

"hello world" =~ /(\w+) (\w+)/;
print "$1, $2\n";    # prints "hello, world"

%+ - Named Captures

Hash containing the text matched by named capture groups.

"hello world" =~ /(?<first>\w+) (?<second>\w+)/;
print "$+{first}, $+{second}\n";    # prints "hello, world"

Process Variables

$< - Real UID

The real user ID of this process.

print "Real UID: $<\n";

$> - Effective UID

The effective user ID of this process.

print "Effective UID: $>\n";

$( - Real GID

The real group ID of this process.

print "Real GID: $(\n";

$) - Effective GID

The effective group ID of this process, followed by supplementary group IDs.

print "Effective GID: $)\n";

System Variables

%ENV - Environment Variables

Hash containing the current environment variables.

print $ENV{HOME};
$ENV{MY_VAR} = "value";

@ARGV - Command Line Arguments

Contains the command-line arguments passed to the script.

# script.pl arg1 arg2
print "Args: @ARGV\n";    # prints "Args: arg1 arg2"

@INC - Include Path

List of directories to search for use and require statements.

push @INC, '/my/lib/path';

%SIG - Signal Handlers

Hash used to set signal handlers.

$SIG{INT} = sub { die "Caught SIGINT" };

Version Variables

$] - Perl Version (Numeric)

The version number of the Perl interpreter, as a decimal.

print $];    # e.g., 5.042000

$^V - Perl Version (String)

The version of Perl as a version string.

print $^V;   # e.g., v5.42.0

$^O - Operating System

The name of the operating system.

print $^O;   # "linux" for PetaPerl

$^X - Perl Executable Path

The path to the Perl (or PetaPerl) executable.

print $^X;   # e.g., /usr/local/bin/pperl

PetaPerl-Specific Variables

Reserved for future PetaPerl-specific extensions.

SEE ALSO

• perlfunc - Built-in functions
• perlop - Operators
• perlre - Regular expressions

Built-in Functions

PetaPerl implements the Perl 5 built-in function library. This document lists all implemented functions, organized by category.

Legend:

• ✅ Fully implemented
• ⚠️ Partially implemented
• ❌ Not yet implemented

I/O Functions

Print Operations

print "Hello\n";
print $fh "data\n";
say "Hello";                    # Adds newline
printf "%d items\n", $count;
my $str = sprintf "%05d", $num;

File Operations

open my $fh, '<', $filename or die $!;
my $data;
read $fh, $data, 1024;          # Read 1024 bytes
my $line = readline($fh);       # or <$fh>
my $char = getc($fh);
seek $fh, 0, 0;                 # Rewind to start
my $pos = tell $fh;
close $fh;

Directory Operations

opendir my $dh, $dir or die $!;
my @entries = readdir $dh;
closedir $dh;

mkdir "newdir", 0755 or die $!;
rmdir "olddir";
chdir "/tmp";

File System Operations

unlink "file.txt" or die $!;
rename "old.txt", "new.txt";
link "source", "link";
symlink "target", "symlink";
my $target = readlink "symlink";
chmod 0644, @files;
chown $uid, $gid, @files;
utime $atime, $mtime, @files;
truncate $fh, $length;
my @info = stat $file;
my @info = lstat $symlink;      # Doesn't follow symlink
my @files = glob "*.txt";

String Functions

my $len = length $str;
my $sub = substr $str, 0, 5;    # First 5 chars
substr($str, 7, 5) = "replace";  # Lvalue substr
my $pos = index $str, "find";
my $rpos = rindex $str, "last";

my $char = chr(65);              # "A"
my $code = ord("A");             # 65

my $lower = lc "HELLO";          # "hello"
my $upper = uc "hello";          # "HELLO"
my $cap = ucfirst "hello";       # "Hello"

chomp $line;                     # Remove \n if present
chop $str;                       # Remove last char
my $quoted = quotemeta '.*';     # '\\.\\\*'

my $num = hex "FF";              # 255
my $num = oct "377";             # 255

Lvalue substr: substr can be used as assignment target.

substr($str, 0, 3) = "New";      # Replace first 3 chars

Array Functions

push @arr, $val;
push @arr, @more;
my $last = pop @arr;
my $first = shift @arr;
unshift @arr, $val;

splice @arr, $offset, $length, @replacement;
my $str = join ",", @arr;
my @parts = split /,/, $str;
my @reversed = reverse @arr;
my @sorted = sort @arr;
my @sorted = sort { $a <=> $b } @numbers;
my @filtered = grep { $_ > 10 } @numbers;
my @doubled = map { $_ * 2 } @numbers;

Parallel execution: map, grep, and simple for loops may execute in parallel when safe.

Hash Functions

my @keys = keys %hash;
my @vals = values %hash;
while (my ($k, $v) = each %hash) { ... }
if (exists $hash{key}) { ... }
my $removed = delete $hash{key};

Context sensitivity: keys and values return list in list context, count in scalar context.

my $count = keys %hash;          # Number of keys
my @all_keys = keys %hash;       # All keys

Math Functions

my $abs = abs -5;                # 5
my $int = int 3.7;               # 3
my $sqrt = sqrt 16;              # 4
my $sin = sin $angle;
my $cos = cos $angle;
my $exp = exp 1;                 # e
my $log = log 10;
my $atan = atan2 $y, $x;
my $rand = rand 10;              # 0 to <10
srand 42;                        # Seed with specific value

Type and Reference Functions

my $type = ref $value;           # 'ARRAY', 'HASH', 'CODE', etc.
my $obj = bless {}, 'MyClass';
my $obj = bless $ref, 'MyClass';
if (defined $var) { ... }
undef $var;                      # Set to undef
my $count = scalar @arr;         # Force scalar context

Control and Introspection

my ($package, $file, $line) = caller;
my ($pkg, $file, $line, $sub) = caller(1);
if (wantarray) {
    return @list;
} else {
    return $scalar;
}
my $proto = prototype \&mysub;
my $pos = pos $str;
study $str;                      # Optimize for repeated regex
reset;                           # Reset ?? searches

Process and System

die "Error: $!" if $error;
warn "Warning message";
exit 0;

my $status = system "ls", "-l";
exec "command", @args;           # No return if success
my $pid = fork;
if ($pid == 0) {
    # Child process
} else {
    # Parent process
}
wait;                            # Wait for any child
waitpid $pid, 0;                 # Wait for specific child

sleep 5;                         # Sleep 5 seconds
my $now = time;
my @times = times;               # (user, system, cuser, csystem)
my @lt = localtime time;
my @gmt = gmtime time;
my $user = getlogin;

User and Group Database

All user/group database functions are implemented:

my @pwinfo = getpwnam "username";
my @pwinfo = getpwuid $uid;
while (my @entry = getpwent) { ... }
endpwent;

my @grinfo = getgrnam "groupname";
my @grinfo = getgrgid $gid;

Network Database

All network database functions are implemented:

my @host = gethostbyname "example.com";
my @net = getnetbyname "loopback";
my @proto = getprotobyname "tcp";
my @serv = getservbyname "http", "tcp";

Tie Mechanism

The functions are recognized and callable but do not dispatch to tie class methods. Modules depending on tie (e.g., Tie::File) will not function correctly.

Formats (Legacy)

Perl formats are a legacy feature. The functions exist but the format output system is not implemented. Use printf/sprintf instead.

Socket Functions

All socket operations are implemented:

IPC Functions

Known Limitations

Regular Expressions

• qr// is fully implemented including precompiled pattern reuse
• (?{code}) embedded code execution is implemented
• Possessive quantifiers (*+, ++, ?+) are implemented
• See Regular Expressions for remaining edge cases (self-referential captures, multi-char case folding)

Module System

• use and require work for Pure Perl modules
• XS modules are not supported (native reimplementations provided for common ones)
• Some pragma effects may differ from perl5

Special Variables

• Most special variables are populated ($^O, $^X, $], $^V, etc.)
• Internals::SvREADONLY is not implemented

PetaPerl-Specific Notes

Constant Folding

PetaPerl performs compile-time constant folding for:

length("hello")      # Folded to 5 at compile time
substr("text", 0, 2) # Folded to "te"

Parallel Execution

These functions may execute in parallel when safe:

• map - Parallel element transformation
• grep - Parallel filtering
• sort with pure comparison function

Parallelization requires:

• No side effects in the callback
• No shared mutable state
• Array size above parallelization threshold

Performance

• String functions use UTF-8 aware operations
• Array operations minimize copying
• Hash operations use optimized hash tables
• Math functions map to CPU instructions when possible

Operators

PetaPerl implements the full set of Perl 5 operators with identical semantics. All operators maintain Perl’s context sensitivity and precedence rules.

Binary Operators

Arithmetic

All arithmetic operators coerce operands to numeric context. Division by zero produces a warning and returns infinity or NaN.

my $x = 5 + 3;        # 8
my $y = 10 / 3;       # 3.333...
my $z = 2 ** 10;      # 1024
my $m = 17 % 5;       # 2

String

String operators coerce operands to string context.

my $str = "Hello" . " " . "World";  # "Hello World"
my $rep = "X" x 5;                   # "XXXXX"
my $pad = " " x 10;                  # 10 spaces

Numeric Comparison

Numeric comparisons coerce operands to numbers.

if ($age >= 18) { ... }
my $cmp = $a <=> $b;  # -1 if $a < $b, 0 if equal, 1 if $a > $b

String Comparison

String comparisons use lexicographic (dictionary) ordering.

if ($name eq "John") { ... }
my $cmp = $a cmp $b;  # -1, 0, or 1

Logical

Logical operators return the last evaluated value, not just true/false.

my $result = $x && $y;         # Returns $y if $x true, else $x
my $default = $user || "guest"; # Returns "guest" if $user false
my $value = $config // 0;      # Returns 0 only if $config undefined

Defined-or (//): Unlike ||, this only checks if the left side is defined, not just true. 0 and "" are both false but defined.

my $x = 0;
my $a = $x || 10;   # 10 (0 is false)
my $b = $x // 10;   # 0 (0 is defined)

Bitwise

Bitwise operators work on integers. Operands are converted to unsigned integers.

my $mask = 0xFF & $value;
my $flags = $READ | $WRITE;
my $double = $x << 1;

Range

my @digits = (0..9);              # (0, 1, 2, ..., 9)
my @letters = ('a'..'z');         # ('a', 'b', ..., 'z')
for my $i (1..100) { ... }       # Loop 1 to 100

In scalar context, .. and ... are flip-flop operators (stateful boolean range).

Binding

Binding operators connect strings with regex operations.

if ($email =~ /\@/) { ... }       # Contains @
if ($name !~ /^\d/) { ... }       # Doesn't start with digit

Unary Operators

Arithmetic

my $neg = -5;
my $pos = +$x;  # Numeric context

Logical

if (!$error) { ... }
die "Failed" if not $ok;

Bitwise

my $inverted = ~$bits;

Reference

my $scalar_ref = \$value;
my $array_ref = \@data;
my $hash_ref = \%config;

Increment/Decrement

my $x = 5;
my $a = ++$x;  # $x is 6, $a is 6
my $b = $x++;  # $x is 7, $b is 6

String increment: ++ on strings performs “magic increment” (Perl-style).

my $s = "aa";
$s++;  # "ab"
$s++;  # "ac"

File Test Operators

File test operators check properties of files and filehandles. All return true/false except -s which returns file size.

if (-e $file) { ... }               # File exists
if (-f $path && -r $path) { ... }   # Regular file and readable
my $size = -s $file;                # Size in bytes
if (-d $path) { ... }               # Is directory

Stacked file tests: -f -w -r $file checks all three conditions.

Other Unary Operators

if (defined $value) { ... }

Assignment Operators

Simple Assignment

my $x = 10;
my ($a, $b, $c) = (1, 2, 3);  # List assignment

Compound Assignment

All binary operators have compound assignment forms:

my $count = 10;
$count += 5;        # 15
$count *= 2;        # 30

my $path = "/home";
$path .= "/user";   # "/home/user"

$cache ||= load_data();   # Only load if $cache is false
$config //= {};           # Only assign if $config is undef

Ternary Operator

my $result = $x > 0 ? "positive" : "non-positive";
my $max = $a > $b ? $a : $b;

Ternary as lvalue: The ternary operator can be used as an assignment target.

($x > 0 ? $pos : $neg) = 10;  # Assigns to $pos or $neg

Array/Hash Subscripts

my $first = $arr[0];
my $value = $hash{key};
my @subset = @arr[0, 2, 4];       # Elements 0, 2, 4
my @values = @hash{'a', 'b'};     # Values for keys 'a', 'b'

Arrow Operator

my $element = $array_ref->[5];
my $value = $hash_ref->{name};
my $result = $object->method(@args);

Comma Operators

The fat comma (=>) autoquotes barewords on its left side.

my %hash = (
    name => "John",     # 'name' autoquoted
    age => 30,
);

Operator Precedence

Highest to lowest precedence (same as Perl 5):

1. Terms and list operators (left)
2. -> (left)
3. ++ -- (none)
4. ** (right)
5. ! ~ \ unary + unary - (right)
6. =~ !~ (left)
7. * / % x (left)
8. + - . (left)
9. << >> (left)
10. Named unary operators
11. < > <= >= lt gt le ge (none)
12. == != <=> eq ne cmp ~~ (none) — ~~ smart match is partial
13. & (left)
14. | ^ (left)
15. && (left)
16. || // (left)
17. .. ... (none)
18. ?: (right)
19. = += -= etc. (right)
20. , => (left)
21. List operators (right)
22. not (right)
23. and (left)
24. or xor (left)

Use parentheses when precedence is unclear.

PetaPerl-Specific Notes

Parallelization

Operators execute sequentially by default. PetaPerl’s parallelization applies at the loop/map/grep level, not individual operators.

Performance

• Bitwise operations compile to native machine instructions
• String concatenation may allocate new memory (use .= for efficiency)
• Numeric operations are optimized for integers and floats separately

Regular Expressions

PetaPerl implements a Perl 5-compatible regex engine with support for the full range of Perl regex features.

Pattern Syntax

Literals

/hello/         # Match literal "hello"
/foo bar/       # Match "foo bar"

Metacharacters

/^start/        # Must be at start
/end$/          # Must be at end
/\bword\b/      # Whole word match
/\Abegin/       # Absolute start
/finish\z/      # Absolute end

Character Classes

[abc]           # Match a, b, or c
[^abc]          # Match anything except a, b, c
[a-z]           # Match lowercase letter
[A-Z0-9]        # Match uppercase or digit
[a-zA-Z_]       # Match word character

Predefined Character Classes

/\d+/           # One or more digits
/\w+/           # One or more word chars
/\s*/           # Zero or more spaces

POSIX Character Classes

[:alnum:]       # Alphanumeric [a-zA-Z0-9]
[:alpha:]       # Alphabetic [a-zA-Z]
[:ascii:]       # ASCII characters [0-127]
[:blank:]       # Space and tab
[:cntrl:]       # Control characters
[:digit:]       # Digits [0-9]
[:graph:]       # Visible characters (not space)
[:lower:]       # Lowercase letters
[:print:]       # Printable characters
[:punct:]       # Punctuation
[:space:]       # Whitespace
[:upper:]       # Uppercase letters
[:word:]        # Word characters [a-zA-Z0-9_]
[:xdigit:]      # Hex digits [0-9A-Fa-f]

Usage: [[:digit:]] or [[:alpha:][:digit:]]

Quantifiers

/a*/            # 0 or more 'a' (greedy)
/a*?/           # 0 or more 'a' (non-greedy)
/a+/            # 1 or more 'a'
/a?/            # 0 or 1 'a'
/a{3}/          # Exactly 3 'a'
/a{3,}/         # 3 or more 'a'
/a{3,5}/        # 3 to 5 'a'

Greedy vs Non-greedy: Greedy quantifiers match as much as possible, non-greedy match as little as possible.

# Given: "foo123bar"
/\d+/           # Matches "123" (greedy)
/\d+?/          # Matches "1" (non-greedy, but entire pattern must match)

Groups and Captures

Capturing Groups

/(foo)/         # Capture "foo" in $1
/(foo)(bar)/    # Capture in $1 and $2

Access captures with $1, $2, etc., or use @+ array.

Non-Capturing Groups

/(?:foo)/       # Group but don't capture

Use when grouping is needed but capture overhead is not.

Named Captures

/(?<name>\w+)/  # Named capture "name"
/(?'name'\w+)/  # Alternative syntax

Access with $+{name} hash.

Alternation

/foo|bar/       # Match "foo" or "bar"
/(red|green|blue)/ # Capture color

Anchors and Assertions

Zero-Width Assertions

/foo(?=bar)/    # "foo" followed by "bar" (bar not consumed)
/foo(?!bar)/    # "foo" not followed by "bar"
/(?<=foo)bar/   # "bar" preceded by "foo"
/(?<!foo)bar/   # "bar" not preceded by "foo"

Atomic Groups

/(?>pattern)/   # Atomic group (no backtracking)

Once matched, the group’s contents are fixed. Used for performance optimization.

Backreferences

/(foo)\1/       # Match "foofoo" - \1 references first capture
/(['"]).*?\1/   # Match quoted string (same quote type)

Named Backreferences

/(?<tag>\w+)...\k<tag>/ # Named backreference

Conditionals

/(?(condition)yes|no)/ # If condition matches, try "yes", else try "no"

Conditions can be:

• Capture group number: (?(1)yes|no) - if group 1 matched
• Named capture: (?(<name>)yes|no) - if named group matched
• Lookahead: (?(?=test)yes|no) - if lookahead succeeds

Modifiers

Modifiers change regex behavior. Applied after closing delimiter:

/pattern/i      # Case-insensitive
/pattern/ms     # Multiline + single-line
/pattern/x      # Extended (readable)
/pattern/g      # Global matching

Examples

# Case-insensitive
if ($str =~ /hello/i) { ... }

# Multiline: ^ and $ match line starts/ends
while ($text =~ /^Line: (.+)$/mg) {
    print "Found: $1\n";
}

# Extended: whitespace and comments ignored
my $email_re = qr{
    (\w+)           # Username
    @               # At sign
    ([\w.]+)        # Domain
}x;

# Global: find all matches
my @words = $text =~ /\w+/g;

Matching and Substitution

Match Operator

$str =~ /pattern/       # True if matches
$str =~ /pattern/g      # Global, returns all matches

In list context with captures:

my ($user, $domain) = $email =~ /(\w+)@([\w.]+)/;

In list context with global:

my @numbers = $text =~ /\d+/g;  # All numbers

Substitution

$str =~ s/old/new/      # Replace first occurrence
$str =~ s/old/new/g     # Replace all occurrences
$str =~ s/old/new/i     # Case-insensitive replace
$str =~ s/old/new/gi    # Global + case-insensitive

Replacement with captures:

$str =~ s/(\w+)@(\w+)/$2\@$1/;  # Reverse user@domain

Evaluated replacement:

$str =~ s/(\d+)/$1 * 2/e;       # Double all numbers

Transliteration

$str =~ tr/abc/xyz/     # Replace a→x, b→y, c→z
$str =~ y/abc/xyz/      # Same as tr
$str =~ tr/a-z/A-Z/     # Uppercase
$str =~ tr/ //d         # Delete spaces
$str =~ tr/a-z//c       # Count non-lowercase

Special Variables

After a successful match:

if ($str =~ /(foo)(bar)/) {
    print "Full match: $&\n";     # "foobar"
    print "Group 1: $1\n";        # "foo"
    print "Group 2: $2\n";        # "bar"
    print "Before: $`\n";
    print "After: $'\n";
}

Regex Compilation

qr// Operator

Compile regex for reuse:

my $word = qr/\w+/;
my $email = qr/\w+@\w+\.\w+/;

if ($str =~ $word) { ... }
if ($str =~ /$word@$word/) { ... }  # Interpolate

Benefits:

• Compile once, use many times
• Readable regex composition
• Performance optimization

Performance Considerations

Anchored Patterns

Patterns anchored with ^ or \A are faster:

/^pattern/      # Fast: only checks start
/pattern/       # Slower: scans entire string

Atomic Groups

Use atomic groups (?>...) to prevent backtracking:

# Slow: backtracks on failure
/\d+\w+/

# Fast: no backtracking in \d+
/(?>\d+)\w+/

Non-Capturing Groups

Use (?:...) when captures aren’t needed:

/(?:foo|bar)/   # Faster than /(foo|bar)/ when capture not needed

PetaPerl-Specific Features

Bytecode Compilation

Regex patterns compile to bytecode for efficient execution. PetaPerl uses:

• Bitmap character classes for fast ASCII matching
• Literal prefix extraction to skip impossible positions
• Anchored detection to avoid unnecessary scanning

Possessive Quantifiers

Possessive quantifiers prevent backtracking entirely (more efficient than atomic groups for simple cases):

/a++/           # 1 or more 'a', no backtracking
/a*+/           # 0 or more 'a', no backtracking
/a?+/           # 0 or 1 'a', no backtracking

Embedded Code

/pattern(?{ code })/    # Execute code during match
/(??{ code })/          # Postponed regex (code returns pattern)

(?{code}) executes Perl code at the point in the pattern where it appears. The code can access $1, $2, etc. from captures made so far.

Current Limitations

PetaPerl’s regex engine passes 99.3% of perl5’s re_tests suite (1959/1972 tests). Remaining gaps:

• Self-referential captures — patterns like (a\1) (3 tests)
• local in code blocks — (?{ local $x = ... }) (2 tests)
• Multi-character case folding — Unicode chars that fold to multiple chars (2 tests)
• Branch reset backreferences — complex (?|...) with backrefs (5 tests)
• String interpolation edge case — 1 test

Unicode property support (\p{Letter}, \p{Digit}, etc.) is fully implemented for standard Unicode categories.

Examples

Email Validation

my $email_re = qr/^[\w.+-]+@[\w.-]+\.[a-zA-Z]{2,}$/;
if ($email =~ $email_re) {
    print "Valid email\n";
}

URL Parsing

my ($protocol, $host, $path) = $url =~
    m{^(https?)://([^/]+)(/.*)$};

Log File Parsing

while ($line =~ /\[(\d{4}-\d{2}-\d{2})\] (\w+): (.+)/g) {
    my ($date, $level, $msg) = ($1, $2, $3);
    # Process log entry
}

String Cleanup

# Remove multiple spaces
$text =~ s/\s+/ /g;

# Remove leading/trailing whitespace
$text =~ s/^\s+|\s+$//g;

# Or using two substitutions
$text =~ s/^\s+//;
$text =~ s/\s+$//;

Template Substitution

my %vars = (name => "John", age => 30);
my $template = "Hello {{name}}, you are {{age}} years old.";
$template =~ s/\{\{(\w+)\}\}/$vars{$1}/ge;

See Also

• perlop - Binding operators =~ and !~
• perlvar - Special variables like $&, $1, etc.

Data Types

Perl has three fundamental data types: scalars, arrays, and hashes. PetaPerl implements these with identical semantics to Perl 5.

Scalars

Scalars are Perl’s basic data type, holding a single value. The variable name begins with $.

my $number = 42;
my $string = "hello";
my $float = 3.14;
my $ref = \@array;

Scalar Types

Internally, PetaPerl represents scalars as an enum with these variants:

Dynamic typing: A scalar can change type during execution.

my $x = 42;          # Integer
$x = "hello";        # Now a string
$x = 3.14;           # Now a float

Scalar Context

Operations that expect a single value force scalar context:

my $count = @array;          # Array length
my $last = (1, 2, 3);        # Last element (3)
if (@array) { ... }          # True if non-empty

Special Scalars

Truth values: These are false in boolean context: undef, 0, "0", "". Everything else is true.

if ($value) { ... }          # False if undef, 0, "0", or ""
if (defined $value) { ... }  # False only if undef

Arrays

Arrays are ordered lists of scalars. Variable names begin with @.

my @numbers = (1, 2, 3, 4, 5);
my @words = qw(foo bar baz);
my @empty = ();

Array Access

my $first = $numbers[0];     # First element (index 0)
my $last = $numbers[-1];     # Last element
$numbers[5] = 6;             # Set element

Note the sigil change: Use $ to access a single element because you’re getting a scalar.

Array Length

my $length = @array;         # Scalar context
my $length = scalar @array;  # Explicit scalar context
my $max_index = $#array;     # Highest index (length - 1)

Array Operations

push @arr, $value;           # Append
my $value = pop @arr;        # Remove last
my $value = shift @arr;      # Remove first
unshift @arr, $value;        # Prepend

splice @arr, $offset, $len, @replacement;  # General removal/insertion

Array Slices

Extract multiple elements at once:

my @subset = @arr[0, 2, 4];  # Elements 0, 2, 4
my @range = @arr[0..5];      # Elements 0 through 5
@arr[1, 3] = (10, 20);       # Assign to multiple elements

List Context

Operations that expect multiple values force list context:

my @copy = @original;        # Array copy
my ($a, $b, $c) = (1, 2, 3); # List assignment
my @results = function();    # Function returns list

Array References

Create references to arrays:

my $aref = \@array;          # Reference to existing array
my $aref = [1, 2, 3];        # Anonymous array reference

Access via reference:

my $elem = $aref->[0];       # First element
my @copy = @$aref;           # Dereference to array
push @$aref, $value;         # Push via reference

Hashes

Hashes are unordered key-value pairs. Variable names begin with %.

my %user = (
    name => "John",
    age => 30,
    email => "john@example.com",
);

Hash Access

my $name = $user{name};      # Get value
$user{city} = "NYC";         # Set value

Sigil change: Use $ for single element access (getting a scalar).

Hash Operations

my @keys = keys %hash;       # All keys
my @values = values %hash;   # All values
while (my ($k, $v) = each %hash) { ... }  # Iterate

if (exists $hash{key}) { ... }  # Check existence
my $val = delete $hash{key};    # Remove and return

Hash Slices

Extract multiple values at once:

my @vals = @hash{qw(name age)};         # Values for keys
@hash{qw(x y)} = (10, 20);              # Assign multiple

Note: Hash slices use @ sigil because they return a list.

Hash References

Create references to hashes:

my $href = \%hash;           # Reference to existing hash
my $href = { key => "val" }; # Anonymous hash reference

Access via reference:

my $val = $href->{key};      # Get value
$href->{new} = "value";      # Set value
my @keys = keys %$href;      # Dereference to hash

References

References are scalars that point to other data.

Creating References

my $scalar_ref = \$scalar;
my $array_ref = \@array;
my $hash_ref = \%hash;
my $code_ref = \⊂
my $anon_array = [1, 2, 3];
my $anon_hash = { a => 1, b => 2 };
my $anon_sub = sub { ... };

Dereferencing

my $value = $$scalar_ref;    # Scalar dereference
my @array = @$array_ref;     # Array dereference
my %hash = %$hash_ref;       # Hash dereference
my $result = &$code_ref();   # Code dereference

Arrow notation (preferred for clarity):

my $elem = $array_ref->[0];
my $val = $hash_ref->{key};
my $result = $code_ref->(@args);

Reference Types

Check reference type with ref:

my $type = ref $ref;
# Returns: 'SCALAR', 'ARRAY', 'HASH', 'CODE', 'REF', or '' (not a ref)

Nested Data Structures

References enable complex data structures:

my $data = {
    users => [
        { name => "John", age => 30 },
        { name => "Jane", age => 25 },
    ],
    config => {
        debug => 1,
        timeout => 30,
    },
};

my $name = $data->{users}->[0]->{name};  # "John"

Autovivification

Perl automatically creates intermediate references:

my %hash;
$hash{a}{b}{c} = 1;          # Creates nested hashes automatically
my $val = $hash{x}[0];       # Creates array ref at $hash{x}

Type Conversions

Perl performs automatic type conversions based on context.

String to Number

my $x = "42";
my $y = $x + 10;             # 52 (string → number)

Number to String

my $x = 42;
my $s = "Value: $x";         # "Value: 42" (number → string)

String Concatenation

my $result = 10 . 20;        # "1020" (both → string)

Boolean Context

if ("0")    { ... }          # False
if ("00")   { ... }          # True
if (0)      { ... }          # False
if (0.0)    { ... }          # False
if ("")     { ... }          # False
if (undef)  { ... }          # False

Typeglobs

Typeglobs are a special type that can hold entries for all variable types with the same name.

*name = \$scalar;            # Alias glob to scalar
*name = \⊂               # Alias glob to subroutine

Primarily used for symbol table manipulation and importing.

PetaPerl-Specific Implementation

Memory Representation

PetaPerl uses efficient internal representations:

Scalars: Rust enum with variants for each type. Two string representations optimize for different access patterns.

#![allow(unused)]
fn main() {
pub enum Sv {
    Undef,
    Iv(i64),                 // Integer
    Uv(u64),                 // Unsigned
    Nv(f64),                 // Float
    Pv(Arc<str>, u32),       // Immutable string + virtual length (O(1) chomp)
    PvBuf(Arc<String>),      // Mutable string (COW via Arc::make_mut)
    Rv(RvInner),             // Reference
    Av(Av),                  // Array
    Hv(Hv),                  // Hash
    // ... additional types
}
}

Dual string representation: Pv is used for constants and literals — the u32 virtual length enables O(1) chomp without modifying the shared string. PvBuf is used for mutable strings (default for new_string()) — Arc::make_mut() provides copy-on-write semantics with zero allocation when unshared.

Arrays: Dynamic vectors with efficient push/pop operations.

Hashes: Optimized hash tables with fast key lookup.

Shared Ownership

String scalars use Arc<str> (atomic reference counting):

• Cheap cloning (just increment counter)
• Thread-safe sharing for parallel execution
• Common strings can share storage

Aliasing Support

PetaPerl implements @_ aliasing correctly:

• Arguments are aliases to caller’s variables
• Modifications write through to original
• Uses SvCell for mutable indirection

sub modify {
    $_[0] = "changed";       # Modifies caller's variable
}

my $x = "original";
modify($x);
print $x;                    # "changed"

Performance Characteristics

Parallel Execution

PetaPerl’s parallelization model:

• Each thread gets its own lexical pad (no shared mutation)
• Array and hash operations are thread-safe
• Arc<str> strings share across threads safely
• Loop-level parallelism doesn’t require global locks

Context Sensitivity

Perl’s context system determines how expressions evaluate.

Scalar Context

Forces single-value evaluation:

my $count = @array;          # Length
my $last = (1, 2, 3);        # Last element
my $concat = (1, 2, 3);      # 3

List Context

Forces multiple-value evaluation:

my @copy = @array;           # All elements
my @results = func();        # All return values
my ($a, $b) = (1, 2, 3);     # First two elements

Void Context

Result is discarded:

func();                      # Return value ignored
print "hello";               # No assignment

Context Propagation

my @arr = (1, 2, 3);

# Scalar context
my $x = keys @arr;           # keys in scalar context → count

# List context
my @k = keys @arr;           # keys in list context → all keys

# Function argument context
func(@arr);                  # List context
func(scalar @arr);           # Scalar context (explicit)

Constants

Constants are immutable values.

Literal Constants

42                           # Integer
3.14                         # Float
"string"                     # String
qw(a b c)                    # List of strings

Named Constants

use constant PI => 3.14159;
use constant MAX => 100;
use constant {
    RED   => 0xFF0000,
    GREEN => 0x00FF00,
    BLUE  => 0x0000FF,
};

Compile-Time Constant Folding

PetaPerl performs constant folding at compile time:

my $x = 2 + 3;               # Folded to 5
my $len = length("hello");   # Folded to 5
my $sub = substr("text", 0, 2);  # Folded to "te"

This optimization eliminates runtime computation for constant expressions.

Special Types

Code References

Subroutines can be referenced and called dynamically:

my $coderef = sub { return $_[0] * 2 };
my $result = $coderef->(21);  # 42

my $coderef = \&existing_sub;
$coderef->(@args);

Filehandles

Filehandles are special scalars:

open my $fh, '<', $file or die $!;
my $line = <$fh>;
close $fh;

Globs

Typeglobs reference symbol table entries:

*alias = *original;          # Alias all types
*func = sub { ... };         # Install subroutine

See Also

• perlop - Operators that work with these types
• perlfunc - Functions for manipulating data
• perlref - More on references (Perl 5 docs)

Subroutines

Subroutines are reusable code blocks in Perl. PetaPerl implements Perl5-compatible subroutines with full support for lexical variables, closures, and signatures.

Declaration

sub greet {
    print "Hello, World!\n";
}

# Named sub
sub add {
    my ($a, $b) = @_;
    return $a + $b;
}

# Anonymous sub
my $sub = sub {
    my $x = shift;
    return $x * 2;
};

Arguments (@_)

Arguments are passed via the special @_ array. Each element is aliased to the caller’s variable.

sub modify {
    $_[0] = "modified";  # Modifies caller's variable
}

my $x = "original";
modify($x);
say $x;  # "modified"

Copying arguments:

sub safe_modify {
    my ($val) = @_;      # Copy, not alias
    $val = "modified";   # Does not affect caller
}

Direct access:

sub first { $_[0] }
sub second { $_[1] }

Return Values

Explicit Return

sub max {
    my ($a, $b) = @_;
    return $a if $a > $b;
    return $b;
}

Implicit Return

The last expression’s value is returned automatically.

sub square {
    my $x = shift;
    $x * $x  # Implicit return
}

Context-Sensitive Returns

sub get_data {
    if (wantarray) {
        return (1, 2, 3);      # List context
    } else {
        return "scalar data";  # Scalar context
    }
}

my @list = get_data();   # (1, 2, 3)
my $scalar = get_data(); # "scalar data"

Note: PetaPerl’s wantarray works for direct calls and most common patterns. Complex nesting may have edge cases.

Prototypes

Prototypes provide compile-time argument checking and context forcing.

sub scalar_arg ($) {
    my $x = shift;
}

sub array_arg (@) {
    my @vals = @_;
}

sub no_args () {
    return 42;
}

Common prototypes:

PetaPerl Status: Basic prototype parsing implemented. Runtime enforcement partial.

Signatures (Experimental)

Perl 5.20+ signatures provide named parameters with optional type constraints and defaults.

sub greet ($name, $greeting = "Hello") {
    say "$greeting, $name!";
}

greet("Alice");              # Hello, Alice!
greet("Bob", "Hi");          # Hi, Bob!

Slurpy parameters:

sub sum ($first, @rest) {
    my $total = $first;
    $total += $_ for @rest;
    return $total;
}

sum(1, 2, 3, 4);  # 10

PetaPerl Status: Signature parsing implemented in AST. Codegen lowers to pad allocation. Runtime parameter assignment works. Default values and slurpy params functional.

Closures

Anonymous subs capture lexical variables from enclosing scope.

sub make_counter {
    my $count = 0;
    return sub {
        return ++$count;
    };
}

my $c1 = make_counter();
say $c1->();  # 1
say $c1->();  # 2

my $c2 = make_counter();
say $c2->();  # 1  (independent counter)

Closure capture mechanism:

• Parser identifies outer lexicals referenced in sub body
• Codegen records outer_refs mapping (sub_pad_slot, outer_pad_slot)
• pp_anoncode captures cells at instantiation time
• pp_entersub shares captured cells into sub’s pad

Example: Closure factory

sub make_adder {
    my $offset = shift;
    return sub {
        my $x = shift;
        return $x + $offset;  # Captures $offset
    };
}

my $add5 = make_adder(5);
my $add10 = make_adder(10);

say $add5->(3);   # 8
say $add10->(3);  # 13

Each closure captures its own $offset cell. Modifications affect only that closure’s instance.

Method Calls

my $obj = Some::Class->new();
$obj->method($arg);

# Indirect object notation (discouraged)
method $obj $arg;

PetaPerl Status: Method dispatch via pp_method, pp_method_named. ISA lookup implemented. AUTOLOAD supported.

Special Subroutines

AUTOLOAD

Called when undefined sub is invoked.

package Foo;

our $AUTOLOAD;

sub AUTOLOAD {
    my $method = $AUTOLOAD;
    $method =~ s/.*:://;  # Strip package
    print "Called undefined method: $method\n";
}

Foo->undefined_method();  # Triggers AUTOLOAD

PetaPerl Status: AUTOLOAD dispatch implemented in pp_entersub. Sets $Package::AUTOLOAD correctly.

BEGIN, END, INIT, CHECK, UNITCHECK

PetaPerl Status: BEGIN blocks execute during compilation. END blocks execute at program exit. INIT, CHECK, and UNITCHECK have partial support.

Recursion

Recursive calls are supported with depth limit.

sub factorial {
    my $n = shift;
    return 1 if $n <= 1;
    return $n * factorial($n - 1);
}

Recursion limit: Default 1000 levels (configurable via PPERL_MAX_RECURSION). Prevents stack overflow.

Calling Conventions

With parentheses

foo();        # No arguments
foo($a);      # One argument
foo($a, $b);  # Multiple arguments

Without parentheses (ampersand form)

&foo;   # Pass current @_ to foo

When called as &foo (no parens), the current @_ is passed to the callee. This enables wrapper functions:

sub wrapper {
    log_call();
    goto &real_function;  # Tail call with current @_
}

Goto and Tail Calls

sub outer {
    # ... setup ...
    goto &inner;  # Replace current call frame
}

goto &sub performs tail call optimization: replaces current frame instead of adding a new one.

PetaPerl Status: goto &sub implemented in pp_goto. Tail recursion optimization functional.

Advanced Features

Constant Subs

use constant PI => 3.14159;
use constant DEBUG => 0;

# Equivalent to:
sub PI () { 3.14159 }

Constant subs have empty prototype () and return fixed value. Perl can inline them at compile time.

PetaPerl Status: use constant creates constant subs. pp_entersub returns constant value directly without entering sub.

Lvalue Subs

sub get_value : lvalue {
    $global_var;
}

get_value() = 42;  # Assigns to $global_var

PetaPerl Status: :lvalue attribute not implemented. pp_leavesublv stub exists.

State Variables

sub counter {
    state $count = 0;
    return ++$count;
}

state variables persist across calls (initialized once).

PetaPerl Status: State variables are implemented. Variables are initialized once and persist across calls.

Built-in Functions

wantarray

Returns calling context: undef (void), 0 (scalar), 1 (list).

sub context_aware {
    if (!defined wantarray) {
        say "void context";
    } elsif (wantarray) {
        say "list context";
        return (1, 2, 3);
    } else {
        say "scalar context";
        return 42;
    }
}

PetaPerl Status: Partial implementation. Works for direct calls. May fail in complex nesting.

caller

Returns information about calling stack frame.

# Scalar context: boolean (is there a caller?)
if (caller) {
    # Called from another sub
}

# List context: detailed info
my ($package, $filename, $line) = caller(0);
my ($pkg, $file, $line, $sub) = caller(1);  # One frame up

PetaPerl Status: Implemented in pp_caller. Returns (package, filename, line, subroutine, ...) in list context.

PetaPerl Implementation Notes

Op Tree Structure

Named subs register CV (Code Value) in arena:

SubDef → lower_sub() → NextState → body ops → LeaveSub
                     ↓
                 Register CV(name, start_op, pad_size, outer_refs)

Anonymous subs emit AnonCode op:

AnonSub → lower_anon_sub() → NextState → body ops → LeaveSub
                           ↓
                       AnonCode (pushes CV onto stack)

Call Sequence

1. Caller pushes args onto stack
2. Caller pushes mark
3. Caller pushes CV reference
4. EnterSub pops CV, pops mark, collects args into aliased @_
5. New pad allocated (slot 0 = @_)
6. Closure cells shared into pad (if any)
7. Jump to CV’s start_op
8. Body executes
9. LeaveSub collects return values, restores pad
10. Return to caller

Pad Layout

Slot 0: @_ (always, populated by EnterSub)
Slot 1+: Lexical variables in declaration order

Signature parameters become pad slots:

sub foo ($x, $y, @rest) { }

# Pad layout:
# 0: @_
# 1: $x
# 2: $y
# 3: @rest

Closure Capture

Two-stage process:

1. Codegen: Analyze outer lexicals, record outer_refs in CV
2. Runtime: pp_anoncode captures cells, pp_entersub shares them

Why two stages? Closure factories need per-instance capture, not per-definition.

Known Limitations

Performance

PetaPerl subs execute via the interpreter with fast-path dispatch. The JIT compiler (Cranelift) handles hot loops within subroutines but does not JIT subroutine call/return itself.

The interpreter’s function-pointer dispatch table and inline fast paths for common operations (arithmetic, comparison, assignment) minimize per-op overhead.

Closure overhead: Cell allocation per captured variable. Minimal at runtime (Arc clone).

Testing

See t/05-op/sub.t, t/05-op/closure.t for comprehensive test coverage.

Built-in Functions

pperl PP runtime built-in functions extracted from the Rust implementation source.

Array Functions

• delete — Removes the specified element(s) from a hash or array.
• each — Returns the next key-value pair from a hash’s internal iterator.
• exists — Tests whether a hash key or array index is present in the container.
• keys — Returns all keys of a hash, or the number of keys in scalar context.
• pop — Removes and returns the last element of an array.
• push — Appends one or more values to the end of an array, growing it as needed.
• shift — Removes and returns the first element of an array, shifting all
• sort — Sorts a list of values and returns them in sorted order.
• splice — Removes and/or replaces elements in an array, returning the removed
• unshift — Prepends one or more values to the beginning of an array.
• values — Returns all values of a hash, or the number of values in scalar context.

File Functions

• chdir — Changes the process’s current working directory.
• chmod — Changes file permissions on one or more files.
• chown — Changes the owner and group of one or more files.
• closedir — Closes a directory handle, releasing its resources.
• glob — Expands shell-style filename patterns into matching pathnames.
• link — Creates a hard link to an existing file.
• lstat — Returns file metadata without following symbolic links.
• mkdir — Creates a new directory with the specified permissions.
• opendir — Opens a directory for reading via a directory handle.
• readdir — Reads entries from an open directory handle.
• readlink — Returns the target of a symbolic link.
• rename — Renames or moves a file.
• rewinddir — Resets the position of a directory handle back to the beginning.
• rmdir — Removes an empty directory.
• stat — Returns file metadata as a 13-element list.
• symlink — Creates a symbolic (soft) link.
• umask — Gets or sets the process file-creation permission mask.
• unlink — Deletes one or more files from the filesystem.
• utime — Sets the access and modification timestamps of one or more files.

Formatting

• sprintf — Formats a string according to a printf-style format specification.

Hash Functions

• delete — Removes the specified element(s) from a hash or array.
• each — Returns the next key-value pair from a hash’s internal iterator.
• exists — Tests whether a hash key or array index is present in the container.
• keys — Returns all keys of a hash, or the number of keys in scalar context.
• values — Returns all values of a hash, or the number of values in scalar context.

I/O Functions

• binmode — Sets the I/O discipline (encoding layer) for a filehandle.
• close — Closes a filehandle, flushing any buffered output.
• eof — Tests whether the next read on a filehandle will return end-of-file.
• fileno — Returns the underlying OS file descriptor for a Perl filehandle.
• getc — Reads a single character from a filehandle.
• open — Opens a file, pipe, or duplicates a file descriptor, associating
• pipe — Creates a unidirectional pipe pair (read end + write end).
• print — Outputs a list of values to a filehandle.
• printf — Formats and prints a list of values to a filehandle using a format string.
• read — Reads a fixed number of bytes from a filehandle into a scalar buffer.
• readline — PP function for readline
• say — Like print, but automatically appends a newline after the output.
• seek — Sets the read/write position in a filehandle.
• select — Sets the default output filehandle or performs I/O multiplexing.
• sysopen — Opens a file using POSIX open(2) flags for precise mode control.
• sysread — Performs an unbuffered read directly from the OS file descriptor.
• syswrite — Performs an unbuffered write directly to the OS file descriptor.
• tell — Returns the current byte position in a filehandle.
• truncate — Truncates a file to a specified length.

Numeric Functions

• rand — Returns a pseudo-random floating-point number.
• srand — Seeds the pseudo-random number generator used by rand.

Process Functions

• alarm — Schedules a SIGALRM signal to be delivered after a given number
• die — Raises an exception, terminating execution unless caught by an eval
• exec — Replaces the current process image with a new program via execvp(3).
• exit — Terminates the program with the given exit status.
• fork — Creates a child process by duplicating the current process.
• kill — Sends a signal to one or more processes or process groups.
• sleep — Suspends execution for the specified number of seconds.
• system — Executes an external command and waits for it to complete.
• wait — Waits for any child process to terminate.
• waitpid — Waits for a specific child process to change state.
• warn — Issues a warning message to STDERR without terminating the program.

Regular Expressions

• m// — Tests a string against a regular expression pattern.
• pos — Gets or sets the position of the last m//g match on a string.
• qr — Creates a precompiled regular expression object.
• quotemeta — Escapes all non-“word” characters with a preceding backslash.
• s/// — Searches a string for a pattern and replaces matched text.
• split — Splits a string into a list of substrings using a pattern.
• tr — Performs character-by-character transliteration on a string.

Scope and Variables

• bless — Associates a reference with a package, turning it into an object.
• caller — Returns information about the calling subroutine’s context.
• defined — Tests whether a value is defined (not undef).
• do — Reads, compiles, and executes a Perl file, returning the value of
• pos — Gets or sets the position of the last m//g match on a string.
• prototype — Returns the prototype string of a subroutine, or undef if none.
• ref — Returns the reference type or blessed class name of a value.
• require — Loads and executes a Perl file or module, caching it in %INC so
• reset — Resets ?? (one-shot match) operators so they can match again.
• tie — Binds a variable to an object class, enabling magical access
• tied — Returns the underlying object of a tied variable.
• undef — Produces the undefined value, or undefines an existing variable.
• untie — Removes the tie binding from a variable, restoring normal access.
• vec — Treats a string as a bit vector and accesses individual bitfields.

String Functions

• chomp — Removes the trailing record separator (default: newline) from each
• chop — Removes the last character from each argument
• chr — Converts a Unicode code point number to the corresponding character.
• crypt — One-way password hashing using the system crypt(3) library.
• hex — Interprets a hexadecimal string as an integer.
• index — Finds the first occurrence of a substring within a string.
• join — Concatenates a list of values into a single string with a separator.
• lc — Converts a string to lowercase.
• lcfirst — Lowercases the first character of a string.
• length — Returns the number of characters in a string.
• oct — Interprets a string as an octal number, with automatic prefix dispatch.
• ord — Returns the Unicode code point of the first character of a string.
• pack — Converts a list of values into a binary string according to a template.
• quotemeta — Escapes all non-“word” characters with a preceding backslash.
• reverse — Reverses a list of values or the characters of a string, depending
• rindex — Finds the last occurrence of a substring within a string.
• sprintf — Formats a string according to a printf-style format specification.
• substr — and 3-argument forms)
• uc — Converts a string to uppercase.
• ucfirst — Uppercases the first character of a string.
• unpack — Extracts values from a binary string according to a template.

Time Functions

• gmtime — Converts a Unix timestamp to UTC (Greenwich Mean Time), returning
• localtime — Converts a Unix timestamp to the local time zone, returning either
• time — Returns the number of seconds since the Unix epoch.

alarm

Schedules a SIGALRM signal to be delivered after a given number of seconds.

Arranges for a SIGALRM to be delivered to the process after the specified number of seconds. If an alarm was already pending, the old alarm is cancelled and the number of seconds that were remaining is returned. Calling alarm(0) cancels the current alarm without setting a new one.

Commonly used with eval/die or $SIG{ALRM} to implement timeouts:

eval {
    local $SIG{ALRM} = sub { die "timeout\n" };
    alarm(10);
    # ... long operation ...
    alarm(0);
};

Negative values are clamped to 0.

Synopsis

my $remaining = alarm(30);   # fire SIGALRM in 30 seconds
alarm(0);                    # cancel any pending alarm

See Also

sleep, alarm, POSIX

backticks

Executes a shell command and captures its standard output.

Passes the command string to /bin/sh -c "..." for execution. In scalar context, returns the entire captured stdout as a single string. In list context, returns a list of lines (each including its trailing newline), split on $/ (input record separator).

After execution, $? (child error) is set to the child process wait status. Stdin is inherited from the parent so that interactive commands (e.g. tput) work correctly; stderr is also inherited.

Synopsis

my $output = `command`;
my $output = qx{command};
my @lines  = `command`;

See Also

system, exec, open

binmode

Sets the I/O discipline (encoding layer) for a filehandle.

Configures the encoding layer on a filehandle. When called with just a filehandle, sets binary mode (disabling any CRLF translation, though Linux does not perform CRLF translation by default). When called with a layer string, applies the specified encoding.

Currently recognized layers:

• :utf8, :encoding(UTF-8) – mark the handle as UTF-8
• :raw, :bytes – mark the handle as raw bytes

Returns true on success, false on failure.

Synopsis

binmode(STDOUT);              # set binary mode (no CRLF translation)
binmode(STDOUT, ":utf8");     # set UTF-8 encoding layer
binmode(STDOUT, ":raw");      # remove all layers
binmode($fh, ":encoding(UTF-8)");

See Also

open, PerlIO, Encode

bless

Associates a reference with a package, turning it into an object.

Marks the referent so that method calls will dispatch through the given class (or the current package if no class is specified). The reference is modified in place and also returned, enabling the common return bless {}, $class pattern.

Handles multiple referent types: for Av and Hv containers the blessing is stored via interior mutability on the container itself. For Rv wrapping an Av or Hv, the inner container is blessed. For scalar references, a new blessed RvInner is created.

Synopsis

my $obj = bless {}, 'MyClass';
my $obj = bless {};              # blesses into current package
my $obj = bless \$scalar, 'Foo';
my $obj = bless [], 'Bar';

See Also

ref, Scalar::Util

caller

Returns information about the calling subroutine’s context.

In scalar context, returns the package name of the calling subroutine. In list context, returns a multi-element list with (at minimum) package, filename, and line number. When called with a numeric argument N, returns information about the Nth stack frame above the current subroutine:

Returns undef (scalar) or an empty list if the requested stack depth exceeds the actual call depth. caller(0) returns info from call_stack.last() (the current sub’s frame); caller(1) looks one frame further up.

When the op has WANT bits set to 0 (unknown), the context is inherited from the enclosing call frame, matching perl5 behavior.

Synopsis

my $package = caller;                  # scalar: package name
my ($pkg, $file, $line) = caller;      # list: basic triple
my ($pkg, $file, $line, $sub, ...) = caller(0);
my @info = caller(1);                  # caller's caller

See Also

die, warn, caller

chdir

Changes the process’s current working directory.

Changes the working directory to the specified path. If called with no argument or an empty string, changes to the directory specified by the HOME environment variable (or / if HOME is not set).

Returns 1 on success, undef on failure.

Synopsis

chdir("/tmp") or die "Cannot chdir: $!";
chdir($dir);
chdir();         # changes to $HOME
chdir("");       # also changes to $HOME

See Also

mkdir, rmdir, Cwd, getcwd

chmod

Changes file permissions on one or more files.

Changes the permissions of each listed file to MODE. The first argument is the numeric mode (typically given as an octal literal); the remaining arguments are file paths. Returns the number of files successfully changed. Preserves file-type bits (S_IFMT) from the existing mode and replaces only the permission bits (lower 12 bits).

Synopsis

chmod 0755, $file1, $file2;
chmod 0644, @files;
my $count = chmod 0600, glob("*.conf");

See Also

chown, stat, umask

chomp

Removes the trailing record separator (default: newline) from each argument. Returns the total number of characters removed.

Respects $/ (input record separator). When $/ is undef (slurp mode), chomp is a no-op. When $/ is "" (paragraph mode), removes all trailing newlines. Handles CRLF line endings — \r\n counts as 2 characters removed.

Synopsis

$count = chomp($var);
$count = chomp(@list);
chomp $var;

See Also

chop, $/

chop

Removes the last character from each argument. Returns the last character removed (from the final argument).

Unlike chomp, chop always removes exactly one character regardless of $/. Operates on each element when given an array. Returns the last character removed. Correctly handles multi-byte UTF-8 characters.

Synopsis

$char = chop($var);
$char = chop(@list);
chop $var;

See Also

chomp

chown

Changes the owner and group of one or more files.

Changes the owner and group of each listed file. The first argument is the numeric UID, the second is the numeric GID, and the remaining arguments are file paths. A value of -1 for either UID or GID means “don’t change that field” (converted to u32::MAX for the libc call). Uses libc::chown (follows symlinks). Returns the number of files successfully changed.

Synopsis

chown $uid, $gid, @files;
chown 0, 0, '/etc/shadow';
chown -1, $gid, @files;    # -1 leaves uid unchanged

See Also

chmod, stat

chr

Converts a Unicode code point number to the corresponding character.

Returns the character represented by the given code point. Negative values produce an empty string. Invalid Unicode code points (e.g. surrogates) produce the replacement character U+FFFD.

Synopsis

$char = chr(65);        # "A"
$char = chr(0x263A);    # "☺"

See Also

ord

close

Closes a filehandle, flushing any buffered output.

Closes the filehandle and releases its resources from the global FILEHANDLE_TABLE. For in-memory filehandles (opened against a scalar reference), the accumulated buffer is written back to the target variable. For pipe filehandles, the child process’s stdin is closed and waitpid is called; $? is set to the child’s exit status.

Both lexical ($fh) and bareword (FH) filehandle forms are supported. The standard handles STDIN/STDOUT/STDERR are recognized by name.

Returns 1 on success, undef on failure.

Synopsis

close($fh) or die "Cannot close: $!";
close(FH);

See Also

open, eof, $?

closedir

Closes a directory handle, releasing its resources.

Removes the directory handle from the global DIRHANDLE_TABLE. After closing, the handle is no longer valid for readdir or other directory operations.

Returns 1 on success, undef if the handle was not found or already closed.

Synopsis

closedir($dh);
closedir(DH);

See Also

opendir, readdir

crypt

One-way password hashing using the system crypt(3) library.

Calls the system crypt(3) function. The SALT determines the hashing algorithm (DES, MD5, SHA-256, SHA-512, etc. depending on the platform). The result can be compared against a stored hash to verify a password without storing the plaintext.

Synopsis

my $hashed = crypt($plaintext, $salt);
if (crypt($input, $hashed) eq $hashed) { ... }  # verify

See Also

Digest::SHA, Digest::MD5

defined

Tests whether a value is defined (not undef).

Pops one value from the stack and pushes 1 if it is defined, 0 otherwise. For code values (Cv), “defined” means the CV has actual executable code and is not merely an empty stub. For all other types, delegates to Sv::is_defined().

Synopsis

if (defined $x)        { ... }
if (defined &func)     { ... }   # is sub defined (not a stub)?
if (defined $hash{$k}) { ... }

See Also

undef, exists

delete

Removes the specified element(s) from a hash or array.

For hashes, removes the key-value pair and returns the deleted value (or undef if the key did not exist). Read-only hashes (such as %!) and Hash::Util-restricted hashes reject deletion with an error. For arrays, sets the element to undef without changing the array size; use splice to actually shrink.

Stash-backed hashes (accessed via %{"Package::"}) route the deletion through the PackageRegistry so the symbol is removed from the live stash, not just from the snapshot Hv.

Synopsis

delete $hash{$key};
delete @hash{@keys};               # hash slice
delete $array[$index];
my $val = delete $hash{$key};       # returns deleted value

See Also

exists, each, keys, splice

die

Raises an exception, terminating execution unless caught by an eval block or a try/catch construct.

If called with a string argument, raises that string as the exception message. If the string does not end with a newline, Perl appends at FILE line LINE. If called with a reference (e.g. a hashref or blessed object), the reference is propagated as the exception value in $@.

When called with no arguments (or an empty string / undef), re-raises the current value of $@. If $@ is also empty, dies with "Died".

If there is an active try block (from use feature 'try'), the exception is caught and execution transfers to the catch block instead of propagating.

Synopsis

die "something went wrong";
die "Error at $file line $line\n";
die $exception_object;
die;                              # re-raises $@

See Also

warn, eval

do

Reads, compiles, and executes a Perl file, returning the value of the last expression evaluated.

Unlike require, do FILE:

• Always re-reads and re-executes the file (no %INC caching).
• Does not die on failure; instead it returns undef and sets $@ to the error message.
• Does not inherit caller lexicals (unlike eval STRING).
• Evaluates the file in the current package context.

On success, returns the value of the last expression evaluated in the file and clears $@. On compilation or runtime error, returns undef and sets $@.

Synopsis

do "config.pl";
my $result = do "/path/to/file.pm";

See Also

require, eval, use

each

Returns the next key-value pair from a hash’s internal iterator.

Advances the hash’s internal iterator and returns the next entry. In list context, pushes a (key, value) pair. In scalar context, returns only the key. When the iterator is exhausted, returns an empty list (list context) or undef (scalar context), and the iterator resets automatically for the next traversal.

Note: keys and values reset the same internal iterator, so calling them during an each loop will restart iteration.

Synopsis

while (my ($k, $v) = each %hash) { ... }
while (my $k = each %hash) { ... }    # scalar context: key only

See Also

keys, values, exists, delete

eof

Tests whether the next read on a filehandle will return end-of-file.

Returns true (1) when the filehandle has reached end-of-file, or an empty string (false) otherwise. Called without arguments, eof() checks the filehandle most recently read via <> or readline.

If the filehandle is invalid or has never been read, returns true.

Synopsis

if (eof($fh))  { ... }   # test specific filehandle
if (eof())     { ... }   # test last-read filehandle
if (eof)       { ... }   # same as eof()

See Also

readline, read, tell

exec

Replaces the current process image with a new program via execvp(3).

On success, exec does not return because the current process image is replaced entirely. If exec does return, it means the call failed, and the return value is false.

In the single-argument form, shell metacharacters trigger execution via /bin/sh -c. If no metacharacters are detected, the command is executed directly. In the multi-argument form, the first argument is the program and subsequent arguments are passed directly (no shell involvement).

The child inherits Perl’s %ENV (the OS environment is replaced before exec).

Synopsis

exec("ls -la");              # shell form
exec("ls", "-la");           # list form (no shell)
exec { "ls" } "ls", "-l";   # indirect object form

See Also

system, fork, exec

exists

Tests whether a hash key or array index is present in the container.

Pops a key and a container (hash or array) from the stack. For hashes, checks whether the key is present (even if the associated value is undef). For arrays, checks whether the index is within bounds and the element has not been deleted. Pushes 1 (true) or 0 (false).

When the container is a stash (package symbol table accessed via %{"Package::"}), checks for the existence of any symbol type (scalar, array, hash, or code) with the given name.

Synopsis

if (exists $hash{$key})   { ... }
if (exists $array[$idx])  { ... }
if (exists $stash{$name}) { ... }   # stash symbol lookup

See Also

defined, delete, keys

exit

Terminates the program with the given exit status.

Evaluates the argument as an integer exit status and terminates the process. If no argument is given, exits with status 0. END blocks and object destructors are run before exit (in perl5; pperl currently calls std::process::exit directly).

In daemon mode (config.daemon_mode), exit does not terminate the process but instead returns an Err(RuntimeError::Exit) so the caller can handle it.

Synopsis

exit;          # exits with status 0
exit 0;        # success
exit 1;        # failure
exit $code;

See Also

die, END blocks

fileno

Returns the underlying OS file descriptor for a Perl filehandle.

Returns the numeric file descriptor associated with the given filehandle, or undef if the handle is not connected to a real OS file descriptor (e.g. in-memory handles, closed handles).

Accepts bareword filehandles (STDIN), lexical filehandles ($fh), and IO::Handle / IO::File objects (blessed hashrefs with __fh_id).

The standard streams always return their well-known descriptors: STDIN = 0, STDOUT = 1, STDERR = 2.

Synopsis

$fd = fileno(STDIN);     # 0
$fd = fileno(STDOUT);    # 1
$fd = fileno($fh);       # fd number or undef

See Also

open, close, IO::Handle

fork

Creates a child process by duplicating the current process.

Calls POSIX fork(2) to create a new child process. Both parent and child continue execution from the point of the fork call.

Returns:

• undef on failure (fork could not be performed)
• 0 in the child process
• The child’s PID (positive integer) in the parent process

Synopsis

my $pid = fork();
die "fork failed: $!" unless defined $pid;
if ($pid == 0) {
    # child process
    exit(0);
} else {
    # parent process, $pid is child's PID
    waitpid($pid, 0);
}

See Also

exec, wait, waitpid, exit

getc

Reads a single character from a filehandle.

Returns the next character from the specified filehandle as a one-character string. When called without arguments, reads from STDIN (filehandle id 0). Returns undef at end-of-file or on error.

Accepts both lexical ($fh) and bareword (FH) filehandles.

Synopsis

$ch = getc($fh);   # one character from $fh
$ch = getc();      # one character from STDIN

See Also

readline, read, eof

glob

Expands shell-style filename patterns into matching pathnames.

Expands the given pattern using shell globbing rules. Supports *, ?, [charset], {alt1,alt2} (brace expansion), and ~ (home directory). In list context returns all matches; in scalar context returns the next match (iterating on successive calls with the same pattern).

The <PATTERN> syntax is equivalent to glob(PATTERN).

When File::Glob is loaded, delegates to bsd_glob semantics where whitespace in patterns is treated literally. Otherwise, the default behaviour splits the pattern on whitespace to process multiple globs.

Results are returned sorted and deduplicated.

Synopsis

@files = glob('*.pl');
@files = glob('lib/**/*.pm');
@files = <*.txt>;         # angle-bracket form

See Also

opendir, readdir, File::Glob

gmtime

Converts a Unix timestamp to UTC (Greenwich Mean Time), returning the same structure as localtime but without timezone or DST adjustments.

Identical to localtime in interface, but all values are in UTC rather than the local timezone. The $isdst field is always 0. If called without an argument, uses the current time.

The implementation uses a pure-Rust UTC calculation (no libc dependency), correctly handling negative timestamps (dates before the epoch) and leap years.

Synopsis

my @t = gmtime(0);     # (0,0,0,1,0,70,4,0,0) - epoch in UTC
my $s = gmtime(0);     # "Thu Jan  1 00:00:00 1970"
my @t = gmtime();      # current time in UTC

See Also

localtime, time, POSIX::strftime

hex

Interprets a hexadecimal string as an integer.

Accepts an optional 0x or 0X prefix. Underscores are allowed as digit separators. Leading and trailing whitespace is stripped. Returns 0 for empty or non-hex input.

Synopsis

$val = hex("ff");       # 255
$val = hex("0xDEAD");   # 57005
$val = hex("ff_ff");    # 65535

See Also

oct

index

Finds the first occurrence of a substring within a string.

Searches STRING for the first occurrence of SUBSTR starting at character position START (default 0). Returns the zero-based character position of the match, or -1 if the substring is not found.

Positions are in characters (not bytes), so this works correctly with multi-byte UTF-8 strings. An ASCII fast path avoids the overhead of character-index conversion when both operands are pure ASCII.

When the OPpTARGET_MY flag (0x10) is set, the result is stored directly into the pad slot rather than pushed to the stack.

Synopsis

$pos = index($string, $substr);
$pos = index($string, $substr, $start);

See Also

rindex, substr, pos

join

Concatenates a list of values into a single string with a separator.

Takes a separator string followed by a list of values (from a pushmark-delimited argument list on the stack). The separator is inserted between each adjacent pair of values. Array arguments are flattened. Returns the resulting string; an empty string when no list values are given.

Uses Cow<str> for the separator and parts to avoid allocation when the underlying SVs are already string-typed.

Synopsis

$str = join(',', @array);
$str = join(' ', 'hello', 'world');
$str = join('', @chars);           # no separator

See Also

split, sprintf

keys

Returns all keys of a hash, or the number of keys in scalar context.

In list context, pushes all keys of the hash onto the stack as individual string values. In scalar context, returns the number of key-value pairs. Accepts both %hash and $hashref (auto- dereferences). As a side effect, resets the hash’s internal iterator used by each.

Synopsis

my @k = keys %hash;
my $count = keys %hash;         # scalar context: number of keys
for my $key (keys %hash) { ... }

See Also

values, each, exists, delete

kill

Sends a signal to one or more processes or process groups.

The first argument is the signal, specified either as a name ('TERM', 'HUP', with or without SIG prefix) or as a number. The remaining arguments are PIDs to signal.

If the signal is negative, the absolute value is sent to the process group identified by each PID (using kill(-sig, -abs(pid))).

Signal 0 does not actually send a signal but checks whether the process exists and is reachable (permission check).

Returns the number of processes successfully signaled.

Synopsis

kill 'TERM', $pid;                # send SIGTERM by name
kill 15, $pid;                    # send SIGTERM by number
kill 'TERM', $pid1, $pid2;        # signal multiple processes
kill 0, $pid;                     # check if process exists
kill -15, $pgrp;                  # signal a process group

See Also

%SIG, POSIX signals, fork, waitpid

lc

Converts a string to lowercase.

Returns a lowercased copy of STRING. For ASCII input, an in-place byte mutation fast path avoids allocation when a TARG pad slot is available. For Unicode input, Rust’s to_lowercase() is used, which handles case mappings that change byte length.

Synopsis

$lower = lc($string);
$lower = lc('HELLO');   # "hello"

See Also

uc, ucfirst, lcfirst

lcfirst

Lowercases the first character of a string.

Returns a copy of STRING with the first character converted to lowercase and all other characters left unchanged. For ASCII first characters, a single-byte in-place mutation is used. For Unicode first characters, to_lowercase() may change the byte length.

Returns an empty string when given an empty string.

Synopsis

$result = lcfirst($string);
$result = lcfirst('HELLO');   # "hELLO"

See Also

ucfirst, uc, lc

length

Returns the number of characters in a string.

Returns the character count (not byte count) for Unicode correctness. length(undef) returns undef, matching perl5 behavior.

Synopsis

$len = length($string);
$len = length("café");   # 4 (characters, not bytes)

See Also

substr

link

Creates a hard link to an existing file.

Creates a new directory entry NEWFILE that refers to the same inode as OLDFILE. Both paths must be on the same filesystem. The link count of the file is incremented. Uses std::fs::hard_link. Returns 1 on success, 0 on failure (and sets $!).

Synopsis

link $oldfile, $newfile or die "Cannot link: $!";
link '/data/original', '/data/hardlink';

See Also

symlink, unlink, rename

localtime

Converts a Unix timestamp to the local time zone, returning either a 9-element list or a human-readable string depending on context.

If called without an argument (or with undef), uses the current time. In list context, returns a 9-element list:

In scalar context, returns a ctime-style string like "Thu Jan 1 00:00:00 1970".

Uses libc::localtime_r for accurate timezone/DST handling.

Synopsis

my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
    = localtime($time);
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
    = localtime();           # uses current time
my $str = localtime($time);  # "Thu Jan  1 00:00:00 1970"

See Also

gmtime, time, POSIX::strftime, POSIX::mktime

lstat

Returns file metadata without following symbolic links.

Identical to stat except that if the target is a symbolic link, lstat returns information about the link itself rather than the file it points to. Uses std::fs::symlink_metadata. Returns the same 13-element list as stat, or an empty list on failure.

Synopsis

my @s = lstat($symlink);
my ($dev, $ino, $mode, $nlink, $uid, $gid, $rdev, $size,
    $atime, $mtime, $ctime, $blksize, $blocks) = lstat($path);
lstat _;               # reuse last stat buffer

See Also

stat, readlink, symlink

m//

Tests a string against a regular expression pattern.

Matches the target string against the compiled regex pattern. The target is determined by context:

• If targ > 0: reads from the pad slot (lexical $str =~ /pat/)
• If STACKED flag is set: pops from the stack (expression =~ /pat/)
• Otherwise: matches against $_ (bare /pat/)

In scalar context, returns true (1) or false (“”) indicating whether the pattern matched. Sets $1, $2, etc. for capture groups and updates pos() for /g matches.

In list context without /g, returns the list of captured substrings ($1, $2, …), or (1) if there are no captures.

In list context with /g, returns all matches: if the pattern has captures, returns all captured groups from all matches; otherwise returns all matched substrings.

Patterns are cached per-op for static regexes; dynamic patterns (from regcomp) use a HashMap-based cache.

Synopsis

if ($str =~ /pattern/)       { ... }
if ($str =~ /pattern/flags)  { ... }
my @captures = ($str =~ /(\w+)/g);
/bare pattern/;                        # matches against $_

See Also

s///, split, qr//, perlre, perlop

mkdir

Creates a new directory with the specified permissions.

Creates a directory with the given name. The optional second argument specifies the permissions mode (default 0777), which is modified by the process umask before being applied. If no arguments are given, uses $_ as the directory name.

Returns 1 on success, 0 on failure. On failure, sets $! to the OS error code (e.g. EEXIST, EACCES).

Synopsis

mkdir("newdir", 0755) or die "Cannot mkdir: $!";
mkdir("newdir");         # default mode 0777 (modified by umask)
mkdir $_;                # uses $_ if no argument

See Also

rmdir, chmod, umask

oct

Interprets a string as an octal number, with automatic prefix dispatch.

Dispatches on prefix: 0x/x for hexadecimal, 0b/b for binary, 0o for explicit octal (Perl 5.34+), otherwise plain octal. Underscores are allowed as digit separators. Leading whitespace is stripped.

Synopsis

$val = oct("77");       # 63
$val = oct("0xff");     # 255 (hex)
$val = oct("0b1010");   # 10  (binary)
$val = oct("0o77");     # 63  (explicit octal)

See Also

hex

open

Opens a file, pipe, or duplicates a file descriptor, associating it with a filehandle.

Supports both the 2-argument form (mode embedded in the filename string) and the 3-argument form (separate mode and filename). The 3-argument form is preferred as it avoids shell metacharacter issues.

In-memory I/O is supported via scalar references: open $fh, '>', \$buf.

Returns 1 on success, undef on failure. Sets $! on error.

Synopsis

open(my $fh, '<', $filename);       # read
open(my $fh, '>', $filename);       # write (truncate)
open(my $fh, '>>', $filename);      # append
open(my $fh, '+<', $filename);      # read/write
open(my $fh, '|-', @cmd);           # pipe to command
open(my $fh, '-|', @cmd);           # pipe from command
open(my $fh, '>&', $other_fh);      # dup for writing
open(my $fh, '<', \$scalar);        # in-memory I/O
open(FH, "<$filename");             # 2-arg form

See Also

close, binmode, print, read, sysopen, perlopentut

opendir

Opens a directory for reading via a directory handle.

Associates a directory handle with the named directory. The handle can then be used with readdir, rewinddir, seekdir, telldir, and closedir. All directory entries (including . and ..) are loaded eagerly into a Vec at open time.

The directory handle variable receives a numeric ID stored in the global DIRHANDLE_TABLE. Both lexical (my $dh) and bareword (DH) forms are supported.

Returns 1 on success, undef on failure.

Synopsis

opendir(my $dh, $dir) or die "Cannot open $dir: $!";
opendir(DH, "/tmp");

See Also

readdir, closedir, rewinddir, File::Find

ord

Returns the Unicode code point of the first character of a string.

Returns the code point of the first character. For an empty string, returns 0. Multi-character strings return only the first character’s code point.

Synopsis

$code = ord("A");       # 65
$code = ord("☺");      # 9786

See Also

chr

pack

Converts a list of values into a binary string according to a template.

Takes a TEMPLATE string and a LIST of values and packs them into a binary string. The template is a sequence of format characters, each optionally followed by a repeat count or * (consume all remaining).

Common format characters:

• a, A, Z – ASCII string (null-padded, space-padded, null-terminated)
• c, C – signed/unsigned char (8-bit)
• s, S – signed/unsigned short (16-bit native)
• l, L – signed/unsigned long (32-bit native)
• q, Q – signed/unsigned quad (64-bit native)
• n, N – unsigned short/long in network (big-endian) byte order
• v, V – unsigned short/long in VAX (little-endian) byte order
• f, d – single/double-precision float (native)
• H, h – hex string (high/low nybble first)
• w – BER compressed integer
• U – Unicode code point
• x – null byte padding
• X – back up one byte
• @ – null-pad to absolute position
• (...)N – group with repeat count

Whitespace and #-comments in templates are ignored.

Synopsis

my $bin = pack("A10", "hello");         # space-padded string
my $bin = pack("NnA*", $long, $short, $str);
my $bin = pack("(A2)*", @pairs);        # group repeat

See Also

unpack, vec

pipe

Creates a unidirectional pipe pair (read end + write end).

Calls the POSIX pipe(2) system call to create a connected pair of file descriptors. The first argument receives the read end and the second receives the write end, both as filehandles.

Typically used together with fork to set up inter-process communication. Returns 1 on success or undef on failure (with $! set to the system error).

Synopsis

pipe(my $read_fh, my $write_fh) or die "pipe: $!";

See Also

open, close

pop

Removes and returns the last element of an array.

Removes the last element from the array and returns it. If the array is empty, returns undef. The array shrinks by one element.

Synopsis

my $val = pop @array;
pop @array;              # discard removed element

See Also

push, shift, unshift, splice

pos

Gets or sets the position of the last m//g match on a string.

As an rvalue, returns the character offset where the most recent global (/g) match left off, or undef if no match has been performed on that string. As an lvalue, sets the starting position for the next m//g match.

Without an argument, operates on $_. Positions are stored in a side table (pos_table) keyed by string content.

Synopsis

$str =~ /pattern/g;
my $p = pos($str);       # position after last /g match
pos($str) = 0;           # reset match position
my $p = pos;             # defaults to $_

See Also

m//g, reset

print

Outputs a list of values to a filehandle.

Pops values from the stack and writes them to the target filehandle. When the STACKED flag is set, the first value after the mark is the filehandle; otherwise, STDOUT is used.

The output field separator $, ($OFS) is inserted between values, and the output record separator $\ ($ORS) is appended after all values. For say (which shares this implementation), a newline is always appended after the output.

Supports Gv (typeglob), bareword string, and lexical (integer ID) filehandle forms. In-memory filehandles (open my $fh, '>', \$buf) write to the backing buffer.

Returns 1 on success (Perl convention).

Synopsis

print "hello world\n";
print STDERR "error message\n";
print $fh @data;
print @array;                # uses $, and $\

See Also

say, printf, write, perlvar

printf

Formats and prints a list of values to a filehandle using a format string.

Equivalent to print FILEHANDLE sprintf(FORMAT, LIST). Formats the list of values according to FORMAT (see sprintf for format specifiers) and writes the result to the specified filehandle (or STDOUT if none is given).

Like print, honors $\ (output record separator), which is appended after the formatted output. The filehandle is determined by the stacked flag on the op, exactly as in pp_print.

Internally delegates to pp_sprintf for formatting, then writes the resulting string to the filehandle.

Synopsis

printf FORMAT, LIST;
printf FILEHANDLE FORMAT, LIST;

See Also

sprintf, print, say

prototype

Returns the prototype string of a subroutine, or undef if none.

Accepts a code reference, a reference to a CV, or a string naming the subroutine. For CORE:: builtins, returns the well-known prototype from a built-in table (e.g. \@@ for push, ;$ for defined). For user-defined subs, looks up the CV in the stash and returns its prototype. Unqualified names are resolved in the current package. Returns undef when the subroutine has no prototype or cannot be found.

Synopsis

my $proto = prototype(\&mysub);         # "$$"
my $proto = prototype('CORE::push');    # "\@@"
my $proto = prototype('main::func');    # look up by name

See Also

sub, CORE::

push

Appends one or more values to the end of an array, growing it as needed.

Treats the first argument as an array and appends all subsequent arguments to it. Array arguments are flattened (their elements are pushed individually, not as nested arrays). Returns the new number of elements in the array.

Synopsis

push @array, $value;
push @array, @more_values;
push @array, $v1, $v2, $v3;
my $new_len = push @array, $value;

See Also

pop, unshift, shift, splice

qr

Creates a precompiled regular expression object.

Compiles the pattern (from OpData::Pm or a runtime-interpolated string in runtime_regex_pattern) into a regex and wraps it as a blessed reference in the Regexp class. The stringified form is (?^flags:pattern), matching perl5 behaviour.

The returned object can be used directly in pattern matches, interpolated into other patterns, or stored in variables, arrays, and hashes for later use.

Synopsis

my $re = qr/pattern/flags;
$str =~ $re;             # use in match
$str =~ /${re}suffix/;   # interpolate into pattern

See Also

m//, s///, perlre, perlop

quotemeta

Escapes all non-“word” characters with a preceding backslash.

Returns a version of the string where every non-word character ([^A-Za-z0-9_]) is preceded by \. Useful for interpolating literal strings into regular expressions. If all characters are already word characters, the input is returned unchanged with no allocation.

Synopsis

my $safe = quotemeta($string);
$string =~ /\Q$pattern\E/;     # \Q invokes quotemeta

See Also

m//, s///

rand

Returns a pseudo-random floating-point number.

Returns a pseudo-random floating-point number greater than or equal to 0 and less than EXPR (or 1 if omitted). If EXPR evaluates to zero, 1.0 is used instead. Uses the interpreter’s StdRng state, which can be seeded via srand. Not suitable for cryptographic purposes.

Synopsis

my $r = rand;          # 0 <= $r < 1
my $r = rand(10);      # 0 <= $r < 10
my $r = rand($n);

See Also

srand, int

read

Reads a fixed number of bytes from a filehandle into a scalar buffer.

Attempts to read LENGTH bytes from the filehandle FH into the scalar BUFFER. When OFFSET is supplied, data is placed at that byte position within the buffer (the buffer is null-padded if OFFSET exceeds its current length).

Returns the number of bytes actually read (which may be less than LENGTH), 0 at end-of-file, or undef on error. The target buffer is written back through lvalue targets (pad slot or stash variable).

Synopsis

$bytes = read($fh, $buf, $length);
$bytes = read($fh, $buf, $length, $offset);

See Also

sysread, readline, eof

readdir

Reads entries from an open directory handle.

In scalar context, returns the next directory entry name as a string, or undef when the directory is exhausted. In list context, returns all remaining entries as a list of strings.

Entry names are bare filenames (no path prefix). The entries . and .. are included, matching perl5 behavior.

Synopsis

my $entry = readdir($dh);      # scalar: one entry
my @entries = readdir($dh);     # list: all remaining entries

See Also

opendir, closedir, rewinddir, glob

readline

PP function for readline

Reads one or more records from a filehandle.

In scalar context, returns the next record from the filehandle (including the record separator, typically a newline). Returns undef at end-of-file. In list context, returns all remaining records.

The record separator is controlled by $/:

• "\n" (default) – line-at-a-time mode
• "" – paragraph mode (reads until a blank line)
• undef – slurp mode (reads the entire file)
• \N (reference to integer) – fixed-length record mode (reads N bytes)
• arbitrary string – reads until that separator is found

When the STACKED flag is set, the result is assigned to the lvalue target on the stack (e.g. my $line = <$fh>).

Supports both lexical ($fh) and bareword (FH) filehandles, as well as IO::Handle / IO::File objects.

Synopsis

$line  = <$fh>;           # scalar: next line
@lines = <$fh>;           # list: all remaining lines
$line  = readline($fh);   # explicit function form

See Also

eof, read, getc, chomp

readlink

Returns the target of a symbolic link.

Returns the filename pointed to by the symbolic link EXPR, or $_ if omitted. Returns undef on error (e.g., not a symlink, file not found) and sets $!. Uses std::fs::read_link and converts the result to a string via to_string_lossy.

Synopsis

my $target = readlink $symlink;
my $target = readlink '/usr/bin/perl';
my $target = readlink;     # readlink($_)

See Also

symlink, lstat, stat

ref

Returns the reference type or blessed class name of a value.

Pops one value and pushes a string describing its reference type. For blessed references, returns the class name (e.g. "MyClass"). For unblessed references, returns the underlying type: "SCALAR", "ARRAY", "HASH", "CODE", "REF", "GLOB", or "Regexp". For non-references, returns the empty string "".

Delegates to Sv::ref_type() for the actual type determination.

Synopsis

my $type = ref $ref;           # "HASH", "ARRAY", "SCALAR", "CODE", etc.
my $class = ref $object;       # "MyClass" for blessed references
if (ref $x) { ... }            # true if $x is a reference

See Also

bless, Scalar::Util

rename

Renames or moves a file.

Renames the file OLDNAME to NEWNAME. If NEWNAME already exists, it is replaced atomically (on the same filesystem). Cannot move files across filesystem boundaries. Uses std::fs::rename. Returns 1 on success, 0 on failure (and sets $!).

Synopsis

rename $old, $new or die "Cannot rename: $!";
rename 'file.tmp', 'file.dat';

See Also

unlink, link, File::Copy

require

Loads and executes a Perl file or module, caching it in %INC so that subsequent calls for the same module are no-ops.

Behaviour depends on the argument type:

1. Version number (numeric or v-string): asserts that the Perl version is at least that value. pperl claims 5.42 compatibility, so any 5.x requirement succeeds; 6+ dies.

2. Bareword / string: converts Foo::Bar to Foo/Bar.pm, then searches @INC for the file. If already present in %INC, the call is a no-op. Otherwise the file is compiled and executed in a sub-interpreter, subs are registered, and %INC is updated.

Dies with "Can't locate ..." if the file is not found. Returns 1 on success.

Synopsis

require 5.036;              # version check
require Carp;               # load Carp.pm via @INC
require "config.pl";        # load a file by path

See Also

use, do, eval, @INC, %INC

reset

Resets ?? (one-shot match) operators so they can match again.

The ?? operator matches only once between calls to reset. Without an argument, resets all one-shot matches in the current package. With a character-range argument, resets only those in variables whose names fall within the range.

This is a deprecated and rarely used feature. Returns 1.

Implementation status: Stub (no-op). PetaPerl does not currently track ?? match state.

Synopsis

reset;            # reset all ?? in current package
reset 'a-z';      # reset ?? in variables matching range

See Also

m//g, pos

reverse

Reverses a list of values or the characters of a string, depending on context.

In list context, collects all items between the stack mark and the current position (flattening any intermediate arrays), reverses their order, and pushes them back. In scalar context, concatenates all items into a single string and reverses the characters. An ASCII fast path reverses bytes in-place; non-ASCII strings are reversed by Unicode code point.

Synopsis

my @rev = reverse @list;
my @rev = reverse 1, 2, 3;       # (3, 2, 1)
my $rev = reverse "Hello";        # "olleH"

See Also

sort

rewinddir

Resets the position of a directory handle back to the beginning.

Sets the current position of DIRHANDLE back to the beginning of the directory, so that subsequent readdir calls will re-read the directory from the start. The directory must have been previously opened with opendir.

Returns 1 on success, undef on failure.

Synopsis

rewinddir(DIRHANDLE);

See Also

opendir, readdir, closedir

rindex

Finds the last occurrence of a substring within a string.

Searches STRING for the last occurrence of SUBSTR, considering only matches that start at or before character position END (default: end of string). Returns the zero-based character position of the match, or -1 if the substring is not found.

For an empty SUBSTR, returns min(END, length(STRING)) to match perl5 behaviour.

Positions are in characters (not bytes), so this works correctly with multi-byte UTF-8 strings. An ASCII fast path uses rfind directly when both operands are pure ASCII.

When the OPpTARGET_MY flag (0x10) is set, the result is stored directly into the pad slot rather than pushed to the stack.

Synopsis

$pos = rindex($string, $substr);
$pos = rindex($string, $substr, $end);

See Also

index, substr, pos

rmdir

Removes an empty directory.

Deletes the named directory, which must be empty. If no argument is given, uses $_. Returns 1 on success, 0 on failure. On failure, sets $! to the OS error code (e.g. ENOTEMPTY, ENOENT, EACCES).

Only empty directories can be removed; use File::Path::rmtree for recursive deletion.

Synopsis

rmdir("olddir") or die "Cannot rmdir: $!";
rmdir $_;        # uses $_ if no argument

See Also

mkdir, unlink, File::Path

s///

Searches a string for a pattern and replaces matched text.

Compiles the pattern from OpData::Pm, finds matches in the target string, performs the substitution, and updates the source variable in place. Pushes the number of successful substitutions to the stack (0 if no match, which is false in boolean context).

The target string is resolved from:

• A PadSv op (lexical variable $str =~ s/.../.../)
• A GvSv op (package variable)
• A Sassign op (compound (my $x = $y) =~ s/.../.../)

Supports replacement templates with backreferences ($1, $&, etc.) and replacement ops for the /e flag (evaluate replacement as Perl code).

Flags: /g (global), /i (case-insensitive), /m (multiline), /s (single-line), /e (eval replacement), /r (non-destructive, returns modified copy).

Synopsis

$str =~ s/pattern/replacement/;
$str =~ s/pattern/replacement/g;     # global
$str =~ s/pattern/replacement/gi;    # global, case-insensitive
($copy = $orig) =~ s/old/new/g;      # compound assign+subst
s/pattern/replacement/;               # operates on $_

See Also

m//, tr///, perlre, perlop

say

Like print, but automatically appends a newline after the output.

Behaves identically to print except that a newline character is appended after all output (including any $\ record separator). Requires use feature 'say' or use v5.10 or later in perl5.

Internally delegates to pp_print, which detects OpCode::Say and appends the newline to the correct filehandle.

Synopsis

say "hello world";           # prints "hello world\n"
say STDERR "debug info";
say $fh @data;

See Also

print, printf

seek

Sets the read/write position in a filehandle.

Repositions the file pointer for the given filehandle. The WHENCE argument selects the reference point: 0 (SEEK_SET) for the beginning of the file, 1 (SEEK_CUR) for the current position, and 2 (SEEK_END) for the end of the file. Returns 1 on success, 0 on failure.

Also accepts IO::Handle / IO::File objects (blessed hashrefs with __fh_id).

Synopsis

seek($fh, $offset, 0);   # SEEK_SET — absolute position
seek($fh, $offset, 1);   # SEEK_CUR — relative to current
seek($fh, $offset, 2);   # SEEK_END — relative to end

See Also

tell, sysseek, Fcntl

select

Sets the default output filehandle or performs I/O multiplexing.

1-argument form: Sets the default output filehandle (used by print and write when no explicit handle is given) and returns the previously selected handle. With no arguments, returns the current default output handle name without changing it.

4-argument form: Wraps the POSIX select(2) system call. Waits for I/O readiness on the file descriptors encoded in the bit vectors RBITS (readable), WBITS (writable), and EBITS (exceptional). TIMEOUT is in seconds (may be fractional). Returns the number of ready descriptors, or -1 on error.

Synopsis

$prev = select($fh);                                # 1-arg form
$nfound = select($rbits, $wbits, $ebits, $timeout); # 4-arg form

See Also

print, IO::Select, fileno

shift

Removes and returns the first element of an array, shifting all remaining elements down by one index.

Removes the first element from the array, shifts all remaining elements down by one, and returns the removed element. Returns undef if the array is empty.

When the SPECIAL flag is set (bare shift without an explicit array), the implicit target depends on call context: inside a subroutine it reads from @_ (pad slot 0); at file scope it reads from @ARGV. Handles both regular Av and AliasedAv (the typical representation of @_).

Synopsis

my $val = shift @array;
my $arg = shift;          # shifts from @_ inside a sub, @ARGV at top level

See Also

unshift, pop, push, splice

sleep

Suspends execution for the specified number of seconds.

Causes the process to sleep for the given number of whole seconds. Returns the number of seconds actually slept, which may be less than requested if a signal interrupted the sleep.

If Time::HiRes::sleep has been imported into the current package, fractional seconds are supported and the override is used instead. Time::HiRes::sleep dies on negative values.

Without arguments, sleeps indefinitely (until a signal arrives). Negative values are clamped to 0.

Uses libc::sleep() (not std::thread::sleep) so that signals like SIGALRM can interrupt the sleep. If interrupted, any pending $SIG{...} handler is dispatched synchronously before returning.

Synopsis

my $slept = sleep(5);    # pause 5 seconds, returns 5
sleep;                   # sleep forever (until signal)
# with: use Time::HiRes qw(sleep);
sleep(0.5);              # fractional seconds

See Also

alarm, Time::HiRes, select

sort

Sorts a list of values and returns them in sorted order.

Sorts the input list according to the comparison mode determined by the op’s private flags:

• Default (string): Lexicographic comparison via cmp.
• Numeric (OPpSORT_NUMERIC, 0x01): Floating-point comparison.
• Custom block (OPpSORT_BLOCK, 0x20): A CV on the stack is used as the comparator. $a and $b are set in the current package via cached cells and the CV is executed using the multicall pattern (pad + call frame set up once, only $a/$b updates per comparison) with a merge-sort algorithm.
• Descend (OPpSORT_DESCEND, 0x08): Reverses the final result.

Array arguments are flattened before sorting.

Synopsis

my @sorted = sort @list;                    # lexicographic
my @sorted = sort { $a <=> $b } @list;      # numeric
my @sorted = sort { $b cmp $a } @list;      # reverse lexicographic
my @sorted = sort \&compare, @list;          # named comparator

See Also

reverse, map, grep

splice

Removes and/or replaces elements in an array, returning the removed elements.

Removes $length elements starting at $offset from @array, optionally replacing them with @replacements, and returns the removed elements. Negative $offset counts from the end of the array. If $length is omitted, removes everything from $offset onward. A negative $length leaves that many elements at the end. Replacement arrays are flattened. The array is rebuilt in place.

Synopsis

my @removed = splice @array, $offset;
my @removed = splice @array, $offset, $length;
my @removed = splice @array, $offset, $length, @replacements;
splice @array, 0, 0, @prepend;    # insert at beginning

See Also

push, pop, shift, unshift, delete

split

Splits a string into a list of substrings using a pattern.

Splits EXPR (or $_ if omitted) into substrings at each match of PATTERN. If LIMIT is positive, returns at most LIMIT fields. If LIMIT is negative, behaves as if arbitrarily large. If LIMIT is zero or omitted (default), trailing empty fields are stripped.

Special case: split ' ' (with pmflags & 0x800) uses awk-style semantics – splits on runs of whitespace and ignores leading whitespace. An empty pattern (split //, $str) splits every character.

If a split_targ is set in the op, results are stored directly into the target array (pad slot) instead of the stack. In scalar context, returns the number of fields.

Synopsis

@fields = split /PATTERN/, EXPR, LIMIT;
@fields = split /PATTERN/, EXPR;
@fields = split /PATTERN/;           # splits $_
@fields = split ' ', $string;        # awk-style split
my $count = split /,/, $csv;         # scalar context: count

See Also

join, m//g, perlre

sprintf

Formats a string according to a printf-style format specification.

Takes a format string followed by a list of arguments (from a pushmark-delimited argument list on the stack) and returns the formatted result string. Supports the standard C-style conversion specifiers:

• %s string, %d/%i signed decimal, %u unsigned decimal
• %o octal, %x/%X hex, %b/%B binary
• %e/%E scientific, %f/%F fixed, %g/%G general float
• %c character (by codepoint), %p pointer, %% literal percent

Flags: - (left-justify), + (force sign), (space for sign), 0 (zero-pad), # (alternate form). Width and precision may be literal or * (consumed from the argument list). Indexed arguments via %N$ are supported. The %vd vector flag formats a string as dot-separated byte values (e.g. version strings).

Uses a zero-allocation fast path: arguments are peeked from the stack as &[Sv] without cloning, and integer formatting uses stack buffers.

Synopsis

$s = sprintf('%d items at $%.2f each', $count, $price);
$s = sprintf('%05x', $hex_val);
$s = sprintf('%-20s', $name);

See Also

printf, join

srand

Seeds the pseudo-random number generator used by rand.

Sets the seed for the random number generator used by rand. If EXPR is provided and defined, its integer value is used. Otherwise, a system-derived seed (nanosecond timestamp XOR PID) is used. Creates a new StdRng instance via seed_from_u64. Returns the seed that was actually used as an integer.

Synopsis

srand(42);             # deterministic sequence
srand;                 # seed from system entropy
my $seed = srand;      # returns the seed used

See Also

rand

stat

Returns file metadata as a 13-element list.

Returns a 13-element list giving the status info for a file. The elements are: dev, ino, mode, nlink, uid, gid, rdev, size, atime, mtime, ctime, blksize, blocks. Follows symbolic links (use lstat to stat the link itself). Returns an empty list on failure.

When Time::HiRes::stat has been imported into the caller’s namespace, the atime/mtime/ctime fields are returned as floating-point seconds with nanosecond precision.

Synopsis

my @s = stat($file);
my ($dev, $ino, $mode, $nlink, $uid, $gid, $rdev, $size,
    $atime, $mtime, $ctime, $blksize, $blocks) = stat($file);
stat $fh;                  # stat on a filehandle
stat _;                    # reuse last stat buffer

See Also

lstat, chmod, chown

stringify

Converts a value to its string representation, respecting overload.

If the value is already a string, passes it through unchanged. If it is a blessed reference with a "" (stringify) overload handler, invokes that handler. Otherwise converts via default stringification (Sv::to_str_cow).

Synopsis

my $s = "$value";    # stringify via interpolation

See Also

ref, overload

substr

and 3-argument forms)

Extracts a substring from a string.

Returns the portion of STRING starting at character position OFFSET. If OFFSET is negative, it counts backwards from the end of the string. When LENGTH is given, at most that many characters are extracted; a negative LENGTH leaves that many characters at the end.

The argument count is encoded in the lower 4 bits of the op’s private flags (set by codegen). When those bits are zero (e.g. bytecode/JSON fallback path), the stack length is used instead.

Synopsis

$part = substr($string, $offset);
$part = substr($string, $offset, $length);

See Also

index, rindex, substr

symlink

Creates a symbolic (soft) link.

Creates a symbolic link LINKNAME that points to TARGET. Unlike hard links, symbolic links can span filesystems and can point to directories. Uses std::os::unix::fs::symlink. Returns 1 on success, 0 on failure (and sets $!).

Synopsis

symlink $target, $linkname or die "Cannot symlink: $!";
symlink '/usr/bin/perl', '/usr/local/bin/perl';

See Also

link, readlink, unlink

sysopen

Opens a file using POSIX open(2) flags for precise mode control.

Unlike the high-level open, sysopen takes explicit POSIX mode flags (from Fcntl) and an optional permissions mask. The flags are passed directly to the underlying open(2) system call.

Arguments on the stack (via mark): filehandle target, filename, mode flags, and optional permissions (defaults to 0666, modified by umask).

Returns 1 on success (the filehandle is stored in the first argument) or undef on failure.

Synopsis

use Fcntl;
sysopen(my $fh, $filename, O_RDWR | O_CREAT, 0644);
sysopen(FH, $path, O_WRONLY | O_TRUNC);

See Also

open, close, Fcntl

sysread

Performs an unbuffered read directly from the OS file descriptor.

Reads up to LENGTH bytes from the filehandle into BUFFER using the underlying read(2) system call, bypassing Perl’s buffered I/O layer. When OFFSET is given, data is placed starting at that byte position within the buffer.

Returns the number of bytes actually read (which may be less than LENGTH), 0 at end-of-file, or undef on error (with $! set to the OS errno).

Warning: Do not mix sysread with buffered I/O (read, readline, <>) on the same filehandle.

Synopsis

$n = sysread($fh, $buf, $length);
$n = sysread($fh, $buf, $length, $offset);

See Also

read, syswrite, sysseek

sysseek

Repositions the OS file pointer, bypassing Perl’s buffered I/O layer.

Calls lseek(2) on the underlying file descriptor to reposition the read/write offset. Unlike seek, this operates at the system-call level and does not interact with Perl’s I/O buffering.

Returns the resulting absolute position (as a “0 but true” string when the position is zero, per perl5 convention), or undef on error (with $! set).

Warning: Do not mix sysseek with buffered I/O (seek, tell) on the same filehandle.

Synopsis

$pos = sysseek($fh, $offset, SEEK_SET);  # absolute
$pos = sysseek($fh, 0, SEEK_CUR);        # query position
$pos = sysseek($fh, 0, SEEK_END);        # query file size

See Also

seek, tell, sysread, syswrite

system

Executes an external command and waits for it to complete.

In the single-argument form, the command string is passed to /bin/sh -c for shell interpretation (pipes, redirects, etc.). In the multi-argument form (list form), the program is executed directly via execvp without a shell, avoiding shell metacharacter interpretation.

Returns the full wait status (same encoding as $?):

• 0 on success (exit code 0)
• $? >> 8 extracts the exit code
• Lower 8 bits contain signal information
• -1 on failure to execute

The child process inherits Perl’s %ENV (not the OS environment).

Synopsis

my $status = system("ls -la");
my $status = system("program", "arg1", "arg2");
system("echo hello") == 0 or die "system failed: $?";

See Also

exec, fork, waitpid, backticks, $?

syswrite

Performs an unbuffered write directly to the OS file descriptor.

Writes data from SCALAR to the filehandle using the underlying write(2) system call, bypassing Perl’s buffered I/O layer. When LENGTH is specified, at most that many bytes are written. When OFFSET is given, writing starts from that byte position within the scalar.

Returns the number of bytes actually written, or undef on error (with $! set to the OS errno).

Warning: Do not mix syswrite with buffered I/O (print, say) on the same filehandle.

Synopsis

$n = syswrite($fh, $scalar);
$n = syswrite($fh, $scalar, $length);
$n = syswrite($fh, $scalar, $length, $offset);

See Also

sysread, sysseek, print

tell

Returns the current byte position in a filehandle.

Returns the current read/write position (in bytes) for the given filehandle, or for the most recently read filehandle when called without arguments. Returns -1 on error or when no filehandle is available.

The returned value is suitable as the POSITION argument to seek.

Synopsis

$pos = tell($fh);    # position in $fh
$pos = tell();       # position in last-read filehandle

See Also

seek, eof, sysseek

tie

Binds a variable to an object class, enabling magical access through method dispatch.

Associates a variable with a class by calling the class’s TIEHASH, TIEARRAY, TIESCALAR, or TIEHANDLE constructor. After tying, all accesses to the variable are redirected through FETCH/STORE/etc. methods on the tie object. Returns the tie object on success.

Implementation status: Stub. Returns undef (simulating a graceful failure) because full tie support requires deep integration with the value layer to intercept variable access.

Synopsis

tie my %hash, 'DB_File', 'filename';
tie my @array, 'Tie::File', 'data.txt';
tie my $scalar, 'Tie::StdScalar';
my $obj = tie %hash, 'MyTieClass', @args;

See Also

tied, untie

tied

Returns the underlying object of a tied variable.

Returns the object that was associated with the variable by a previous tie call. Returns undef if the variable is not tied. Commonly used to access the tie object’s methods directly.

Implementation status: Stub. Always returns undef because tie is not yet implemented.

Synopsis

my $obj = tied %hash;
if (tied $scalar) { ... }   # check if variable is tied

See Also

tie, untie

time

Returns the number of seconds since the Unix epoch.

Returns the current time as a non-negative integer representing whole seconds elapsed since 1970-01-01 00:00:00 UTC (the Unix epoch).

If Time::HiRes::time has been imported into the current package (overriding the builtin), this op dispatches to the high-resolution version which returns a floating-point value with microsecond precision. The CORE::time form (SPECIAL flag set) always uses the integer builtin, bypassing any override.

Synopsis

my $now = time();             # e.g. 1704067200
my $core = CORE::time;        # always integer, bypasses overrides
# with: use Time::HiRes qw(time);
my $hires = time();           # e.g. 1704067200.123456

See Also

localtime, gmtime, Time::HiRes

tr

Performs character-by-character transliteration on a string.

Transliterates characters in the target string according to a precompiled translation table. Each character found in the search list is replaced by the corresponding character in the replacement list.

The target string is obtained from the targ pad slot, the stack, or $_. For tr/// (OP_TRANS), the string is modified in place and the count of translated characters is pushed. For tr///r (OP_TRANSR), a new modified copy is pushed instead.

Modifiers (encoded in op_private):

• /c (0x20): Complement the search list
• /d (0x80): Delete found but unreplaced characters
• /s (0x08): Squash duplicate replaced characters

Synopsis

$str =~ tr/searchlist/replacementlist/;
$str =~ y/a-z/A-Z/;          # y is a synonym
my $count = ($s =~ tr/a//);   # count occurrences
my $new   = $s =~ tr/a-z/A-Z/r;  # /r returns copy

See Also

s///, m//, perlop

truncate

Truncates a file to a specified length.

Truncates the file identified by the first argument to at most LENGTH bytes. The first argument may be either an open filehandle or a filename string. When given a filename, the file is opened for writing just long enough to perform the truncation.

Returns 1 on success, undef on failure (e.g. permissions, invalid filehandle).

Synopsis

truncate($fh, $length);          # by open filehandle
truncate('/path/to/file', $len);  # by filename

See Also

open, seek, tell

uc

Converts a string to uppercase.

Returns an uppercased copy of STRING. For ASCII input, an in-place byte mutation fast path avoids allocation when a TARG pad slot is available. For Unicode input, Rust’s to_uppercase() is used, which handles case mappings that change byte length (e.g. the German sharp-s \u{00DF} becomes "SS").

Synopsis

$upper = uc($string);
$upper = uc('hello');   # "HELLO"

See Also

lc, ucfirst, lcfirst

ucfirst

Uppercases the first character of a string.

Returns a copy of STRING with the first character converted to uppercase and all other characters left unchanged. For ASCII first characters, a single-byte in-place mutation is used. For Unicode first characters, to_uppercase() may produce multiple characters (e.g. the ffi ligature U+FB03).

Returns an empty string when given an empty string.

Synopsis

$result = ucfirst($string);
$result = ucfirst('hello');   # "Hello"

See Also

lcfirst, uc, lc

umask

Gets or sets the process file-creation permission mask.

With an argument, sets the umask to the given value and returns the previous mask. Without an argument (or with undef), queries the current mask by temporarily setting it to 0 and restoring it, then returns the value.

The umask affects the default permissions of newly created files and directories. The actual permissions are requested & ~umask.

Returns the previous umask as an integer (typically displayed in octal).

Synopsis

my $old_mask = umask(0022);  # Set new mask, return old
my $current  = umask();      # Query current mask

See Also

chmod, mkdir, open

undef

Produces the undefined value, or undefines an existing variable.

Operates in three modes determined by op flags:

• MOD (lvalue placeholder): Used in list assignment patterns like my (undef, $x) = @list. Adds a sentinel to lvalue_targets so pp_aassign skips that position.
• STACKED (function call undef $x): Pops the target from the stack and undefines it. For arrays and hashes this clears the container; for hash/array element targets it sets the element to undef; for scalars it writes undef through the alias.
• Default: If targ is set, sets the corresponding pad slot to undef. Always pushes undef onto the stack as the return value.

Synopsis

my $x = undef;
undef $x;                    # set $x to undef
undef @array;                # clear the array
undef %hash;                 # clear the hash
my (undef, @rest) = @list;   # skip first element in list assignment

See Also

defined

unlink

Deletes one or more files from the filesystem.

Deletes a list of files. If called with no arguments (empty list after pushmark, or no mark at all), defaults to $_. Returns the number of files successfully deleted. Does not delete directories (use rmdir for that). Uses std::fs::remove_file.

Synopsis

unlink $file;
my $count = unlink @files;
unlink or die "Cannot unlink $_: $!";   # uses $_
unlink glob("*.bak");

See Also

rename, link, rmdir

unpack

Extracts values from a binary string according to a template.

The inverse of pack: takes a TEMPLATE and a binary STRING (or $_ if omitted) and returns a list of values extracted according to the template format characters. The template syntax is the same as for pack, including group syntax (...)N, repeat counts, and *.

String data is decoded using Latin-1 encoding (each byte maps 1:1 to a char code point), which correctly round-trips with pack’s output. The U format uses character offsets instead of byte offsets.

Synopsis

my @vals = unpack("A10", $data);
my ($long, $short, $str) = unpack("NnA*", $packet);
my @chars = unpack("C*", $bytes);
my @vals = unpack("A5", $_);   # $_ when string omitted

See Also

pack, vec, ord

unshift

Prepends one or more values to the beginning of an array.

Prepends the listed values to the front of the array, preserving argument order: unshift(@a, 1, 2, 3) yields (1, 2, 3, @original). Array arguments are flattened. Returns the new number of elements. Internally, values are inserted in reverse order to achieve the correct final ordering.

Synopsis

unshift @array, $value;
unshift @array, $v1, $v2, $v3;
unshift @array, @more_values;
my $new_len = unshift @array, $value;

See Also

shift, push, pop, splice

untie

Removes the tie binding from a variable, restoring normal access.

Breaks the association between a variable and its tie class established by tie. Subsequent accesses to the variable bypass the FETCH/STORE methods and operate on the variable directly. Returns true on success.

Implementation status: Stub. Always returns 1 (success) since tie is not yet implemented.

Synopsis

untie %hash;
untie @array;
untie $scalar;

See Also

tie, tied

utime

Sets the access and modification timestamps of one or more files.

Takes an access time, a modification time (both as Unix epoch seconds, or undef for “now”), followed by a list of file paths. Each file’s timestamps are updated via the POSIX utimes(2) call. When Time::HiRes::utime is available, nanosecond precision is used via utimensat(2).

Passing undef for either timestamp sets it to the current time.

Returns the number of files successfully modified.

Synopsis

utime $atime, $mtime, @files;
utime undef, undef, @files;    # set to current time

See Also

stat, lstat

values

Returns all values of a hash, or the number of values in scalar context.

In list context, pushes all values of the hash onto the stack. In scalar context, returns the number of key-value pairs (same as keys in scalar context). Accepts both %hash and $hashref. Resets the hash’s internal iterator as a side effect.

When the REF flag is set (foreach aliasing context from the native parser), values are pushed onto the stack and the hash plus its keys are recorded for write-back of $_ modifications during iteration.

Synopsis

my @v = values %hash;
my $count = values %hash;       # scalar context: number of values
for my $val (values %hash) { ... }

See Also

keys, each, exists, delete

vec

Treats a string as a bit vector and accesses individual bitfields.

Treats EXPR as a bit vector made up of elements of width BITS and returns the unsigned integer value of the element at OFFSET. BITS must be a power of 2 from 1 to 32.

As an lvalue, vec stores values into the specified bitfield, growing the string as needed.

my $flags = "";
vec($flags, 0, 8) = 255;     # Set byte 0 to 255
vec($flags, 1, 8) = 10;      # Set byte 1 to 10
my $val = vec($flags, 0, 8); # Get byte 0 (255)
my $bit = vec($flags, 5, 1); # Get bit 5 of byte 0

Synopsis

my $val = vec($string, $offset, $bits);
vec($string, $offset, $bits) = $value;

See Also

pack, unpack

wait

Waits for any child process to terminate.

Suspends the current process until any child process terminates. Returns the PID of the deceased child, or -1 if there are no child processes. Sets $? to the wait status of the child (encoding exit code and signal information).

Synopsis

my $pid = wait();
print "Child $pid exited with status $?\n";

See Also

waitpid, fork, $?

waitpid

Waits for a specific child process to change state.

Suspends the current process until the child identified by $pid terminates (or changes state, depending on flags). Sets $? to the wait status.

Returns:

• The PID of the terminated child on success
• 0 if WNOHANG was specified and no child has exited yet
• -1 on error (e.g. no such child)

When $pid is -1, waits for any child (equivalent to wait()).

Synopsis

my $result = waitpid($pid, 0);        # blocking wait
my $result = waitpid($pid, WNOHANG);  # non-blocking
my $result = waitpid(-1, 0);           # any child (like wait)

See Also

wait, fork, POSIX

warn

Issues a warning message to STDERR without terminating the program.

Prints the argument to STDERR. If the string does not end with a newline, Perl appends at FILE line LINE.

If $SIG{__WARN__} is set to a code reference, that handler is called with the warning message as its sole argument instead of printing to STDERR. The handler runs in void context and its return value is discarded.

Synopsis

warn "something looks wrong";
warn "problem at $file line $line\n";
warn $object;

See Also

die, Carp

x

Repeats a string a given number of times.

Pops the repeat count (right operand) and the string (left operand) from the stack. Returns a new string consisting of the left operand concatenated with itself COUNT times. A count of zero or less produces an empty string. Inf and NaN counts are treated as zero (matching perl5).

Synopsis

$line = '-' x 80;          # 80 dashes
$pad  = ' ' x $width;
$s    = 'ab' x 3;          # "ababab"

See Also

x, perlop

Native Modules

pperl PP runtime native (Rust) reimplementations of CPAN/core XS modules. These provide identical Perl-level APIs without requiring XS compilation.

• B — Native implementation of the B module (Perl compiler backend) (134 functions)
• Config — pp runtime adapter for Config.
• Cwd — Provides current working directory operations. (8 functions)
• Data::Dumper — Provides data structure serialization to Perl syntax. (2 functions)
• Digest::MD5 — Provides MD5 hashing functionality compatible with the Digest::MD5 Perl module. (14 functions)
• Digest::SHA — Provides SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and (54 functions)
• Encode — Provides character encoding/decoding functions compatible with Perl’s (9 functions)
• Errno — Provides system errno constants for Linux (6 functions)
• Fcntl — Provides file control constants and file-type test functions matching (55 functions)
• File::Basename — Provides path parsing functions: basename, dirname, fileparse. (4 functions)
• File::Copy — Provides file copy and move operations. (4 functions)
• File::Find — Provides recursive directory traversal: find() and finddepth(). (2 functions)
• File::Glob — Provides BSD glob pattern matching via libc’s glob(). (3 functions)
• File::Path — Provides directory tree creation and removal operations. (4 functions)
• File::Spec — Provides portable file path operations using Unix semantics. (18 functions)
• File::Temp — Provides tempfile() and tempdir() with automatic cleanup on process exit. (15 functions)
• File::stat — Provides by-name interface to Perl’s stat() builtin. (3 functions)
• FileHandle — FileHandle is a compatibility module that wraps IO::File and IO::Handle.
• Hash::Util — Provides hash introspection and manipulation utilities. (38 functions)
• I18N::Langinfo — Provides locale information querying via nl_langinfo(). (56 functions)
• IO::Dir — Provides object-oriented directory operations compatible with Perl’s IO::Dir. (9 functions)
• IO::File — Provides object-oriented file operations compatible with Perl’s IO::File. (13 functions)
• IO::Handle — Provides object-oriented filehandle methods compatible with Perl’s IO::Handle. (47 functions)
• IO::Pipe — Provides object-oriented pipe operations compatible with Perl’s IO::Pipe. (4 functions)
• IO::Seekable — Provides seek/tell operations on filehandles compatible with Perl’s IO::Seekable. (4 functions)
• IO::Select — Provides multiplexed I/O via the POSIX select() system call, compatible (11 functions)
• IO::Socket — Provides object-oriented socket operations compatible with Perl’s IO::Socket. (21 functions)
• Internals — Provides internal Perl functions that manipulate SV flags. (3 functions)
• List::Util — Provides list utility functions (first, sum, min, max, reduce, etc.) (35 functions)
• MIME::Base64 — Provides base64 encoding and decoding functions compatible with Perl’s (6 functions)
• MIME::QuotedPrint — Provides quoted-printable encoding and decoding functions compatible with (2 functions)
• Math::GMP — Math::GMP — High-speed arbitrary precision integers (1 functions)
• POSIX — Native implementation of Perl’s POSIX module (214 functions)
• PadWalker — PadWalker provides introspective access to lexical variables in Perl subroutine
• Peta::FFI — Peta::FFI — Dynamic FFI for calling C library functions from Perl (8 functions)
• Peta::FFI::GMP — Peta::FFI::GMP — Pre-baked libgmp bindings (Layer 1) (50 functions)
• Peta::FFI::Libc — Peta::FFI::Libc — Pre-baked libc bindings (Layer 1) (29 functions)
• Peta::FFI::UUID — Peta::FFI::UUID — Pre-baked libuuid bindings (Layer 1) (6 functions)
• Scalar::Util — Provides scalar utility functions (blessed, reftype, etc.) (14 functions)
• Socket — Native implementation of Perl’s Socket module (15 functions)
• Storable — Provides serialization/deserialization functions for Perl data structures. (19 functions)
• Sub::Util — Provides subroutine utility functions for introspection and manipulation. (4 functions)
• Sys::Hostname — Provides hostname retrieval functionality. (1 functions)
• Time::HiRes — pp runtime adapter for Time::HiRes.
• mro — MRO (Method Resolution Order) implementation (9 functions)
• sdl2 — Native SDL2 module — dlopen-based SDL2 bindings with direct SDL2-style API. (33 functions)
• version — Native implementation of the version module (17 functions)

B

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

Native implementation of the B module (Perl compiler backend)

Provides introspection into Perl’s internal representation of code. Supports svref_2object for all SV types (IV, NV, PV, CV, GV, AV, HV, NULL), class(), ppname(), opnumber(), special SVs, utility functions, and basic op tree introspection via B::CV::ROOT/START.

Functions

AV

CUR

CV

CvFLAGS

DEPTH

EGV

FILE

FLAGS

GV

GvREFCNT

HV

IV

IVX

LEN

LINE

NAME

NAME_HEK

NV

NVX

OUTSIDE

PADLIST

PV

PVX

REFCNT

ROOT

SAFENAME

START

STASH

SV

SvTYPE

UVX

amagic_generation

Returns the current overload magic generation counter (always 0 in pperl).

use B qw(amagic_generation);
my $gen = amagic_generation();

See also: sv_undef

can

cast_I32

cast_i32

Casts a value to a signed 32-bit integer, truncating as needed.

use B qw(cast_I32);
my $i = cast_I32(0xFFFFFFFF);  # -1

See also: hash

children

class

Returns the B:: class name of a B object (e.g. “CV”, “GV”, “SV”).

use B qw(class);
my $type = class($b_obj);

See also: svref_2object

cop_file

Returns the filename recorded in this COP (control op).

use B qw(main_root);
# walk to a COP node, then:
my $file = $cop->file;

See also: B::COP::line, B::COP::stash

cop_label

Returns the label associated with this COP (e.g. loop labels like “LOOP:”).

use B qw(main_root);
my $label = $cop->label;

See also: B::COP::file, B::COP::line

cop_line

Returns the line number recorded in this COP.

use B qw(main_root);
my $line = $cop->line;

See also: B::COP::file, B::COP::stash

cop_stash

Returns the stash (package) active at this COP as a B::HV object.

use B qw(main_root);
my $stash = $cop->stash;

See also: B::COP::stashpv, B::COP::file

cop_stashpv

Returns the stash name as a plain string (e.g. “main”).

use B qw(main_root);
my $pkg = $cop->stashpv;

See also: B::COP::stash, B::COP::file

cstring

Returns the C-escaped double-quoted representation of a string.

use B qw(cstring);
my $c = cstring("hello\nworld");  # "hello\\nworld"

See also: perlstring

cv_cvflags

Returns the CV flags bitmask (always 0 in pperl).

use B qw(svref_2object);
my $flags = svref_2object(\&foo)->CvFLAGS;

See also: B::CV::DEPTH, B::SV::FLAGS

cv_depth

Returns the recursion depth of this CV (always 0 in pperl).

use B qw(svref_2object);
my $depth = svref_2object(\&foo)->DEPTH;

See also: B::CV::CvFLAGS

cv_file

Returns the filename where this CV was defined.

use B qw(svref_2object);
my $file = svref_2object(\&foo)->FILE;

See also: B::CV::GV, B::CV::START

cv_gv

Returns the GV (glob value) associated with this CV as a B::GV object.

use B qw(svref_2object);
my $gv = svref_2object(\&foo)->GV;

See also: B::GV::NAME, B::CV::FILE

cv_name_hek

Returns the name of the CV from its HEK (hash entry key), or undef for anonymous/global subs.

use B qw(svref_2object);
my $name = svref_2object(\&foo)->NAME_HEK;

See also: B::CV::GV, B::GV::NAME

cv_outside

Returns the lexically enclosing CV as a B::CV object.

use B qw(svref_2object);
my $outer = svref_2object(\&foo)->OUTSIDE;

See also: B::CV::ROOT, B::CV::PADLIST

cv_padlist

Returns the padlist for this CV (currently undef in pperl).

use B qw(svref_2object);
my $padlist = svref_2object(\&foo)->PADLIST;

See also: B::CV::OUTSIDE, B::CV::DEPTH

cv_root

Returns the root op of this CV’s op tree as a B::OP object.

use B qw(svref_2object);
my $root = svref_2object(\&foo)->ROOT;

See also: B::CV::START, B::CV::GV

cv_start

Returns the first op in execution order for this CV as a B::OP object.

use B qw(svref_2object);
my $start = svref_2object(\&foo)->START;

See also: B::CV::ROOT, B::CV::GV

cv_stash

Returns the stash (package hash) associated with this CV as a B::HV object.

use B qw(svref_2object);
my $stash = svref_2object(\&foo)->STASH;

See also: B::CV::GV, B::HV::NAME

desc

file

first

flags

generic_isa

Checks whether a B object is a member of the given class via the @ISA chain.

use B qw(svref_2object);
if (svref_2object(\&foo)->isa("B::CV")) { ... }

See also: class, svref_2object

gv_av

Returns the array slot of this GV as a B::AV object.

use B qw(svref_2object);
my $av = svref_2object(\*foo)->AV;

See also: B::GV::SV, B::GV::HV, B::GV::CV

gv_cv

Returns the code slot of this GV as a B::CV object.

use B qw(svref_2object);
my $cv = svref_2object(\*foo)->CV;

See also: B::GV::SV, B::GV::AV, B::GV::HV

gv_egv

Returns the effective GV (usually the same as the GV itself).

use B qw(svref_2object);
my $egv = svref_2object(\*foo)->EGV;

See also: B::GV::NAME, B::GV::STASH

gv_file

Returns the filename where this GV was first defined.

use B qw(svref_2object);
my $file = svref_2object(\*foo)->FILE;

See also: B::GV::LINE, B::GV::NAME

gv_hv

Returns the hash slot of this GV as a B::HV object.

use B qw(svref_2object);
my $hv = svref_2object(\*foo)->HV;

See also: B::GV::SV, B::GV::AV, B::GV::CV

gv_is_empty

Returns whether this GV is empty (has no assigned slots).

use B qw(svref_2object);
my $empty = svref_2object(\*foo)->is_empty;

See also: B::GV::isGV_with_GP, B::GV::NAME

gv_isgv_with_gp

Returns true if this GV has a GP (glob pointer) structure (always 1 in pperl).

use B qw(svref_2object);
my $has_gp = svref_2object(\*foo)->isGV_with_GP;

See also: B::GV::NAME, B::GV::is_empty

gv_line

Returns the line number where this GV was first defined (always 0 in pperl).

use B qw(svref_2object);
my $line = svref_2object(\*foo)->LINE;

See also: B::GV::FILE, B::GV::NAME

gv_name

Returns the name of this GV (glob value), e.g. “foo” for *main::foo.

use B qw(svref_2object);
my $name = svref_2object(\*foo)->NAME;

See also: B::GV::SAFENAME, B::GV::STASH

gv_refcnt

Returns the GV-specific reference count (always 1 in pperl).

use B qw(svref_2object);
my $rc = svref_2object(\*foo)->GvREFCNT;

See also: B::SV::REFCNT, B::GV::NAME

gv_safename

Returns the name of this GV with control characters converted to ^X notation.

use B qw(svref_2object);
my $safe = svref_2object(\*foo)->SAFENAME;

See also: B::GV::NAME, safename

gv_stash

Returns the stash (package) this GV belongs to as a B::HV object.

use B qw(svref_2object);
my $stash = svref_2object(\*foo)->STASH;

See also: B::GV::NAME, B::HV::NAME

gv_sv

Returns the scalar slot of this GV as a B::SV object.

use B qw(svref_2object);
my $sv = svref_2object(\*foo)->SV;

See also: B::GV::AV, B::GV::HV, B::GV::CV

hash

Returns the hash value of a string as a hex string (e.g. “0x1a2b3c”).

use B qw(hash);
my $h = hash("foo");

See also: cstring, perlstring

hv_name

Returns the name of this HV (stash name), e.g. “main” for %main::.

use B qw(svref_2object);
my $name = svref_2object(\%Foo::)->NAME;

See also: B::GV::STASH, B::CV::STASH

import

Handles use B qw(...) by exporting requested functions into the caller’s namespace.

use B qw(svref_2object class ppname);

See also: svref_2object, class, ppname

int_value

isGV_with_GP

is_empty

isa

iv_iv

Returns the integer value stored in this B::IV object.

use B qw(svref_2object);
my $val = svref_2object(\$n)->IV;

See also: B::IV::UVX, B::NV::NV

iv_uvx

Returns the unsigned integer interpretation of this B::IV object’s value.

use B qw(svref_2object);
my $uval = svref_2object(\$n)->UVX;

See also: B::IV::IV, B::NV::NV

label

last

line

main_cv

Returns the main program’s CV (code value) as a B::CV object.

use B qw(main_cv);
my $cv = main_cv();

See also: main_root, main_start

main_root

Returns the root op of the main program as a B::OP object.

use B qw(main_root);
my $root = main_root();

See also: main_start, main_cv

main_start

Returns the starting op of the main program as a B::OP object.

use B qw(main_start);
my $start = main_start();

See also: main_root, main_cv

moresib

name

next

nv_nv

Returns the floating-point value stored in this B::NV object.

use B qw(svref_2object);
my $val = svref_2object(\$f)->NV;

See also: B::IV::IV, B::PV::PV

object_2svref

op_can

Returns true if the B::OP object supports the named method.

use B qw(main_root);
if (main_root()->can("first")) { ... }

See also: B::OP::isa, B::OP::name

op_children

Returns the number of child ops by walking the first->sibling chain.

use B qw(main_root);
my $count = main_root()->children;

See also: B::OP::first, B::OP::last, B::OP::sibling

op_desc

Returns a human-readable description of this op.

use B qw(main_root);
my $desc = main_root()->desc;

See also: B::OP::name, B::OP::type

op_first

Returns the first child op of a UNOP/BINOP/LISTOP as a B::OP object.

use B qw(main_root);
my $first = main_root()->first;

See also: B::OP::last, B::OP::sibling

op_flags

Returns the op_flags bitmask for this op (OPf_WANT, OPf_KIDS, etc.).

use B qw(main_root);
my $flags = main_root()->flags;

See also: B::OP::private, B::OP::targ

op_last

Returns the last child op of a BINOP/LISTOP as a B::OP object.

use B qw(main_root);
my $last = main_root()->last;

See also: B::OP::first, B::OP::children

op_moresib

Returns true (1) if this op has more siblings, false (0) otherwise.

use B qw(main_root);
my $has_sib = main_root()->first->moresib;

See also: B::OP::sibling, B::OP::children

op_name

Returns the name of this op (e.g. “add”, “const”, “null”).

use B qw(main_root);
my $name = main_root()->name;

See also: B::OP::type, B::OP::desc

op_next

Returns the next op in execution order as a B::OP object.

use B qw(main_start);
my $next = main_start()->next;

See also: B::OP::sibling, B::OP::first

op_opt

Returns whether this op has been optimized (always 0 in pperl).

use B qw(main_root);
my $optimized = main_root()->opt;

See also: B::OP::flags, B::OP::name

op_parent

Returns the parent op in the op tree (always B::NULL in pperl, parent tracking not implemented).

use B qw(main_root);
my $parent = main_root()->first->parent;

See also: B::OP::first, B::OP::sibling

op_ppaddr

Returns the pp function address as a string like “PL_ppaddr[OP_ADD]”.

use B qw(main_root);
my $addr = main_root()->ppaddr;

See also: B::OP::name, ppname

op_private

Returns the op_private flags byte for this op.

use B qw(main_root);
my $priv = main_root()->private;

See also: B::OP::flags, B::OP::targ

op_sibling

Returns the next sibling op in the op tree as a B::OP object.

use B qw(main_root);
my $sib = main_root()->first->sibling;

See also: B::OP::next, B::OP::moresib

op_targ

Returns the op_targ pad offset for this op.

use B qw(main_root);
my $targ = main_root()->targ;

See also: B::OP::flags, B::OP::private

op_type

Returns the numeric op type for this op.

use B qw(main_root);
my $type = main_root()->type;

See also: B::OP::name, B::OP::desc

opnumber

Returns the op number for a given op name (e.g. “add” returns 42).

use B qw(opnumber);
my $num = opnumber("add");

See also: ppname

opt

parent

parents

Returns the parent ops collected during the last walkoptree traversal (currently always empty).

use B qw(parents);
my @parents = parents();

See also: walkoptree, walkoptree_debug

perlstring

Returns the Perl-escaped double-quoted representation of a string, escaping $, @, and using \x{} notation.

use B qw(perlstring);
my $p = perlstring('$foo');  # "\\$foo"

See also: cstring

ppaddr

ppname

Returns the PP function name for a given op number (e.g. “pp_add”).

use B qw(ppname);
my $name = ppname(42);

See also: opnumber

private

pv_cur

Returns the current length (SvCUR) of the string in this B::PV object.

use B qw(svref_2object);
my $len = svref_2object(\$s)->CUR;

See also: B::PV::PV, B::PV::LEN

pv_len

Returns the allocated buffer length (SvLEN) of this B::PV object.

use B qw(svref_2object);
my $alloc = svref_2object(\$s)->LEN;

See also: B::PV::PV, B::PV::CUR

pv_pv

Returns the string value stored in this B::PV object.

use B qw(svref_2object);
my $str = svref_2object(\$s)->PV;

See also: B::PV::CUR, B::PV::LEN

safename

Converts control characters in a name to ^X notation for safe display.

use B qw(safename);
my $safe = safename("\x01foo");  # "^Afoo"

See also: cstring, perlstring

sibling

stash

stashpv

sv_flags

Returns the SV flags bitmask (IOK, NOK, POK, etc.).

use B qw(svref_2object);
my $flags = svref_2object(\$x)->FLAGS;

See also: B::SV::REFCNT, B::SV::SvTYPE

sv_no

Returns a B::SPECIAL object representing PL_sv_no.

use B qw(sv_no);
my $no = sv_no();

See also: sv_undef, sv_yes

sv_object_2svref

Converts a B object back to a reference to the original Perl value.

use B qw(svref_2object);
my $ref = svref_2object(\$x)->object_2svref;

See also: svref_2object

sv_refcnt

Returns the reference count of this SV.

use B qw(svref_2object);
my $rc = svref_2object(\$x)->REFCNT;

See also: B::SV::FLAGS, B::SV::SvTYPE

sv_svtype

Returns the SV type number (SVt_NULL=0, SVt_IV=1, SVt_NV=2, SVt_PV=4, etc.).

use B qw(svref_2object);
my $type = svref_2object(\$x)->SvTYPE;

See also: B::SV::FLAGS, B::SV::REFCNT

sv_undef

Returns a B::SPECIAL object representing PL_sv_undef.

use B qw(sv_undef);
my $undef = sv_undef();

See also: sv_yes, sv_no

sv_yes

Returns a B::SPECIAL object representing PL_sv_yes.

use B qw(sv_yes);
my $yes = sv_yes();

See also: sv_undef, sv_no

svref_2object

Converts a Perl reference to its corresponding B:: object representation.

use B qw(svref_2object);
my $b_obj = svref_2object(\$scalar);

See also: class, sv_undef, sv_yes, sv_no

targ

type

walkoptree

Walks the op tree starting from $op, calling $op->$method() on each node in tree order.

use B qw(walkoptree main_root);
walkoptree(main_root(), "print_name");

See also: walkoptree_debug, parents, main_root

walkoptree_debug

Gets or sets the debug flag for walkoptree output.

use B qw(walkoptree_debug);
walkoptree_debug(1);
my $dbg = walkoptree_debug();

See also: walkoptree

Config

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

pp runtime adapter for Config.

Thin wrapper: delegates config data and formatting to core.rs, handles only pp-runtime value type conversions (Sv, Hv, Av, Cv).

Cwd

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

Provides current working directory operations.

Synopsis

use Cwd;
my $dir = cwd();

use Cwd 'abs_path';
my $abs = abs_path('relative/path');
my $abs = abs_path('/symlinked/../path');

Perl Equivalent

Cwd

Functions

abs_path

Returns the canonicalized absolute pathname of the argument. Resolves symlinks. Returns undef if the path cannot be resolved. If no argument is given, resolves the current directory.

use Cwd 'abs_path';
my $abs = abs_path('relative/path');
my $abs = abs_path();   # current directory

chdir

Changes the working directory and updates $ENV{PWD}. Unlike CORE::chdir, does NOT default to $ENV{HOME} when called without arguments. Returns 1 on success, 0 on failure.

use Cwd 'chdir';
chdir('/tmp') or die "Cannot chdir: $!";

cwd

Returns the current working directory as a string. All four names are synonyms in PetaPerl (no distinction between XS and pure-Perl implementations).

use Cwd;
my $dir = cwd();

fast_abs_path

Returns the canonicalized absolute pathname of the argument. Resolves symlinks. Returns undef if the path cannot be resolved. If no argument is given, resolves the current directory.

use Cwd 'abs_path';
my $abs = abs_path('relative/path');
my $abs = abs_path();   # current directory

fastcwd

Returns the current working directory as a string. All four names are synonyms in PetaPerl (no distinction between XS and pure-Perl implementations).

use Cwd;
my $dir = cwd();

fastgetcwd

Returns the current working directory as a string. All four names are synonyms in PetaPerl (no distinction between XS and pure-Perl implementations).

use Cwd;
my $dir = cwd();

getcwd

Returns the current working directory as a string. All four names are synonyms in PetaPerl (no distinction between XS and pure-Perl implementations).

use Cwd;
my $dir = cwd();

realpath

Returns the canonicalized absolute pathname of the argument. Resolves symlinks. Returns undef if the path cannot be resolved. If no argument is given, resolves the current directory.

use Cwd 'abs_path';
my $abs = abs_path('relative/path');
my $abs = abs_path();   # current directory

Data::Dumper

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

Provides data structure serialization to Perl syntax.

Perl Equivalent

Data::Dumper

Synopsis

use Data::Dumper;

print Dumper(\%hash, \@array);

my $d = Data::Dumper->new([$ref], ['name']);
$d->Indent(1);
$d->Sortkeys(1);
print $d->Dump();

Functions

Dumper

Dumps one or more references to Perl syntax. Returns a string containing the serialized representation.

use Data::Dumper;
print Dumper($hashref, $arrayref);

### DumperX

Digest::MD5

Native Rust implementation built into the interpreter. Runtime: PP. See original documentation for the full Perl reference.

Provides MD5 hashing functionality compatible with the Digest::MD5 Perl module.

Synopsis

use Digest::MD5 qw(md5_hex md5_base64);

my $hex    = md5_hex("some data");
my $base64 = md5_base64("some data");

# OO interface for incremental hashing
my $ctx = Digest::MD5->new;
$ctx->add("first chunk");
$ctx->add("second chunk");
my $digest = $ctx->hexdigest;

Functional Interface

• md5($data) - Returns binary MD5 digest (16 bytes)
• md5_hex($data) - Returns hexadecimal MD5 digest (32 characters)
• md5_base64($data) - Returns base64-encoded MD5 digest (22 characters, no padding)

Object-Oriented Interface

• Digest::MD5->new() - Creates a new MD5 context object
• $ctx->add($data, ...) - Adds data to the context
• $ctx->addfile($fh) - Adds data from a filehandle (not yet implemented)
• $ctx->digest() - Returns binary digest and resets the context
• $ctx->hexdigest() - Returns hex digest and resets the context
• $ctx->b64digest() - Returns base64 digest (no padding) and resets the context
• $ctx->reset() - Resets the context
• $ctx->clone() - Clones the context

Implementation Notes

The OO interface stores accumulated data in a blessed hash reference. The hash uses a special key _data to store the accumulated bytes. Computing the actual MD5 hash is done when digest(), hexdigest(), or b64digest() is called.

This approach avoids the complexity of storing Rust state (Md5 hasher) in Perl values while maintaining compatibility with the Perl interface.

Functions

Digest

add

Appends data to the MD5 context for incremental digesting. Returns the context for method chaining.

See also: addfile, digest, hexdigest

add_bits

Adds bits to the MD5 context. The argument is a string of ‘0’ and ‘1’ characters whose length must be a multiple of 8.

See also: add, addfile

addfile

Reads all data from the given filehandle and adds it to the MD5 context. Returns the context for method chaining.

See also: add, digest

b64digest

Returns the base64-encoded MD5 digest (22 characters, no padding) of the accumulated data and resets the context.

See also: digest, hexdigest

clone

Creates and returns a copy of the MD5 context, preserving accumulated data and blessed class.

See also: new, reset

context

Gets or sets the internal MD5 computation state. In get mode returns ($block_count, $state_buffer[, $unprocessed]). In set mode restores state from arguments.

See also: digest, reset, clone

digest

Returns the binary MD5 digest (16 bytes) of the accumulated data and resets the context.

See also: hexdigest, b64digest

hexdigest