This is a facility for creating non-modifiable variables. This is useful for configuration files, headers, etc. It can also be useful as a development and debugging tool for catching updates to variables that should not be changed.

Readonly has the ability to create both deep and shallow readonly variables.

If any of the values you pass to Scalar, Array, Hash, or the standard Readonly are references, then those functions recurse over the data structures, marking everything as Readonly. The entire structure is nonmodifiable. This is normally what you want.

If you want only the top level to be Readonly, use the alternate (and poorly named) Scalar1, Array1, and Hash1 functions.

Readonly.pm, on the other hand, will work with global variables and with lexical ("my") variables. It will create scalars, arrays, or hashes, all of which look and work like normal, read-write Perl variables. You can use them in scalar context, in list context; you can take references to them, pass them to functions, anything.

Readonly.pm also works well with complex data structures, allowing you to tag the whole structure as nonmodifiable, or just the top level.

Also, Readonly variables may not be reassigned. The following code will die:

Readonly.pm used to impose a performance penalty. It was pretty slow. How slow? Run the eg/benchmark.pl script that comes with Readonly. On my test system, "use constant" (const), typeglob constants (tglob), regular read/write Perl variables (normal/literal), and the new Readonly (ro/ro_simple) are all about the same speed, the old, tie based Readonly.pm constants were about 1/22 the speed.

However, there is relief. There is a companion module available, Readonly::XS. You won't need this if you're using Perl 5.8.x or higher.

I repeat, you do not need Readonly::XS if your environment has perl 5.8.x or higher. Please see section entitled Internals for more.

Creates a nonmodifiable scalar, $var, and assigns a value of $value to it. Thereafter, its value may not be changed. Any attempt to modify the value will cause your program to die.

A value must be supplied. If you want the variable to have undef as its value, you must specify undef.

If $value is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the $value marked as Readonly, use Scalar1.

If $var is already a Readonly variable, the program will die with an error about reassigning Readonly variables.

Creates a nonmodifiable array, @arr, and assigns the specified list of values to it. Thereafter, none of its values may be changed; the array may not be lengthened or shortened or spliced. Any attempt to do so will cause your program to die.

If any of the values passed is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the hash %@arr itself marked as Readonly, use Array1.

If @arr is already a Readonly variable, the program will die with an error about reassigning Readonly variables.

Creates a nonmodifiable hash, %h, and assigns the specified keys and values to it. Thereafter, its keys or values may not be changed. Any attempt to do so will cause your program to die.

A list of keys and values may be specified (with parentheses in the synopsis above), or a hash reference may be specified (curly braces in the synopsis above). If a list is specified, it must have an even number of elements, or the function will die.

If any of the values is a reference to a scalar, array, or hash, then this function will mark the scalar, array, or hash it points to as being Readonly as well, and it will recursively traverse the structure, marking the whole thing as Readonly. Usually, this is what you want. However, if you want only the hash %h itself marked as Readonly, use Hash1.

If %h is already a Readonly variable, the program will die with an error about reassigning Readonly variables.

The Readonly function is an alternate to the Scalar, Array, and Hash functions. It has the advantage (if you consider it an advantage) of being one function. That may make your program look neater, if you're initializing a whole bunch of constants at once. You may or may not prefer this uniform style.

It has the disadvantage of having a slightly different syntax for versions of Perl prior to 5.8. For earlier versions, you must supply a backslash, because it requires a reference as the first parameter.

Historically, this module exports the Readonly symbol into the calling program's namespace by default. The following symbols are also available for import into your program, if you like: Scalar, Scalar1, Array, Array1, Hash, and Hash1.

Some people simply do not understand the relationship between this module and Readonly::XS so I'm adding this section. Odds are, they still won't understand but I like to write so...

In the past, Readonly's "magic" was performed by tie()-ing variables to the Readonly::Scalar, Readonly::Array, and Readonly::Hash packages (not to be confused with the functions of the same names) and acting on WRITE, READ, et. al. While this worked well, it was slow. Very slow. Like 20-30 times slower than accessing variables directly or using one of the other const-related modules that have cropped up since Readonly was released in 2003.

To 'fix' this, Readonly::XS was written. If installed, Readonly::XS used the internal methods SvREADONLY and SvREADONLY_on to lock simple scalars. On the surface, everything was peachy but things weren't the same behind the scenes. In edge cases, code perfromed very differently if Readonly::XS was installed and because it wasn't a required dependency in most code, it made downstream bugs very hard to track.

In the years since Readonly::XS was released, the then private internal methods have been exposed and can be used in pure perl. Similar modules were written to take advantage of this and a patch to Readonly was created. We no longer need to build and install another module to make Readonly useful on modern builds of perl.

You do not need to install Readonly::XS.

You should stop listing Readonly::XS as a dependency or expect it to be installed.

Please note that most users of Readonly no longer need to install the companion module Readonly::XS which is recommended but not required for perl 5.6.x and under. Please do not force it as a requirement in new code and do not use the package variable $Readonly::XSokay in code/tests. For more, see "Internals" in the section on Readonly's new internals.