Perl Nuts &
Bolts

#!/usr/bin/perl
use strict;
use warnings;

# $ sigil — ONE value (a scalar)
my $name   = "Alice";    # holds a string
my $age    = 30;          # holds a number
my $pi     = 3.14159;     # holds a float
my $empty;                # holds undef (no value)

# @ sigil — an ORDERED LIST (array)
my @colors  = ("red", "green", "blue");
my @numbers = (1, 2, 3, 4, 5);
my @empty_list = ();     # empty array

# % sigil — KEY-VALUE PAIRS (hash / dictionary)
my %person  = (
    name  => "Bob",         # => is the "fat comma" — same as ","
    age   => 25,
    city  => "London",
);

# Accessing values — sigil changes based on WHAT you get back
print $name;              # scalar — stays $
print $colors[0];         # ONE element from array — $ (not @)
print $person{name};      # ONE value from hash  — $ (not %)

my $name = "Alice";
my $age  = 30;

# Double quotes: variables ARE expanded, \n IS a newline
print "Hello, $name! You are $age years old.\n";
# Output: Hello, Alice! You are 30 years old.

# Single quotes: everything is LITERAL — \ is just a backslash
print 'Hello, $name! \n';
# Output: Hello, $name! \n   (literally)

# String concatenation uses the . (dot) operator
my $greeting = "Hello" . ", " . $name;    # "Hello, Alice"

# String repetition uses the x operator
my $line  = "-" x 20;    # "--------------------"
my $stars = "*" x 5;    # "*****"

# Common string functions
my $s = "  Hello, World!  ";

length($s);             # 18  — number of characters
uc($s);                # "  HELLO, WORLD!  " — uppercase
lc($s);                # "  hello, world!  " — lowercase
ucfirst("hello");       # "Hello"
index($s, "World");    # 9   — position (0-based), -1 if not found
substr($s, 2, 5);      # "Hello" — start at 2, length 5

# Trim whitespace (no built-in — use a substitution)
$s =~ s/^\s+|\s+$//g;  # now "Hello, World!"

# Heredoc — multiline string (useful for templates)
my $block = <<END;
Line one
Line two: $name
Line three
END

# Numeric literals
my $int   = 42;
my $float = 3.14;
my $neg   = -7;
my $sci   = 1.5e6;       # 1,500,000
my $big   = 1_000_000;   # _ separators: ignored, for readability
my $hex   = 0xFF;         # 255  (0x prefix = hexadecimal)
my $oct   = 0755;         # 493  (0 prefix  = octal!)
my $bin   = 0b1010;      # 10   (0b prefix = binary)

# Arithmetic operators
my $sum  = 10 +  3;   # 13   addition
my $diff = 10 -  3;   # 7    subtraction
my $prod = 10 *  3;   # 30   multiplication
my $quot = 10 /  3;   # 3.33 division (float)
my $mod  = 10 %  3;   # 1    modulo (remainder)
my $pow  =  2 ** 8;   # 256  exponentiation (power)

# Increment / Decrement
$sum++;    # $sum += 1 — post-increment
$sum--;    # $sum -= 1 — post-decrement
$sum += 5; # compound assignment: $sum = $sum + 5

# NUMERIC comparison (returns true/false)
10 == 10;   # equal
10 !=  5;   # not equal
10 >   5;   # greater than
10 <  20;   # less than
10 >= 10;   # greater than or equal

# STRING comparison (uses alphabetical/ASCII order)
"abc" eq "abc";   # equal
"abc" ne "xyz";   # not equal
"abc" lt "xyz";   # less than (alphabetically)
"abc" gt "aaa";   # greater than

# Spaceship operators — return -1, 0, or 1 (for sorting)
5 <=> 3;          # 1  (numeric spaceship)
"b" cmp "a";       # 1  (string spaceship)

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

# Access by index — ALWAYS use $ because you get one thing back
print $fruits[0];      # "apple"  (first element)
print $fruits[-1];     # "cherry" (last element — negative indexes)
print $fruits[-2];     # "banana" (second-to-last)

# Length — use scalar() or $# (last index)
my $count      = scalar(@fruits);  # 3 — number of elements
my $last_index = $#fruits;         # 2 — last valid index (count - 1)

# push/pop — add/remove from the END
push @fruits, "date";      # ("apple","banana","cherry","date")
my $last = pop @fruits;   # removes and returns "date"

# shift/unshift — add/remove from the FRONT
unshift @fruits, "avocado";  # ("avocado","apple","banana","cherry")
my $first = shift @fruits;  # removes and returns "avocado"

# sort and reverse
my @sorted  = sort @fruits;            # alphabetical
my @nums    = sort { $a <=> $b } (5,2,8,1);  # numeric sort
my @rev     = reverse @sorted;

# grep — filter (like WHERE in SQL)
my @long = grep { length($_) > 5 } @fruits;

# map — transform (like SELECT in SQL)
my @upper = map { uc($_) } @fruits;

# join — turn array into a single string
my $csv    = join(",",  @fruits);  # "apple,banana,cherry"
my $spaced = join(" ", @fruits);  # "apple banana cherry"

# split — turn a string into an array
my @parts  = split(/,/, "a,b,c");  # ("a","b","c")
my @words  = split(/\s+/, "hello world foo");

# Array slices — multiple elements at once
my @two    = @fruits[0, 2];   # elements 0 and 2  — note @ not $
my @range  = @fruits[0..1];  # elements 0 to 1 (range operator)

my %person = (
    name  => "Carol",
    age   => 28,
    city  => "Paris",
);

# Read a value — use $ because you get ONE thing back
print $person{name};    # "Carol"
print $person{age};     # 28

# Add a new key or modify existing
$person{email} = "carol@example.com";
$person{age}   = 29;              # update

# Check if a key exists (don't just test the value!)
if (exists $person{email}) {
    print "email is set\n";
}

# Delete a key
delete $person{city};

# List all keys (order is RANDOM each run)
my @k = keys   %person;   # ("name","age","email") in some order
my @v = values %person;   # ("Carol",29,"carol@...") same order as keys

# Iterate with for — sort keys for consistent order
for my $key (sort keys %person) {
    print "$key: $person{$key}\n";
}

# Iterate with while/each (key-value at once)
while (my ($k, $v) = each %person) {
    print "$k = $v\n";
}

# Count entries
my $count = scalar(keys %person);  # 3

# Hash slice — get multiple values at once
my ($name, $age) = @person{qw(name age)};  # @ sigil for multiple

my @arr = ("a", "b", "c");

# SCALAR context — @arr evaluates to its COUNT
my $n    = @arr;           # $n = 3
my $n2   = scalar(@arr);  # explicit scalar context
if (@arr) { ... }          # boolean (true if array not empty)
print "count: " . @arr;   # . forces scalar: "count: 3"

# LIST context — @arr returns all elements
my ($first, $second) = @arr;  # $first="a", $second="b"
my @copy             = @arr;  # @copy = ("a","b","c")

# localtime in scalar context = formatted string
my $time_str = localtime;    # "Mon Jan  1 12:00:00 2024"

# localtime in list context = individual components
my ($sec, $min, $hour, $day, $mon, $year) = localtime;

# wantarray() — test which context YOUR sub was called in
sub flexible {
    if (wantarray) {
        return (1, 2, 3);   # list context: return list
    } else {
        return "summary";    # scalar context: return string
    }
}
my $s  = flexible();        # "summary"
my @l  = flexible();        # (1, 2, 3)

my $score = 75;

# Standard if / elsif / else
if    ($score >= 90) { print "A\n" }
elsif ($score >= 80) { print "B\n" }
elsif ($score >= 70) { print "C\n" }  # fires: score is 75
else                  { print "F\n" }

# unless = "if NOT" — reads naturally in English
unless ($score < 60) {
    print "Passed!\n";
}

# Ternary operator: condition ? if_true : if_false
my $label = ($score >= 60) ? "pass" : "fail";

# Postfix forms — condition AFTER the statement (very Perlish)
print "High score!\n"  if     $score >  90;
print "Not perfect\n"  unless $score == 100;

# Defined-or operator // — use default if value is undef
my $name  = undef;
my $label2 = $name // "Guest";    # "Guest" (because $name is undef)
$name //= "Guest";                # assign only if currently undef

# Boolean operators: && and || (or 'and' / 'or' in words)
my $valid = ($score > 0) && ($score <= 100);
my $ok    = ($score >= 90) || ($score == 42);

# 'or' and 'and' are the same but lower precedence (for flow control)
open(my $fh, '<', 'file.txt') or die "Can't open: $!\n";

# foreach — iterate over a list (most common)
foreach my $fruit ("apple", "banana", "cherry") {
    print "$fruit\n";
}

# for and foreach are interchangeable in Perl
for my $i (1..5) {    # 1..5 is the range operator
    print "$i\n";       # prints 1 2 3 4 5
}

# Default variable $_ — no explicit loop variable needed
for (qw(red green blue)) {
    print "$_\n";    # $_ holds the current element
}

# C-style for loop
for (my $i = 0; $i < 5; $i++) {
    print "$i\n";      # init; condition; increment
}

# while — loop while condition is true
my $count = 3;
while ($count > 0) {
    print "$count\n";
    $count--;
}

# until — loop UNTIL condition becomes true (while NOT)
$count = 0;
until ($count >= 3) {
    print "$count\n";
    $count++;
}

# Loop control
for my $n (1..10) {
    next if $n % 2 == 0;  # skip even numbers (next = continue)
    last if $n > 7;        # stop when n > 7 (last = break)
    print "$n\n";           # prints 1, 3, 5, 7
}

# Postfix for — one-liner iteration
print "$_\n" for (1..3);     # prints 1, 2, 3

# Reading a file line by line (canonical while loop pattern)
while (my $line = <$fh>) {
    chomp $line;            # remove trailing newline
    print $line;
}

# Basic sub definition
sub greet {
    my ($name) = @_;   # @_ holds ALL arguments
    return "Hello, $name!";
}
print greet("World");   # "Hello, World!"

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

# Default parameter values using //=
sub greet2 {
    my ($name, $title) = @_;
    $title //= "friend";    # use "friend" if $title is undef
    return "Hello, $title $name!";
}
print greet2("Alice");          # "Hello, friend Alice!"
print greet2("Bob", "Dr.");    # "Hello, Dr. Bob!"

# Returning multiple values (as a list)
sub min_max {
    my @nums = @_;
    my $min = $nums[0];
    my $max = $nums[0];
    for my $n (@nums) {
        $min = $n if $n < $min;
        $max = $n if $n > $max;
    }
    return ($min, $max);   # return TWO values
}
my ($lo, $hi) = min_max(5,2,9,1);  # $lo=1, $hi=9

# Named parameters via a hash (useful for many args)
sub create_user {
    my (%args) = @_;        # unpack @_ as a hash
    $args{role} //= "user";
    return \%args;
}
my $u = create_user(name=>"Eve", age=>22);

# Creating references with backslash \
my @arr   = (1,2,3);
my $aref  = \@arr;         # ref to existing array

my %hash  = (a=>1, b=>2);
my $href  = \%hash;         # ref to existing hash

# Anonymous refs — create without naming the original
my $aref2 = [10, 20, 30];  # [ ] creates anonymous arrayref
my $href2 = { x=>1, y=>2 }; # { } creates anonymous hashref

# Accessing via -> (arrow/dereference operator)
print $aref2->[0];         # 10 — element 0
print $href2->{x};         # 1  — key "x"

# Nested structures — array of hashes (common pattern)
my @people = (
    { name => "Alice", age => 30 },  # hashref
    { name => "Bob",   age => 25 },
);

# Access nested: $array[index]->{key}
print $people[0]->{name};    # "Alice"
print $people[1]->{age};     # 25

# Iterate array of hashes
for my $p (@people) {
    print "$p->{name} is $p->{age}\n";
}

# ref() tells you what kind of reference something is
print ref($aref);   # "ARRAY"
print ref($href);   # "HASH"
print ref(\$aref);  # "REF"  (reference to a reference)

my $text = "The price is $42.50 today";

# =~ tests if a string matches a pattern
if ($text =~ /price/) {
    print "Found 'price'\n";
}

# Capture groups ( ) — results in $1, $2, $3...
if ($text =~ /\$(\d+\.\d+)/) {
    print "Amount: $1\n";    # "42.50"
}

# !~ tests if something does NOT match
if ($text !~ /banana/) {
    print "No banana here\n";
}

# Common modifiers
# /i  — case-insensitive
# /g  — global (find all matches)
# /m  — multiline (^ and $ match line boundaries)
# /x  — extended (ignore whitespace, allow comments)
$text =~ /PRICE/i;          # matches "price" case-insensitively

# Global match — capture all occurrences into an array
my $html   = "<b>bold</b> and <i>italic</i>";
my @tags   = ($html =~ /<(\w+)>/g);
# @tags = ("b", "b", "i", "i") — all tag names

# Substitution: s/pattern/replacement/
my $str = "Hello World";
$str =~ s/World/Perl/;    # "Hello Perl"  (first match)

# Global substitution /g — replace all occurrences
my $s2 = "aaa bbb aaa";
$s2 =~ s/aaa/xxx/g;      # "xxx bbb xxx"

# Common metacharacters
# .    any character except newline
# \d   digit [0-9]        \D  non-digit
# \w   word char [a-z0-9_]\W  non-word
# \s   whitespace         \S  non-whitespace
# ^    start of string    $   end of string
# +    one or more        *   zero or more
# ?    zero or one        {n} exactly n times
# |    alternation (or)   [abc] character class

# Write a file — '>' creates/overwrites
open(my $out, '>', 'myfile.txt')
    or die "Cannot open for writing: $!\n";
# $! holds the OS error message on failure

print $out "First line\n";
print $out "Second line\n";
close($out);    # always close when done

# Read a file line by line — most memory-efficient
open(my $in, '<', 'myfile.txt')
    or die "Cannot open: $!\n";

while (my $line = <$in>) {
    chomp $line;         # remove trailing \n
    print "Line: $line\n";
}
close($in);

# Read entire file into an array (one line per element)
open(my $fh, '<', 'myfile.txt') or die $!;
my @lines = <$fh>;   # list context: reads all lines
close($fh);
chomp @lines;          # chomp all elements at once

# Append to a file — '>>' keeps existing content
open(my $app, '>>', 'myfile.txt') or die $!;
print $app "Third line\n";
close($app);

# Test operators — check file attributes
if (-e 'myfile.txt')  { print "exists\n"      }
if (-f 'myfile.txt')  { print "is a file\n"   }
if (-d '/tmp')        { print "is a dir\n"    }
if (-r 'myfile.txt')  { print "is readable\n" }
my $sz = -s 'myfile.txt';  # file size in bytes

#!/usr/bin/perl
use strict;     # ALWAYS — require declared variables
use warnings;  # ALWAYS — enable diagnostic messages

# Without strict, this silently creates a new global $nme (typo!):
# $nme = "Alice";  # oops! $name was intended

# With strict, this fails at compile time with "Global symbol...
# requires explicit package name" — you catch the bug immediately

# With strict, you MUST use my (or our for globals, local for dynamic)
my $name = "Alice";  # correct

# use warnings catches these common problems:

# 1. Using undef in a numeric context
my $x;
my $y = $x + 1;   # warns: "Use of uninitialized value"

# 2. Comparing string with == (numeric operator)
if ("hello" == "world") {}  # warns: both treated as 0

# 3. Useless use of a variable in void context
$name;   # warns: "Useless use of $name in void context"

# Suppressing a specific warning when you know it's safe:
{
    no warnings 'uninitialized';
    my $val = $x . "suffix";  # no warning in this block
}

# For modern Perl (5.10+), add these too:
use feature 'say';     # enables say() — print with auto-newline
use feature 'state';   # enables state variables (persistent in subs)

# Or all in one:
use 5.010;  # enables all features from Perl 5.10 onwards
use 5.020;  # enables all features from Perl 5.20 onwards

# $_ — the default variable (used by loops, grep, map, etc.)
for (qw(a b c)) {
    print;        # print $_ — print without argument uses $_
}

# @_ — arguments to the current subroutine
sub show_args {
    print "Got: " . join(", ", @_) . "\n";
}

# $! — OS error string after failed system call
open(my $fh, '<', 'missing.txt') or print "Error: $!\n";
# Error: No such file or directory

# $@ — error from last eval { } block
eval { die "something failed\n" };
print "Caught: $@" if $@;

# $0 — name of the current script
print "Running: $0\n";

# $$ — process ID of current Perl process
print "PID: $$\n";

# @ARGV — command-line arguments to the script
# perl script.pl arg1 arg2  -->  @ARGV = ("arg1","arg2")
if (@ARGV) {
    print "First arg: $ARGV[0]\n";
}

# %ENV — environment variables
print "Home: $ENV{HOME}\n";
print "Path: $ENV{PATH}\n";

# $/ — input record separator (default: newline)
# Setting $/ to undef makes <$fh> read entire file at once (slurp mode)
my $entire_file;
{
    local $/ = undef;   # temporarily unset (local = restore after block)
    open(my $f, '<', 'myfile.txt') or die $!;
    $entire_file = <$f>; # reads entire file
}

# $, — output field separator (between print args, default: none)
# $\ — output record separator (after each print, default: none)
{
    local $, = ", ";   # print "a","b","c"  ==>  "a, b, c"
    local $\ = "\n";   # auto-append newline to every print
    print "x", "y", "z";
}