{
    "content": [
        {
            "type": "text",
            "text": "# perldata(1) (man)\n\n**Summary:** perldata - Perl data types\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **DESCRIPTION** (1 lines) — 10 subsections\n  - Variable names (72 lines)\n  - Identifier parsing (106 lines)\n  - Context (40 lines)\n  - Scalar values (103 lines)\n  - Scalar value constructors (206 lines)\n  - List value constructors (241 lines)\n  - Subscripts (27 lines)\n  - Multi-dimensional array emulation (11 lines)\n  - Slices (96 lines)\n  - Typeglobs and Filehandles (75 lines)\n- **SEE ALSO** (7 lines)\n\n## Full Content\n\n### NAME\n\nperldata - Perl data types\n\n### DESCRIPTION\n\n#### Variable names\n\nPerl has three built-in data types: scalars, arrays of scalars, and associative arrays of\nscalars, known as \"hashes\".  A scalar is a single string (of any size, limited only by the\navailable memory), number, or a reference to something (which will be discussed in perlref).\nNormal arrays are ordered lists of scalars indexed by number, starting with 0.  Hashes are\nunordered collections of scalar values indexed by their associated string key.\n\nValues are usually referred to by name, or through a named reference.  The first character of\nthe name tells you to what sort of data structure it refers.  The rest of the name tells you\nthe particular value to which it refers.  Usually this name is a single identifier, that is,\na string beginning with a letter or underscore, and containing letters, underscores, and\ndigits.  In some cases, it may be a chain of identifiers, separated by \"::\" (or by the\nslightly archaic \"'\"); all but the last are interpreted as names of packages, to locate the\nnamespace in which to look up the final identifier (see \"Packages\" in perlmod for details).\nFor a more in-depth discussion on identifiers, see \"Identifier parsing\".  It's possible to\nsubstitute for a simple identifier, an expression that produces a reference to the value at\nruntime.   This is described in more detail below and in perlref.\n\nPerl also has its own built-in variables whose names don't follow these rules.  They have\nstrange names so they don't accidentally collide with one of your normal variables.  Strings\nthat match parenthesized parts of a regular expression are saved under names containing only\ndigits after the \"$\" (see perlop and perlre).  In addition, several special variables that\nprovide windows into the inner working of Perl have names containing punctuation characters.\nThese are documented in perlvar.\n\nScalar values are always named with '$', even when referring to a scalar that is part of an\narray or a hash.  The '$' symbol works semantically like the English word \"the\" in that it\nindicates a single value is expected.\n\n$days               # the simple scalar value \"days\"\n$days[28]           # the 29th element of array @days\n$days{'Feb'}        # the 'Feb' value from hash %days\n$#days              # the last index of array @days\n\nEntire arrays (and slices of arrays and hashes) are denoted by '@', which works much as the\nword \"these\" or \"those\" does in English, in that it indicates multiple values are expected.\n\n@days               # ($days[0], $days[1],... $days[n])\n@days[3,4,5]        # same as ($days[3],$days[4],$days[5])\n@days{'a','c'}      # same as ($days{'a'},$days{'c'})\n\nEntire hashes are denoted by '%':\n\n%days               # (key1, val1, key2, val2 ...)\n\nIn addition, subroutines are named with an initial '&', though this is optional when\nunambiguous, just as the word \"do\" is often redundant in English.  Symbol table entries can\nbe named with an initial '*', but you don't really care about that yet (if ever :-).\n\nEvery variable type has its own namespace, as do several non-variable identifiers.  This\nmeans that you can, without fear of conflict, use the same name for a scalar variable, an\narray, or a hash--or, for that matter, for a filehandle, a directory handle, a subroutine\nname, a format name, or a label.  This means that $foo and @foo are two different variables.\nIt also means that $foo[1] is a part of @foo, not a part of $foo.  This may seem a bit weird,\nbut that's okay, because it is weird.\n\nBecause variable references always start with '$', '@', or '%', the \"reserved\" words aren't\nin fact reserved with respect to variable names.  They are reserved with respect to labels\nand filehandles, however, which don't have an initial special character.  You can't have a\nfilehandle named \"log\", for instance.  Hint: you could say \"open(LOG,'logfile')\" rather than\n\"open(log,'logfile')\".  Using uppercase filehandles also improves readability and protects\nyou from conflict with future reserved words.  Case is significant--\"FOO\", \"Foo\", and \"foo\"\nare all different names.  Names that start with a letter or underscore may also contain\ndigits and underscores.\n\nIt is possible to replace such an alphanumeric name with an expression that returns a\nreference to the appropriate type.  For a description of this, see perlref.\n\nNames that start with a digit may contain only more digits.  Names that do not start with a\nletter, underscore, digit or a caret are limited to one character, e.g.,  $% or $$.  (Most of\nthese one character names have a predefined significance to Perl.  For instance, $$ is the\ncurrent process id.  And all such names are reserved for Perl's possible use.)\n\n#### Identifier parsing\n\nUp until Perl 5.18, the actual rules of what a valid identifier was were a bit fuzzy.\nHowever, in general, anything defined here should work on previous versions of Perl, while\nthe opposite -- edge cases that work in previous versions, but aren't defined here --\nprobably won't work on newer versions.  As an important side note, please note that the\nfollowing only applies to bareword identifiers as found in Perl source code, not identifiers\nintroduced through symbolic references, which have much fewer restrictions.  If working under\nthe effect of the \"use utf8;\" pragma, the following rules apply:\n\n/ (?[ ( \\p{Word} & \\p{XIDStart} ) + [] ])\n(?[ ( \\p{Word} & \\p{XIDContinue} ) ]) *    /x\n\nThat is, a \"start\" character followed by any number of \"continue\" characters.  Perl requires\nevery character in an identifier to also match \"\\w\" (this prevents some problematic cases);\nand Perl additionally accepts identifier names beginning with an underscore.\n\nIf not under \"use utf8\", the source is treated as ASCII + 128 extra generic characters, and\nidentifiers should match\n\n/ (?aa) (?!\\d) \\w+ /x\n\nThat is, any word character in the ASCII range, as long as the first character is not a\ndigit.\n\nThere are two package separators in Perl: A double colon (\"::\") and a single quote (\"'\").\nNormal identifiers can start or end with a double colon, and can contain several parts\ndelimited by double colons.  Single quotes have similar rules, but with the exception that\nthey are not legal at the end of an identifier: That is, \"$'foo\" and \"$foo'bar\" are legal,\nbut \"$foo'bar'\" is not.\n\nAdditionally, if the identifier is preceded by a sigil -- that is, if the identifier is part\nof a variable name -- it may optionally be enclosed in braces.\n\nWhile you can mix double colons with singles quotes, the quotes must come after the colons:\n\"$::::'foo\" and \"$foo::'bar\" are legal, but \"$::'::foo\" and \"$foo'::bar\" are not.\n\nPut together, a grammar to match a basic identifier becomes\n\n/\n(?(DEFINE)\n(?<variable>\n(?&sigil)\n(?:\n(?&normalidentifier)\n|   \\{ \\s* (?&normalidentifier) \\s* \\}\n)\n)\n(?<normalidentifier>\n(?: :: )* '?\n(?&basicidentifier)\n(?: (?= (?: :: )+ '? | (?: :: )* ' ) (?&normalidentifier) )?\n(?: :: )*\n)\n(?<basicidentifier>\n# is use utf8 on?\n(?(?{ (caller(0))[8] & $utf8::hintbits })\n(?&PerlXIDS) (?&PerlXIDC)*\n| (?aa) (?!\\d) \\w+\n)\n)\n(?<sigil> [&*\\$\\@\\%])\n(?<PerlXIDS> (?[ ( \\p{Word} & \\p{XIDStart} ) + [] ]) )\n(?<PerlXIDC> (?[ \\p{Word} & \\p{XIDContinue} ]) )\n)\n/x\n\nMeanwhile, special identifiers don't follow the above rules; For the most part, all of the\nidentifiers in this category have a special meaning given by Perl.  Because they have special\nparsing rules, these generally can't be fully-qualified.  They come in six forms (but don't\nuse forms 5 and 6):\n\n1.  A sigil, followed solely by digits matching \"\\p{POSIXDigit}\", like $0, $1, or $10000.\n\n2.  A sigil followed by a single character matching the \"\\p{POSIXPunct}\" property, like $!\nor \"%+\", except the character \"{\" doesn't work.\n\n3.  A sigil, followed by a caret and any one of the characters \"[][A-Z^?\\]\", like $^V or\n$^].\n\n4.  Similar to the above, a sigil, followed by bareword text in braces, where the first\ncharacter is a caret.  The next character is any one of the characters \"[][A-Z^?\\]\",\nfollowed by ASCII word characters.  An example is \"${^GLOBALPHASE}\".\n\n5.  A sigil, followed by any single character in the range \"[\\xA1-\\xAC\\xAE-\\xFF]\" when not\nunder \"use utf8\".  (Under \"use utf8\", the normal identifier rules given earlier in this\nsection apply.)  Use of non-graphic characters (the C1 controls, the NO-BREAK SPACE, and\nthe SOFT HYPHEN) has been disallowed since v5.26.0.  The use of the other characters is\nunwise, as these are all reserved to have special meaning to Perl, and none of them\ncurrently do have special meaning, though this could change without notice.\n\nNote that an implication of this form is that there are identifiers only legal under\n\"use utf8\", and vice-versa, for example the identifier \"$état\" is legal under \"use utf8\",\nbut is otherwise considered to be the single character variable $é followed by the\nbareword \"tat\", the combination of which is a syntax error.\n\n6.  This is a combination of the previous two forms.  It is valid only when not under\n\"use utf8\" (normal identifier rules apply when under \"use utf8\").  The form is a sigil,\nfollowed by text in braces, where the first character is any one of the characters in the\nrange \"[\\x80-\\xFF]\" followed by ASCII word characters up to the trailing brace.\n\nThe same caveats as the previous form apply:  The non-graphic characters are no longer\nallowed with \"use utf8\", it is unwise to use this form at all, and utf8ness makes a big\ndifference.\n\nPrior to Perl v5.24, non-graphical ASCII control characters were also allowed in some\nsituations; this had been deprecated since v5.20.\n\n#### Context\n\nThe interpretation of operations and values in Perl sometimes depends on the requirements of\nthe context around the operation or value.  There are two major contexts: list and scalar.\nCertain operations return list values in contexts wanting a list, and scalar values\notherwise.  If this is true of an operation it will be mentioned in the documentation for\nthat operation.  In other words, Perl overloads certain operations based on whether the\nexpected return value is singular or plural.  Some words in English work this way, like\n\"fish\" and \"sheep\".\n\nIn a reciprocal fashion, an operation provides either a scalar or a list context to each of\nits arguments.  For example, if you say\n\nint( <STDIN> )\n\nthe integer operation provides scalar context for the <> operator, which responds by reading\none line from STDIN and passing it back to the integer operation, which will then find the\ninteger value of that line and return that.  If, on the other hand, you say\n\nsort( <STDIN> )\n\nthen the sort operation provides list context for <>, which will proceed to read every line\navailable up to the end of file, and pass that list of lines back to the sort routine, which\nwill then sort those lines and return them as a list to whatever the context of the sort was.\n\nAssignment is a little bit special in that it uses its left argument to determine the context\nfor the right argument.  Assignment to a scalar evaluates the right-hand side in scalar\ncontext, while assignment to an array or hash evaluates the righthand side in list context.\nAssignment to a list (or slice, which is just a list anyway) also evaluates the right-hand\nside in list context.\n\nWhen you use the \"use warnings\" pragma or Perl's -w command-line option, you may see warnings\nabout useless uses of constants or functions in \"void context\".  Void context just means the\nvalue has been discarded, such as a statement containing only \"\"fred\";\" or \"getpwuid(0);\".\nIt still counts as scalar context for functions that care whether or not they're being called\nin list context.\n\nUser-defined subroutines may choose to care whether they are being called in a void, scalar,\nor list context.  Most subroutines do not need to bother, though.  That's because both\nscalars and lists are automatically interpolated into lists.  See \"wantarray\" in perlfunc for\nhow you would dynamically discern your function's calling context.\n\n#### Scalar values\n\nAll data in Perl is a scalar, an array of scalars, or a hash of scalars.  A scalar may\ncontain one single value in any of three different flavors: a number, a string, or a\nreference.  In general, conversion from one form to another is transparent.  Although a\nscalar may not directly hold multiple values, it may contain a reference to an array or hash\nwhich in turn contains multiple values.\n\nScalars aren't necessarily one thing or another.  There's no place to declare a scalar\nvariable to be of type \"string\", type \"number\", type \"reference\", or anything else.  Because\nof the automatic conversion of scalars, operations that return scalars don't need to care\n(and in fact, cannot care) whether their caller is looking for a string, a number, or a\nreference.  Perl is a contextually polymorphic language whose scalars can be strings,\nnumbers, or references (which includes objects).  Although strings and numbers are considered\npretty much the same thing for nearly all purposes, references are strongly-typed, uncastable\npointers with builtin reference-counting and destructor invocation.\n\nA scalar value is interpreted as FALSE in the Boolean sense if it is undefined, the null\nstring or the number 0 (or its string equivalent, \"0\"), and TRUE if it is anything else.  The\nBoolean context is just a special kind of scalar context where no conversion to a string or a\nnumber is ever performed.  Negation of a true value by \"!\" or \"not\" returns a special false\nvalue.  When evaluated as a string it is treated as \"\", but as a number, it is treated as 0.\nMost Perl operators that return true or false behave this way.\n\nThere are actually two varieties of null strings (sometimes referred to as \"empty\" strings),\na defined one and an undefined one.  The defined version is just a string of length zero,\nsuch as \"\".  The undefined version is the value that indicates that there is no real value\nfor something, such as when there was an error, or at end of file, or when you refer to an\nuninitialized variable or element of an array or hash.  Although in early versions of Perl,\nan undefined scalar could become defined when first used in a place expecting a defined\nvalue, this no longer happens except for rare cases of autovivification as explained in\nperlref.  You can use the defined() operator to determine whether a scalar value is defined\n(this has no meaning on arrays or hashes), and the undef() operator to produce an undefined\nvalue.\n\nTo find out whether a given string is a valid non-zero number, it's sometimes enough to test\nit against both numeric 0 and also lexical \"0\" (although this will cause noises if warnings\nare on).  That's because strings that aren't numbers count as 0, just as they do in awk:\n\nif ($str == 0 && $str ne \"0\")  {\nwarn \"That doesn't look like a number\";\n}\n\nThat method may be best because otherwise you won't treat IEEE notations like \"NaN\" or\n\"Infinity\" properly.  At other times, you might prefer to determine whether string data can\nbe used numerically by calling the POSIX::strtod() function or by inspecting your string with\na regular expression (as documented in perlre).\n\nwarn \"has nondigits\"        if     /\\D/;\nwarn \"not a natural number\" unless /^\\d+$/;             # rejects -3\nwarn \"not an integer\"       unless /^-?\\d+$/;           # rejects +3\nwarn \"not an integer\"       unless /^[+-]?\\d+$/;\nwarn \"not a decimal number\" unless /^-?\\d+\\.?\\d*$/;     # rejects .2\nwarn \"not a decimal number\" unless /^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$/;\nwarn \"not a C float\"\nunless /^([+-]?)(?=\\d|\\.\\d)\\d*(\\.\\d*)?([Ee]([+-]?\\d+))?$/;\n\nThe length of an array is a scalar value.  You may find the length of array @days by\nevaluating $#days, as in csh.  However, this isn't the length of the array; it's the\nsubscript of the last element, which is a different value since there is ordinarily a 0th\nelement.  Assigning to $#days actually changes the length of the array.  Shortening an array\nthis way destroys intervening values.  Lengthening an array that was previously shortened\ndoes not recover values that were in those elements.\n\nYou can also gain some minuscule measure of efficiency by pre-extending an array that is\ngoing to get big.  You can also extend an array by assigning to an element that is off the\nend of the array.  You can truncate an array down to nothing by assigning the null list () to\nit.  The following are equivalent:\n\n@whatever = ();\n$#whatever = -1;\n\nIf you evaluate an array in scalar context, it returns the length of the array.  (Note that\nthis is not true of lists, which return the last value, like the C comma operator, nor of\nbuilt-in functions, which return whatever they feel like returning.)  The following is always\ntrue:\n\nscalar(@whatever) == $#whatever + 1;\n\nSome programmers choose to use an explicit conversion so as to leave nothing to doubt:\n\n$elementcount = scalar(@whatever);\n\nIf you evaluate a hash in scalar context, it returns a false value if the hash is empty.  If\nthere are any key/value pairs, it returns a true value.  A more precise definition is version\ndependent.\n\nPrior to Perl 5.25 the value returned was a string consisting of the number of used buckets\nand the number of allocated buckets, separated by a slash.  This is pretty much useful only\nto find out whether Perl's internal hashing algorithm is performing poorly on your data set.\nFor example, you stick 10,000 things in a hash, but evaluating %HASH in scalar context\nreveals \"1/16\", which means only one out of sixteen buckets has been touched, and presumably\ncontains all 10,000 of your items.  This isn't supposed to happen.\n\nAs of Perl 5.25 the return was changed to be the count of keys in the hash. If you need\naccess to the old behavior you can use \"Hash::Util::bucketratio()\" instead.\n\nIf a tied hash is evaluated in scalar context, the \"SCALAR\" method is called (with a fallback\nto \"FIRSTKEY\").\n\nYou can preallocate space for a hash by assigning to the keys() function.  This rounds up the\nallocated buckets to the next power of two:\n\nkeys(%users) = 1000;                # allocate 1024 buckets\n\n#### Scalar value constructors\n\nNumeric literals are specified in any of the following floating point or integer formats:\n\n12345\n12345.67\n.23E-10             # a very small number\n3.141592          # a very important number\n4294967296       # underscore for legibility\n0xff                # hex\n0xdeadbeef         # more hex\n0377                # octal (only numbers, begins with 0)\n0o12345            # alternative octal (introduced in Perl 5.33.5)\n0b011011            # binary\n0x1.999ap-4         # hexadecimal floating point (the 'p' is required)\n\nYou are allowed to use underscores (underbars) in numeric literals between digits for\nlegibility (but not multiple underscores in a row: \"23500\" is not legal; \"23500\" is).  You\ncould, for example, group binary digits by threes (as for a Unix-style mode argument such as\n0b110100100) or by fours (to represent nibbles, as in 0b10100110) or in other groups.\n\nString literals are usually delimited by either single or double quotes.  They work much like\nquotes in the standard Unix shells: double-quoted string literals are subject to backslash\nand variable substitution; single-quoted strings are not (except for \"\\'\" and \"\\\\\").  The\nusual C-style backslash rules apply for making characters such as newline, tab, etc., as well\nas some more exotic forms.  See \"Quote and Quote-like Operators\" in perlop for a list.\n\nHexadecimal, octal, or binary, representations in string literals (e.g. '0xff') are not\nautomatically converted to their integer representation.  The hex() and oct() functions make\nthese conversions for you.  See \"hex\" in perlfunc and \"oct\" in perlfunc for more details.\n\nHexadecimal floating point can start just like a hexadecimal literal, and it can be followed\nby an optional fractional hexadecimal part, but it must be followed by \"p\", an optional sign,\nand a power of two.  The format is useful for accurately presenting floating point values,\navoiding conversions to or from decimal floating point, and therefore avoiding possible loss\nin precision.  Notice that while most current platforms use the 64-bit IEEE 754 floating\npoint, not all do.  Another potential source of (low-order) differences are the floating\npoint rounding modes, which can differ between CPUs, operating systems, and compilers, and\nwhich Perl doesn't control.\n\nYou can also embed newlines directly in your strings, i.e., they can end on a different line\nthan they begin.  This is nice, but if you forget your trailing quote, the error will not be\nreported until Perl finds another line containing the quote character, which may be much\nfurther on in the script.  Variable substitution inside strings is limited to scalar\nvariables, arrays, and array or hash slices.  (In other words, names beginning with $ or @,\nfollowed by an optional bracketed expression as a subscript.)  The following code segment\nprints out \"The price is $100.\"\n\n$Price = '$100';    # not interpolated\nprint \"The price is $Price.\\n\";     # interpolated\n\nThere is no double interpolation in Perl, so the $100 is left as is.\n\nBy default floating point numbers substituted inside strings use the dot (\".\")  as the\ndecimal separator.  If \"use locale\" is in effect, and POSIX::setlocale() has been called, the\ncharacter used for the decimal separator is affected by the LCNUMERIC locale.  See\nperllocale and POSIX.\n\nAs in some shells, you can enclose the variable name in braces to disambiguate it from\nfollowing alphanumerics (and underscores).  You must also do this when interpolating a\nvariable into a string to separate the variable name from a following double-colon or an\napostrophe, since these would be otherwise treated as a package separator:\n\n$who = \"Larry\";\nprint PASSWD \"${who}::0:0:Superuser:/:/bin/perl\\n\";\nprint \"We use ${who}speak when ${who}'s here.\\n\";\n\nWithout the braces, Perl would have looked for a $whospeak, a $who::0, and a \"$who's\"\nvariable.  The last two would be the $0 and the $s variables in the (presumably) non-existent\npackage \"who\".\n\nIn fact, a simple identifier within such curlies is forced to be a string, and likewise\nwithin a hash subscript.  Neither need quoting.  Our earlier example, $days{'Feb'} can be\nwritten as $days{Feb} and the quotes will be assumed automatically.  But anything more\ncomplicated in the subscript will be interpreted as an expression.  This means for example\nthat \"$version{2.0}++\" is equivalent to \"$version{2}++\", not to \"$version{'2.0'}++\".\n\nSpecial floating point: infinity (Inf) and not-a-number (NaN)\n\nFloating point values include the special values \"Inf\" and \"NaN\", for infinity and not-a-\nnumber.  The infinity can be also negative.\n\nThe infinity is the result of certain math operations that overflow the floating point range,\nlike 999.  The not-a-number is the result when the result is undefined or\nunrepresentable.  Though note that you cannot get \"NaN\" from some common \"undefined\" or \"out-\nof-range\" operations like dividing by zero, or square root of a negative number, since Perl\ngenerates fatal errors for those.\n\nThe infinity and not-a-number have their own special arithmetic rules.  The general rule is\nthat they are \"contagious\": \"Inf\" plus one is \"Inf\", and \"NaN\" plus one is \"NaN\".  Where\nthings get interesting is when you combine infinities and not-a-numbers: \"Inf\" minus \"Inf\"\nand \"Inf\" divided by \"Inf\" are \"NaN\" (while \"Inf\" plus \"Inf\" is \"Inf\" and \"Inf\" times \"Inf\"\nis \"Inf\").  \"NaN\" is also curious in that it does not equal any number, including itself:\n\"NaN\" != \"NaN\".\n\nPerl doesn't understand \"Inf\" and \"NaN\" as numeric literals, but you can have them as\nstrings, and Perl will convert them as needed: \"Inf\" + 1.  (You can, however, import them\nfrom the POSIX extension; \"use POSIX qw(Inf NaN);\" and then use them as literals.)\n\nNote that on input (string to number) Perl accepts \"Inf\" and \"NaN\" in many forms.   Case is\nignored, and the Win32-specific forms like \"1.#INF\" are understood, but on output the values\nare normalized to \"Inf\" and \"NaN\".\n\nVersion Strings\n\nA literal of the form \"v1.20.300.4000\" is parsed as a string composed of characters with the\nspecified ordinals.  This form, known as v-strings, provides an alternative, more readable\nway to construct strings, rather than use the somewhat less readable interpolation form\n\"\\x{1}\\x{14}\\x{12c}\\x{fa0}\".  This is useful for representing Unicode strings, and for\ncomparing version \"numbers\" using the string comparison operators, \"cmp\", \"gt\", \"lt\" etc.  If\nthere are two or more dots in the literal, the leading \"v\" may be omitted.\n\nprint v9786;              # prints SMILEY, \"\\x{263a}\"\nprint v102.111.111;       # prints \"foo\"\nprint 102.111.111;        # same\n\nSuch literals are accepted by both \"require\" and \"use\" for doing a version check.  Note that\nusing the v-strings for IPv4 addresses is not portable unless you also use the\ninetaton()/inetntoa() routines of the Socket package.\n\nNote that since Perl 5.8.1 the single-number v-strings (like \"v65\") are not v-strings before\nthe \"=>\" operator (which is usually used to separate a hash key from a hash value); instead\nthey are interpreted as literal strings ('v65').  They were v-strings from Perl 5.6.0 to Perl\n5.8.0, but that caused more confusion and breakage than good.  Multi-number v-strings like\n\"v65.66\" and 65.66.67 continue to be v-strings always.\n\nSpecial Literals\n\nThe special literals FILE, LINE, and PACKAGE represent the current filename, line\nnumber, and package name at that point in your program.  SUB gives a reference to the\ncurrent subroutine.  They may be used only as separate tokens; they will not be interpolated\ninto strings.  If there is no current package (due to an empty \"package;\" directive),\nPACKAGE is the undefined value.  (But the empty \"package;\" is no longer supported, as of\nversion 5.10.)  Outside of a subroutine, SUB is the undefined value.  SUB is only\navailable in 5.16 or higher, and only with a \"use v5.16\" or \"use feature \"currentsub\"\"\ndeclaration.\n\nThe two control characters ^D and ^Z, and the tokens END and DATA may be used to\nindicate the logical end of the script before the actual end of file.  Any following text is\nignored by the interpreter unless read by the program as described below.\n\nText after DATA may be read via the filehandle \"PACKNAME::DATA\", where \"PACKNAME\" is the\npackage that was current when the DATA token was encountered.  The filehandle is left\nopen pointing to the line after DATA.  The program should \"close DATA\" when it is done\nreading from it.  (Leaving it open leaks filehandles if the module is reloaded for any\nreason, so it's a safer practice to close it.)  For compatibility with older scripts written\nbefore DATA was introduced, END behaves like DATA in the top level script (but\nnot in files loaded with \"require\" or \"do\") and leaves the remaining contents of the file\naccessible via \"main::DATA\".\n\nwhile (my $line = <DATA>) { print $line; }\nclose DATA;\nDATA\nHello world.\n\nThe \"DATA\" file handle by default has whatever PerlIO layers were in place when Perl read the\nfile to parse the source.  Normally that means that the file is being read bytewise, as if it\nwere encoded in Latin-1, but there are two major ways for it to be otherwise.  Firstly, if\nthe \"END\"/\"DATA\" token is in the scope of a \"use utf8\" pragma then the \"DATA\" handle\nwill be in UTF-8 mode.  And secondly, if the source is being read from perl's standard input\nthen the \"DATA\" file handle is actually aliased to the \"STDIN\" file handle, and may be in\nUTF-8 mode because of the \"PERLUNICODE\" environment variable or perl's command-line\nswitches.\n\nSee SelfLoader for more description of DATA, and an example of its use.  Note that you\ncannot read from the DATA filehandle in a BEGIN block: the BEGIN block is executed as soon as\nit is seen (during compilation), at which point the corresponding DATA (or END) token\nhas not yet been seen.\n\nBarewords\n\nA word that has no other interpretation in the grammar will be treated as if it were a quoted\nstring.  These are known as \"barewords\".  As with filehandles and labels, a bareword that\nconsists entirely of lowercase letters risks conflict with future reserved words, and if you\nuse the \"use warnings\" pragma or the -w switch, Perl will warn you about any such words.\nPerl limits barewords (like identifiers) to about 250 characters.  Future versions of Perl\nare likely to eliminate these arbitrary limitations.\n\nSome people may wish to outlaw barewords entirely.  If you say\n\nuse strict 'subs';\n\nthen any bareword that would NOT be interpreted as a subroutine call produces a compile-time\nerror instead.  The restriction lasts to the end of the enclosing block.  An inner block may\ncountermand this by saying \"no strict 'subs'\".\n\nArray Interpolation\n\nArrays and slices are interpolated into double-quoted strings by joining the elements with\nthe delimiter specified in the $\" variable ($LISTSEPARATOR if \"use English;\" is specified),\nspace by default.  The following are equivalent:\n\n$temp = join($\", @ARGV);\nsystem \"echo $temp\";\n\nsystem \"echo @ARGV\";\n\nWithin search patterns (which also undergo double-quotish substitution) there is an\nunfortunate ambiguity:  Is \"/$foo[bar]/\" to be interpreted as \"/${foo}[bar]/\" (where \"[bar]\"\nis a character class for the regular expression) or as \"/${foo[bar]}/\" (where \"[bar]\" is the\nsubscript to array @foo)?  If @foo doesn't otherwise exist, then it's obviously a character\nclass.  If @foo exists, Perl takes a good guess about \"[bar]\", and is almost always right.\nIf it does guess wrong, or if you're just plain paranoid, you can force the correct\ninterpretation with curly braces as above.\n\nIf you're looking for the information on how to use here-documents, which used to be here,\nthat's been moved to \"Quote and Quote-like Operators\" in perlop.\n\n#### List value constructors\n\nList values are denoted by separating individual values by commas (and enclosing the list in\nparentheses where precedence requires it):\n\n(LIST)\n\nIn a context not requiring a list value, the value of what appears to be a list literal is\nsimply the value of the final element, as with the C comma operator.  For example,\n\n@foo = ('cc', '-E', $bar);\n\nassigns the entire list value to array @foo, but\n\n$foo = ('cc', '-E', $bar);\n\nassigns the value of variable $bar to the scalar variable $foo.  Note that the value of an\nactual array in scalar context is the length of the array; the following assigns the value 3\nto $foo:\n\n@foo = ('cc', '-E', $bar);\n$foo = @foo;                # $foo gets 3\n\nYou may have an optional comma before the closing parenthesis of a list literal, so that you\ncan say:\n\n@foo = (\n1,\n2,\n3,\n);\n\nTo use a here-document to assign an array, one line per element, you might use an approach\nlike this:\n\n@sauces = <<EndLines =~ m/(\\S.*\\S)/g;\nnormal tomato\nspicy tomato\ngreen chile\npesto\nwhite wine\nEndLines\n\nLISTs do automatic interpolation of sublists.  That is, when a LIST is evaluated, each\nelement of the list is evaluated in list context, and the resulting list value is\ninterpolated into LIST just as if each individual element were a member of LIST.  Thus arrays\nand hashes lose their identity in a LIST--the list\n\n(@foo,@bar,&SomeSub,%glarch)\n\ncontains all the elements of @foo followed by all the elements of @bar, followed by all the\nelements returned by the subroutine named SomeSub called in list context, followed by the\nkey/value pairs of %glarch.  To make a list reference that does NOT interpolate, see perlref.\n\nThe null list is represented by ().  Interpolating it in a list has no effect.  Thus\n((),(),()) is equivalent to ().  Similarly, interpolating an array with no elements is the\nsame as if no array had been interpolated at that point.\n\nThis interpolation combines with the facts that the opening and closing parentheses are\noptional (except when necessary for precedence) and lists may end with an optional comma to\nmean that multiple commas within lists are legal syntax.  The list \"1,,3\" is a concatenation\nof two lists, \"1,\" and 3, the first of which ends with that optional comma.  \"1,,3\" is\n\"(1,),(3)\" is \"1,3\" (And similarly for \"1,,,3\" is \"(1,),(,),3\" is \"1,3\" and so on.)  Not that\nwe'd advise you to use this obfuscation.\n\nA list value may also be subscripted like a normal array.  You must put the list in\nparentheses to avoid ambiguity.  For example:\n\n# Stat returns list value.\n$time = (stat($file))[8];\n\n# SYNTAX ERROR HERE.\n$time = stat($file)[8];  # OOPS, FORGOT PARENTHESES\n\n# Find a hex digit.\n$hexdigit = ('a','b','c','d','e','f')[$digit-10];\n\n# A \"reverse comma operator\".\nreturn (pop(@foo),pop(@foo))[0];\n\nLists may be assigned to only when each element of the list is itself legal to assign to:\n\n($x, $y, $z) = (1, 2, 3);\n\n($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);\n\nAn exception to this is that you may assign to \"undef\" in a list.  This is useful for\nthrowing away some of the return values of a function:\n\n($dev, $ino, undef, undef, $uid, $gid) = stat($file);\n\nAs of Perl 5.22, you can also use \"(undef)x2\" instead of \"undef, undef\".  (You can also do\n\"($x) x 2\", which is less useful, because it assigns to the same variable twice, clobbering\nthe first value assigned.)\n\nWhen you assign a list of scalars to an array, all previous values in that array are wiped\nout and the number of elements in the array will now be equal to the number of elements in\nthe right-hand list -- the list from which assignment was made.  The array will automatically\nresize itself to precisely accommodate each element in the right-hand list.\n\nuse warnings;\nmy (@xyz, $x, $y, $z);\n\n@xyz = (1, 2, 3);\nprint \"@xyz\\n\";                             # 1 2 3\n\n@xyz = ('al', 'be', 'ga', 'de');\nprint \"@xyz\\n\";                             # al be ga de\n\n@xyz = (101, 102);\nprint \"@xyz\\n\";                             # 101 102\n\nWhen, however, you assign a list of scalars to another list of scalars, the results differ\naccording to whether the left-hand list -- the list being assigned to -- has the same, more\nor fewer elements than the right-hand list.\n\n($x, $y, $z) = (1, 2, 3);\nprint \"$x $y $z\\n\";                         # 1 2 3\n\n($x, $y, $z) = ('al', 'be', 'ga', 'de');\nprint \"$x $y $z\\n\";                         # al be ga\n\n($x, $y, $z) = (101, 102);\nprint \"$x $y $z\\n\";                         # 101 102\n# Use of uninitialized value $z in concatenation (.)\n# or string at [program] line [line number].\n\nIf the number of scalars in the left-hand list is less than that in the right-hand list, the\n\"extra\" scalars in the right-hand list will simply not be assigned.\n\nIf the number of scalars in the left-hand list is greater than that in the left-hand list,\nthe \"missing\" scalars will become undefined.\n\n($x, $y, $z) = (101, 102);\nfor my $el ($x, $y, $z) {\n(defined $el) ? print \"$el \" : print \"<undef>\";\n}\nprint \"\\n\";\n# 101 102 <undef>\n\nList assignment in scalar context returns the number of elements produced by the expression\non the right side of the assignment:\n\n$x = (($foo,$bar) = (3,2,1));       # set $x to 3, not 2\n$x = (($foo,$bar) = f());           # set $x to f()'s return count\n\nThis is handy when you want to do a list assignment in a Boolean context, because most list\nfunctions return a null list when finished, which when assigned produces a 0, which is\ninterpreted as FALSE.\n\nIt's also the source of a useful idiom for executing a function or performing an operation in\nlist context and then counting the number of return values, by assigning to an empty list and\nthen using that assignment in scalar context.  For example, this code:\n\n$count = () = $string =~ /\\d+/g;\n\nwill place into $count the number of digit groups found in $string.  This happens because the\npattern match is in list context (since it is being assigned to the empty list), and will\ntherefore return a list of all matching parts of the string.  The list assignment in scalar\ncontext will translate that into the number of elements (here, the number of times the\npattern matched) and assign that to $count.  Note that simply using\n\n$count = $string =~ /\\d+/g;\n\nwould not have worked, since a pattern match in scalar context will only return true or\nfalse, rather than a count of matches.\n\nThe final element of a list assignment may be an array or a hash:\n\n($x, $y, @rest) = split;\nmy($x, $y, %rest) = @;\n\nYou can actually put an array or hash anywhere in the list, but the first one in the list\nwill soak up all the values, and anything after it will become undefined.  This may be useful\nin a my() or local().\n\nA hash can be initialized using a literal list holding pairs of items to be interpreted as a\nkey and a value:\n\n# same as map assignment above\n%map = ('red',0x00f,'blue',0x0f0,'green',0xf00);\n\nWhile literal lists and named arrays are often interchangeable, that's not the case for\nhashes.  Just because you can subscript a list value like a normal array does not mean that\nyou can subscript a list value as a hash.  Likewise, hashes included as parts of other lists\n(including parameters lists and return lists from functions) always flatten out into\nkey/value pairs.  That's why it's good to use references sometimes.\n\nIt is often more readable to use the \"=>\" operator between key/value pairs.  The \"=>\"\noperator is mostly just a more visually distinctive synonym for a comma, but it also arranges\nfor its left-hand operand to be interpreted as a string if it's a bareword that would be a\nlegal simple identifier.  \"=>\" doesn't quote compound identifiers, that contain double\ncolons.  This makes it nice for initializing hashes:\n\n%map = (\nred   => 0x00f,\nblue  => 0x0f0,\ngreen => 0xf00,\n);\n\nor for initializing hash references to be used as records:\n\n$rec = {\nwitch => 'Mable the Merciless',\ncat   => 'Fluffy the Ferocious',\ndate  => '10/31/1776',\n};\n\nor for using call-by-named-parameter to complicated functions:\n\n$field = $query->radiogroup(\nname      => 'groupname',\nvalues    => ['eenie','meenie','minie'],\ndefault   => 'meenie',\nlinebreak => 'true',\nlabels    => \\%labels\n);\n\nNote that just because a hash is initialized in that order doesn't mean that it comes out in\nthat order.  See \"sort\" in perlfunc for examples of how to arrange for an output ordering.\n\nIf a key appears more than once in the initializer list of a hash, the last occurrence wins:\n\n%circle = (\ncenter => [5, 10],\ncenter => [27, 9],\nradius => 100,\ncolor => [0xDF, 0xFF, 0x00],\nradius => 54,\n);\n\n# same as\n%circle = (\ncenter => [27, 9],\ncolor => [0xDF, 0xFF, 0x00],\nradius => 54,\n);\n\nThis can be used to provide overridable configuration defaults:\n\n# values in %args take priority over %configdefaults\n%config = (%configdefaults, %args);\n\n#### Subscripts\n\nAn array can be accessed one scalar at a time by specifying a dollar sign (\"$\"), then the\nname of the array (without the leading \"@\"), then the subscript inside square brackets.  For\nexample:\n\n@myarray = (5, 50, 500, 5000);\nprint \"The Third Element is\", $myarray[2], \"\\n\";\n\nThe array indices start with 0.  A negative subscript retrieves its value from the end.  In\nour example, $myarray[-1] would have been 5000, and $myarray[-2] would have been 500.\n\nHash subscripts are similar, only instead of square brackets curly brackets are used.  For\nexample:\n\n%scientists =\n(\n\"Newton\" => \"Isaac\",\n\"Einstein\" => \"Albert\",\n\"Darwin\" => \"Charles\",\n\"Feynman\" => \"Richard\",\n);\n\nprint \"Darwin's First Name is \", $scientists{\"Darwin\"}, \"\\n\";\n\nYou can also subscript a list to get a single element from it:\n\n$dir = (getpwnam(\"daemon\"))[7];\n\n#### Multi-dimensional array emulation\n\nMultidimensional arrays may be emulated by subscripting a hash with a list.  The elements of\nthe list are joined with the subscript separator (see \"$;\" in perlvar).\n\n$foo{$x,$y,$z}\n\nis equivalent to\n\n$foo{join($;, $x, $y, $z)}\n\nThe default subscript separator is \"\\034\", the same as SUBSEP in awk.\n\n#### Slices\n\nA slice accesses several elements of a list, an array, or a hash simultaneously using a list\nof subscripts.  It's more convenient than writing out the individual elements as a list of\nseparate scalar values.\n\n($him, $her)   = @folks[0,-1];              # array slice\n@them          = @folks[0 .. 3];            # array slice\n($who, $home)  = @ENV{\"USER\", \"HOME\"};      # hash slice\n($uid, $dir)   = (getpwnam(\"daemon\"))[2,7]; # list slice\n\nSince you can assign to a list of variables, you can also assign to an array or hash slice.\n\n@days[3..5]    = qw/Wed Thu Fri/;\n@colors{'red','blue','green'}\n= (0xff0000, 0x0000ff, 0x00ff00);\n@folks[0, -1]  = @folks[-1, 0];\n\nThe previous assignments are exactly equivalent to\n\n($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;\n($colors{'red'}, $colors{'blue'}, $colors{'green'})\n= (0xff0000, 0x0000ff, 0x00ff00);\n($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);\n\nSince changing a slice changes the original array or hash that it's slicing, a \"foreach\"\nconstruct will alter some--or even all--of the values of the array or hash.\n\nforeach (@array[ 4 .. 10 ]) { s/peter/paul/ }\n\nforeach (@hash{qw[key1 key2]}) {\ns/^\\s+//;           # trim leading whitespace\ns/\\s+$//;           # trim trailing whitespace\ns/(\\w+)/\\u\\L$1/g;   # \"titlecase\" words\n}\n\nAs a special exception, when you slice a list (but not an array or a hash), if the list\nevaluates to empty, then taking a slice of that empty list will always yield the empty list\nin turn.  Thus:\n\n@a = ()[0,1];          # @a has no elements\n@b = (@a)[0,1];        # @b has no elements\n@c = (sub{}->())[0,1]; # @c has no elements\n@d = ('a','b')[0,1];   # @d has two elements\n@e = (@d)[0,1,8,9];    # @e has four elements\n@f = (@d)[8,9];        # @f has two elements\n\nThis makes it easy to write loops that terminate when a null list is returned:\n\nwhile ( ($home, $user) = (getpwent)[7,0] ) {\nprintf \"%-8s %s\\n\", $user, $home;\n}\n\nAs noted earlier in this document, the scalar sense of list assignment is the number of\nelements on the right-hand side of the assignment.  The null list contains no elements, so\nwhen the password file is exhausted, the result is 0, not 2.\n\nSlices in scalar context return the last item of the slice.\n\n@a = qw/first second third/;\n%h = (first => 'A', second => 'B');\n$t = @a[0, 1];                  # $t is now 'second'\n$u = @h{'first', 'second'};     # $u is now 'B'\n\nIf you're confused about why you use an '@' there on a hash slice instead of a '%', think of\nit like this.  The type of bracket (square or curly) governs whether it's an array or a hash\nbeing looked at.  On the other hand, the leading symbol ('$' or '@') on the array or hash\nindicates whether you are getting back a singular value (a scalar) or a plural one (a list).\n\nKey/Value Hash Slices\n\nStarting in Perl 5.20, a hash slice operation with the % symbol is a variant of slice\noperation returning a list of key/value pairs rather than just values:\n\n%h = (blonk => 2, foo => 3, squink => 5, bar => 8);\n%subset = %h{'foo', 'bar'}; # key/value hash slice\n# %subset is now (foo => 3, bar => 8)\n%removed = delete %h{'foo', 'bar'};\n# %removed is now (foo => 3, bar => 8)\n# %h is now (blonk => 2, squink => 5)\n\nHowever, the result of such a slice cannot be localized or assigned to.  These are otherwise\nvery much consistent with hash slices using the @ symbol.\n\nIndex/Value Array Slices\n\nSimilar to key/value hash slices (and also introduced in Perl 5.20), the % array slice syntax\nreturns a list of index/value pairs:\n\n@a = \"a\"..\"z\";\n@list = %a[3,4,6];\n# @list is now (3, \"d\", 4, \"e\", 6, \"g\")\n@removed = delete %a[3,4,6]\n# @removed is now (3, \"d\", 4, \"e\", 6, \"g\")\n# @list[3,4,6] are now undef\n\nNote that calling \"delete\" on array values is strongly discouraged.\n\n#### Typeglobs and Filehandles\n\nPerl uses an internal type called a typeglob to hold an entire symbol table entry.  The type\nprefix of a typeglob is a \"*\", because it represents all types.  This used to be the\npreferred way to pass arrays and hashes by reference into a function, but now that we have\nreal references, this is seldom needed.\n\nThe main use of typeglobs in modern Perl is create symbol table aliases.  This assignment:\n\n*this = *that;\n\nmakes $this an alias for $that, @this an alias for @that, %this an alias for %that, &this an\nalias for &that, etc.  Much safer is to use a reference.  This:\n\nlocal *Here::blue = \\$There::green;\n\ntemporarily makes $Here::blue an alias for $There::green, but doesn't make @Here::blue an\nalias for @There::green, or %Here::blue an alias for %There::green, etc.  See \"Symbol Tables\"\nin perlmod for more examples of this.  Strange though this may seem, this is the basis for\nthe whole module import/export system.\n\nAnother use for typeglobs is to pass filehandles into a function or to create new\nfilehandles.  If you need to use a typeglob to save away a filehandle, do it this way:\n\n$fh = *STDOUT;\n\nor perhaps as a real reference, like this:\n\n$fh = \\*STDOUT;\n\nSee perlsub for examples of using these as indirect filehandles in functions.\n\nTypeglobs are also a way to create a local filehandle using the local() operator.  These last\nuntil their block is exited, but may be passed back.  For example:\n\nsub newopen {\nmy $path = shift;\nlocal  *FH;  # not my!\nopen   (FH, $path)          or  return undef;\nreturn *FH;\n}\n$fh = newopen('/etc/passwd');\n\nNow that we have the *foo{THING} notation, typeglobs aren't used as much for filehandle\nmanipulations, although they're still needed to pass brand new file and directory handles\ninto or out of functions.  That's because *HANDLE{IO} only works if HANDLE has already been\nused as a handle.  In other words, *FH must be used to create new symbol table entries;\n*foo{THING} cannot.  When in doubt, use *FH.\n\nAll functions that are capable of creating filehandles (open(), opendir(), pipe(),\nsocketpair(), sysopen(), socket(), and accept()) automatically create an anonymous filehandle\nif the handle passed to them is an uninitialized scalar variable.  This allows the constructs\nsuch as \"open(my $fh, ...)\" and \"open(local $fh,...)\" to be used to create filehandles that\nwill conveniently be closed automatically when the scope ends, provided there are no other\nreferences to them.  This largely eliminates the need for typeglobs when opening filehandles\nthat must be passed around, as in the following example:\n\nsub myopen {\nopen my $fh, \"@\"\nor die \"Can't open '@': $!\";\nreturn $fh;\n}\n\n{\nmy $f = myopen(\"</etc/motd\");\nprint <$f>;\n# $f implicitly closed here\n}\n\nNote that if an initialized scalar variable is used instead the result is different: \"my\n$fh='zzz'; open($fh, ...)\" is equivalent to \"open( *{'zzz'}, ...)\".  \"use strict 'refs'\"\nforbids such practice.\n\nAnother way to create anonymous filehandles is with the Symbol module or with the IO::Handle\nmodule and its ilk.  These modules have the advantage of not hiding different types of the\nsame name during the local().  See the bottom of \"open\" in perlfunc for an example.\n\n### SEE ALSO\n\nSee perlvar for a description of Perl's built-in variables and a discussion of legal variable\nnames.  See perlref, perlsub, and \"Symbol Tables\" in perlmod for more discussion on typeglobs\nand the *foo{THING} syntax.\n\n\n\nperl v5.34.0                                 2025-07-25                                  PERLDATA(1)\n\n"
        }
    ],
    "structuredContent": {
        "command": "perldata",
        "section": "1",
        "mode": "man",
        "summary": "perldata - Perl data types",
        "synopsis": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 1,
                "subsections": [
                    {
                        "name": "Variable names",
                        "lines": 72
                    },
                    {
                        "name": "Identifier parsing",
                        "lines": 106
                    },
                    {
                        "name": "Context",
                        "lines": 40
                    },
                    {
                        "name": "Scalar values",
                        "lines": 103
                    },
                    {
                        "name": "Scalar value constructors",
                        "lines": 206
                    },
                    {
                        "name": "List value constructors",
                        "lines": 241
                    },
                    {
                        "name": "Subscripts",
                        "lines": 27
                    },
                    {
                        "name": "Multi-dimensional array emulation",
                        "lines": 11
                    },
                    {
                        "name": "Slices",
                        "lines": 96
                    },
                    {
                        "name": "Typeglobs and Filehandles",
                        "lines": 75
                    }
                ]
            },
            {
                "name": "SEE ALSO",
                "lines": 7,
                "subsections": []
            }
        ]
    }
}