index: release v1.18 with only altgr index linked

[sheet.git] / perl.plp

diff --git a/perl.plp b/perl.plp
index 7b230383a50c813afb4394dd2647da5b4fd706f4..596e4d84d80afeafe4dece3facdbe662e04d326c 100644 (file)
--- a/perl.plp
+++ b/perl.plp
@@ -2,7 +2,7 @@
 
 Html({
        title => 'perl version cheat sheet',
 
 Html({
        title => 'perl version cheat sheet',

-       version => 'v1.0',
+       version => '1.6',

        keywords => [qw'
                perl version feature features comparison
                sheet cheat overview summary
        keywords => [qw'
                perl version feature features comparison
                sheet cheat overview summary


@@ -11,24 +11,132 @@ Html({
        data => ['perl.inc.pl'],
 });
 
        data => ['perl.inc.pl'],
 });
 

+use experimental 'signatures';

 :>
 <h1>Perl release summary</h1>
 
 :>
 <h1>Perl release summary</h1>
 

-<p>The most significant features introduced for recent versions of the Perl scripting language.
-Depending on desired compatibility you'll want to support a minimum of
-<span title="on stable/enterprise platforms such as Solaris 10, RHEL 3, SLES 8">v5.8</span> or
-<span title="on up-to-date servers such as Debian wheezy, Ubuntu 12.04, CentOS 7">v5.14</span>.
-</p>
-
+<p>The most significant features introduced for recent versions of the Perl
+scripting language.

 <:
 <:

-my $info = do 'perl.inc.pl' or die $@ // $!;
+my $info = Data('perl');
+
+use feature 'signatures';
+sub vname ($v) {
+       return sprintf 'v%d%03d', unpack 'C*', $v;
+}
+sub linkversion ($v) {
+       return showlink(sprintf('%vd', $v), '#'.vname($v));
+}
+
+eval {
+       use List::Util 'first';
+       use Time::Piece;
+       use Time::Seconds;
+
+       my $now = Time::Piece->new;
+       if (my $ts = $get{at}) {
+               $now = $now->strptime($ts, '%Y-%m-%d');
+               say "Compatibility details emulated for <em>$ts</em>.";
+       }
+       my $ts = $now->strftime('%F');
+       my @versions = sort grep { $info->{$_}{release} le $ts } keys %{$info};
+
+       # perlpolicy: «We "officially" support the two most recent stable release
+       # series. [...] we will attempt to fix critical issues»
+       $info->{ $versions[-2] }{versum} //= "active core support";
+       $info->{ $versions[-1] }{versum} //= "latest stable release";
+
+       # perlpolicy: «we will attempt to fix critical issues in the two most
+       # recent stable 5.x release series»
+       my $coreeol = ($now - ONE_YEAR * 3)->strftime('%F');
+       my $vcore = first { $info->{$_}{release} ge $coreeol } @versions;
+       print "<p>Core security support is provided for 3 years";
+       print ", so typical users should run at least ", linkversion($_)
+               for $vcore // ();
+       say '.';
+       $info->{$vcore}{versum} //= "official security patches";
+
+       # «We encourage vendors to ship the most recent supported release of Perl
+       # at the time of their code freeze»
+       # assume debian ships after 1 year, and expires after 5 years LTS
+       my $vendoreol = ($now - ONE_YEAR * 6)->strftime('%F');
+       my $vdebian = first {
+               $info->{$_}{release} ge $vendoreol && $info->{$_}{distro}{debian}
+       } @versions;
+       say sprintf "Stable distributions such as Debian %s maintain %s+.",
+               $info->{$_}{distro}{debian}, linkversion($_) for $vdebian // ();
+       $info->{$vdebian}{versum} //= "still maintained by common vendors";
+
+       # extended support given at random
+       my $nowcmp = $now->strftime('%F');
+       my $vdino = first { $info->{$_}{support} ge $nowcmp } @versions;
+       say "Enterprise platforms retain versions up to $_."
+               for map { linkversion($_) } $vdino // ();
+       return 1;
+} or Alert('Missing version recommendations', $@);
+say '</p>';
+

 for my $vernum (reverse sort keys %{$info}) {
        my $verrow = $info->{$vernum};
 for my $vernum (reverse sort keys %{$info}) {
        my $verrow = $info->{$vernum};

-       print '<div class="section">'."\n";
-       printf '<h2>%vd <small>%s</small></h2><dl>'."\n", $vernum, $verrow->{release};
-       printf '<dt>%s<dd>%s', @{$_}, '<br/>' for @{ $verrow->{new} };
-       printf '<dt>Unicode</dt><dd>v%s', $_ for $verrow->{unicode} || ();
-       print "</dl>\n";
-       print "</div>\n\n";
+       defined $verrow->{unstable} and next unless exists $get{v};
+
+       say sprintf '<div class="section" id="%s">', vname($vernum);
+       my $title = $verrow->{release} // '?';
+       $title .= ": $_" for $verrow->{versum} // ();
+       say sprintf '<h2>%vd <small>%s</small></h2>', $vernum, $title;
+       say '<dl>';
+       for (@{ $verrow->{new} }) {
+               my ($topic, $desc, $attr) = @{$_};
+               $desc .= featattrs($attr);
+               my $ref = defined $attr->{name} && sprintf ' id="%s"', $attr->{name};
+               say sprintf '<dt%s>%s<dd>%s', $ref, $topic, $desc || '<br/>';
+       }
+       if (my $mods = $verrow->{modules}) {
+               for (@{$mods}) {
+                       my ($name, $desc, $attr) = @{$_};
+                       my $ref = lc $name =~ s/::/_/gr;
+                       $desc .= featattrs($attr);
+                       printf '<dt id="%s"><code>use %s</code>', $ref, $name;
+                       say '<dd>', $desc;
+               }
+       }
+       say sprintf '<dt>Unicode</dt><dd>v%s', $_ for $verrow->{unicode} || ();
+       say '</dl>';
+       say "</div>\n";

 }
 
 }
 

+sub featattrs ($attr) {
+       $attr or return '';
+       ref $attr or $attr = {eg => $attr};
+       my $title;
+       if (defined $attr->{experimental}) {
+               $title = 'experimental';
+       }
+       if (defined $attr->{dropped}) {
+               return '' unless exists $get{v};
+               $title = sprintf 'removed in %vd', $_ for $attr->{dropped} || ();
+       }
+       elsif ($attr->{stable}) {
+               $title .= sprintf ' until %vd', $attr->{stable};
+       }
+       if ($attr->{experimental}) {
+               $title = sprintf '<span title="experimental::%s">%s</span>',
+                       $attr->{experimental}, $title;
+               $attr->{name} //= $attr->{experimental};
+       }
+       if ($attr->{feature}) {
+               my $prefix = sprintf '<span title="%s">feature</span>',
+                       $attr->{feature};
+               $title = join ', ', $prefix, $title // ();
+               $attr->{name} //= $attr->{feature};
+       }
+       $title = $title ? sprintf ' <em class="ex">(%s)</em>', $title : '';
+
+       if (my $eg = $attr->{eg}) {
+               my $pre = Entity($eg);
+               $pre =~ s<\N{ZERO WIDTH SPACE}>{</code><wbr/><code>}g;
+               $pre = " <small>{<code>$pre</code>}</small>";
+               $title = $pre . $title;
+       }
+       return $title;
+}