view release on metacpan or  search on metacpan

lib/const.pm  view on Meta::CPAN

package
    const;
use strict;
use warnings;
our $VERSION = '0.18';
require XSLoader;
XSLoader::load('const', $VERSION);
1;

__END__

=head1 NAME

const - fast read-only constants with compile-time optimization

=head1 SYNOPSIS

    use const;
    
    # Create a constant inline (compile-time optimized!)
    my $pi = const::c(3.14159);
    my $name = const::c("immutable");
    my $data = const::c({ key => "value", nested => [1, 2, 3] });
    
    # Traditional Const::XS style
    const::const(my $greeting => "Hello World");
    const::const(my @list => qw/a b c/);
    const::const(my %config => (debug => 1, verbose => 0));
    
    # Make existing variable readonly
    my $x = 42;
    const::make_readonly(\$x);
    
    # Check readonly status
    if (const::is_readonly(\$x)) {
        print "x is constant\n";
    }
    
    # Undo if needed
    const::unmake_readonly(\$x);

=head1 DESCRIPTION

C<const> provides high-performance read-only constants for Perl. It's designed
for Perl programmers who prefer declaring constants the way Perl programmers
actually like to: inline, with minimal ceremony.

Unlike C<use constant> which creates subroutines, C<const::c()> creates actual
readonly scalars that behave like normal variables.

=head1 COMPILE-TIME OPTIMIZATION

The killer feature of this module is compile-time constant folding:

    my $val = const::c(42);           # Constant-folded at compile time!
    my $str = const::c("hello");      # No function call at runtime

When C<const::c()> is called with a B<literal constant value>, the entire
function call is eliminated and replaced with the readonly value directly.
This means B<zero runtime overhead> for constant literals.

=head2 What Gets Optimized

    # OPTIMIZED - literal values
    const::c(42)                      # Integer literal
    const::c(3.14)                    # Float literal
    const::c("string")                # String literal
    const::c('also string')           # Single-quoted string

    # NOT OPTIMIZED - runtime values (XS fallback, still fast)
    my $v = get_value();
    const::c($v)                      # Variable - needs runtime evaluation
    const::c($a + $b)                 # Expression - needs runtime evaluation

=head1 FUNCTIONS

=head2 c

    my $const = const::c($value);

Create a readonly copy of C<$value>. If C<$value> is a reference, it will be
deeply frozen (the entire structure becomes readonly).

When called with a literal constant, this is optimized away at compile time.

    my $answer = const::c(42);        # Just becomes: my $answer = 42;
                                      # (but readonly)