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

@@ -158,6 +158,12 @@
 :
 :   For a numeric argument, you may specify that it can't be 0 by using 'NZ'
 :
+:   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.  When doing so, weigh
+:   that doing it here will make it less visible to a maintainer than keeping
+:   it in the function it applies to
+:
 :   regen/embed.pl may automatically add further checking for any argument as
 :   it deems desirable.  You can override this by specifying 'NOCHECK'
 :

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/ ( 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__";