#
# spec file for package perl-Carp
#
# Copyright (c) 2024 SUSE LLC
#
# All modifications and additions to the file contributed by third parties
# remain the property of their copyright owners, unless otherwise agreed
# upon. The license for this file, and modifications and additions to the
# file, is the same license as for the pristine package itself (unless the
# license for the pristine package is not an Open Source License, in which
# case the license is the MIT License). An "Open Source License" is a
# license that conforms to the Open Source Definition (Version 1.9)
# published by the Open Source Initiative.

# Please submit bugfixes or comments via https://bugs.opensuse.org/
#


%define cpan_name Carp
Name:           perl-Carp
Version:        1.50
Release:        0
License:        Artistic-1.0 OR GPL-1.0-or-later
Summary:        Alternative warn and die for modules
URL:            https://metacpan.org/release/%{cpan_name}
Source0:        https://cpan.metacpan.org/authors/id/X/XS/XSAWYERX/%{cpan_name}-%{version}.tar.gz
Source1:        cpanspec.yml
Source100:      README.md
BuildArch:      noarch
BuildRequires:  perl
BuildRequires:  perl-macros
%{perl_requires}

%description
The Carp routines are useful in your own modules because they act like
'die()' or 'warn()', but with a message which is more likely to be useful
to a user of your module. In the case of 'cluck()' and 'confess()', that
context is a summary of every call in the call-stack; 'longmess()' returns
the contents of the error message.

For a shorter message you can use 'carp()' or 'croak()' which report the
error as being from where your module was called. 'shortmess()' returns the
contents of this error message. There is no guarantee that that is where
the error was, but it is a good educated guess.

'Carp' takes care not to clobber the status variables '$!' and '$^E' in the
course of assembling its error messages. This means that a '$SIG{__DIE__}'
or '$SIG{__WARN__}' handler can capture the error information held in those
variables, if it is required to augment the error message, and if the code
calling 'Carp' left useful values there. Of course, 'Carp' can't guarantee
the latter.

You can also alter the way the output and logic of 'Carp' works, by
changing some global variables in the 'Carp' namespace. See the section on
'GLOBAL VARIABLES' below.

Here is a more complete description of how 'carp' and 'croak' work. What
they do is search the call-stack for a function call stack where they have
not been told that there shouldn't be an error. If every call is marked
safe, they give up and give a full stack backtrace instead. In other words
they presume that the first likely looking potential suspect is guilty.
Their rules for telling whether a call shouldn't generate errors work as
follows:

* 1.

Any call from a package to itself is safe.

* 2.

Packages claim that there won't be errors on calls to or from packages
explicitly marked as safe by inclusion in '@CARP_NOT', or (if that array is
empty) '@ISA'. The ability to override what @ISA says is new in 5.8.

* 3.

The trust in item 2 is transitive. If A trusts B, and B trusts C, then A
trusts C. So if you do not override '@ISA' with '@CARP_NOT', then this
trust relationship is identical to, "inherits from".

* 4.

Any call from an internal Perl module is safe. (Nothing keeps user modules
from marking themselves as internal to Perl, but this practice is
discouraged.)

* 5.

Any call to Perl's warning system (eg Carp itself) is safe. (This rule is
what keeps it from reporting the error at the point where you call 'carp'
or 'croak'.)

* 6.

'$Carp::CarpLevel' can be set to skip a fixed number of additional call
levels. Using this is not recommended because it is very difficult to get
it to behave correctly.

%prep
%autosetup  -n %{cpan_name}-%{version}

%build
perl Makefile.PL INSTALLDIRS=vendor
%make_build

%check
make test

%install
%perl_make_install
%perl_process_packlist
%perl_gen_filelist

%files -f %{name}.files
%doc Changes README

%changelog