Lines Matching defs:Readonly
10 Readonly - Facility for creating read-only scalars, arrays, hashes.
14 This documentation describes version 1.03 of Readonly.pm, April 20, 2004.
25 package Readonly;
26 $Readonly::VERSION = '1.03'; # Also change in the documentation!
36 # These functions may be overridden by Readonly::XS, if installed.
39 use vars qw/$XSokay/; # Set to true in Readonly::XS, if available
48 $Readonly::XS::MAGIC_COOKIE = "Do NOT use or require Readonly::XS unless you're me.";
49 eval 'use Readonly::XS';
55 package Readonly::Scalar;
60 Readonly::croak "Invalid tie" unless $whence && $whence =~ /^Readonly::(?:Scalar1?|Readonly)$/;
62 Readonly::croak "No value specified for readonly scalar" unless @_;
63 Readonly::croak "Too many values specified for readonly scalar" unless @_ == 1;
76 sub {Readonly::croak $Readonly::MODIFY};
82 package Readonly::Array;
87 Readonly::croak "Invalid tie" unless $whence =~ /^Readonly::Array1?$/;
119 sub {Readonly::croak $Readonly::MODIFY};
125 package Readonly::Hash;
130 Readonly::croak "Invalid tie" unless $whence =~ /^Readonly::Hash1?$/;
134 Readonly::croak $Readonly::ODDHASH unless (@_ %2 == 0);
169 sub {Readonly::croak $Readonly::MODIFY};
176 package Readonly;
180 push @EXPORT, qw/Readonly/;
188 # Returns true if a string begins with "Readonly::"
189 # Used to prevent reassignment of Readonly variables.
193 return lc $type if $type =~ s/^Readonly:://;
197 # Shallow Readonly scalar
213 my $tieobj = eval {tie $_[0], 'Readonly::Scalar', $_[1]};
222 # Shallow Readonly array
229 return tie @$aref, 'Readonly::Array', @_;
232 # Shallow Readonly hash
243 return tie %$href, 'Readonly::Hash', %{$_[0]};
249 return tie %$href, 'Readonly::Hash', @_;
252 # Deep Readonly scalar
261 # Recursively check passed element for references; if any, make them Readonly
278 my $tieobj = eval {tie $_[0], 'Readonly::Scalar', $value};
287 # Deep Readonly array
296 # Recursively check passed elements for references; if any, make them Readonly
304 return tie @$aref, 'Readonly::Array', @values;
307 # Deep Readonly hash
325 # Recursively check passed elements for references; if any, make them Readonly
333 return tie %$href, 'Readonly::Hash', @values;
338 eval q{sub Readonly} . ( $] < 5.008 ? '' : '(\[$@%]@)' ) . <<'SUB_READONLY';
345 croak "Readonly scalar must have only one value" if @_ > 2;
347 my $tieobj = eval {tie ${$_[0]}, 'Readonly::Scalar', $_[1]};
369 croak "Readonly only supports scalar, array, and hash variables.";
373 croak "First argument to Readonly must be a reference.";
384 use Readonly;
387 Readonly::Scalar $sca => $initial_value;
388 Readonly::Scalar my $sca => $initial_value;
391 Readonly::Array @arr => @values;
392 Readonly::Array my @arr => @values;
395 Readonly::Hash %has => (key => value, key => value, ...);
396 Readonly::Hash my %has => (key => value, key => value, ...);
398 Readonly::Hash %has => {key => value, key => value, ...};
413 Readonly $sca => $initial_value;
414 Readonly my $sca => $initial_value;
415 Readonly @arr => @values;
416 Readonly my @arr => @values;
417 Readonly %has => (key => value, key => value, ...);
418 Readonly my %has => (key => value, key => value, ...);
420 Readonly \$sca => $initial_value;
421 Readonly \my $sca => $initial_value;
422 Readonly \@arr => @values;
423 Readonly \my @arr => @values;
424 Readonly \%has => (key => value, key => value, ...);
425 Readonly \my %has => (key => value, key => value, ...);
437 marking everything as Readonly. Usually, this is what you want: the
439 Readonly, use the alternate C<Scalar1>, C<Array1> and C<Hash1>
442 Please note that most users of Readonly will also want to install a
443 companion module Readonly::XS. See the L</CONS> section below for more
527 Readonly.pm, on the other hand, will work with global variables and
533 Readonly.pm also works well with complex data structures, allowing you
536 Also, Readonly variables may not be reassigned. The following code
539 Readonly::Scalar $pi => 3.14159;
541 Readonly::Scalar $pi => 2.71828;
545 Readonly.pm does impose a performance penalty. It's pretty slow. How
546 slow? Run the C<benchmark.pl> script that comes with Readonly. On my
549 Readonly.pm constants were about 1/20 the speed.
552 Readonly::XS. If it is installed on your system, Readonly.pm uses it
553 to make read-only scalars much faster. With Readonly::XS, Readonly
554 scalars are as fast as the other types of variables. Readonly arrays
556 of your Readonly variables will be scalars.
558 If you can't use Readonly::XS (for example, if you don't have a C
560 re-link it), you have to decide whether the benefits of Readonly
562 (and other things that Readonly is likely to be useful for), the speed
565 still want to use Readonly.pm during development, to catch changes to
570 Readonly::Scalar $Foo_Directory => '/usr/local/foo';
571 Readonly::Scalar $Bar_Directory => '/usr/local/bar';
576 # Readonly::Scalar $Foo_Directory => '/usr/local/foo';
577 # Readonly::Scalar $Bar_Directory => '/usr/local/bar';
586 =item Readonly::Scalar $var => $value;
597 Readonly as well, and it will recursively traverse the structure,
598 marking the whole thing as Readonly. Usually, this is what you want.
599 However, if you want only the C<$value> marked as Readonly, use
602 If $var is already a Readonly variable, the program will die with
603 an error about reassigning Readonly variables.
605 =item Readonly::Array @arr => (value, value, ...);
614 being Readonly as well, and it will recursively traverse the structure,
615 marking the whole thing as Readonly. Usually, this is what you want.
616 However, if you want only the hash C<%@arr> itself marked as Readonly,
619 If @arr is already a Readonly variable, the program will die with
620 an error about reassigning Readonly variables.
622 =item Readonly::Hash %h => (key => value, key => value, ...);
624 =item Readonly::Hash %h => {key => value, key => value, ...};
637 being Readonly as well, and it will recursively traverse the
638 structure, marking the whole thing as Readonly. Usually, this is what
640 Readonly, use C<Hash1>.
642 If %h is already a Readonly variable, the program will die with
643 an error about reassigning Readonly variables.
645 =item Readonly $var => $value;
647 =item Readonly @arr => (value, value, ...);
649 =item Readonly %h => (key => value, ...);
651 =item Readonly %h => {key => value, ...};
653 The C<Readonly> function is an alternate to the C<Scalar>, C<Array>,
663 Readonly \$var => $value;
664 Readonly \@arr => (value, value, ...);
665 Readonly \%h => (key => value, ...);
666 Readonly \%h => {key => value, ...};
670 =item Readonly::Scalar1 $var => $value;
672 =item Readonly::Array1 @arr => (value, value, ...);
674 =item Readonly::Hash1 %h => (key => value, key => value, ...);
676 =item Readonly::Hash1 %h => {key => value, key => value, ...};
678 These alternate functions create shallow Readonly variables, instead
681 Readonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
682 Readonly::Array @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);
685 $shal[2]{APL}='Weird'; # Allowed! since the hash isn't Readonly
687 $deep[2]{APL}='Weird'; # error, since the hash is Readonly
698 Readonly::Scalar $a => "A string value";
701 Readonly::Scalar $a => $computed_value;
707 Readonly::Array @a => (1, 2, 3, 4);
710 Readonly::Array @a => 1, 2, 3, 4;
713 Readonly::Array @a => qw/1 2 3 4/;
716 Readonly::Array @a => @computed_values;
719 Readonly::Array @a => ();
720 Readonly::Array @a; # equivalent
726 Readonly::Hash %a => (key1 => 'value1', key2 => 'value2');
729 Readonly::Hash %a => %computed_values;
732 Readonly::Hash %a => ();
733 Readonly::Hash %a; # equivalent
736 Readonly::Hash %a => (key1 => 'value1', "value2");
745 Readonly
761 Readonly::XS is recommended but not required.
766 (Readonly) for all three types of variables (13 April 2002).
769 deeply-Readonly data structures (21 May 2002).
772 Readonly function work a lot smoother under perl 5.8+.
787 Readonly.pm is made from 100% recycled electrons. No animals were
789 in stores! Readonly::XS sold separately. Void where prohibited.