perl.plp

   1 <(common.inc.plp)><:
   2
   3 Html({
   4         title => 'perl version cheat sheet',
   5         version => '1.8',
   6         keywords => [qw'
   7                 perl version feature features comparison
   8                 sheet cheat overview summary
   9         '],
  10         image => 'data/camels.jpg',
  11         stylesheet => [qw'light dark red'],
  12         data => ['perl.inc.pl'],
  13 });
  14
  15 use experimental 'signatures';
  16 :>
  17 <h1>Perl release summary</h1>
  18
  19 <p>The most significant features introduced for recent versions of the Perl
  20 scripting language.
  21 <:
  22 my $info = Data('perl');
  23
  24 use feature 'signatures';
  25 sub vname ($v) {
  26         return sprintf 'v%d%03d', unpack 'C*', $v;
  27 }
  28 sub linkversion ($v) {
  29         return showlink(sprintf('%vd', $v), '#'.vname($v));
  30 }
  31
  32 eval {
  33         use List::Util 'first';
  34         use Time::Piece;
  35         use Time::Seconds;
  36
  37         my $now = Time::Piece->new;
  38         if (my $ts = $get{at}) {
  39                 $now = $now->strptime($ts, '%Y-%m-%d');
  40                 say "Compatibility details emulated for <em>$ts</em>.";
  41         }
  42         my $ts = $now->strftime('%F');
  43         my @versions = sort grep { $info->{$_}{release} le $ts } keys %{$info};
  44
  45         # perlpolicy: «We "officially" support the two most recent stable release
  46         # series. [...] we will attempt to fix critical issues»
  47         $info->{ $versions[-2] }{versum} //= "active core support";
  48         $info->{ $versions[-1] }{versum} //= "latest stable release";
  49
  50         # perlpolicy: «we will attempt to fix critical issues in the two most
  51         # recent stable 5.x release series»
  52         my $coreeol = ($now - ONE_YEAR * 3)->strftime('%F');
  53         my $vcore = first { $info->{$_}{release} ge $coreeol } @versions;
  54         print "<p>Core security support is provided for 3 years";
  55         print ", so typical users should run at least ", linkversion($_)
  56                 for $vcore // ();
  57         say '.';
  58         $info->{$vcore}{versum} //= "official security patches";
  59
  60         # «We encourage vendors to ship the most recent supported release of Perl
  61         # at the time of their code freeze»
  62         # assume debian ships after 1 year, and expires after 5 years LTS
  63         my $vendoreol = ($now - ONE_YEAR * 6)->strftime('%F');
  64         my $vdebian = first {
  65                 $info->{$_}{release} ge $vendoreol && $info->{$_}{distro}{debian}
  66         } @versions;
  67         say sprintf "Stable distributions such as Debian %s maintain %s+.",
  68                 $info->{$_}{distro}{debian}, linkversion($_) for $vdebian // ();
  69         $info->{$vdebian}{versum} //= "still maintained by common vendors";
  70
  71         # extended support given at random
  72         my $nowcmp = $now->strftime('%F');
  73         my $vdino = first { $info->{$_}{support} ge $nowcmp } @versions;
  74         say "Enterprise platforms retain versions up to $_."
  75                 for map { linkversion($_) } $vdino // ();
  76         return 1;
  77 } or Alert('Missing version recommendations', $@);
  78 say '</p>';
  79
  80 for my $vernum (reverse sort keys %{$info}) {
  81         my $verrow = $info->{$vernum};
  82         defined $verrow->{unstable} and next unless exists $get{v};
  83
  84         say sprintf '<div class="section" id="%s">', vname($vernum);
  85         my $title = $verrow->{release} // '?';
  86         $title .= ": $_" for $verrow->{versum} // ();
  87         say sprintf '<h2>%vd <small>%s</small></h2>', $vernum, $title;
  88         say '<dl>';
  89         for (@{ $verrow->{new} }) {
  90                 my ($topic, $desc, $attr) = @{$_};
  91                 $desc .= featattrs($attr);
  92                 my $ref = defined $attr->{name} && sprintf ' id="%s"', $attr->{name};
  93                 say sprintf '<dt%s>%s<dd>%s', $ref, $topic, $desc || '<br/>';
  94         }
  95         if (my $mods = $verrow->{modules}) {
  96                 for (@{$mods}) {
  97                         my ($name, $desc, $attr) = @{$_};
  98                         my $ref = lc $name =~ s/::/_/gr;
  99                         $desc .= featattrs($attr);
 100                         printf '<dt id="%s"><code>use %s</code>', $ref, $name;
 101                         say '<dd>', $desc;
 102                 }
 103         }
 104         say sprintf '<dt>Unicode</dt><dd>v%s', $_ for $verrow->{unicode} || ();
 105         say '</dl>';
 106         say "</div>\n";
 107 }
 108
 109 sub featattrs ($attr) {
 110         $attr or return '';
 111         ref $attr or $attr = {eg => $attr};
 112         my $title;
 113         if (defined $attr->{experimental}) {
 114                 $title = 'experimental';
 115         }
 116         if (defined $attr->{dropped}) {
 117                 no warnings 'exiting';
 118                 next unless exists $get{v}; # skip containing feature
 119                 $title = sprintf 'removed in %vd', $_ for $attr->{dropped} || ();
 120         }
 121         elsif ($attr->{stable}) {
 122                 $title .= sprintf ' until %vd', $attr->{stable};
 123         }
 124         if ($attr->{experimental}) {
 125                 $title = sprintf '<span title="experimental::%s">%s</span>',
 126                         $attr->{experimental}, $title;
 127                 $attr->{name} //= $attr->{experimental};
 128         }
 129         if ($attr->{feature}) {
 130                 my $prefix = sprintf '<span title="%s">feature</span>',
 131                         $attr->{feature};
 132                 $title = join ', ', $prefix, $title // ();
 133                 $attr->{name} //= $attr->{feature};
 134         }
 135         $title = $title ? sprintf ' <em class="ex">(%s)</em>', $title : '';
 136
 137         if (my $eg = $attr->{eg}) {
 138                 my $pre = Entity($eg);
 139                 $pre =~ s<\N{ZERO WIDTH SPACE}>{</code><wbr/><code>}g;
 140                 $pre = " <small>{<code>$pre</code>}</small>";
 141                 $title = $pre . $title;
 142         }
 143         return $title;
 144 }