Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 149 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/stable.3pm b/upstream/mageia-cauldron/man3pm/stable.3pm
new file mode 100644
index 00000000..4f1f4734
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/stable.3pm
@@ -0,0 +1,149 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "stable 3pm"
+.TH stable 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+stable \- Experimental features made easy, once we know they're stable
+.SH VERSION
+.IX Header "VERSION"
+version 0.031
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&        use stable \*(Aqlexical_subs\*(Aq, \*(Aqbitwise\*(Aq;
+\&        my sub is_odd($value) { $value & 1 }
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The experimental pragma makes it easy to turn on experimental while turning
+off associated warnings.  You should read about it, if you don't already know
+what it does.
+.PP
+Seeing \f(CW\*(C`use experimental\*(C'\fR in code might be scary.  In fact, it probably should
+be!  Code that uses experimental features might break in the future if the perl
+development team decides that the experiment needs to be altered.  When
+experiments become stable, because the developers decide they're a success, the
+warnings associated with them go away.  When that happens, they can generally
+be turned on with \f(CW\*(C`use feature\*(C'\fR.
+.PP
+This is great, if you are using a version of perl where the feature you want is
+already stable.  If you're using an older perl, though, it might be the case
+that you want to use an experimental feature that still warns, even though
+there's no risk in using it, because subsequent versions of perl have that
+feature unchanged and now stable.
+.PP
+Here's an example:  The \f(CW\*(C`postderef\*(C'\fR feature was added in perl 5.20.0.  In perl
+5.24.0, it was marked stable.  Using it would no longer trigger a warning.  The
+behavior of the feature didn't change between 5.20.0 and 5.24.0.  That means
+that it's perfectly safe to use the feature on 5.20 or 5.22, even though
+there's a warning.
+.PP
+In that case, you could very justifiably add \f(CW\*(C`use experimental \*(Aqpostderef\*(Aq\*(C'\fR
+but the casual reader may still be worried at seeing that.  The \f(CW\*(C`stable\*(C'\fR
+pragma exists to turn on experimental features only when it's known that
+their behavior in the running perl is their stable behavior.
+.PP
+If you try to use an experimental feature that isn't stable or available on
+the running version of perl, an exception will be thrown.  You should also take
+care that you've required the version of \f(CW\*(C`stable\*(C'\fR that you need!
+.PP
+If it's not immediately obvious why, here's a bit of explanation:
+.IP \(bu 4
+\&\f(CW\*(C`stable\*(C'\fR comes with perl, starting with perl v5.38.
+.IP \(bu 4
+Imagine that v5.38 adds a feature called "florps".  It will stop being
+experimental in v5.42.
+.IP \(bu 4
+The version of \f(CW\*(C`stable\*(C'\fR that comes with perl v5.38 can't know that the
+\&\fIflorps\fR experiment will succeed, so you can't \f(CW\*(C`use stable \*(Aqflorps\*(Aq\*(C'\fR on the
+version of stable ships with v5.38, because it can't see the future!
+.IP \(bu 4
+You'll need to write \f(CW\*(C`use stable 1.234 \*(Aqflorps\*(Aq\*(C'\fR to say that you need version
+1.234 of stable, which is when \fIflorps\fR became known to stable.
+.PP
+Sure, it's a little weird, but it's worth it!  The documentation of this pragma
+will tell you what version of \f(CW\*(C`stable\*(C'\fR you need to require in order to use
+various features.  See below.
+.PP
+At present there are only a few "stable" features:
+.IP \(bu 4
+\&\f(CW\*(C`bitwise\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
+.IP \(bu 4
+\&\f(CW\*(C`isa\*(C'\fR \- stable as of perl 5.32, available via stable 0.031
+.IP \(bu 4
+\&\f(CW\*(C`lexical_subs\*(C'\fR \- stable as of perl 5.22, available via stable 0.031
+.Sp
+Lexical subroutines were actually added in 5.18, and their design did not
+change, but significant bugs makes them unsafe to use before 5.22.
+.IP \(bu 4
+\&\f(CW\*(C`postderef\*(C'\fR \- stable as of perl 5.20, available via stable 0.031
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlexperiment contains more information about experimental features.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Leon Timmermans <leont@cpan.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+This software is copyright (c) 2013 by Leon Timmermans.
+.PP
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.