embed.fnc: Add ability to customize ARGS_ASSERT macros

This enhances embed.fnc entries to contain arbitrary assert() calls,
which will be added to the corresponding generated ARGS_ASSERT macros.

The next commit will use it.

Author: khwilliamson

embed.fnc

@@ -35,7 +35,7 @@
 :		Supported at least since perl-5.23.8, with or without ppport.h.
 :
 : Lines in this file are of the form:
-:    flags|return_type|name|arg1|arg2|...|argN
+:    flags|return_type|name|arg1|arg2|...|argN ( assert(...) )*
 :
 : 'flags' is a string of single letters.  Most of the flags are meaningful only
 : to embed.pl; some only to autodoc.pl, and others only to makedef.pl.  The
@@ -46,6 +46,9 @@
 : A line may be continued onto the next by ending it with a backslash.
 : Leading and trailing whitespace will be ignored in each component.
 :
+: The optional list of asserts are used to customize the generated
+: PERL_ARGS_ASSERT macro.  See AUTOMATIC PARAMETER SANITY CHECKING below
+:
 : Most entries here have a macro created with the entry name.  This presents
 : name space collision potentials which haven't been well thought out, but are
 : now documented here.  In practice this has rarely been an issue.  At least,
@@ -168,6 +171,13 @@
 :	may not be of the correct type. As already mentioned, NOCHECK
 :	suppresses this check.
 :
+:   You can specify your own checking beyond these by adding any number of
+:   assert() calls to en entry after the final argument.  Whatever you specify
+:   will be added to the ARGS_ASSERT macro for the entry in the order you've
+:   specified, and after all the assertions that already have been described in
+:   this section.  When adding yours, weigh that doing it here will make it
+:   less visible to a maintainer than keeping it in the function it applies to
+:
 :   Currently, it is optional to include an empty ARGS_ASSERT macro in your
 :   functions.  But a porting test enforces that a non-empty one is included.
 :   The call should be at the top of your function so that the sanity checks

regen/HeaderParser.pm

@@ -746,6 +746,11 @@ sub tidy_embed_fnc_entry {
     $line =~ s/\s+\z//;         # No trailing white space
     ($line)= expand($line);     # No tabs
 
+    # Remove any assertions, and save them.  This must be done before the
+    # split because the assertions can contain '|'
+    $line =~ s/ \b ( assert \s* \( .* ) \z //x;
+    my $assertions = $1;
+
     # Split into fields
     my ($flags, $ret, $name, @args)= split /\s*\|\s*/, $line;
 
@@ -795,6 +800,28 @@ sub tidy_embed_fnc_entry {
         $head .= "|$arg";
         $head .= "\\\n" . (" " x 32) if $ix < $#args;
     }
+
+    my @assertions;
+    if ($assertions) {
+        # Put each assertion into a separate array element
+        @assertions = split / \s* assert \s* \( /x, $assertions;
+        shift @assertions;  # The split leaves an empty first element
+
+        # Trim each assertion, including any trailing semicolon
+        foreach my $this_assertion (@assertions) {
+            $this_assertion =~ s/ ^ \s+  //x;
+            $this_assertion =~ s/ \s+ \z //x;
+            $this_assertion =~ s/ ; \z   //x;
+
+            # Restore split delimitter
+            $this_assertion = "assert($this_assertion";
+
+            # Each assertion is on a separate line (for now, anyway)
+            $head .= "\\\n" . (" " x 32);
+            $head .= $this_assertion;
+        }
+    }
+
     $line= $head . "\n";
 
     # Make all lines in this entry the same length; minimum 72
@@ -816,6 +843,7 @@ sub tidy_embed_fnc_entry {
         return_type => $ret,
         name        => $name,
         args        => \@args,
+        assertions  => \@assertions,
     );
 
     $line =~ s/\s+\z/\n/;

regen/embed.pl

@@ -121,7 +121,8 @@ sub generate_proto_h {
         $ind .= "  " x ($level-1) if $level>1;
         my $inner_ind= $ind ? "  " : " ";
 
-        my ($flags,$retval,$plain_func,$args) = @{$embed}{qw(flags return_type name args)};
+        my ($flags, $retval, $plain_func, $args, $assertions ) =
+                        @{$embed}{qw(flags return_type name args assertions)};
         if ($flags =~ / ( [^ AabCDdEefFGhIiMmNnOoPpRrSsTUuvWXx;] ) /xx) {
             die_at_end "flag $1 is not legal (for function $plain_func)";
         }
@@ -311,6 +312,9 @@ sub generate_proto_h {
         }
         $ret .= " comma_pDEPTH" if $has_depth;
         $ret .= ")";
+
+        push @asserts, $assertions->@* if $assertions;
+
         my @attrs;
         if ( $flags =~ /r/ ) {
             push @attrs, "__attribute__noreturn__";