/ 
Package-CopyContents-0.004
River stage one • 2 direct dependents • 2 total dependents
/ Package::CopyContents

NAME

Package::CopyContents - Copy (some) contents from another package

VERSION

This document describes version 0.004 of Package::CopyContents (from Perl distribution Package-CopyContents), released on 2020-02-16.

SYNOPSIS

package My::Package;
use Package::CopyContents; # exports copy_contents_from()

BEGIN { copy_contents_from 'Your::Package' }

# provide your own variables/subroutines
our $scalar = 'foo';
sub func1 { ... }
...

1;

DESCRIPTION

This module provides "copy_contents_from" to fill the contents of the caller's (target) package from the specified (source) package, with some options. copy_contents_from can be used as an alternative to OO inheritance: you copy routines from another "base" package then add/modify some other.

FUNCTIONS

copy_contents_from

Usage:

copy_contents_from [ \%opts, ] $source_package

Load module $source_package if not already loaded (unless the load option is set to false, in which case no module loading is done), then copy the contents of the package into the caller's package. Currently only coderefs, scalars, arrays, and hashes are copied.

Options:

  • to

    String. Default to copy_contents_from's caller package. Can be used to explicitly set the target package.

  • load

    Boolean, default true. If set to false, no attempt to load module named $source_package is made.

  • dclone

    Boolean, default false. By default, only shallow copying of arrays and hashes are done. If this option is true, Storable's dclone is used.

  • skip_sub

    Boolean, default false. Whether to exclude all subs.

  • skip_scalar

    Boolean. Whether to exclude all scalar variables.

  • skip_array

    Boolean, default false. Whether to exclude all array variables.

  • skip_hash

    Boolean, default false. Whether to exclude all hash variables.

  • exclude

    Arrayref. List of names to exclude.

    Examples:

    exclude => ['@EXPORT', '@EXPORT_OK', '%EXPORT_TAGS', '$VERSION'];

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Package-CopyContents.

SOURCE

Source repository is at https://github.com/perlancar/perl-Package-CopyContents.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Package-CopyContents

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

GOTCHAS

If your copying module is loaded by user during runtime instead of compile-time, then subroutine name from your module will be overwritten by the runtime copy_contents_from invocation. Illustration:

# in Source.pm
package Source;
sub func1 { ... }
sub func2 { print "Source's version" }
1;

# in YourModule.pm
package YourModule;
use Package::CopyContents;
copy_contents_from 'Source';
# modify func2
sub func2 { "YourModule's version" }
1;

# in script1.pl
use YourModule;
YourModule::func2(); # prints "YourModule's version", ok.

# in script2.pl
require YourModule;
YourModule::func2(); # prints "Source's version"!

To ensure that your subroutines do not get copied (overwritten) by the source package's that have the same name, perform the copying at compile-time:

# in YourModule.pm
package YourModule;
BEGIN { use Package::CopyContents; copy_contents_from 'Source' }
# modify func2
sub func2 { "YourModule's version" }
1;

SEE ALSO

Package::Rename can also copy packages.

Variants: Perinci::Package::CopyContents

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.