Identifier length cap (Identifier too long)#

Upstream wording#

perl5-upstream/pod/perlvar.pod says, in the Syntax of Variable Names section:

Variable names in Perl can have several formats. Usually, they must begin with a letter or underscore, in which case they can be arbitrarily long (up to an internal limit of 251 characters) and may contain letters, digits, underscores, or the special sequence :: or '.

This wording is wrong on three counts: the number, the unit, and the suggestion that the limit is soft.

Correction#

The correct statement, as of the Perl 5.44 stable series, is:

Identifiers may be up to 1019 bytes long. Names exceeding this length cause a parse-time error: Identifier too long.

Three things to take from this:

  1. 1019, not 251. Perl 5.44 sizes the parser’s token buffer from PERL_IDENTIFIER_LENGTH (parser.h), defined as 256 * MAX_UNICODE_UTF8_BYTES = 1024 bytes. S_parse_ident reserves the sigil byte, the trailing NUL and a margin, leaving 1019 bytes of name proper.

    The 251-character figure in the pod describes Perl 5.42 and earlier, where the same buffer was a flat tokenbuf[256]. The buffer was widened by commit 8785c114b5 (“parser.h Allow up to 256 characters in a token”, 2025-09-28) and given its name by 9bc8cdede1 (“Add #define for the maximum Perl identifier length”, 2025-10-11). Both are in v5.44.0. The pod text was not updated and is now stale.

  2. Bytes, not characters. The cap is measured in bytes of the source representation, not in Unicode code points. UTF-8 identifiers therefore reach the limit at fewer characters, and a name is rejected as soon as a character’s end crosses the bound:

    Char width

    Last accepted

    First rejected

    1 byte (ASCII)

    1019 chars = 1019 B

    1020 chars = 1020 B

    2 bytes (e.g. é)

    509 chars = 1018 B

    510 chars = 1020 B

    3 bytes (e.g. ㄅ)

    339 chars = 1017 B

    340 chars = 1020 B

    4 bytes (e.g. 𐌰 - Gothic)

    254 chars = 1016 B

    255 chars = 1020 B

    The “characters” in the upstream text is correct only for the ASCII case, where bytes and characters coincide.

  3. Hard error, not “internal limit”. The phrasing “up to an internal limit” suggests something soft. It is not - perl5’s parser raises a fatal Identifier too long exception. The message is the only thing the user sees; there is no truncation, warning, or fallback.

pperl behavior#

pperl matches upstream Perl 5.44 exactly at every boundary in the table above, for ASCII and for 2-, 3- and 4-byte UTF-8 identifiers alike. There is no divergence to report.

Note

An earlier revision of this page claimed pperl diverged here by accepting names between 252 and 1019 bytes. That claim was an artifact of measuring against a Perl 5.42 binary while labelling it 5.44. Both perl 5.44 and pperl accept those names. The comparison baseline, not pperl, was wrong.

Tests#

The conformance tests covering this errata live in:

  • t/01-parsing/090-identifier-length-ascii.t

  • t/01-parsing/091-identifier-length-utf8.t

They probe the boundary at 1019/1020 bytes for ASCII and for each UTF-8 character width, plus a byte-versus-character discriminator (600 two-byte characters: only 600 characters, but 1200 bytes, so rejected) and lengths far past the cap.