1Readonly version 1.03 2===================== 3 4CHANGES FROM VERSION 1.02 (See "Changes" file for details) 5 6o Syntax of Readonly() function has changed, for users of 7 Perl 5.8 and later. 8 9 10DESCRIPTION 11 12Readonly.pm provides a facility for creating non-modifiable scalars, 13arrays, and hashes. 14 15Perl provides a built-in mechanism (the "use constant" pragma) to 16create constant scalars and lists. That mechanism has several 17limitations, however: 18 19 It creates only scalars and arrays (not hashes). 20 It creates "variables" that have no leading $ or @ character. 21 The variables it creates cannot be interpolated into strings. 22 It works only at compile time. 23 The variables it creates are global, never lexical. 24 Sometimes you have to be careful with your syntax when using them 25 (for example, when using one as a hash key). 26 You can't pass these constants around like variables (for example, 27 you can't take references to them). 28 It is rather difficult to make and use complex data structures with 29 use constant. 30 "use constant" directives can be overridden by subsequent "use 31 constant" directives. (this does generate a warning). 32 33Readonly.pm, by contrast: 34 35 Creates scalars, arrays (not lists), and hashes. 36 Creates variables that look and work like native perl variables. 37 Creates global or lexical variables. 38 Works at runtime or compile time. 39 Works with deep or shallow data structures. 40 Prevents reassignment of Readonly variables. 41 42EXAMPLES OF USE 43 44 Readonly::Scalar $x => "A string value"; 45 Readonly::Array @x => (1, 2, 3, 4); 46 Readonly::Hash %x => (key1 => 'value1', key2 => 'value2'); 47 48If the program subsequently tries to modify $x, @x, or %x, the program 49will die with an error message. 50 51Deep structures are a breeze: 52 53 Readonly::Hash %x => {key1 => [1, 2], key2 => [3, 4, 5]}; 54 print $x{key1}[1]; 55 56Try that with "use constant"! 57 58INSTALLATION 59 60To install this module, do the standard Perl module four-step: 61 62 perl Makefile.PL or perl Makefile.pl LIB='my/install/path' 63 make 64 make test 65 make install 66 67 68DEPENDENCIES 69 70Test::Harness and Test::More, if you want to run the test suites (and 71yes, you should). Also, Carp.pm and Exporter.pm, but they come with 72Perl. 73 74Readonly::XS (available on CPAN) is a companion module to Readonly. 75If that module is present, Readonly will use it for handling scalars. 76This results in a significant speed improvement. This is transparent 77to your code; whether or not the XS module is present, Readonly works 78the same. 79 80 81COPYRIGHT AND LICENSE 82 83Eric J. Roode, roode@cpan.org 84 85Copyright (c) 2001-2004 by Eric J. Roode. All Rights Reserved. This module 86is free software; you can redistribute it and/or modify it under the 87same terms as Perl itself. 88 89If you have suggestions for improvement, please drop me a line. If 90you make improvements to this software, I ask that you please send me 91a copy of your changes. Thanks. 92