This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Croak on unimplemented already at import time
[perl5.git] / ext / POSIX / lib / POSIX.pm
index 2b339b7..fcaf298 100644 (file)
@@ -4,7 +4,7 @@ use warnings;
 
 our ($AUTOLOAD, %SIGRT);
 
-our $VERSION = '1.64';
+our $VERSION = '1.68';
 
 require XSLoader;
 
@@ -18,18 +18,6 @@ use Fcntl qw(FD_CLOEXEC F_DUPFD F_GETFD F_GETFL F_GETLK F_RDLCK F_SETFD
 
 my $loaded;
 
-sub import {
-    my $pkg = shift;
-
-    load_imports() unless $loaded++;
-
-    # Grandfather old foo_h form to new :foo_h form
-    s/^(?=\w+_h$)/:/ for my @list = @_;
-
-    local $Exporter::ExportLevel = 1;
-    Exporter::import($pkg,@list);
-}
-
 sub croak { require Carp;  goto &Carp::croak }
 sub usage { croak "Usage: POSIX::$_[0]" }
 
@@ -110,6 +98,7 @@ my %replacement = (
     strspn      => undef,
     strtok      => undef,
     tmpfile     => 'IO::File::new_tmpfile',
+    tmpnam      => 'use File::Temp',
     ungetc      => 'IO::Handle::ungetc',
     vfprintf    => undef,
     vprintf     => undef,
@@ -117,74 +106,105 @@ my %replacement = (
 );
 
 my %reimpl = (
+    abs       => 'x => CORE::abs($_[0])',
+    alarm     => 'seconds => CORE::alarm($_[0])',
     assert    => 'expr => croak "Assertion failed" if !$_[0]',
-    tolower   => 'string => lc($_[0])',
-    toupper   => 'string => uc($_[0])',
-    closedir  => 'dirhandle => CORE::closedir($_[0])',
-    opendir   => 'directory => my $dh; CORE::opendir($dh, $_[0]) ? $dh : undef',
-    readdir   => 'dirhandle => CORE::readdir($_[0])',
-    rewinddir => 'dirhandle => CORE::rewinddir($_[0])',
-    errno     => '$! + 0',
-    creat     => 'filename, mode => &open($_[0], &O_WRONLY | &O_CREAT | &O_TRUNC, $_[1])',
-    fcntl     => 'filehandle, cmd, arg => CORE::fcntl($_[0], $_[1], $_[2])',
-    getgrgid  => 'gid => CORE::getgrgid($_[0])',
-    getgrnam  => 'name => CORE::getgrnam($_[0])',
     atan2     => 'x, y => CORE::atan2($_[0], $_[1])',
+    chdir     => 'directory => CORE::chdir($_[0])',
+    chmod     => 'mode, filename => CORE::chmod($_[0], $_[1])',
+    chown     => 'uid, gid, filename => CORE::chown($_[0], $_[1], $_[2])',
+    closedir  => 'dirhandle => CORE::closedir($_[0])',
     cos       => 'x => CORE::cos($_[0])',
+    creat     => 'filename, mode => &open($_[0], &O_WRONLY | &O_CREAT | &O_TRUNC, $_[1])',
+    errno     => '$! + 0',
+    exit      => 'status => CORE::exit($_[0])',
     exp       => 'x => CORE::exp($_[0])',
     fabs      => 'x => CORE::abs($_[0])',
-    log       => 'x => CORE::log($_[0])',
-    pow       => 'x, exponent => $_[0] ** $_[1]',
-    sin       => 'x => CORE::sin($_[0])',
-    sqrt      => 'x => CORE::sqrt($_[0])',
-    getpwnam  => 'name => CORE::getpwnam($_[0])',
-    getpwuid  => 'uid => CORE::getpwuid($_[0])',
-    kill      => 'pid, sig => CORE::kill $_[1], $_[0]',
-    raise     => 'sig => CORE::kill $_[0], $$; # Is this good enough',
+    fcntl     => 'filehandle, cmd, arg => CORE::fcntl($_[0], $_[1], $_[2])',
+    fork      => 'CORE::fork',
+    fstat     => 'fd => CORE::open my $dup, "<&", $_[0]; CORE::stat($dup)', # Gross.
     getc      => 'handle => CORE::getc($_[0])',
     getchar   => 'CORE::getc(STDIN)',
-    gets      => 'scalar <STDIN>',
-    remove    => 'filename => (-d $_[0]) ? CORE::rmdir($_[0]) : CORE::unlink($_[0])',
-    rename    => 'oldfilename, newfilename => CORE::rename($_[0], $_[1])',
-    rewind    => 'filehandle => CORE::seek($_[0],0,0)',
-    abs       => 'x => CORE::abs($_[0])',
-    exit      => 'status => CORE::exit($_[0])',
-    getenv    => 'name => $ENV{$_[0]}',
-    system    => 'command => CORE::system($_[0])',
-    strerror  => 'errno => BEGIN { local $!; require locale; locale->import} my $e = $_[0] + 0; local $!; $! = $e; "$!"',
-    strstr    => 'big, little => CORE::index($_[0], $_[1])',
-    chmod     => 'mode, filename => CORE::chmod($_[0], $_[1])',
-    fstat     => 'fd => CORE::open my $dup, "<&", $_[0]; CORE::stat($dup)', # Gross.
-    mkdir     => 'directoryname, mode => CORE::mkdir($_[0], $_[1])',
-    stat      => 'filename => CORE::stat($_[0])',
-    umask     => 'mask => CORE::umask($_[0])',
-    wait      => 'CORE::wait()',
-    waitpid   => 'pid, options => CORE::waitpid($_[0], $_[1])',
-    gmtime    => 'time => CORE::gmtime($_[0])',
-    localtime => 'time => CORE::localtime($_[0])',
-    time      => 'CORE::time',
-    alarm     => 'seconds => CORE::alarm($_[0])',
-    chdir     => 'directory => CORE::chdir($_[0])',
-    chown     => 'uid, gid, filename => CORE::chown($_[0], $_[1], $_[2])',
-    fork      => 'CORE::fork',
     getegid   => '$) + 0',
+    getenv    => 'name => $ENV{$_[0]}',
     geteuid   => '$> + 0',
     getgid    => '$( + 0',
+    getgrgid  => 'gid => CORE::getgrgid($_[0])',
+    getgrnam  => 'name => CORE::getgrnam($_[0])',
     getgroups => 'my %seen; grep !$seen{$_}++, split " ", $)',
     getlogin  => 'CORE::getlogin()',
     getpgrp   => 'CORE::getpgrp',
     getpid    => '$$',
     getppid   => 'CORE::getppid',
+    getpwnam  => 'name => CORE::getpwnam($_[0])',
+    getpwuid  => 'uid => CORE::getpwuid($_[0])',
+    gets      => 'scalar <STDIN>',
     getuid    => '$<',
+    gmtime    => 'time => CORE::gmtime($_[0])',
     isatty    => 'filehandle => -t $_[0]',
+    kill      => 'pid, sig => CORE::kill $_[1], $_[0]',
     link      => 'oldfilename, newfilename => CORE::link($_[0], $_[1])',
+    localtime => 'time => CORE::localtime($_[0])',
+    log       => 'x => CORE::log($_[0])',
+    mkdir     => 'directoryname, mode => CORE::mkdir($_[0], $_[1])',
+    opendir   => 'directory => my $dh; CORE::opendir($dh, $_[0]) ? $dh : undef',
+    pow       => 'x, exponent => $_[0] ** $_[1]',
+    raise     => 'sig => CORE::kill $_[0], $$; # Is this good enough',
+    readdir   => 'dirhandle => CORE::readdir($_[0])',
+    remove    => 'filename => (-d $_[0]) ? CORE::rmdir($_[0]) : CORE::unlink($_[0])',
+    rename    => 'oldfilename, newfilename => CORE::rename($_[0], $_[1])',
+    rewind    => 'filehandle => CORE::seek($_[0],0,0)',
+    rewinddir => 'dirhandle => CORE::rewinddir($_[0])',
     rmdir     => 'directoryname => CORE::rmdir($_[0])',
+    sin       => 'x => CORE::sin($_[0])',
+    sqrt      => 'x => CORE::sqrt($_[0])',
+    stat      => 'filename => CORE::stat($_[0])',
+    strerror  => 'errno => BEGIN { local $!; require locale; locale->import} my $e = $_[0] + 0; local $!; $! = $e; "$!"',
+    strstr    => 'big, little => CORE::index($_[0], $_[1])',
+    system    => 'command => CORE::system($_[0])',
+    time      => 'CORE::time',
+    tolower   => 'string => lc($_[0])',
+    toupper   => 'string => uc($_[0])',
+    umask     => 'mask => CORE::umask($_[0])',
     unlink    => 'filename => CORE::unlink($_[0])',
     utime     => 'filename, atime, mtime => CORE::utime($_[1], $_[2], $_[0])',
+    wait      => 'CORE::wait()',
+    waitpid   => 'pid, options => CORE::waitpid($_[0], $_[1])',
 );
 
+sub import {
+    my $pkg = shift;
+
+    load_imports() unless $loaded++;
+
+    # Grandfather old foo_h form to new :foo_h form
+    s/^(?=\w+_h$)/:/ for my @list = @_;
+
+    my @unimpl = sort grep { exists $replacement{$_} } @list;
+    if (@unimpl) {
+      for my $u (@unimpl) {
+        warn "Unimplemented: POSIX::$u(): ", unimplemented_message($u);
+      }
+      croak(sprintf("Unimplemented: %s",
+                    join(" ", map { "POSIX::$_()" } @unimpl)));
+    }
+
+    local $Exporter::ExportLevel = 1;
+    Exporter::import($pkg,@list);
+}
+
 eval join ';', map "sub $_", keys %replacement, keys %reimpl;
 
+sub unimplemented_message {
+  my $func = shift;
+  my $how = $replacement{$func};
+  return "C-specific, stopped" unless defined $how;
+  return "$$how" if ref $how;
+  return "$how instead" if $how =~ /^use /;
+  return "Use method $how() instead" if $how =~ /::/;
+  return "C-specific: use $how instead";
+}
+
 sub AUTOLOAD {
     my ($func) = ($AUTOLOAD =~ /.*::(.*)/);
 
@@ -207,12 +227,7 @@ sub AUTOLOAD {
        goto &$AUTOLOAD;
     }
     if (exists $replacement{$func}) {
-       my $how = $replacement{$func};
-       croak "Unimplemented: POSIX::$func() is C-specific, stopped"
-           unless defined $how;
-       croak "Unimplemented: POSIX::$func() is $$how" if ref $how;
-       croak "Use method $how() instead of POSIX::$func()" if $how =~ /::/;
-       croak "Unimplemented: POSIX::$func() is C-specific: use $how instead";
+      croak "Unimplemented: POSIX::$func(): ", unimplemented_message($func);
     }
 
     constant($func);
@@ -234,7 +249,7 @@ sub sprintf {
 }
 
 sub load_imports {
-my %default_export_tags = (
+my %default_export_tags = ( # cf. exports policy below
 
     assert_h =>        [qw(assert NDEBUG)],
 
@@ -404,7 +419,7 @@ if ($^O eq 'MSWin32') {
        WSAEREFUSED)];
 }
 
-my %other_export_tags = (
+my %other_export_tags = ( # cf. exports policy below
     fenv_h => [qw(
         FE_DOWNWARD FE_TONEAREST FE_TOWARDZERO FE_UPWARD fegetround fesetround
     )],
@@ -435,6 +450,10 @@ my %other_export_tags = (
   )],
 );
 
+# exports policy:
+# - new functions may not be added to @EXPORT, only to @EXPORT_OK
+# - new SHOUTYCONSTANTS are OK to add to @EXPORT
+
 {
   # De-duplicate the export list: 
   my ( %export, %export_ok );
@@ -444,8 +463,12 @@ my %other_export_tags = (
   # @EXPORT are actually shared hash key scalars, which will save some memory.
   our @EXPORT = keys %export;
 
+  # you do not want to add symbols to the following list. add a new tag instead
   our @EXPORT_OK = (qw(close lchown nice open pipe read sleep times write
-                      printf sprintf),
+                      printf sprintf lround),
+                    # lround() should really be in the :math_h_c99 tag, but
+                    # we're too far into the 5.24 code freeze for that to be
+                    # done now. This can be revisited in the 5.25.x cycle.
                    grep {!exists $export{$_}} keys %reimpl, keys %replacement, keys %export_ok);
 
   our %EXPORT_TAGS = ( %default_export_tags, %other_export_tags );