handy.h: Mark more clearly things for internal-only use

This changes the names of some macros to begin with an underscore, and
changes comments to more clearly indicate things which aren't to be used
outside the Perl core.

1 files changed, 47 insertions, 50 deletions

diff --git a/handy.h b/handy.h
index c7b79bbba7..e0255f8f35 100644
--- a/handy.h
+++ b/handy.h
@@ -602,11 +602,11 @@ patched there.  The file as of this writing is cpan/Devel-PPPort/parts/inc/misc
 /* ASCII range only */
 #ifdef H_PERL       /* If have access to perl.h, lookup in its table */
 
-/* Character class numbers.  These are used in PL_charclass[] and the ones
- * up through the one that corresponds to <_HIGHEST_REGCOMP_DOT_H_SYNC> are
- * used by regcomp.h.  These use names used in l1_char_class_tab.h but their
- * actual definitions are here.  If that has a name not used here, it won't
- * compile. */
+/* Character class numbers.  For internal core Perl use only.  These are used
+ * in PL_charclass[] and the ones up through the one that corresponds to
+ * <_HIGHEST_REGCOMP_DOT_H_SYNC> are used by regcomp.h.  These use names used
+ * in l1_char_class_tab.h but their actual definitions are here.  If that has a
+ * name not used here, it won't compile. */
 #  define _CC_WORDCHAR           0
 #  define _CC_SPACE              1
 #  define _CC_DIGIT              2
@@ -910,38 +910,38 @@ EXTCONST U32 PL_charclass[];
 
 #define isPSXSPC_LC(c)		(isSPACE_LC(c) || (c) == '\v')
 
-/* For use in the macros just below.  If the input is Latin1, use the Latin1
- * (_L1) version of the macro; otherwise use the function.  Won't compile if
- * 'c' isn't unsigned, as won't match function prototype. The macros do bounds
- * checking, so have duplicate checks here, so could create versions of the
- * macros that don't, but experiments show that gcc optimizes them out anyway.
- */
-#define generic_uni(classnum, function, c) ((c) < 256                     \
+/* For internal core Perl use only.  If the input is Latin1, use the Latin1
+ * macro; otherwise use the function.  Won't compile if 'c' isn't unsigned, as
+ * won't match function prototype. The macros do bounds checking, so have
+ * duplicate checks here, so could create versions of the macros that don't,
+ * but experiments show that gcc optimizes them out anyway. */
+
+/* Note that all ignore 'use bytes' */
+#define _generic_uni(classnum, function, c) ((c) < 256                    \
                                              ? _generic_isCC(c, classnum) \
                                              : function(c))
-/* Note that all ignore 'use bytes' */
 
-#define isWORDCHAR_uni(c)       generic_uni(_CC_WORDCHAR, is_uni_alnum, c)
+#define isWORDCHAR_uni(c)       _generic_uni(_CC_WORDCHAR, is_uni_alnum, c)
 #define isALNUM_uni(c)          isWORDCHAR_uni(c)
-#define isBLANK_uni(c)          generic_uni(_CC_BLANK, is_uni_blank, c)
-#define isIDFIRST_uni(c)        generic_uni(_CC_IDFIRST, is_uni_idfirst, c)
-#define isALPHA_uni(c)          generic_uni(_CC_ALPHA, is_uni_alpha, c)
-#define isSPACE_uni(c)          generic_uni(_CC_SPACE, is_uni_space, c)
-#define isDIGIT_uni(c)          generic_uni(_CC_DIGIT, is_uni_digit, c)
-#define isUPPER_uni(c)          generic_uni(_CC_UPPER, is_uni_upper, c)
-#define isLOWER_uni(c)          generic_uni(_CC_LOWER, is_uni_lower, c)
+#define isBLANK_uni(c)          _generic_uni(_CC_BLANK, is_uni_blank, c)
+#define isIDFIRST_uni(c)        _generic_uni(_CC_IDFIRST, is_uni_idfirst, c)
+#define isALPHA_uni(c)          _generic_uni(_CC_ALPHA, is_uni_alpha, c)
+#define isSPACE_uni(c)          _generic_uni(_CC_SPACE, is_uni_space, c)
+#define isDIGIT_uni(c)          _generic_uni(_CC_DIGIT, is_uni_digit, c)
+#define isUPPER_uni(c)          _generic_uni(_CC_UPPER, is_uni_upper, c)
+#define isLOWER_uni(c)          _generic_uni(_CC_LOWER, is_uni_lower, c)
 #define isASCII_uni(c)          isASCII(c)
 
 /* All controls are in Latin1 */
 #define isCNTRL_uni(c)          isCNTRL_L1(c)
 
-#define isGRAPH_uni(c)          generic_uni(_CC_GRAPH, is_uni_graph, c)
-#define isPRINT_uni(c)          generic_uni(_CC_PRINT, is_uni_print, c)
-#define isPUNCT_uni(c)          generic_uni(_CC_PUNCT, is_uni_punct, c)
-#define isXDIGIT_uni(c)         generic_uni(_CC_XDIGIT, is_uni_xdigit, c)
+#define isGRAPH_uni(c)          _generic_uni(_CC_GRAPH, is_uni_graph, c)
+#define isPRINT_uni(c)          _generic_uni(_CC_PRINT, is_uni_print, c)
+#define isPUNCT_uni(c)          _generic_uni(_CC_PUNCT, is_uni_punct, c)
+#define isXDIGIT_uni(c)         _generic_uni(_CC_XDIGIT, is_uni_xdigit, c)
 
 /* Posix and regular space differ only in U+000B, which is in Latin1 */
-#define isPSXSPC_uni(c)         generic_uni(_CC_PSXSPC, is_uni_space, c)
+#define isPSXSPC_uni(c)         _generic_uni(_CC_PSXSPC, is_uni_space, c)
 
 #define toUPPER_uni(c,s,l)	to_uni_upper(c,s,l)
 #define toTITLE_uni(c,s,l)	to_uni_title(c,s,l)
@@ -963,12 +963,12 @@ EXTCONST U32 PL_charclass[];
 #define isPSXSPC_LC_uni(c)	(isSPACE_LC_uni(c) ||(c) == '\f')
 #define isBLANK_LC_uni(c)	isBLANK(c) /* could be wrong */
 
-/* For use in the macros just below.  If the input is ASCII, use the ASCII (_A)
- * version of the macro; if the input is in the upper Latin1 range, use the
- * Latin1 (_L1) version of the macro, after converting from utf8; otherwise use
- * the function.  This relies on the fact that ASCII characters have the same
- * representation whether utf8 or not */
-#define generic_utf8(classnum, function, p) (UTF8_IS_INVARIANT(*(p))           \
+/* For internal core Perl use only.  If the input is in the Latin1 range, use
+ * the Latin1 macro, after converting from utf8 if necessary; otherwise use the
+ * function.  This relies on the fact that ASCII characters have the same
+ * representation whether utf8 or not.  Note that all assume that the utf8 has
+ * been validated, and ignore 'use bytes' */
+#define _generic_utf8(classnum, function, p) (UTF8_IS_INVARIANT(*(p))           \
                                          ? _generic_isCC(*(p), classnum)       \
                                          : (UTF8_IS_DOWNGRADEABLE_START(*(p))) \
                                            ? _generic_isCC(                    \
@@ -977,10 +977,7 @@ EXTCONST U32 PL_charclass[];
                                                    classnum)                   \
                                            : (function)(aTHX_ p))
 
-/* Note that all assume that the utf8 has been validated, and ignore 'use
- * bytes' */
-
-#define isWORDCHAR_utf8(p)      generic_utf8(_CC_WORDCHAR, Perl_is_utf8_alnum, p)
+#define isWORDCHAR_utf8(p)      _generic_utf8(_CC_WORDCHAR, Perl_is_utf8_alnum, p)
 #define isALNUM_utf8(p)		isWORDCHAR_utf8(p)  /* back compat */
 /* To prevent S_scan_word in toke.c from hanging, we have to make sure that
  * IDFIRST is an alnum.  See
@@ -989,30 +986,30 @@ EXTCONST U32 PL_charclass[];
  * isIDFIRST_uni() which it hasn't so far.  (In the ASCII range, there isn't a
  * difference.) This used to be not the XID version, but we decided to go with
  * the more modern Unicode definition */
-#define isIDFIRST_utf8(p)       generic_utf8(_CC_IDFIRST, Perl__is_utf8__perl_idstart, p)
-#define isIDCONT_utf8(p)	generic_utf8(_CC_WORDCHAR, Perl_is_utf8_xidcont, p)
-#define isALPHA_utf8(p)		generic_utf8(_CC_ALPHA, Perl_is_utf8_alpha, p)
-#define isBLANK_utf8(p)		generic_utf8(_CC_BLANK, Perl_is_utf8_blank, p)
-#define isSPACE_utf8(p)		generic_utf8(_CC_SPACE, Perl_is_utf8_space, p)
-#define isDIGIT_utf8(p)		generic_utf8(_CC_DIGIT, Perl_is_utf8_digit, p)
-#define isUPPER_utf8(p)		generic_utf8(_CC_UPPER, Perl_is_utf8_upper, p)
-#define isLOWER_utf8(p)		generic_utf8(_CC_LOWER, Perl_is_utf8_lower, p)
+#define isIDFIRST_utf8(p)       _generic_utf8(_CC_IDFIRST, Perl__is_utf8__perl_idstart, p)
+#define isIDCONT_utf8(p)	_generic_utf8(_CC_WORDCHAR, Perl_is_utf8_xidcont, p)
+#define isALPHA_utf8(p)		_generic_utf8(_CC_ALPHA, Perl_is_utf8_alpha, p)
+#define isBLANK_utf8(p)		_generic_utf8(_CC_BLANK, Perl_is_utf8_blank, p)
+#define isSPACE_utf8(p)		_generic_utf8(_CC_SPACE, Perl_is_utf8_space, p)
+#define isDIGIT_utf8(p)		_generic_utf8(_CC_DIGIT, Perl_is_utf8_digit, p)
+#define isUPPER_utf8(p)		_generic_utf8(_CC_UPPER, Perl_is_utf8_upper, p)
+#define isLOWER_utf8(p)		_generic_utf8(_CC_LOWER, Perl_is_utf8_lower, p)
 
 /* Because ASCII is invariant under utf8, the non-utf8 macro works */
 #define isASCII_utf8(p)		isASCII(*p)
 
-#define isCNTRL_utf8(p)		generic_utf8(_CC_CNTRL, Perl_is_utf8_cntrl, p)
-#define isGRAPH_utf8(p)		generic_utf8(_CC_GRAPH, Perl_is_utf8_graph, p)
-#define isPRINT_utf8(p)		generic_utf8(_CC_PRINT, Perl_is_utf8_print, p)
-#define isPUNCT_utf8(p)		generic_utf8(_CC_PUNCT, Perl_is_utf8_punct, p)
-#define isXDIGIT_utf8(p)	generic_utf8(_CC_XDIGIT, Perl_is_utf8_xdigit, p)
+#define isCNTRL_utf8(p)		_generic_utf8(_CC_CNTRL, Perl_is_utf8_cntrl, p)
+#define isGRAPH_utf8(p)		_generic_utf8(_CC_GRAPH, Perl_is_utf8_graph, p)
+#define isPRINT_utf8(p)		_generic_utf8(_CC_PRINT, Perl_is_utf8_print, p)
+#define isPUNCT_utf8(p)		_generic_utf8(_CC_PUNCT, Perl_is_utf8_punct, p)
+#define isXDIGIT_utf8(p)	_generic_utf8(_CC_XDIGIT, Perl_is_utf8_xdigit, p)
 #define toUPPER_utf8(p,s,l)	to_utf8_upper(p,s,l)
 #define toTITLE_utf8(p,s,l)	to_utf8_title(p,s,l)
 #define toLOWER_utf8(p,s,l)	to_utf8_lower(p,s,l)
 
 /* Posix and regular space differ only in U+000B, which is in ASCII (and hence
  * Latin1 */
-#define isPSXSPC_utf8(p)	generic_utf8(_CC_PSXSPC, Perl_is_utf8_space, p)
+#define isPSXSPC_utf8(p)	_generic_utf8(_CC_PSXSPC, Perl_is_utf8_space, p)
 
 #define isALNUM_LC_utf8(p)	isALNUM_LC_uvchr(valid_utf8_to_uvchr(p,  0))
 #define isIDFIRST_LC_utf8(p)	isIDFIRST_LC_uvchr(valid_utf8_to_uvchr(p,  0))