From 922cda0836df6901bba2f8f600f85b69520cae95 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sun, 4 Jan 2026 05:54:14 -0700 Subject: [PATCH 1/3] embed.pl: Use /xx to make pattern clearer This adds white space to a character class, and reorders things like Mm to mM to make it much easier to read. --- regen/embed.pl | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/regen/embed.pl b/regen/embed.pl index 7dc72f765831..5c0e268bcf35 100755 --- a/regen/embed.pl +++ b/regen/embed.pl @@ -3655,7 +3655,9 @@ sub generate_proto_h { my ($flags, $retval, $plain_func, $args, $assertions ) = @{$embed}{qw(flags return_type name args assertions)}; - if ($flags =~ / ( [^ AabCDdEefFhIiMmNnOoPpRrSsTUuWXx;] ) /xx) { + if ($flags =~ + m/([^ aA b C dD eE fF h iI mM nN oO pP Rr sS T uU W xX ; ])/xx) + { die_at_end "flag $1 is not legal (for function $plain_func)"; } From 1ca122b7870fbc0bdf834d92d5f08a4156291724 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sun, 4 Jan 2026 05:51:45 -0700 Subject: [PATCH 2/3] Add 'v' flag for embed.fnc/apidoc An enum constant isn't a macro; it can't be #undef-ined. This distinction will matter in a future commit, so create a separate flag for elements like this. I suspect this would also apply to other types of elements, such as struct members, should we eventually need to deal with those. --- autodoc.pl | 10 ++++++---- embed.fnc | 9 ++++++++- regen/embed.pl | 2 +- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 7f95ea0d6d3c..ef1aca9f860e 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -75,7 +75,7 @@ use warnings; my $known_flags_re = - qr/[ aA bC dD eE fF h iI mM nN oO pP rR sS T uU vW xX y ;@#? ] /xx; + qr/[ aA bC dD eE fF h iI mM nN oO pP rR sS T uU v W xX y ;@#? ] /xx; # Flags that don't apply to this program, like implementation details. my $irrelevant_flags_re = qr/[ ab eE iI P rR X? ]/xx; @@ -617,7 +617,9 @@ sub check_and_add_proto_defn { $flags .= "m" if $flags =~ /M/; $flags .= "U" if $flags =~ /@/; # No usage output for @arrays - $flags .= "n" if $flags =~ /#/; # No threads, arguments for #ifdef + $flags .= "n" if $flags =~ /[#v]/; # No threads, arguments for #ifdef's, + # plain values + my @munged_args= $args_ref->@*; s/\b(?:NN|NULLOK|[SM]PTR|EPTRQ?)\b\s+//g for @munged_args; @@ -1904,9 +1906,9 @@ ($fh, $section_name, $element_name, $docref) my $has_args = $flags !~ /n/; if (! $has_args) { - warn "$name: n flag without [m#] " + warn "$name: n flag without [mv#] " . where_from_string($item->{file}, $item->{line_num}) - unless $flags =~ /[m#]/; + unless $flags =~ /[mv#]/; if ($item->{args} && $item->{args}->@*) { warn "$name: n flag but apparently has args" diff --git a/embed.fnc b/embed.fnc index e8409f450d89..44783ddb1817 100644 --- a/embed.fnc +++ b/embed.fnc @@ -364,7 +364,7 @@ : : The 'name' in any such line must not be the same as any in this file (i.e., : no redundant definitions), and one of the flags on the apidoc lines must be -: 'm', 'y', or '@', indicating it is not a function. +: 'm', 'v', 'y', or '@', indicating it is not a function. : : All but the name field of an apidoc_item line are optional, and if empty, : inherits from a corresponding apidoc_defn line, if one exists, or the @@ -713,6 +713,13 @@ : tools, such as Devel::PPPort, that this requires special handling. : : 'U' autodoc.pl will not output a usage example +: +: 'v' The element is some sort of value that isn't any of the other types in +: this file. For example, it could be an enumeration constant; that is, +: it is one of the members of the list of constants a variable declared +: to be a particular enum can have. These are always visible to XS code +: unless guarded by preprocessor directives, Also implies 'n'. + : : 'W' Add a comma_pDEPTH argument to function prototypes, and a comma_aDEPTH : argument to the function calls. This means that under DEBUGGING a diff --git a/regen/embed.pl b/regen/embed.pl index 5c0e268bcf35..1cfe35a8217e 100755 --- a/regen/embed.pl +++ b/regen/embed.pl @@ -3656,7 +3656,7 @@ sub generate_proto_h { my ($flags, $retval, $plain_func, $args, $assertions ) = @{$embed}{qw(flags return_type name args assertions)}; if ($flags =~ - m/([^ aA b C dD eE fF h iI mM nN oO pP Rr sS T uU W xX ; ])/xx) + m/([^ aA b C dD eE fF h iI mM nN oO pP Rr sS T uU v W xX ; ])/xx) { die_at_end "flag $1 is not legal (for function $plain_func)"; } From 4a0cce460b94c7416a0b074200d6f1ff16b9f0c8 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Sun, 4 Jan 2026 06:01:07 -0700 Subject: [PATCH 3/3] REGEX_LOCALE_CHARSET is an enum constant Previously, it was considered a macro. But the previous commit created a new flag for elements like this, which this commit now changes to use. --- pod/perlreapi.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod index 00dc87c6da67..8d2f134a7e34 100644 --- a/pod/perlreapi.pod +++ b/pod/perlreapi.pod @@ -165,7 +165,7 @@ is defined as per L, and by the internal macros C under UTF-8, and C under C. -=for apidoc Amnh||REGEX_LOCALE_CHARSET +=for apidoc Avnh||REGEX_LOCALE_CHARSET =back