{
    "mode": "perldoc",
    "parameter": "Regexp::Common",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Regexp%3A%3ACommon/json",
    "generated": "2026-08-21T11:39:25Z",
    "synopsis": "# STANDARD USAGE\nuse Regexp::Common;\nwhile (<>) {\n/$RE{num}{real}/               and print q{a number};\n/$RE{quoted}/                  and print q{a ['\"`] quoted string};\nm[$RE{delimited}{-delim=>'/'}]  and print q{a /.../ sequence};\n/$RE{balanced}{-parens=>'()'}/ and print q{balanced parentheses};\n/$RE{profanity}/               and print q{a #*@%-ing word};\n}\n# SUBROUTINE-BASED INTERFACE\nuse Regexp::Common 'REALL';\nwhile (<>) {\n$ =~ REnumreal()              and print q{a number};\n$ =~ REquoted()                and print q{a ['\"`] quoted string};\n$ =~ REdelimited(-delim=>'/')  and print q{a /.../ sequence};\n$ =~ REbalanced(-parens=>'()'} and print q{balanced parentheses};\n$ =~ REprofanity()             and print q{a #*@%-ing word};\n}\n# IN-LINE MATCHING...\nif ( $RE{num}{int}->matches($text) ) {...}\n# ...AND SUBSTITUTION\nmy $cropped = $RE{ws}{crop}->subs($uncropped);\n# ROLL-YOUR-OWN PATTERNS\nuse Regexp::Common 'pattern';\npattern name   => ['name', 'mine'],\ncreate => '(?i:J[.]?\\s+A[.]?\\s+Perl-Hacker)',\n;\nmy $namematcher = $RE{name}{mine};\npattern name    => [ 'lineof', '-char=' ],\ncreate  => sub {\nmy $flags = shift;\nmy $char = quotemeta $flags->{-char};\nreturn '(?:^$char+$)';\n},\nmatch   => sub {\nmy ($self, $str) = @;\nreturn $str !~ /[^$self->{flags}{-char}]/;\n},\nsubs   => sub {\nmy ($self, $str, $replacement) = @;\n$[1] =~ s/^$self->{flags}{-char}+$//g;\n},\n;\nmy $asterisks = $RE{lineof}{-char=>'*'};\n# DECIDING WHICH PATTERNS TO LOAD.\nuse Regexp::Common qw /comment number/;  # Comment and number patterns.\nuse Regexp::Common qw /nodefaults/;     # Don't load any patterns.\nuse Regexp::Common qw /!delimited/;      # All, but delimited patterns.",
    "sections": {
        "NAME": {
            "content": "Regexp::Common - Provide commonly requested regular expressions\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "# STANDARD USAGE\n\nuse Regexp::Common;\n\nwhile (<>) {\n/$RE{num}{real}/               and print q{a number};\n/$RE{quoted}/                  and print q{a ['\"`] quoted string};\nm[$RE{delimited}{-delim=>'/'}]  and print q{a /.../ sequence};\n/$RE{balanced}{-parens=>'()'}/ and print q{balanced parentheses};\n/$RE{profanity}/               and print q{a #*@%-ing word};\n}\n\n\n# SUBROUTINE-BASED INTERFACE\n\nuse Regexp::Common 'REALL';\n\nwhile (<>) {\n$ =~ REnumreal()              and print q{a number};\n$ =~ REquoted()                and print q{a ['\"`] quoted string};\n$ =~ REdelimited(-delim=>'/')  and print q{a /.../ sequence};\n$ =~ REbalanced(-parens=>'()'} and print q{balanced parentheses};\n$ =~ REprofanity()             and print q{a #*@%-ing word};\n}\n\n\n# IN-LINE MATCHING...\n\nif ( $RE{num}{int}->matches($text) ) {...}\n\n\n# ...AND SUBSTITUTION\n\nmy $cropped = $RE{ws}{crop}->subs($uncropped);\n\n\n# ROLL-YOUR-OWN PATTERNS\n\nuse Regexp::Common 'pattern';\n\npattern name   => ['name', 'mine'],\ncreate => '(?i:J[.]?\\s+A[.]?\\s+Perl-Hacker)',\n;\n\nmy $namematcher = $RE{name}{mine};\n\npattern name    => [ 'lineof', '-char=' ],\ncreate  => sub {\nmy $flags = shift;\nmy $char = quotemeta $flags->{-char};\nreturn '(?:^$char+$)';\n},\nmatch   => sub {\nmy ($self, $str) = @;\nreturn $str !~ /[^$self->{flags}{-char}]/;\n},\nsubs   => sub {\nmy ($self, $str, $replacement) = @;\n$[1] =~ s/^$self->{flags}{-char}+$//g;\n},\n;\n\nmy $asterisks = $RE{lineof}{-char=>'*'};\n\n# DECIDING WHICH PATTERNS TO LOAD.\n\nuse Regexp::Common qw /comment number/;  # Comment and number patterns.\nuse Regexp::Common qw /nodefaults/;     # Don't load any patterns.\nuse Regexp::Common qw /!delimited/;      # All, but delimited patterns.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "By default, this module exports a single hash (%RE) that stores or generates commonly needed\nregular expressions (see \"List of available patterns\").\n\nThere is an alternative, subroutine-based syntax described in \"Subroutine-based interface\".\n",
            "subsections": [
                {
                    "name": "General syntax for requesting patterns",
                    "content": "To access a particular pattern, %RE is treated as a hierarchical hash of hashes (of hashes...),\nwith each successive key being an identifier. For example, to access the pattern that matches\nreal numbers, you specify:\n\n$RE{num}{real}\n\nand to access the pattern that matches integers:\n\n$RE{num}{int}\n\nDeeper layers of the hash are used to specify *flags*: arguments that modify the resulting\npattern in some way. The keys used to access these layers are prefixed with a minus sign and may\nhave a value; if a value is given, it's done by using a multidimensional key. For example, to\naccess the pattern that matches base-2 real numbers with embedded commas separating groups of\nthree digits (e.g. 10,101,110.110101101):\n\n$RE{num}{real}{-base => 2}{-sep => ','}{-group => 3}\n\nThrough the magic of Perl, these flag layers may be specified in any order (and even\ninterspersed through the identifier keys!) so you could get the same pattern with:\n\n$RE{num}{real}{-sep => ','}{-group => 3}{-base => 2}\n\nor:\n\n$RE{num}{-base => 2}{real}{-group => 3}{-sep => ','}\n\nor even:\n\n$RE{-base => 2}{-group => 3}{-sep => ','}{num}{real}\n\netc.\n\nNote, however, that the relative order of amongst the identifier keys *is* significant. That is:\n\n$RE{list}{set}\n\nwould not be the same as:\n\n$RE{set}{list}\n"
                },
                {
                    "name": "Flag syntax",
                    "content": "In versions prior to 2.113, flags could also be written as \"{\"-flag=value\"}\". This no longer\nworks, although \"{\"-flag$;value\"}\" still does. However, \"{-flag => 'value'}\" is the preferred\nsyntax.\n"
                },
                {
                    "name": "Universal flags",
                    "content": "Normally, flags are specific to a single pattern. However, there is two flags that all patterns\nmay specify.\n\n\"-keep\"\nBy default, the patterns provided by %RE contain no capturing parentheses. However, if the\n\"-keep\" flag is specified (it requires no value) then any significant substrings that the\npattern matches are captured. For example:\n\nif ($str =~ $RE{num}{real}{-keep}) {\n$number   = $1;\n$whole    = $3;\n$decimals = $5;\n}\n\nSpecial care is needed if a \"kept\" pattern is interpolated into a larger regular expression,\nas the presence of other capturing parentheses is likely to change the \"number variables\"\ninto which significant substrings are saved.\n\nSee also \"Adding new regular expressions\", which describes how to create new patterns with\n\"optional\" capturing brackets that respond to \"-keep\".\n\n\"-i\"\nSome patterns or subpatterns only match lowercase or uppercase letters. If one wants the do\ncase insensitive matching, one option is to use the \"/i\" regexp modifier, or the special\nsequence \"(?i)\". But if the functional interface is used, one does not have this option. The\n\"-i\" switch solves this problem; by using it, the pattern will do case insensitive matching.\n\nOO interface and inline matching/substitution\nThe patterns returned from %RE are objects, so rather than writing:\n\nif ($str =~ /$RE{some}{pattern}/ ) {...}\n\nyou can write:\n\nif ( $RE{some}{pattern}->matches($str) ) {...}\n\nFor matching this would seem to have no great advantage apart from readability (but see below).\n\nFor substitutions, it has other significant benefits. Frequently you want to perform a\nsubstitution on a string without changing the original. Most people use this:\n\n$changed = $original;\n$changed =~ s/$RE{some}{pattern}/$replacement/;\n\nThe more adept use:\n\n($changed = $original) =~ s/$RE{some}{pattern}/$replacement/;\n\nRegexp::Common allows you do write this:\n\n$changed = $RE{some}{pattern}->subs($original=>$replacement);\n\nApart from reducing precedence-angst, this approach has the added advantages that the\nsubstitution behaviour can be optimized from the regular expression, and the replacement string\ncan be provided by default (see \"Adding new regular expressions\").\n\nFor example, in the implementation of this substitution:\n\n$cropped = $RE{ws}{crop}->subs($uncropped);\n\nthe default empty string is provided automatically, and the substitution is optimized to use:\n\n$uncropped =~ s/^\\s+//;\n$uncropped =~ s/\\s+$//;\n\nrather than:\n\n$uncropped =~ s/^\\s+|\\s+$//g;\n"
                },
                {
                    "name": "Subroutine-based interface",
                    "content": "The hash-based interface was chosen because it allows regexes to be effortlessly interpolated,\nand because it also allows them to be \"curried\". For example:\n\nmy $num = $RE{num}{int};\n\nmy $commad     = $num->{-sep=>','}{-group=>3};\nmy $duodecimal = $num->{-base=>12};\n\nHowever, the use of tied hashes does make the access to Regexp::Common patterns slower than it\nmight otherwise be. In contexts where impatience overrules laziness, Regexp::Common provides an\nadditional subroutine-based interface.\n\nFor each (sub-)entry in the %RE hash (\"$RE{key1}{key2}{etc}\"), there is a corresponding\nexportable subroutine: REkey1key2etc(). The name of each subroutine is the\nunderscore-separated concatenation of the *non-flag* keys that locate the same pattern in %RE.\nFlags are passed to the subroutine in its argument list. Thus:\n\nuse Regexp::Common qw( REwscrop REnumreal REprofanity );\n\n$str =~ REwscrop() and die \"Surrounded by whitespace\";\n\n$str =~ REnumreal(-base=>8, -sep=>\" \") or next;\n\n$offensive = REprofanity(-keep);\n$str =~ s/$offensive/$bad{$1}++; \"<expletive deleted>\"/ge;\n\nNote that, unlike the hash-based interface (which returns objects), these subroutines return\nordinary \"qr\"'d regular expressions. Hence they do not curry, nor do they provide the OO match\nand substitution inlining described in the previous section.\n\nIt is also possible to export subroutines for all available patterns like so:\n\nuse Regexp::Common 'REALL';\n\nOr you can export all subroutines with a common prefix of keys like so:\n\nuse Regexp::Common 'REnumALL';\n\nwhich will export \"REnumint\" and \"REnumreal\" (and if you have create more patterns who have\nfirst key *num*, those will be exported as well). In general, *REkey1...keynALL* will export\nall subroutines whose pattern names have first keys *key1* ... *keyn*.\n"
                },
                {
                    "name": "Adding new regular expressions",
                    "content": "You can add your own regular expressions to the %RE hash at run-time, using the exportable\n\"pattern\" subroutine. It expects a hash-like list of key/value pairs that specify the behaviour\nof the pattern. The various possible argument pairs are:\n\n\"name => [ @list ]\"\nA required argument that specifies the name of the pattern, and any flags it may take, via a\nreference to a list of strings. For example:\n\npattern name => [qw( line of -char )],\n# other args here\n;\n\nThis specifies an entry \"$RE{line}{of}\", which may take a \"-char\" flag.\n\nFlags may also be specified with a default value, which is then used whenever the flag is\nspecified without an explicit value (but not when the flag is omitted). For example:\n\npattern name => [qw( line of -char= )],\n# default char is ''\n# other args here\n;\n\n\"create => $subreforstring\"\nA required argument that specifies either a string that is to be returned as the pattern:\n\npattern name    => [qw( line of underscores )],\ncreate  => q/(?:^+$)/\n;\n\nor a reference to a subroutine that will be called to create the pattern:\n\npattern name    => [qw( line of -char= )],\ncreate  => sub {\nmy ($self, $flags) = @;\nmy $char = quotemeta $flags->{-char};\nreturn '(?:^$char+$)';\n},\n;\n\nIf the subroutine version is used, the subroutine will be called with three arguments: a\nreference to the pattern object itself, a reference to a hash containing the flags and their\nvalues, and a reference to an array containing the non-flag keys.\n\nWhatever the subroutine returns is stringified as the pattern.\n\nNo matter how the pattern is created, it is immediately postprocessed to include or exclude\ncapturing parentheses (according to the value of the \"-keep\" flag). To specify such\n\"optional\" capturing parentheses within the regular expression associated with \"create\", use\nthe notation \"(?k:...)\". Any parentheses of this type will be converted to \"(...)\" when the\n\"-keep\" flag is specified, or \"(?:...)\" when it is not. It is a Regexp::Common convention\nthat the outermost capturing parentheses always capture the entire pattern, but this is not\nenforced.\n\n\"match => $subref\"\nAn optional argument that specifies a subroutine that is to be called when the\n\"$RE{...}->matches(...)\" method of this pattern is invoked.\n\nThe subroutine should expect two arguments: a reference to the pattern object itself, and\nthe string to be matched against.\n\nIt should return the same types of values as a \"m/.../\" does.\n\npattern name    => [qw( line of -char )],\ncreate  => sub {...},\nmatch   => sub {\nmy ($self, $str) = @;\n$str !~ /[^$self->{flags}{-char}]/;\n},\n;\n\n\"subs => $subref\"\nAn optional argument that specifies a subroutine that is to be called when the\n\"$RE{...}->subs(...)\" method of this pattern is invoked.\n\nThe subroutine should expect three arguments: a reference to the pattern object itself, the\nstring to be changed, and the value to be substituted into it. The third argument may be\n\"undef\", indicating the default substitution is required.\n\nThe subroutine should return the same types of values as an \"s/.../.../\" does.\n\nFor example:\n\npattern name    => [ 'lineof', '-char=' ],\ncreate  => sub {...},\nsubs    => sub {\nmy ($self, $str, $ignorereplacement) = @;\n$[1] =~ s/^$self->{flags}{-char}+$//g;\n},\n;\n\nNote that such a subroutine will almost always need to modify $[1] directly.\n\n\"version => $minimumperlversion\"\nIf this argument is given, it specifies the minimum version of perl required to use the new\npattern. Attempts to use the pattern with earlier versions of perl will generate a fatal\ndiagnostic.\n"
                },
                {
                    "name": "Loading specific sets of patterns.",
                    "content": "By default, all the sets of patterns listed below are made available. However, it is possible to\nindicate which sets of patterns should be made available - the wanted sets should be given as\narguments to \"use\". Alternatively, it is also possible to indicate which sets of patterns should\nnot be made available - those sets will be given as argument to the \"use\" statement, but are\npreceded with an exclaimation mark. The argument *nodefaults* indicates none of the default\npatterns should be made available. This is useful for instance if all you want is the pattern()\nsubroutine.\n\nExamples:\n\nuse Regexp::Common qw /comment number/;  # Comment and number patterns.\nuse Regexp::Common qw /nodefaults/;     # Don't load any patterns.\nuse Regexp::Common qw /!delimited/;      # All, but delimited patterns.\n\nIt's also possible to load your own set of patterns. If you have a module\n\"Regexp::Common::mypatterns\" that makes patterns available, you can have it made available with\n\nuse Regexp::Common qw /mypatterns/;\n\nNote that the default patterns will still be made available - only if you use *nodefaults*, or\nmention one of the default sets explicitly, the non mentioned defaults aren't made available.\n"
                },
                {
                    "name": "List of available patterns",
                    "content": "The patterns listed below are currently available. Each set of patterns has its own manual page\ndescribing the details. For each pattern set named *name*, the manual page\n*Regexp::Common::name* describes the details.\n\nCurrently available are:\n\nRegexp::Common::balanced\nProvides regexes for strings with balanced parenthesized delimiters.\n\nRegexp::Common::comment\nProvides regexes for comments of various languages (43 languages currently).\n\nRegexp::Common::delimited\nProvides regexes for delimited strings.\n\nRegexp::Common::lingua\nProvides regexes for palindromes.\n\nRegexp::Common::list\nProvides regexes for lists.\n\nRegexp::Common::net\nProvides regexes for IPv4, IPv6, and MAC addresses.\n\nRegexp::Common::number\nProvides regexes for numbers (integers and reals).\n\nRegexp::Common::profanity\nProvides regexes for profanity.\n\nRegexp::Common::whitespace\nProvides regexes for leading and trailing whitespace.\n\nRegexp::Common::zip\nProvides regexes for zip codes.\n"
                },
                {
                    "name": "Forthcoming patterns and features",
                    "content": "Future releases of the module will also provide patterns for the following:\n\n* email addresses\n* HTML/XML tags\n* more numerical matchers,\n* mail headers (including multiline ones),\n* more URLS\n* telephone numbers of various countries\n* currency (universal 3 letter format, Latin-1, currency names)\n* dates\n* binary formats (e.g. UUencoded, MIMEd)\n\nIf you have other patterns or pattern generators that you think would be generally useful,\nplease send them to the maintainer -- preferably as source code using the \"pattern\" subroutine.\nSubmissions that include a set of tests will be especially welcome.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "\"Can't export unknown subroutine %s\"\nThe subroutine-based interface didn't recognize the requested subroutine. Often caused by a\nspelling mistake or an incompletely specified name.\n\n\"Can't create unknown regex: $RE{...}\"\nRegexp::Common doesn't have a generator for the requested pattern. Often indicates a\nmisspelt or missing parameter.\n\n\"Perl %f does not support the pattern $RE{...}. You need Perl %f or later\"\nThe requested pattern requires advanced regex features (e.g. recursion) that not available\nin your version of Perl. Time to upgrade.\n\n\"pattern() requires argument: name => [ @list ]\"\nEvery user-defined pattern specification must have a name.\n\n\"pattern() requires argument: create => $subreforstring\"\nEvery user-defined pattern specification must provide a pattern creation mechanism: either a\npattern string or a reference to a subroutine that returns the pattern string.\n\n\"Base must be between 1 and 36\"\nThe \"$RE{num}{real}{-base=>'*N*'}\" pattern uses the characters [0-9A-Z] to represent the\ndigits of various bases. Hence it only produces regular expressions for bases up to\nhexatricensimal.\n\n\"Must specify delimiter in $RE{delimited}\"\nThe pattern has no default delimiter. You need to write: \"$RE{delimited}{-delim=>*X*'}\" for\nsome character *X*\n",
            "subsections": []
        },
        "ACKNOWLEDGEMENTS": {
            "content": "Deepest thanks to the many people who have encouraged and contributed to this project,\nespecially: Elijah, Jarkko, Tom, Nat, Ed, and Vivek.\n\nFurther thanks go to: Alexandr Ciornii, Blair Zajac, Bob Stockdale, Charles Thomas, Chris\nVertonghen, the CPAN Testers, David Hand, Fany, Geoffrey Leach, Hermann-Marcus Behrens, Jerome\nQuelin, Jim Cromie, Lars Wilke, Linda Julien, Mike Arms, Mike Castle, Mikko, Murat Uenalan,\nRafaël Garcia-Suarez, Ron Savage, Sam Vilain, Slaven Rezic, Smylers, Tim Maher, and all the\nothers I've forgotten.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Damian Conway (damian@conway.org)\n",
            "subsections": []
        },
        "MAINTENANCE": {
            "content": "This package is maintained by Abigail (*regexp-common@abigail.be*).\n",
            "subsections": []
        },
        "BUGS AND IRRITATIONS": {
            "content": "Bound to be plenty.\n\nFor a start, there are many common regexes missing. Send them in to *regexp-common@abigail.be*.\n\nThere are some POD issues when installing this module using a pre-5.6.0 perl; some manual pages\nmay not install, or may not install correctly using a perl that is that old. You might consider\nupgrading your perl.\n",
            "subsections": []
        },
        "NOT A BUG": {
            "content": "*   The various patterns are not anchored. That is, a pattern like \"$RE {num} {int}\" will match\nagainst \"abc4def\", because a substring of the subject matches. This is by design, and not a\nbug. If you want the pattern to be anchored, use something like:\n\nmy $integer = $RE {num} {int};\n$subj =~ /^$integer$/ and print \"Matches!\\n\";\n\nLICENSE and COPYRIGHT\nThis software is Copyright (c) 2001 - 2017, Damian Conway and Abigail.\n\nThis module is free software, and maybe used under any of the following licenses:\n\n1) The Perl Artistic License.     See the file COPYRIGHT.AL.\n2) The Perl Artistic License 2.0. See the file COPYRIGHT.AL2.\n3) The BSD License.               See the file COPYRIGHT.BSD.\n4) The MIT License.               See the file COPYRIGHT.MIT.\n",
            "subsections": []
        }
    },
    "summary": "Regexp::Common - Provide commonly requested regular expressions",
    "flags": [],
    "examples": [],
    "see_also": []
}