README.md
1# NAME
2
3Clone::Choose - Choose appropriate clone utility
4
5# SYNOPSIS
6
7 use Clone::Choose;
8
9 my $data = {
10 value => 42,
11 href => {
12 set => [ 'foo', 'bar' ],
13 value => 'baz',
14 },
15 };
16
17 my $cloned_data = clone $data;
18
19 # it's also possible to use Clone::Choose and pass a clone preference
20 use Clone::Choose qw(:Storable);
21
22# DESCRIPTION
23
24`Clone::Choose` checks several different modules which provides a
25`clone()` function and selects an appropriate one. The default preference
26is
27
28 Clone
29 Storable
30 Clone::PP
31
32This list might evolve in future. Please see ["EXPORTS"](#exports) how to pick a
33particular one.
34
35# EXPORTS
36
37`Clone::Choose` exports `clone()` by default.
38
39One can explicitly import `clone` by using
40
41 use Clone::Choose qw(clone);
42
43or pick a particular `clone` implementation
44
45 use Clone::Choose qw(:Storable clone);
46
47The exported implementation is resolved dynamically, which means that any
48using module can either rely on the default backend preference or choose
49a particular one.
50
51It is also possible to select a particular `clone` backend by setting the
52environment variable CLONE\_CHOOSE\_PREFERRED\_BACKEND to your preferred backend.
53
54This also means, an already chosen import can't be modified like
55
56 use Clone::Choose qw(clone :Storable);
57
58When one seriously needs different clone implementations, our _recommended_
59way to use them would be:
60
61 use Clone::Choose (); # do not import
62 my ($xs_clone, $st_clone);
63 { local @Clone::Choose::BACKENDS = (Clone => "clone"); $xs_clone = Clone::Choose->can("clone"); }
64 { local @Clone::Choose::BACKENDS = (Storable => "dclone"); $st_clone = Clone::Choose->can("clone"); }
65
66Don't misinterpret _recommended_ - modifying `@Clone::Choose::BACKENDS`
67has a lot of pitfalls and is unreliable beside such small examples. Do
68not hesitate open a request with an appropriate proposal for choosing
69implementations dynamically.
70
71The use of `@Clone::Choose::BACKENDS` is discouraged and will be deprecated
72as soon as anyone provides a better idea.
73
74# PACKAGE METHODS
75
76## backend
77
78`backend` tells the caller about the dynamic chosen backend:
79
80 use Clone::Choose;
81 say Clone::Choose->backend; # Clone
82
83This method currently exists for debug purposes only.
84
85## get\_backends
86
87`get_backends` returns a list of the currently supported backends.
88
89# AUTHOR
90
91 Jens Rehsack <rehsack at cpan dot org>
92 Stefan Hermes <hermes at cpan dot org>
93
94# BUGS
95
96Please report any bugs or feature requests to
97`bug-Clone-Choose at rt.cpan.org`, or through the web interface at
98[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Clone-Choose](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Clone-Choose).
99I will be notified, and then you'll automatically be notified of progress
100on your bug as I make changes.
101
102# SUPPORT
103
104You can find documentation for this module with the perldoc command.
105
106 perldoc Clone::Choose
107
108You can also look for information at:
109
110- RT: CPAN's request tracker
111
112 [http://rt.cpan.org/NoAuth/Bugs.html?Dist=Clone-Choose](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Clone-Choose)
113
114- AnnoCPAN: Annotated CPAN documentation
115
116 [http://annocpan.org/dist/Clone-Choose](http://annocpan.org/dist/Clone-Choose)
117
118- CPAN Ratings
119
120 [http://cpanratings.perl.org/d/Clone-Choose](http://cpanratings.perl.org/d/Clone-Choose)
121
122- Search CPAN
123
124 [http://search.cpan.org/dist/Clone-Choose/](http://search.cpan.org/dist/Clone-Choose/)
125
126# LICENSE AND COPYRIGHT
127
128 Copyright 2017 Jens Rehsack
129 Copyright 2017 Stefan Hermes
130
131This program is free software; you can redistribute it and/or modify it
132under the terms of either: the GNU General Public License as published
133by the Free Software Foundation; or the Artistic License.
134
135See http://dev.perl.org/licenses/ for more information.
136
137# SEE ALSO
138
139[Clone](https://metacpan.org/pod/Clone), [Clone::PP](https://metacpan.org/pod/Clone::PP), [Storable](https://metacpan.org/pod/Storable)
140