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 <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2020 by [email protected].

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