Document and clean up -s option to xsubpp

At the same time, discourage its use. It's an obscure option that, most
of the time, does the opposite of what people actually need. If nothing
else, it should be a feature of XS instead of xsubpp.

But it exists, so documenting it with a warning is the right thing to
do.

2 files changed, 23 insertions, 13 deletions

diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm
index b75be2b454..8cf9831c4b 100644
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/ParseXS.pm
@@ -179,18 +179,11 @@ sub process_file {
 
   $self->{typemap} = process_typemaps( $args{typemap}, $pwd );
 
-  # Since at this point we're ready to begin printing to the output file and
-  # reading from the input file, I want to get as much data as possible into
-  # the proto-object $self.  That means assigning to $self and elements of
-  # %args referenced below this point.
-  # HOWEVER:  This resulted in an error when I tried:
-  #   $args{'s'} ---> $self->{s}.
-  # Use of uninitialized value in quotemeta at
-  #   .../blib/lib/ExtUtils/ParseXS.pm line 733
-
+  # Move more settings from parameters to object
   foreach my $datum ( qw| argtypes except inout optimize | ) {
     $self->{$datum} = $args{$datum};
   }
+  $self->{strip_c_func_prefix} = $args{s};
 
   # Identify the version of xsubpp used
   print <<EOM;
@@ -670,8 +663,9 @@ EOF
               print "THIS->";
             }
           }
-          $self->{func_name} =~ s/^\Q$args{'s'}//
-            if exists $args{'s'};
+          my $strip = $self->{strip_c_func_prefix};
+          $self->{func_name} =~ s/^\Q$strip//
+            if defined $strip;
           $self->{func_name} = 'XSFUNCTION' if $self->{interface};
           print "$self->{func_name}($self->{func_args});\n";
         }
diff --git a/dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp b/dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp
index 7006fcb9fc..e2ac71a323 100644
--- a/dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp
+++ b/dist/ExtUtils-ParseXS/lib/ExtUtils/xsubpp
@@ -16,7 +16,7 @@ use Getopt::Long;
 
 my %args = ();
 
-my $usage = "Usage: xsubpp [-v] [-csuffix csuffix] [-except] [-prototypes] [-noversioncheck] [-nolinenumbers] [-nooptimize] [-noinout] [-noargtypes] [-s pattern] [-typemap typemap]... file.xs\n";
+my $usage = "Usage: xsubpp [-v] [-csuffix csuffix] [-except] [-prototypes] [-noversioncheck] [-nolinenumbers] [-nooptimize] [-noinout] [-noargtypes] [-strip|s pattern] [-typemap typemap]... file.xs\n";
 
 Getopt::Long::Configure qw(no_auto_abbrev no_ignore_case);
 
@@ -33,7 +33,7 @@ GetOptions(\%args, qw(hiertype!
 		      v
 		      typemap=s@
 		      output=s
-		      s=s
+		      s|strip=s
 		      csuffix=s
 		     ))
   or die $usage;
@@ -145,6 +145,22 @@ Currently doesn't do anything at all.  This flag has been a no-op for
 many versions of perl, at least as far back as perl5.003_07.  It's
 allowed here for backwards compatibility.
 
+=item B<-s=...> or B<-strip=...>
+
+I<This option is obscure and discouraged.>
+
+If specified, the given string will be stripped off from the beginning
+of the C function name in the generated XS functions (if it starts with that prefix).
+This only applies to XSUBs without C<CODE> or C<PPCODE> blocks.
+For example, the XS:
+
+  void foo_bar(int i);
+
+when C<xsubpp> is invoked with C<-s foo_> will install a C<foo_bar>
+function in Perl, but really call C<bar(i)> in C. Most of the time,
+this is the opposite of what you want and failure modes are somewhat
+obscure, so please avoid this option where possible.
+
 =back
 
 =head1 ENVIRONMENT