Understanding Perl's Type System: A Practical Guide

# Does "42" belong to the number type?
my $original = "42";
my $as_num = 0 + $original;    # Force numeric: 42
my $back = "$as_num";           # Back to string: "42"
# $back eq $original? YES - "42" is a number

# Does "hello" belong to the number type?
my $original = "hello";
my $as_num = 0 + $original;    # Force numeric: 0 (with warning)
my $back = "$as_num";           # Back to string: "0"
# $back eq $original? NO - "hello" is NOT a number

# "NaN" (the string) round-trips through numeric conversion:
my $nan_str = "NaN";
my $as_num = 0 + $nan_str;     # Becomes IEEE NaN float
my $back = "$as_num";           # Back to "NaN"
# Survives round-trip!

# But it fails behavioral tests (tested on Perl 5.38.2):
use POSIX qw(isnan);
say $as_num == $as_num;         # FALSE - NaN != NaN
say $as_num - $as_num;          # NaN, not 0
# Violates expected number behavior, so "NaN" is NOT a number

my $x = 42;
say $x + 1;     # Works: 43
say "$x";       # Works: "42"
# 42 is an Int, which is also a Num, which is also a Str

my $x = 3.14;
say $x + 1;     # Works: 4.14
my $as_int = int($x);
say "$as_int";  # "3" - lost the .14
# 3.14 is a Num but NOT an Int (fails round-trip test)

my $x = "hello";
say $x + 1;     # 1 (warns) - "hello" becomes 0
# "hello" is a Str but NOT a Num (fails round-trip test)

# Traditional boolean members (round-trip through boolean context)
my @bools = (1, 0, '', 'string', undef);
for my $val (@bools) {
    my $as_bool = !!$val;           # Force boolean context
    my $truthy = $val ? 1 : 0;      # Test truthiness
    # All survive: truthiness is preserved
}

use builtin qw(is_bool true false);

say is_bool(true);   # true - primitive boolean
say is_bool(false);  # true - primitive boolean
say is_bool(1);      # false - boolean, but not primitive
say is_bool(0);      # false - boolean, but not primitive

# API that accepts optional boolean flags
sub process_data {
    my ($data, $verbose) = @_;

    # Using primitive booleans makes intent explicit
    if (is_bool($verbose)) {
        # Caller explicitly passed true/false
        return verbose_process($data) if $verbose;
    } else {
        # Caller passed something else (1, 0, undef, etc.)
        # Use traditional truthiness
        return verbose_process($data) if $verbose;
    }
}

# Clear intent with primitive booleans
process_data($data, true);   # Explicitly verbose
process_data($data, false);  # Explicitly quiet

# Backward compatible with traditional booleans
process_data($data, 1);      # Also works
process_data($data, 0);      # Also works

my $x = "42";
# Is it a string? YES - already is one
# Is it a number? YES - round-trips: "42" -> 42 -> "42"

my $y = "42.5";
# Is it an integer? NO - 42.5 -> 42 -> "42" (lost .5)
# Is it a number? YES - round-trips through numeric conversion

my $hash = { foo => 'bar' };
my $str = "$hash";       # "HASH(0x00000001f42a)"
# Can't convert "HASH(0x00000001f42a)" back to the original hash
# References are NOT strings (fail round-trip test)

# A practical DualVar example: $! (errno)
open my $fh, '<', '/nonexistent/file' or do {
    say "Error: $!";        # "No such file or directory" (string)
    say "Code: ", 0 + $!;   # 2 (numeric errno)
};

# Creating a custom DualVar
use Scalar::Util qw(dualvar);
my $status = dualvar(404, "Not Found");

say "HTTP Status: $status";      # "Not Found" (string part)
say "Status Code: ", 0 + $status; # 404 (numeric part)

# Round-trip as number: "Not Found" -> 0 -> "0" (FAILS)
# Round-trip as string: 404 -> "404" -> ... (FAILS)
# DualVar is neither Num nor Str, but IS Scalar

package Person {
    use Moose;

    has 'age' => (
        is  => 'rw',
        isa => 'Int',
    );

    has 'name' => (
        is  => 'rw',
        isa => 'Str',
    );
}

use Types::Standard qw(Int Str ArrayRef);

my $age_check = Int;
say $age_check->check(42);      # true
say $age_check->check("42");    # true (numeric string)
say $age_check->check("hello"); # false

package Employee {
    use Moo;
    use Types::Standard qw(Int Str);

    has 'employee_id' => (is => 'ro', isa => Int);
    has 'name' => (is => 'rw', isa => Str);
}

my $emp = Employee->new(
    employee_id => "42",    # OK - "42" is an Int (round-trips)
    name => "Alice"
);

use Types::Standard qw(Int Str);

sub process_id {
    my $id = Int->assert_coerce(shift);  # Coerce and validate
    return $id * 2;
}

use v5.38;
use feature 'class';
use Types::Standard qw(Int Str);

class Employee {
    field $employee_id :param :reader;
    field $name :param :reader;

    ADJUST {
        # Manual type validation until native support arrives
        Int->assert_valid($employee_id);
        Str->assert_valid($name);
    }
}

my $emp = Employee->new(
    employee_id => 42,
    name => "Alice"
);

# .perlcriticrc
[ValuesAndExpressions::ProhibitMismatchedOperators]
severity = 4

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: type-check
      name: Check type constraints
      entry: prove -l t/type-constraints.t
      language: system
      pass_filenames: false

use Test::More;
use Test::Fatal;

# Test that type constraints work as expected
like(
    exception { Person->new(age => "hello") },
    qr/type constraint/i,
    'age rejects non-numeric strings'
);

# Test that numeric strings are accepted
is(
    exception { Person->new(age => "42") },
    undef,
    'age accepts numeric strings'
);

my $ref = { foo => 'bar' };
say "$ref";     # "HASH(0x00000001f42a)" - coerces to string
# But $ref is NOT a Str (fails round-trip test)

my $x = "42";
# $x is a Str: "42" -> "42" (round-trips)
# $x is a Num: "42" -> 42 -> "42" (round-trips)
# $x is an Int: "42" -> 42 -> "42" (round-trips, no fraction lost)

say "hello" == "goodbye";  # TRUE (both become 0)

my $x = "0 but true";
say 0 + $x;       # 0 (numeric part)
say !!$x;         # true (string is truthy)

my $x = "NaN";
my $y = 0 + $x;   # IEEE NaN
say "$y";         # "NaN" - round-trips!
say $y == $y;     # FALSE - but violates number semantics

use Text::CSV;
my $csv = Text::CSV->new();

# CSV data: "employee_id,salary\n42,50000\n"
while (my $row = $csv->getline($fh)) {
    my ($id, $salary) = @$row;

    # WRONG: assumes strings are numbers
    if ($salary > 40000) {  # Works, but fragile
        process_high_earner($id, $salary);
    }

    # BETTER: explicit type validation
    use Types::Standard qw(Int);
    if (Int->check($salary) && $salary > 40000) {
        process_high_earner($id, $salary);
    }
}

package UserService {
    use Moo;
    use Types::Standard qw(Int Str);

    sub update_age {
        my ($self, $user_id, $age) = @_;

        # Type checking catches edge cases:
        # - "25" (string) passes - it's an Int
        # - 25.5 fails - not an Int
        # - "twenty-five" fails - not a number at all
        Int->assert_valid($user_id);
        Int->assert_valid($age);

        $self->db->update(users => {age => $age}, {id => $user_id});
    }
}

use YAML::XS qw(LoadFile);
my $config = LoadFile('config.yml');

# config.yml contains: timeout: "30"
my $timeout = $config->{timeout};

# SUBTLE BUG: string "30" in boolean context
if ($timeout) {  # Always true, even if timeout is "0"
    sleep $timeout;  # Numeric coercion works here
}

# CORRECT: explicit numeric check
use Scalar::Util qw(looks_like_number);
if (looks_like_number($timeout) && $timeout > 0) {
    sleep $timeout;
}

# Bug: function returns reference when it should return count
sub get_user_count {
    my $users = shift;
    return $users;  # Oops! Returns hashref, not count
}

my $count = get_user_count(\%users);

# This comparison always succeeds because hashrefs numify to large addresses
if ($count > 10) {  # BUG: Always true if $count is a hashref!
    send_alert("High user count: $count");
}

# The hashref "HASH(0x55d4a8f2b1a0)" becomes a large number when numified
# Output: "High user count: 94381521662368"

use Data::Dumper;
my $value = get_user_count(\%users);

warn Dumper({
    value => $value,
    as_num => 0 + $value,
    back => "" . (0 + $value),
    is_num => ($value eq "" . (0 + $value)),
    ref_type => ref($value)
});

# Output shows: ref_type => 'HASH', is_num => '', revealing the bug

# BAD: Implicit assumptions about types
sub calculate_average {
    my (@numbers) = @_;
    my $sum = 0;
    $sum += $_ for @numbers;
    return $sum / @numbers;
}

# Silently accepts non-numbers and produces nonsense
calculate_average("hello", "world");  # Returns 0 (both become 0)

# GOOD: Explicit type validation
sub calculate_average {
    my (@numbers) = @_;

    # Verify each argument is actually a number
    for my $n (@numbers) {
        my $original = $n;
        my $as_num = 0 + $n;
        my $back = "$as_num";

        die "'$original' is not a number"
            unless $original eq $back && !ref($n);
    }

    my $sum = 0;
    $sum += $_ for @numbers;
    return $sum / @numbers;
}

# Now it fails fast with a clear error
calculate_average("hello", "world");  # Dies: 'hello' is not a number

# Reading user input
my $quantity = <STDIN>;  # User types "5\n"
chomp $quantity;

# Silent bug: quantity is string "5", inventory is array reference
my $inventory = get_inventory();

# This comparison is nonsense but Perl allows it
if ($quantity > $inventory) {  # Compares "5" to array address
    reorder_stock();
}

# BETTER: Validate types explicitly
use Types::Standard qw(Int ArrayRef);

my $quantity = <STDIN>;
chomp $quantity;
Int->assert_valid($quantity);  # Verify it's a valid integer

my $inventory = get_inventory();
ArrayRef->assert_valid($inventory);  # Verify it's an array reference

if ($quantity > scalar(@$inventory)) {  # Correct comparison
    reorder_stock();
}

# Bug: Money amounts stored as floats lose precision
sub calculate_total {
    my @items = @_;
    my $total = 0.0;

    for my $item (@items) {
        $total += $item->{price};  # price is "19.99"
    }

    return $total;
}

# Float arithmetic introduces errors
my $total = calculate_total(
    {price => "19.99"},
    {price => "29.99"},
    {price => "9.99"}
);

# $total is 59.970000000000006, not 59.99!
printf "Total: \$%.2f\n", $total;  # Prints $59.97

# BETTER: Use integer cents
sub calculate_total {
    my @items = @_;
    my $total_cents = 0;

    for my $item (@items) {
        my $price = $item->{price};

        # Verify it round-trips as a number
        die "Invalid price: $price"
            unless $price eq "" . (0 + $price);

        # Convert to cents (integers round-trip perfectly)
        $total_cents += int($price * 100 + 0.5);
    }

    return $total_cents / 100;
}

use Test::More;
use Test::Fatal;

# Don't just test the happy path
is(add(2, 3), 5, 'add two numbers');

# Test type boundaries
is(add("2", "3"), 5, 'add numeric strings');
is(add(2.5, 3.5), 6, 'add floats');

like(
    exception { add("hello", "world") },
    qr/invalid.*number/i,
    'add rejects non-numeric strings'
);

like(
    exception { add([], {}) },
    qr/invalid.*number/i,
    'add rejects references'
);

# If your code stores and retrieves values, test round-tripping
sub test_round_trip {
    my ($storage, $value, $type_name) = @_;

    $storage->set(test_key => $value);
    my $retrieved = $storage->get('test_key');

    is($retrieved, $value, "$type_name round-trips correctly");
    is(ref($retrieved), ref($value), "$type_name reference type preserved")
        if ref($value);
}

test_round_trip($storage, 42, 'integer');
test_round_trip($storage, "42", 'numeric string');
test_round_trip($storage, {foo => 'bar'}, 'hash reference');

# When your code relies on type coercion, test it explicitly
subtest 'accepts various numeric representations' => sub {
    my @valid_ages = (25, "25", "25.0");

    for my $age (@valid_ages) {
        ok(
            lives { $user->update_age($age) },
            "accepts age: $age"
        );
        is($user->age, 25, "stores age as 25 regardless of input format");
    }
};

subtest 'rejects non-numeric ages' => sub {
    my @invalid_ages = ("twenty-five", "N/A", [], {});

    for my $age (@invalid_ages) {
        like(
            exception { $user->update_age($age) },
            qr/type constraint/i,
            "rejects invalid age: " . (ref($age) || $age)
        );
    }
};

use Test::LectroTest;

# Property: Int round-trips through string conversion
Property {
    ##[ x <- Int ]##
    my $original = $x;
    my $as_string = "$x";
    my $back = 0 + $as_string;

    $back == $original;
}, name => "integers round-trip through stringification";

# Property: Non-numeric strings become 0
Property {
    ##[ s <- String(charset => "a-zA-Z", length => [1,10]) ]##
    my $as_num = 0 + $s;

    $as_num == 0;
}, name => "alphabetic strings numify to 0";

use Tie::Scalar;

tie my $magic, 'Tie::StdScalar';
$magic = 42;

# Tied variables can change their value between accesses
# Round-trip test assumptions may not hold
my $original = $magic;
my $as_num = 0 + $magic;
my $back = "$as_num";

# If the tie implementation changes the value between accesses,
# $original may not equal $back even for valid numbers

package Money {
    use overload
        '""' => sub { sprintf "\$%.2f", $_[0]{cents} / 100 },
        '0+' => sub { $_[0]{cents} / 100 },
        fallback => 1;

    sub new {
        my ($class, $dollars) = @_;
        bless { cents => int($dollars * 100) }, $class;
    }
}

my $price = Money->new(19.99);
say "$price";       # "$19.99"
say 0 + $price;     # 19.99

# Overloaded objects can appear to pass round-trip tests
# even though they're objects, not primitive numbers

# $! behaves as a DualVar with errno-specific magic
open my $fh, '<', '/nonexistent' or do {
    my $error = $!;
    # String value depends on current locale
    # Numeric value is the errno
    # Behavior can change based on system state
};

use POSIX qw(setlocale LC_NUMERIC);

# In some locales, "," is the decimal separator
setlocale(LC_NUMERIC, "de_DE.UTF-8");

my $val = "3,14";  # May or may not be treated as 3.14
# Round-trip behavior depends on locale settings

# Good use case: Public API with strict requirements
package UserService {
    use Moo;
    use Types::Standard qw(Int Str);

    method create_user(Int $id, Str $name) {
        # Type checking ensures contract is met
        $self->db->insert(users => {id => $id, name => $name});
    }
}

# Good use case: Debugging mysterious behavior
sub debug_value {
    my ($val, $type_name) = @_;

    my $as_num = 0 + $val;
    my $back = "$as_num";

    warn "$val is " . ($val eq $back ? "" : "NOT ") . "a number\n";
}

# .perlcriticrc catches common mistakes
[ValuesAndExpressions::ProhibitMismatchedOperators]
severity = 4

# Warns about: "hello" == "goodbye"
# Warns about: $hashref > 10

# SLOW: Repeated type conversions
for my $i (1..1000000) {
    my $str = "Value: $i";  # Number to string
    my $num = 0 + $i;       # String to number (if $i is string)
    process($str, $num);
}

# FASTER: Minimize conversions
for my $i (1..1000000) {
    process("Value: $i", $i);  # Single conversion
}

# lvalues can change type context
substr($string, 0, 1) = "X";  # $string is both value and target

# Aliasing means one "value" can have multiple representations
for my $item (@array) {
    $item++;  # Modifies @array element directly
}

# Context affects behavior in ways beyond simple type conversion
my @list = somefunction();  # List context
my $count = somefunction(); # Scalar context - may return different value!