# 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.

```perl
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).

```perl
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.

```perl
print "Running: $0\n";
```

#### `$$` - Process ID

The process ID of the Perl process running this script.

```perl
print "PID: $$\n";
```

#### `$?` - Child Error Status

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

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

#### `$@` - Eval Error

The error message from the last `eval` that failed.

```perl
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.

```perl
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.

```perl
{
    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).

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

#### `$,` - Output Field Separator

Printed between arguments to `print`. Default is `undef`.

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

#### `$"` - List Separator

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

```perl
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.

```perl
$| = 1;    # enable autoflush on STDOUT
```

#### `$.` - Current Line Number

The current line number of the last filehandle read.

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

#### `$;` - Subscript Separator

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

```perl
$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.

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

#### `$^W` - Warning Flag

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

```perl
$^W = 1;    # enable warnings
```

### Regular Expression Variables

#### `$&` - Match String

The string matched by the last successful pattern match.

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

#### `` $` `` - Prematch String

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

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

#### `$'` - Postmatch String

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

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

#### `$1`, `$2`, ... - Capture Groups

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

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

#### `%+` - Named Captures

Hash containing the text matched by named capture groups.

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

### Process Variables

#### `$<` - Real UID

The real user ID of this process.

```perl
print "Real UID: $<\n";
```

#### `$>` - Effective UID

The effective user ID of this process.

```perl
print "Effective UID: $>\n";
```

#### `$(` - Real GID

The real group ID of this process.

```perl
print "Real GID: $(\n";
```

#### `$)` - Effective GID

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

```perl
print "Effective GID: $)\n";
```

### System Variables

#### `%ENV` - Environment Variables

Hash containing the current environment variables.

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

#### `@ARGV` - Command Line Arguments

Contains the command-line arguments passed to the script.

```perl
# 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.

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

#### `%SIG` - Signal Handlers

Hash used to set signal handlers.

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

### Version Variables

#### `$]` - Perl Version (Numeric)

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

```perl
print $];    # e.g., 5.042000
```

#### `$^V` - Perl Version (String)

The version of Perl as a version string.

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

#### `$^O` - Operating System

The name of the operating system.

```perl
print $^O;   # "linux" for PetaPerl
```

#### `$^X` - Perl Executable Path

The path to the Perl (or PetaPerl) executable.

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

### PetaPerl-Specific Variables

*Reserved for future PetaPerl-specific extensions.*

## SEE ALSO

- [perlfunc](./perlfunc.md) - Built-in functions
- [perlop](./perlop.md) - Operators
- [perlre](./perlre.md) - Regular expressions