Formalize symbol names reserved for Perl's use in XS

This creates a regular expression pattern of names that we feel free to
expose to XS code's namespace.  Hence they are names reserved for our use,
and should any conflicts arise, the module needs to change, not us.

Naturally, the pattern is pretty restrictive.

    Any symbol beginning with "PL_"
    Any symbol containing perl, Perl, or PERL, usually delimitted on
        both sides so as to keep it from being part of a larger word.

Any other spelling that we expose could be considered to pollute the XS
code space.  We have felt free to do that all the time.  Any new
function's short name will do that.

And we generally feel free to create macros with arbitrary names which
could conflict with an existing XS name.

Some important potential conflicts are:

New keywords:  We create an exposed KEY_foo macro.  Some existing
modules use some of these.  My grep of CPAN shows maybe a dozen of these
get used; mostly KEY_END.

config.h is full of symbols like HAS_foo, I_bar, and others that are all
exposed.  I don't imagine we can claim to reserve any symbol beginning
with either HAS_ or I_.  And I don't know what to do here.

Informally, myself and others have used a trailing underscore to
indicate a private symbol.  There are a few distributions that use some
of these anyway.  And there has been pushback when new short symbols
that use this convention have been added.

I would like to get a formal rule about use of this convention.  There
are 200+ of these currently.  We could reserve any names with trailing
underscores, or if that is too much, any ending in, say, '_pl_' or
'_PL_'.

We have 3000+ undocumented macro names that don't end in underscores and
which are currently visible to XS code.  This number includes the
KEY_foo ones, but not the ones in config.h.

To deal with namespace pollution, we have had the -DNO_SHORT_NAMES
Configure option for use just with embedded perls.  This hasn't worked
at least since we added inline functions, and it always applied to only
functions.  I have a WIP to get this to work again, and to extend it to
work with documented macros.  It just occurred to me how to make this be
customizable, so that downstream someone could add a list of symbols
that should only exist as 'Perl_foo', and then recompile, leaving short
names for everything not in the list.

Author: khwilliamson

regen/embed.pl

@@ -104,14 +104,35 @@ BEGIN
                    pod/perlreapi.pod
                  );
 
+# A regular expression that matches names that are externally visible, but
+# Perl reserves for itself.  Generally, we want things to be delimitted on
+# both sides to show it isn't part of a larger word such as 'hyperlink',
+# 'perlustrate', or 'properly'.  Underscores delimit besides the typical ^ or
+# \b.  All caps PERL has looser rules to accommodate the many existing symbols
+# where everything is jammed together, and the less likelihood that something
+# with all caps is innocently referring to something unrelated to Perl.
+my $names_reserved_for_perl_use_re =
+                         qr/  ^ (  PL_ \w+ \b
+                                 | perl_        # The underscore delimits
+                                 | Perl [_A-Z]  # Uppercase delimits here too
+                                 | PERL [A-Z]+ [[:alpha:]] ( \b | _ )
+                                )
+
+                              # The \d is for PERL5, for example
+                            | ( _ | \b )  PERL ( _ | \b | \d+ )
+
+                              # This is for obsolete and deprecated uses
+                            | ( _ | \b ) CPERL (arg | scope) ( _ | \b )
+                          /x;
+
 # This is a list of symbols that are not documented to be available for
 # modules to use, but are nevertheless currently not kept by embed.h from
 # being visible to the world.
 #
 # Strive to make this list empty.
 #
 # The list does not include symbols that we have documented as being reserved
-# for perl's use, namely those that begin with 'PL_' or contain qr/perl/i.
+# for perl's use, namely those that match the pattern just above.
 # There are two parts of the list; the second part contains the symbols which
 # have a trailing underscore; the first part those without.
 #
@@ -1336,6 +1357,8 @@ BEGIN
     is_XDIGIT_high
     isXDIGIT_LC_utf8
     isXDIGIT_uni
+    is_XPERLSPACE_cp_high
+    is_XPERLSPACE_high
     IV_DIG
     IV_MAX_P1
     JE_OLD_STACK_HWM_restore
@@ -4729,9 +4752,7 @@ sub find_undefs {
                 # Just the symbol, no arglist nor definition
                 $name =~ s/ (?: \s | \( ) .* //x;
 
-                # These are reserved for Perl's use, so not a problem.
-                next if $name =~ / ^ PL_ /x;
-                next if $name =~ /perl/i;
+                next if $name =~ $names_reserved_for_perl_use_re;
 
                 next unless $line->reduce_conds($constraints_re,
                                                 \%constraints);