NAME

Gentoo::Util::VirtualDepend - Hard-coded replacements for perl-core/ dependencies and dependencies with odd names in Gentoo

VERSION

version 0.003023

SYNOPSIS

  use Gentoo::Util::VirtualDepend;

  my $v = Gentoo::Util::VirtualDepend->new();

  # somewhere in complex dependency resolution

  my $cpan_module = spooky_function();
  my $gentoo_dependency;

  if ( $v->has_module_override( $cpan_module ) ) {
    $gentoo_dependency = $v->get_module_override( $cpan_module );
  } else {
    # do it the hard way.
  }

If you're trying to be defensive and you're going to map the modules to distributions the hard way ( trust me, the code is really ugly ), then you may instead want

  if ( $v->has_dist_override( $cpan_dist ) ) {
    $gentoo_dependency = $v->get_dist_override( $cpan_dist );
  } else {
    # fallback to using dev-perl/Foo-Bar
  }

Which basically serves as a distribution name translator.

WHY YOU WANT TO DO THAT

Well ...

     { requires => { Foo => 1.0 }}

     Foo is in Bar

     Foo 1.0 could have been shipped in in Bar-1.0, Bar-0.5, or Bar-2.0 for all you know.

That's the unfortunate reality of CPAN dependencies.

So if you naively map

    Foo-1.0 → >=dev-lang/Bar-1.0

You might get breakage if Foo 1.0 didn't ship till Bar-2.0, and the user has Bar-1.0 → Shower of sparks.

DESCRIPTION

This module serves as a low level glue layer for the handful of manual mappings that are needed in Gentoo due to things not strictly tracking upstream.

CPANPLUS::Dist::Gentoo has similar logic to this, but not as simple ( or for that matter, usable without CPANPLUS )

This module is not intended to be used entirely on its own, but as a short-circuit before calling complicated MetaCPAN code.

METHODS

has_module_override

  $v->has_module_override( $module )

Returns true if there is a known mapping for $module in Gentoo that is unusual and may require translation.

Will return true for anything that is either a virtual or has an unusual name translation separating it from CPAN.

get_module_override

  $v->get_module_override( $module )

Returns a Gentoo dependency atom corresponding to $module if there is a known mapping for $module.

For instance,

  $v->get_module_override('ExtUtils::MakeMaker')

Emits:

  virtual/perl-ExtUtilsMakeMaker

If ExtUtils::MakeMaker is one day de-cored (Hah!, dreams are free) then has_module_override will return false, and that instructs you to go back to assuming it is in dev-perl/

has_dist_override

  $v->has_dist_override( $distname )

Similar to has_module_override but closer to the dependency spec.

Will return true for anything that is either a virtual or has an unusual name translation separating it from CPAN.

get_dist_override

  $v->get_dist_override( $distname )

Similar to get_module_override but closer to the dependency spec.

For instance:

  $v->get_dist_override('PathTools')

Emits:

  virtual/perl-File-Spec

Because Gentoo is quirky like that.

has_gentoo_package

  $v->has_gentoo_package( 'virtual/perl-Test-Simple' )

Determines if the data file has entries mapping to virtual/perl-Test-Simple.

This is mostly for internal consistency tests/maintenance.

get_dists_in_gentoo_package

  my @list = $v->get_dists_in_gentoo_package( 'virtual/perl-Test-Simple' )

Returns a list of CPAN Distributions that map to this dependency.

get_modules_in_gentoo_package

  my @list = $v->get_modules_in_gentoo_package( 'virtua/perl-Test-Simple' )

Returns a list of modules that map to this dependency.

get_known_gentoo_packages

  my @list = $v->get_known_gentoo_packages

Returns a list of Gentoo packages for which there are known overrides.

get_known_dists

  my @list = $v->get_known_dists

Returns a list of CPAN Distributions for which there are known overrides

get_known_modules

  my @list = $v->get_known_modules

Return a list of CPAN Modules for which there are known overrides

module_is_perl

This function determines if it is "safe" to assume availability of a given module ( or a given module and version ) without needing to stipulate either a virtual or a CPAN dependency.

  ->module_is_perl( $module )
  ->module_is_perl( $module, $min_version )
  ->module_is_perl( \%config, $module, $min_version )

Rules:

• If the module is present in the override map, then it is deemed NOT available from Perl, because you should be using the override instead.

• If the module is missing on any version in the range specified, then it is NOT available from Perl, and you must depend on a virtual or some other dependency you can source.

• If the module is marked deprecated on any version in the range specified, then it is assumed NOT available in Perl ( due to likely deprecation warnings and imminent need to start adapting )

• If a minimum version is specified, and any version of Perl in the range specified does not satisfy that minimum, then it is assumed NOT available in Perl ( due to the inherent need to manually solve the issue via a virtual or a minimum Perl dependency )

• If a minimum version is specified, and any version of Perl in the range specified is an explicit undef, then it is assumed NOT available in Perl, because clearly, one version of Perl having undef and another having an explicit version, and needing only one of the two requires a manual dependency resolution.

Examples:

• Determine if strict is implicitly available.

    if ( $v->module_is_perl( 'strict' ) ) {

• Determine if strict version 1.09 is available.

    if ( $v->module_is_perl( 'strict' => '1.09' ) ) {

  This will of course return undef unless min_perl is at least 5.21.7.

  Thus, if your support range is 5.18.0 to 5.20, and somebody stipulates that minimum, you will have to declare a dependency on Perl 5.21.7.

  Even if your support range is 5.18.0 to 5.22.0, you will still have to declare a dependency on 5.21.7 instead of assuming its presence.

• Determine if strict version 1.09 is available on X to Y Perls.

  For most code where the support range is fixed, this will be unnecessary, and changing the defaults via ->new( min_perl => ... , max_perl => ... ) should be sufficient.

  However:

    if( $v->module_is_perl( { min_perl => '5.21.7', max_perl => '5.21.9' }, 'strict', '1.09' ) ) {
        # true
    }

ATTRIBUTES

max_perl

  ->new( max_perl => '5.20.2' )
  ->max_perl # 5.20.2

Stipulates the default maximum Perl for module_is_perl.

min_perl

  ->new( min_perl => '5.20.2' )
  ->min_perl # 5.20.2

Stipulates the default minimum Perl for module_is_perl.

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric <kentfredric@gmail.com>.

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

cpanm Gentoo::Util::VirtualDepend

perl -MCPAN -e shell
install Gentoo::Util::VirtualDepend