.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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 "Clone::Choose 3"
.TH Clone::Choose 3 2025-06-23 "perl v5.40.2" "User Contributed Perl Documentation"
.\" 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
Clone::Choose \- Choose appropriate clone utility
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Clone::Choose;
\&
\&  my $data = {
\&      value => 42,
\&      href  => {
\&          set   => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ],
\&          value => \*(Aqbaz\*(Aq,
\&      },
\&  };
\&
\&  my $cloned_data = clone $data;
\&
\&  # it\*(Aqs also possible to use Clone::Choose and pass a clone preference
\&  use Clone::Choose qw(:Storable);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Clone::Choose\*(C'\fR checks several different modules which provides a
\&\f(CWclone()\fR function and selects an appropriate one. The default preference
is
.PP
.Vb 3
\&  Clone
\&  Storable
\&  Clone::PP
.Ve
.PP
This list might evolve in future. Please see "EXPORTS" how to pick a
particular one.
.SH EXPORTS
.IX Header "EXPORTS"
\&\f(CW\*(C`Clone::Choose\*(C'\fR exports \f(CWclone()\fR by default.
.PP
One can explicitly import \f(CW\*(C`clone\*(C'\fR by using
.PP
.Vb 1
\&  use Clone::Choose qw(clone);
.Ve
.PP
or pick a particular \f(CW\*(C`clone\*(C'\fR implementation
.PP
.Vb 1
\&  use Clone::Choose qw(:Storable clone);
.Ve
.PP
The exported implementation is resolved dynamically, which means that any
using module can either rely on the default backend preference or choose
a particular one.
.PP
It is also possible to select a particular \f(CW\*(C`clone\*(C'\fR backend by setting the
environment variable CLONE_CHOOSE_PREFERRED_BACKEND to your preferred backend.
.PP
This also means, an already chosen import can't be modified like
.PP
.Vb 1
\&  use Clone::Choose qw(clone :Storable);
.Ve
.PP
When one seriously needs different clone implementations, our \fIrecommended\fR
way to use them would be:
.PP
.Vb 4
\&  use Clone::Choose (); # do not import
\&  my ($xs_clone, $st_clone);
\&  { local @Clone::Choose::BACKENDS = (Clone => "clone"); $xs_clone = Clone::Choose\->can("clone"); }
\&  { local @Clone::Choose::BACKENDS = (Storable => "dclone"); $st_clone = Clone::Choose\->can("clone"); }
.Ve
.PP
Don't misinterpret \fIrecommended\fR \- modifying \f(CW@Clone::Choose::BACKENDS\fR
has a lot of pitfalls and is unreliable beside such small examples. Do
not hesitate open a request with an appropriate proposal for choosing
implementations dynamically.
.PP
The use of \f(CW@Clone::Choose::BACKENDS\fR is discouraged and will be deprecated
as soon as anyone provides a better idea.
.SH "PACKAGE METHODS"
.IX Header "PACKAGE METHODS"
.SS backend
.IX Subsection "backend"
\&\f(CW\*(C`backend\*(C'\fR tells the caller about the dynamic chosen backend:
.PP
.Vb 2
\&  use Clone::Choose;
\&  say Clone::Choose\->backend; # Clone
.Ve
.PP
This method currently exists for debug purposes only.
.SS get_backends
.IX Subsection "get_backends"
\&\f(CW\*(C`get_backends\*(C'\fR returns a list of the currently supported backends.
.SH AUTHOR
.IX Header "AUTHOR"
.Vb 2
\&  Jens Rehsack <rehsack at cpan dot org>
\&  Stefan Hermes <hermes at cpan dot org>
.Ve
.SH BUGS
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-Clone\-Choose at rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Clone\-Choose>.
I will be notified, and then you'll automatically be notified of progress
on your bug as I make changes.
.SH SUPPORT
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&  perldoc Clone::Choose
.Ve
.PP
You can also look for information at:
.IP \(bu 4
RT: CPAN's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Clone\-Choose>
.IP \(bu 4
AnnoCPAN: Annotated CPAN documentation
.Sp
<http://annocpan.org/dist/Clone\-Choose>
.IP \(bu 4
CPAN Ratings
.Sp
<http://cpanratings.perl.org/d/Clone\-Choose>
.IP \(bu 4
Search CPAN
.Sp
<http://search.cpan.org/dist/Clone\-Choose/>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
.Vb 2
\&  Copyright 2017 Jens Rehsack
\&  Copyright 2017 Stefan Hermes
.Ve
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Clone, Clone::PP, Storable