Parse::Distname(3pm)           User Contributed Perl Documentation           Parse::Distname(3pm)



NAME
       Parse::Distname - parse a distribution name

SYNOPSIS
           use Parse::Distname 'parse_distname';
           my $info = parse_distname('ISHIGAKI/Parse-Distname-0.01.tar.gz');

           # for compatibility with CPAN::DistnameInfo
           my $info_obj = Parse::Distname->new('ISHIGAKI/Parse-Distname-0.01.tar.gz');
           say $info_obj->dist; # Parse-Distname

DESCRIPTION
       Parse::Distname is yet another distribution name parser. It works almost the same as
       CPAN::DistnameInfo, but Parse::Distname takes a different approach. It tries to extract a
       version part of a distribution and treat the rest as a distribution name, contrary to
       CPAN::DistnameInfo which tries to define a name part and treat the rest as a version.

       Because of this difference, when Parse::Distname parses a weird distribution name such as
       "AUTHOR/v1.0.tar.gz", it says the name is empty and the version is "v1.0", while
       CPAN::DistnameInfo says the name is "v" and the version is "1.0". See test files in this
       distribution if you need more details. As of this writing, Parse::Distname returns a
       different result for about 200+ distributions among about 320000 BackPan distributions.

FUNCTION
       Parse::Distname exports one function "parse_distname" if requested.  It returns a hash
       reference, with the following keys as of this writing:

       arg The path you passed to the function. If what you passed is some kind of an object (of
           Path::Tiny, for example), it's stringified.

       cpan_path
           A relative path to the distribution, whose base directory is assumed CPAN/authors/id/.
           If org_path doesn't contain a pause_id, the distribution is assumed to belong to LOCAL
           user. For example,

             say parse_distname('Dist-0.01.tar.gz')->{cpan_path};
             # L/LO/LOCAL/Dist-0.01.tar.gz

           If you only gives a pause_id, parent directories are supplemented.

             say parse_distname('ISHIGAKI/Dist-0.01.tar.gz')->{cpan_path};
             # I/IS/ISHIGAKI/Dist-0.01.tar.gz

       pause_id
           The pause_id of the distribution. Contrary to the above, this is empty if you don't
           give a pause_id.

             say parse_distname('Dist-0.01.tar.gz')->{pause_id};
             # (undef, not LOCAL)

       subdir
           A PAUSE distribution may be put into a subdirectory under the author directory. If the
           name contains such a subdirectory, it's kept here.

             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{subdir};
             # sub

           Perl 6 distributions are (almost) always put under Perl6/ subdirectory under each
           author's directory (with a few exceptions).

       name_and_version
           The name and version of the distribution, without an extension and directory parts,
           which should not be empty as long as the distribution has an extension that PAUSE
           accepts.

             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{name_and_version};
             # Dist-0.01

       name
           The name part of the distribution. This may be empty if no valid name is found

             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{name};
             # Dist

             say parse_distname('AUTHOR/v0.1.tar.gz')->{name};
             # (empty)

       version
           The version part of the distribution. This also may be empty, and this may not always
           be a valid version, and may have a following part such as "-TRIAL".

             say parse_distname('AUTHOR/Dist.tar.gz')->{version};
             # (undef)

             say parse_distname('AUTHOR/Dist-0.01-TRIAL.tar.gz')->{version};
             # 0.01-TRIAL

       version_number
           The first numerical part of the version. This also may be empty, and this may not
           always be a valid version.

             say parse_distname('AUTHOR/Dist-0.01-TRIAL.tar.gz')->{version_number};
             # 0.01

             say parse_distname('AUTHOR/Dist-0_0_1.tar.gz')->{version_number};
             # 0_0_1

       extension
           The extension of the distribution. If no valid extension is found, parse_distname
           returns false (undef).

       is_perl6
           For convenience, if subdir exists and it starts with Perl6/, this becomes true.

       is_dev
           If the version looks like "\d+.\d+_\d+", or contains "-TRIAL", this becomes true.
           PAUSE treats such a distribution as a developer's release and doesn't list it in its
           indices.

METHODS
       For compatibility with CPAN::DistnameInfo, Parse::Distname has the same methods/accessors,
       so you can use it as a drop-in replacement.

       In addition, "is_perl6" and "version_number" are available.

SEE ALSO
       CPAN::DistnameInfo

AUTHOR
       Kenichi Ishigaki, <ishigaki AT cpan.org>

COPYRIGHT AND LICENSE
       This software is copyright (c) 2018 by Kenichi Ishigaki.

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



perl v5.20.2                                2019-09-29                       Parse::Distname(3pm)