{
    "mode": "man",
    "parameter": "Readonly",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/man/Readonly/json",
    "generated": "2026-08-21T13:25:08Z",
    "sections": {
        "NAME": {
            "content": "Readonly - Facility for creating read-only scalars, arrays, hashes\n",
            "subsections": []
        },
        "Synopsis": {
            "content": "use Readonly;\n\n# Deep Read-only scalar\nReadonly::Scalar    $sca => $initialvalue;\nReadonly::Scalar my $sca => $initialvalue;\n\n# Deep Read-only array\nReadonly::Array    @arr => @values;\nReadonly::Array my @arr => @values;\n\n# Deep Read-only hash\nReadonly::Hash    %has => (key => value, key => value, ...);\nReadonly::Hash my %has => (key => value, key => value, ...);\n# or:\nReadonly::Hash    %has => {key => value, key => value, ...};\n\n# You can use the read-only variables like any regular variables:\nprint $sca;\n$something = $sca + $arr[2];\nnext if $has{$somekey};\n\n# But if you try to modify a value, your program will die:\n$sca = 7;\npush @arr, 'seven';\ndelete $has{key};\n# The error message is \"Modification of a read-only value attempted\"\n\n# Alternate form (Perl 5.8 and later)\nReadonly    $sca => $initialvalue;\nReadonly my $sca => $initialvalue;\nReadonly    @arr => @values;\nReadonly my @arr => @values;\nReadonly    %has => (key => value, key => value, ...);\nReadonly my %has => (key => value, key => value, ...);\nReadonly my $sca; # Implicit undef, readonly value\n\n# Alternate form (for Perls earlier than v5.8)\nReadonly    \\$sca => $initialvalue;\nReadonly \\my $sca => $initialvalue;\nReadonly    \\@arr => @values;\nReadonly \\my @arr => @values;\nReadonly    \\%has => (key => value, key => value, ...);\nReadonly \\my %has => (key => value, key => value, ...);\n",
            "subsections": []
        },
        "Description": {
            "content": "This is a facility for creating non-modifiable variables. This is useful for configuration\nfiles, headers, etc. It can also be useful as a development and debugging tool for catching\nupdates to variables that should not be changed.\n",
            "subsections": []
        },
        "Variable Depth": {
            "content": "Readonly has the ability to create both deep and shallow readonly variables.\n\nIf you pass a $ref, an @array or a %hash to corresponding functions \"::Scalar()\", \"::Array()\"\nand \"::Hash()\", then those functions recurse over the data structure, marking everything as\nreadonly. The entire structure is then non-modifiable. This is normally what you want.\n\nIf you want only the top level to be readonly, use the alternate (and poorly named)\n\"::Scalar1()\", \"::Array1()\", and \"::Hash1()\" functions.\n\nPlain \"Readonly()\" creates what the original author calls a \"shallow\" readonly variable,\nwhich is great if you don't plan to use it on anything but only one dimensional scalar\nvalues.\n\n\"Readonly::Scalar()\" makes the variable 'deeply' readonly, so the following snippet kills\nover as you expect:\n\nuse Readonly;\n\nReadonly::Scalar my $ref => { 1 => 'a' };\n$ref->{1} = 'b';\n$ref->{2} = 'b';\n\nWhile the following snippet does not make your structure 'deeply' readonly:\n\nuse Readonly;\n\nReadonly my $ref => { 1 => 'a' };\n$ref->{1} = 'b';\n$ref->{2} = 'b';\n\n\nThe Past\nThe following sections are updated versions of the previous authors documentation.\n",
            "subsections": [
                {
                    "name": "Comparison with \"use constant\"",
                    "content": "Perl provides a facility for creating constant values, via the constant pragma. There are\nseveral problems with this pragma.\n\n• The constants created have no leading sigils.\n\n• These constants cannot be interpolated into strings.\n\n• Syntax can get dicey sometimes.  For example:\n\nuse constant CARRAY => (2, 3, 5, 7, 11, 13);\n$aprime = CARRAY[2];        # wrong!\n$aprime = (CARRAY)[2];      # right -- MUST use parentheses\n\n• You have to be very careful in places where barewords are allowed.\n\nFor example:\n\nuse constant SOMEKEY => 'key';\n%hash = (key => 'value', otherkey => 'othervalue');\n$somevalue = $hash{SOMEKEY};        # wrong!\n$somevalue = $hash{+SOMEKEY};       # right\n\n(who thinks to use a unary plus when using a hash to scalarize the key?)\n\n• \"use constant\" works for scalars and arrays, not hashes.\n\n• These  constants  are  global to the package in which they're declared; cannot be lexically\nscoped.\n\n• Works only at compile time.\n\n• Can be overridden:\n\nuse constant PI => 3.14159;\n...\nuse constant PI => 2.71828;\n\n(this does generate a warning, however, if you have warnings enabled).\n\n• It is very difficult to make and use deep structures (complex data  structures)  with  \"use\nconstant\".\n"
                }
            ]
        },
        "Comparison with typeglob constants": {
            "content": "Another  popular  way to create read-only scalars is to modify the symbol table entry for the\nvariable by using a typeglob:\n\n*a = \\'value';\n\nThis works fine, but it only works for global variables (\"my\" variables have no symbol  table\nentry). Also, the following similar constructs do not work:\n\n*a = [1, 2, 3];      # Does NOT create a read-only array\n*a = { a => 'A'};    # Does NOT create a read-only hash\n",
            "subsections": [
                {
                    "name": "Pros",
                    "content": "Readonly.pm,  on  the  other  hand,  will  work with global variables and with lexical (\"my\")\nvariables. It will create scalars, arrays, or hashes, all of which look and work like normal,\nread-write Perl variables. You can use them in scalar context, in list context; you can  take\nreferences to them, pass them to functions, anything.\n\nReadonly.pm  also  works  well  with  complex  data structures, allowing you to tag the whole\nstructure as nonmodifiable, or just the top level.\n\nAlso, Readonly variables may not be reassigned. The following code will die:\n\nReadonly::Scalar $pi => 3.14159;\n...\nReadonly::Scalar $pi => 2.71828;\n"
                },
                {
                    "name": "Cons",
                    "content": "Readonly.pm used to impose a performance penalty. It was  pretty  slow.  How  slow?  Run  the\n\"eg/benchmark.pl\" script that comes with Readonly. On my test system, \"use constant\" (const),\ntypeglob  constants  (tglob), regular read/write Perl variables (normal/literal), and the new\nReadonly (ro/rosimple) are all  about  the  same  speed,  the  old,  tie  based  Readonly.pm\nconstants were about 1/22 the speed.\n\nHowever,  there  is  relief.  There is a companion module available, Readonly::XS.  You won't\nneed this if you're using Perl 5.8.x or higher.\n\nI repeat, you do not need Readonly::XS if your environment has perl 5.8.x or  higher.  Please\nsee section entitled Internals for more.\n"
                }
            ]
        },
        "Functions": {
            "content": "Readonly::Scalar $var => $value;\nCreates  a  nonmodifiable  scalar, $var, and assigns a value of $value to it. Thereafter,\nits value may not be changed. Any attempt to modify the value will cause your program  to\ndie.\n\nA value must be supplied. If you want the variable to have \"undef\" as its value, you must\nspecify \"undef\".\n\nIf  $value  is  a reference to a scalar, array, or hash, then this function will mark the\nscalar, array, or hash it points to as being Readonly as well, and  it  will  recursively\ntraverse  the  structure,  marking the whole thing as Readonly. Usually, this is what you\nwant. However, if you want only the $value marked as Readonly, use \"Scalar1\".\n\nIf $var is already a Readonly  variable,  the  program  will  die  with  an  error  about\nreassigning Readonly variables.\n\nReadonly::Array @arr => (value, value, ...);\nCreates  a  nonmodifiable  array,  @arr,  and assigns the specified list of values to it.\nThereafter, none of its values may be  changed;  the  array  may  not  be  lengthened  or\nshortened or spliced. Any attempt to do so will cause your program to die.\n\nIf  any  of  the  values  passed  is  a  reference to a scalar, array, or hash, then this\nfunction will mark the scalar, array, or hash it points to as being Readonly as well, and\nit will recursively traverse the structure, marking the whole thing as Readonly. Usually,\nthis is what you want. However, if  you  want  only  the  hash  %@arr  itself  marked  as\nReadonly, use \"Array1\".\n\nIf  @arr  is  already  a  Readonly  variable,  the  program  will die with an error about\nreassigning Readonly variables.\n\nReadonly::Hash %h => (key => value, key => value, ...);\nReadonly::Hash %h => {key => value, key => value, ...};\nCreates a nonmodifiable hash, %h, and assigns  the  specified  keys  and  values  to  it.\nThereafter,  its  keys or values may not be changed. Any attempt to do so will cause your\nprogram to die.\n\nA list of keys and values may be specified (with parentheses in the synopsis above), or a\nhash reference may be specified (curly braces in  the  synopsis  above).  If  a  list  is\nspecified, it must have an even number of elements, or the function will die.\n\nIf  any of the values is a reference to a scalar, array, or hash, then this function will\nmark the scalar, array, or hash it points to as being  Readonly  as  well,  and  it  will\nrecursively traverse the structure, marking the whole thing as Readonly. Usually, this is\nwhat  you  want.  However,  if  you  want only the hash %h itself marked as Readonly, use\n\"Hash1\".\n\nIf %h is already  a  Readonly  variable,  the  program  will  die  with  an  error  about\nreassigning Readonly variables.\n\nReadonly $var => $value;\nReadonly @arr => (value, value, ...);\nReadonly %h => (key => value, ...);\nReadonly %h => {key => value, ...};\nReadonly $var;\nThe  \"Readonly\"  function is an alternate to the \"Scalar\", \"Array\", and \"Hash\" functions.\nIt has the advantage (if you consider it an advantage) of being one  function.  That  may\nmake your program look neater, if you're initializing a whole bunch of constants at once.\nYou may or may not prefer this uniform style.\n\nIt  has the disadvantage of having a slightly different syntax for versions of Perl prior\nto 5.8.  For earlier versions, you  must  supply  a  backslash,  because  it  requires  a\nreference as the first parameter.\n\nReadonly \\$var => $value;\nReadonly \\@arr => (value, value, ...);\nReadonly \\%h   => (key => value, ...);\nReadonly \\%h   => {key => value, ...};\n\nYou may or may not consider this ugly.\n\nNote  that  you  can  create  implicit  undefined  variables  with  this function like so\n\"Readonly my $var;\" while a verbose undefined  value  must  be  passed  to  the  standard\n\"Scalar\", \"Array\", and \"Hash\" functions.\n\nReadonly::Scalar1 $var => $value;\nReadonly::Array1 @arr => (value, value, ...);\nReadonly::Hash1 %h => (key => value, key => value, ...);\nReadonly::Hash1 %h => {key => value, key => value, ...};\nThese  alternate  functions  create shallow Readonly variables, instead of deep ones. For\nexample:\n\nReadonly::Array1 @shal => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);\nReadonly::Array  @deep => (1, 2, {perl=>'Rules', java=>'Bites'}, 4, 5);\n\n$shal[1] = 7;           # error\n$shal[2]{APL}='Weird';  # Allowed! since the hash isn't Readonly\n$deep[1] = 7;           # error\n$deep[2]{APL}='Weird';  # error, since the hash is Readonly\n",
            "subsections": []
        },
        "Cloning": {
            "content": "When cloning using Storable or Clone you will notice that the value stays readonly, which  is\ncorrect.  If  you  want to clone the value without copying the readonly flag, use the \"Clone\"\nfunction:\n\nReadonly::Scalar my $scalar => {qw[this that]};\n# $scalar->{'eh'} = 'foo'; # Modification of a read-only value attempted\nmy $scalarclone = Readonly::Clone $scalar;\n$scalarclone->{'eh'} = 'foo';\n# $scalarclone is now {this => 'that', eh => 'foo'};\n\nThe new variable ($scalarclone) is a mutable clone of the original $scalar.\n",
            "subsections": []
        },
        "Examples": {
            "content": "These are a few very simple examples:\n",
            "subsections": [
                {
                    "name": "Scalars",
                    "content": "A plain old read-only value\n\nReadonly::Scalar $a => \"A string value\";\n\nThe value need not be a compile-time constant:\n\nReadonly::Scalar $a => $computedvalue;\n"
                },
                {
                    "name": "Arrays/Lists",
                    "content": "A read-only array:\n\nReadonly::Array @a => (1, 2, 3, 4);\n\nThe parentheses are optional:\n\nReadonly::Array @a => 1, 2, 3, 4;\n\nYou can use Perl's built-in array quoting syntax:\n\nReadonly::Array @a => qw/1 2 3 4/;\n\nYou can initialize a read-only array from a variable one:\n\nReadonly::Array @a => @computedvalues;\n\nA read-only array can be empty, too:\n\nReadonly::Array @a => ();\nReadonly::Array @a;        # equivalent\n"
                },
                {
                    "name": "Hashes",
                    "content": "Typical usage:\n\nReadonly::Hash %a => (key1 => 'value1', key2 => 'value2');\n\nA read-only hash can be initialized from a variable one:\n\nReadonly::Hash %a => %computedvalues;\n\nA read-only hash can be empty:\n\nReadonly::Hash %a => ();\nReadonly::Hash %a;        # equivalent\n\nIf you pass an odd number of values, the program will die:\n\nReadonly::Hash %a => (key1 => 'value1', \"value2\");\n# This dies with \"May not store an odd number of values in a hash\"\n"
                }
            ]
        },
        "Exports": {
            "content": "Historically, this module exports the \"Readonly\" symbol into the calling program's  namespace\nby  default.  The  following  symbols are also available for import into your program, if you\nlike: \"Scalar\", \"Scalar1\", \"Array\", \"Array1\", \"Hash\", and \"Hash1\".\n",
            "subsections": []
        },
        "Internals": {
            "content": "Some people simply do not understand the relationship between this module and Readonly::XS so\nI'm adding this section. Odds are, they still won't understand but I like to write so...\n\nIn  the  past,  Readonly's  \"magic\"  was  performed   by   \"tie()\"-ing   variables   to   the\n\"Readonly::Scalar\", \"Readonly::Array\", and \"Readonly::Hash\" packages (not to be confused with\nthe  functions  of  the  same names) and acting on \"WRITE\", \"READ\", et. al. While this worked\nwell, it was slow. Very slow. Like 20-30 times slower than accessing  variables  directly  or\nusing one of the other const-related modules that have cropped up since Readonly was released\nin 2003.\n\nTo 'fix' this, Readonly::XS was written. If installed, Readonly::XS used the internal methods\n\"SvREADONLY\"  and  \"SvREADONLYon\"  to  lock  simple  scalars. On the surface, everything was\npeachy but things weren't the same behind the scenes. In  edge  cases,  code  performed  very\ndifferently if Readonly::XS was installed and because it wasn't a required dependency in most\ncode, it made downstream bugs very hard to track.\n\nIn  the  years  since  Readonly::XS was released, the then private internal methods have been\nexposed and can be used in pure perl. Similar modules were written to take advantage of  this\nand a patch to Readonly was created. We no longer need to build and install another module to\nmake Readonly useful on modern builds of perl.\n\n•   You do not need to install Readonly::XS.\n\n•   You should stop listing Readonly::XS as a dependency or expect it to be installed.\n\n•   Stop testing the $Readonly::XSokay variable!\n",
            "subsections": []
        },
        "Requirements": {
            "content": "Please  note  that  most  users  of  Readonly  no longer need to install the companion module\nReadonly::XS which is recommended but not required for perl 5.6.x and under.  Please  do  not\nforce  it  as a requirement in new code and do not use the package variable $Readonly::XSokay\nin code/tests. For more, see \"Internals\" in the section on Readonly's new internals.\n\nThere are no non-core requirements.\n",
            "subsections": []
        },
        "Bug Reports": {
            "content": "If email is better for you, my address is mentioned below but I would rather have  bugs  sent\nthrough the issue tracker found at http://github.com/sanko/readonly/issues.\n",
            "subsections": []
        },
        "Acknowledgements": {
            "content": "Thanks  to Slaven Rezic for the idea of one common function (Readonly) for all three types of\nvariables (13 April 2002).\n\nThanks to Ernest Lergon for the idea (and initial code) for deeply-Readonly  data  structures\n(21 May 2002).\n\nThanks  to  Damian Conway for the idea (and code) for making the Readonly function work a lot\nsmoother under perl 5.8+.\n",
            "subsections": []
        },
        "Author": {
            "content": "Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/\n\nCPAN ID: SANKO\n\nOriginal author: Eric J. Roode, roode@cpan.org\n",
            "subsections": []
        },
        "License and Legal": {
            "content": "Copyright (C) 2013-2016 by Sanko Robinson <sanko@cpan.org>\n\nCopyright (c) 2001-2004 by Eric J. Roode. All Rights Reserved.\n\nThis module is free software; you can redistribute it and/or modify it under the  same  terms\nas Perl itself.\n\nperl v5.32.0                                 2021-01-21                                Readonly(3pm)",
            "subsections": []
        }
    },
    "summary": "Readonly - Facility for creating read-only scalars, arrays, hashes",
    "flags": [],
    "examples": [],
    "see_also": [],
    "tldr": {
        "source": "official",
        "description": "Set read-only shell variables.",
        "examples": [
            {
                "description": "Set a read-only variable",
                "command": "readonly {{variable_name}}={{value}}"
            },
            {
                "description": "Mark a variable as read-only",
                "command": "readonly {{existing_variable}}"
            },
            {
                "description": "[p]rint the names and values of all read-only variables to `stdout`",
                "command": "readonly -p"
            }
        ]
    }
}