NAME

Readonly::Tiny - Simple, correct readonly values

SYNOPSIS

    use Readonly::Tiny;

    my $x = readonly [1, 2, 3];
    # $x is not readonly, but the array it points to is.
    
    my @y = (4, 5, 6);
    readonly \@y;
    # @y is readonly, as well as its contents.

DESCRIPTION

Readonly::Tiny provides a simple and correct way of making values readonly. Unlike Readonly it does not cause arrays and hashes to be tied, it just uses the core SvREADONLY flag.

FUNCTIONS

readonly

    my $ro = readonly $ref, \%opts;

Make a data structure readonly. $ref must be a reference; the referenced value, and any values referenced recursively, will be made readonly. $ref is returned, but it will not itself be readonly; it is possible to make a variable readonly by passing a reference to it, as in the "SYNOPSIS".

%opts is a hashref of options:

peek

Normally blessed references will not be looked through. The scalar holding the reference will be made readonly (so a different object cannot be assigned) but the contents of the object itself will be left alone. Supplying peek => 1 allows blessed refs to be looked through.

skip

This should be a hashref keyed by refaddr. Any object whose refaddr is in the hash will be skipped.

Note that making a hash readonly has the same effect as calling Hash::Util::lock_hash; in particular, it causes restricted hashes to be re-restricted to their current set of keys.

readwrite

    my $rw = readwrite $ref, \%opts;

Undo the effects of readonly. %opts is the same. Note that making a hash readwrite will undo any restrictions put in place using Hash::Util.

BE VERY CAREFUL calling this on values you have not made readonly yourself. It will silently ignore attempts to make the core values PL_sv_undef, PL_sv_yes and PL_sv_no readwrite, but there are many other values the core makes readonly, usually with good reason. Recent versions of perl will not allow you to make readwrite a value the core has set readonly, but you should probably not rely on this.

Readonly

    Readonly my $x, 1;
    Readonly my @y, 2, 3, 4;
    Readonly my %z, foo => 5;

This is a compatibility shim for Readonly. It is prototyped to take a reference to its first argument, and assigns the rest of the argument list to that argument before making the whole thing readonly.

EXPORTS

readonly is exported by default. readwrite and Readonly are exported on request.

SEE ALSO

Readonly was the first module to supply readonly values. It was written for Perl 5.6, and as a result the interface and implementation are both rather clunky. With Readonly::XS the performance is improved for scalar varuables, but arrays and hashes still use a tied implementation which is very slow.

Const::Fast is a greatly improved reaoonly module which uses perl's internal SvREADONLY flag instead of ties. The differences between this module and Const::Fast are:

• The readonly function does not insist on performing an assignment, it just returns a readonly value. This is, IMHO, more useful, since it means a readonly value can be returned from a function. In particular, it is often useful to return a readonly value from a builder method.

• It does not attempt to clone deep structures. If Clone::Fast is applied to a structure with cross-links it will clone the whole thing, on the principle that parts of the graph may be shared with something else which should not be readonly. This module takes the approach that if you asked for something to be made readonly you meant it, and if it points to something it shouldn't that's your mistake.

BUGS

Please report bugs to <bug-Readonly-Tiny@rt.cpan.org>.

AUTHOR

Ben Morrow <ben@morrow.me.uk>

COPYRIGHT

Copyright 2015 Ben Morrow.

Released under the 2-clause BSD licence.

cpanm Readonly::Tiny

perl -MCPAN -e shell
install Readonly::Tiny