Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 352 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/autodie::exception.3perl b/upstream/archlinux/man3/autodie::exception.3perl
new file mode 100644
index 00000000..f24d9485
--- /dev/null
+++ b/upstream/archlinux/man3/autodie::exception.3perl
@@ -0,0 +1,352 @@
+.\" -*- 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 "autodie::exception 3perl"
+.TH autodie::exception 3perl 2024-02-11 "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
+autodie::exception \- Exceptions from autodying functions.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    eval {
+\&        use autodie;
+\&
+\&        open(my $fh, \*(Aq<\*(Aq, \*(Aqsome_file.txt\*(Aq);
+\&
+\&        ...
+\&    };
+\&
+\&    if (my $E = $@) {
+\&        say "Ooops!  ",$E\->caller," had problems: $@";
+\&    }
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+When an autodie enabled function fails, it generates an
+\&\f(CW\*(C`autodie::exception\*(C'\fR object.  This can be interrogated to
+determine further information about the error that occurred.
+.PP
+This document is broken into two sections; those methods that
+are most useful to the end-developer, and those methods for
+anyone wishing to subclass or get very familiar with
+\&\f(CW\*(C`autodie::exception\*(C'\fR.
+.SS "Common Methods"
+.IX Subsection "Common Methods"
+These methods are intended to be used in the everyday dealing
+of exceptions.
+.PP
+The following assume that the error has been copied into
+a separate scalar:
+.PP
+.Vb 3
+\&    if ($E = $@) {
+\&        ...
+\&    }
+.Ve
+.PP
+This is not required, but is recommended in case any code
+is called which may reset or alter \f(CW$@\fR.
+.PP
+\fIargs\fR
+.IX Subsection "args"
+.PP
+.Vb 1
+\&    my $array_ref = $E\->args;
+.Ve
+.PP
+Provides a reference to the arguments passed to the subroutine
+that died.
+.PP
+\fIfunction\fR
+.IX Subsection "function"
+.PP
+.Vb 1
+\&    my $sub = $E\->function;
+.Ve
+.PP
+The subroutine (including package) that threw the exception.
+.PP
+\fIfile\fR
+.IX Subsection "file"
+.PP
+.Vb 1
+\&    my $file = $E\->file;
+.Ve
+.PP
+The file in which the error occurred (eg, \f(CW\*(C`myscript.pl\*(C'\fR or
+\&\f(CW\*(C`MyTest.pm\*(C'\fR).
+.PP
+\fIpackage\fR
+.IX Subsection "package"
+.PP
+.Vb 1
+\&    my $package = $E\->package;
+.Ve
+.PP
+The package from which the exceptional subroutine was called.
+.PP
+\fIcaller\fR
+.IX Subsection "caller"
+.PP
+.Vb 1
+\&    my $caller = $E\->caller;
+.Ve
+.PP
+The subroutine that \fIcalled\fR the exceptional code.
+.PP
+\fIline\fR
+.IX Subsection "line"
+.PP
+.Vb 1
+\&    my $line = $E\->line;
+.Ve
+.PP
+The line in \f(CW\*(C`$E\->file\*(C'\fR where the exceptional code was called.
+.PP
+\fIcontext\fR
+.IX Subsection "context"
+.PP
+.Vb 1
+\&    my $context = $E\->context;
+.Ve
+.PP
+The context in which the subroutine was called by autodie; usually
+the same as the context in which you called the autodying subroutine.
+This can be 'list', 'scalar', or undefined (unknown).  It will never
+be 'void', as \f(CW\*(C`autodie\*(C'\fR always captures the return value in one way
+or another.
+.PP
+For some core functions that always return a scalar value regardless
+of their context (eg, \f(CW\*(C`chown\*(C'\fR), this may be 'scalar', even if you
+used a list context.
+.PP
+\fIreturn\fR
+.IX Subsection "return"
+.PP
+.Vb 1
+\&    my $return_value = $E\->return;
+.Ve
+.PP
+The value(s) returned by the failed subroutine.  When the subroutine
+was called in a list context, this will always be a reference to an
+array containing the results.  When the subroutine was called in
+a scalar context, this will be the actual scalar returned.
+.PP
+\fIerrno\fR
+.IX Subsection "errno"
+.PP
+.Vb 1
+\&    my $errno = $E\->errno;
+.Ve
+.PP
+The value of \f(CW$!\fR at the time when the exception occurred.
+.PP
+\&\fBNOTE\fR: This method will leave the main \f(CW\*(C`autodie::exception\*(C'\fR class
+and become part of a role in the future.  You should only call
+\&\f(CW\*(C`errno\*(C'\fR for exceptions where \f(CW$!\fR would reasonably have been
+set on failure.
+.PP
+\fIeval_error\fR
+.IX Subsection "eval_error"
+.PP
+.Vb 1
+\&    my $old_eval_error = $E\->eval_error;
+.Ve
+.PP
+The contents of \f(CW$@\fR immediately after autodie triggered an
+exception.  This may be useful when dealing with modules such
+as Text::Balanced that set (but do not throw) \f(CW$@\fR on error.
+.PP
+\fImatches\fR
+.IX Subsection "matches"
+.PP
+.Vb 1
+\&    if ( $e\->matches(\*(Aqopen\*(Aq) ) { ... }
+\&
+\&    if ( \*(Aqopen\*(Aq ~~ $e ) { ... }
+.Ve
+.PP
+\&\f(CW\*(C`matches\*(C'\fR is used to determine whether a
+given exception matches a particular role.
+.PP
+An exception is considered to match a string if:
+.IP \(bu 4
+For a string not starting with a colon, the string exactly matches the
+package and subroutine that threw the exception.  For example,
+\&\f(CW\*(C`MyModule::log\*(C'\fR.  If the string does not contain a package name,
+\&\f(CW\*(C`CORE::\*(C'\fR is assumed.
+.IP \(bu 4
+For a string that does start with a colon, if the subroutine
+throwing the exception \fIdoes\fR that behaviour.  For example, the
+\&\f(CW\*(C`CORE::open\*(C'\fR subroutine does \f(CW\*(C`:file\*(C'\fR, \f(CW\*(C`:io\*(C'\fR and \f(CW\*(C`:all\*(C'\fR.
+.Sp
+See "CATEGORIES" in autodie for further information.
+.Sp
+On Perl 5.10 and above, using smart-match (\f(CW\*(C`~~\*(C'\fR) with an
+\&\f(CW\*(C`autodie::exception\*(C'\fR object will use \f(CW\*(C`matches\*(C'\fR underneath.  This module
+used to recommend using smart-match with the exception object on the left
+hand side, but in future Perls that is likely to stop working.
+The smart-match facility of this class should only be used with the
+exception object on the right hand side.  Having the exception object on
+the right is both future-proof and portable to older Perls, back to 5.10.
+Beware that this facility can only
+be relied upon when it is certain that the exception object actually is
+an \f(CW\*(C`autodie::exception\*(C'\fR object; it is no more capable than an explicit
+call to the \f(CW\*(C`matches\*(C'\fR method.
+.SS "Advanced methods"
+.IX Subsection "Advanced methods"
+The following methods, while usable from anywhere, are primarily
+intended for developers wishing to subclass \f(CW\*(C`autodie::exception\*(C'\fR,
+write code that registers custom error messages, or otherwise
+work closely with the \f(CW\*(C`autodie::exception\*(C'\fR model.
+.PP
+\fIregister\fR
+.IX Subsection "register"
+.PP
+.Vb 1
+\&    autodie::exception\->register( \*(AqCORE::open\*(Aq => \e&mysub );
+.Ve
+.PP
+The \f(CW\*(C`register\*(C'\fR method allows for the registration of a message
+handler for a given subroutine.  The full subroutine name including
+the package should be used.
+.PP
+Registered message handlers will receive the \f(CW\*(C`autodie::exception\*(C'\fR
+object as the first parameter.
+.PP
+\fIadd_file_and_line\fR
+.IX Subsection "add_file_and_line"
+.PP
+.Vb 1
+\&    say "Problem occurred",$@\->add_file_and_line;
+.Ve
+.PP
+Returns the string \f(CW\*(C` at %s line %d\*(C'\fR, where \f(CW%s\fR is replaced with
+the filename, and \f(CW%d\fR is replaced with the line number.
+.PP
+Primarily intended for use by format handlers.
+.PP
+\fIstringify\fR
+.IX Subsection "stringify"
+.PP
+.Vb 1
+\&    say "The error was: ",$@\->stringify;
+.Ve
+.PP
+Formats the error as a human readable string.  Usually there's no
+reason to call this directly, as it is used automatically if an
+\&\f(CW\*(C`autodie::exception\*(C'\fR object is ever used as a string.
+.PP
+Child classes can override this method to change how they're
+stringified.
+.PP
+\fIformat_default\fR
+.IX Subsection "format_default"
+.PP
+.Vb 1
+\&    my $error_string = $E\->format_default;
+.Ve
+.PP
+This produces the default error string for the given exception,
+\&\fIwithout using any registered message handlers\fR.  It is primarily
+intended to be called from a message handler when they have
+been passed an exception they don't want to format.
+.PP
+Child classes can override this method to change how default
+messages are formatted.
+.PP
+\fInew\fR
+.IX Subsection "new"
+.PP
+.Vb 7
+\&    my $error = autodie::exception\->new(
+\&        args => \e@_,
+\&        function => "CORE::open",
+\&        errno => $!,
+\&        context => \*(Aqscalar\*(Aq,
+\&        return => undef,
+\&    );
+.Ve
+.PP
+Creates a new \f(CW\*(C`autodie::exception\*(C'\fR object.  Normally called
+directly from an autodying function.  The \f(CW\*(C`function\*(C'\fR argument
+is required, its the function we were trying to call that
+generated the exception.  The \f(CW\*(C`args\*(C'\fR parameter is optional.
+.PP
+The \f(CW\*(C`errno\*(C'\fR value is optional.  In versions of \f(CW\*(C`autodie::exception\*(C'\fR
+1.99 and earlier the code would try to automatically use the
+current value of \f(CW$!\fR, but this was unreliable and is no longer
+supported.
+.PP
+Atrributes such as package, file, and caller are determined
+automatically, and cannot be specified.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+autodie, autodie::exception::system
+.SH LICENSE
+.IX Header "LICENSE"
+Copyright (C)2008 Paul Fenwick
+.PP
+This is free software.  You may modify and/or redistribute this
+code under the same terms as Perl 5.10 itself, or, at your option,
+any later version of Perl 5.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Paul Fenwick <pjf@perltraining.com.au>