David J. Oswald

NAME

parent::versioned - Establish an ISA relationship with base classes at compile time, with version checking.

SYNOPSIS

    package Baz;

    # Just like parent:
    use parent::versioned qw(Foo Bar);

    # Plus version checking:
    use parent::versioned ['Foo' => 2.3], ['Bar' => 0.05], 'Baz'; # Version checking for Foo and Bar.

DESCRIPTION

This module behaves identically to parent, except that it also provides a means of specifying a minimum version check for modules. It is a fork of parent version 0.237, and passes all of parent's tests, plus tests added to verify the version checking feature.

Behavior distinct from parent

If the list passed to parent::versioned contains an array-ref, that reference should specify a module name, and a minimum module version number. Multiple array-refs may be passed in the same call. Each module for which version checking is to be done should exist in its own array-ref tuple.

Examples

  # No version checking on Foo or Bar. but Baz must be version 1.0 or higher.
  use parent::versioned qw(Foo Bar), ['Baz' => 1.0];

  # Version check both Foo and Bar.
  use parent::versioned ['Foo' => 0.25], ['Bar' => 1.0];

  # The -norequire parameter still works as expected:
  use parent::versioned -norequire, ['Foo' => 0.25], qw(Bar Baz);

Version checking is accomplished at compile time using the VERSION method. See perldoc -f use for an explanation of how VERSION() works.

The remainder of this documentation is derived directly from parent.

Behavior shared with parent

Allows you to both load one or more modules, while setting up inheritance from those modules at the same time. Mostly similar in effect to

    package Baz;
    BEGIN {
        require Foo;
        require Bar;
        push @ISA, qw(Foo Bar);
    }

By default, every base class needs to live in a file of its own. If you want to have a subclass and its parent class in the same file, you can tell parent::versioned not to load any modules by using the -norequire switch:

  package Foo;
  sub exclaim { "I CAN HAS PERL" }

  package DoesNotLoadFooBar;
  use parent::versioned -norequire, 'Foo', 'Bar';
  # will not go looking for Foo.pm or Bar.pm

This is equivalent to the following code:

  package Foo;
  sub exclaim { "I CAN HAS PERL" }

  package DoesNotLoadFooBar;
  push @DoesNotLoadFooBar::ISA, 'Foo', 'Bar';

This is also helpful for the case where a package lives within a differently named file:

  package MyHash;
  use Tie::Hash;
  use parent::versioned -norequire, 'Tie::StdHash';

This is equivalent to the following code:

  package MyHash;
  require Tie::Hash;
  push @ISA, 'Tie::StdHash';

If you want to load a subclass from a file that require would not consider an eligible filename (that is, it does not end in either .pm or .pmc), use the following code:

  package MySecondPlugin;
  require './plugins/custom.plugin'; # contains Plugin::Custom
  use parent::versioned -norequire, 'Plugin::Custom';

TEST COVERAGE

parent already had very good tests that reached 100% coverage. This module has adapted all of the tests from parent to avoid regressions, and has added testing around the versioning functionality. Coverage remains at 100%:

  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  File                           stmt   bran   cond    sub    pod   time  total
  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  blib/lib/parent/versioned.pm  100.0  100.0  100.0  100.0    n/a  100.0  100.0
  Total                         100.0  100.0  100.0  100.0    n/a  100.0  100.0
  ---------------------------- ------ ------ ------ ------ ------ ------ ------

HISTORY

This module was forked from parent 0.237, which itself was forked from base to remove the cruft that had accumulated in it.

CAVEATS

SEE ALSO

parent
base

AUTHORS AND CONTRIBUTORS

David Oswald forked this module from parent version 0.237, and added version checking.

parent was authored by Rafaël Garcia-Suarez, Bart Lateur, Max Maischein, Anno Siegel, and Michael Schwern.

MAINTAINER

David Oswald davido@cpan.org

Copyright (c) 2019 David Oswald <davido@cpan.org>.

Based on a fork from parent, which is maintained by Max Maischein <corion@cpan.org>, and was introduced to the Perl core with Perl 5.10.1.

LICENSE

This module is released under the same terms as Perl itself.