1Parse::Distname(3)    User Contributed Perl Documentation   Parse::Distname(3)
2
3
4

NAME

6       Parse::Distname - parse a distribution name
7

SYNOPSIS

9           use Parse::Distname 'parse_distname';
10           my $info = parse_distname('ISHIGAKI/Parse-Distname-0.01.tar.gz');
11
12           # for compatibility with CPAN::DistnameInfo
13           my $info_obj = Parse::Distname->new('ISHIGAKI/Parse-Distname-0.01.tar.gz');
14           say $info_obj->dist; # Parse-Distname
15

DESCRIPTION

17       Parse::Distname is yet another distribution name parser. It works
18       almost the same as CPAN::DistnameInfo, but Parse::Distname takes a
19       different approach. It tries to extract a version part of a
20       distribution and treat the rest as a distribution name, contrary to
21       CPAN::DistnameInfo which tries to define a name part and treat the rest
22       as a version.
23
24       Because of this difference, when Parse::Distname parses a weird
25       distribution name such as "AUTHOR/v1.0.tar.gz", it says the name is
26       empty and the version is "v1.0", while CPAN::DistnameInfo says the name
27       is "v" and the version is "1.0". See test files in this distribution if
28       you need more details. As of this writing, Parse::Distname returns a
29       different result for about 200+ distributions among about 320000
30       BackPan distributions.
31

FUNCTION

33       Parse::Distname exports one function "parse_distname" if requested.  It
34       returns a hash reference, with the following keys as of this writing:
35
36       arg The path you passed to the function. If what you passed is some
37           kind of an object (of Path::Tiny, for example), it's stringified.
38
39       cpan_path
40           A relative path to the distribution, whose base directory is
41           assumed CPAN/authors/id/. If org_path doesn't contain a pause_id,
42           the distribution is assumed to belong to LOCAL user. For example,
43
44             say parse_distname('Dist-0.01.tar.gz')->{cpan_path};
45             # L/LO/LOCAL/Dist-0.01.tar.gz
46
47           If you only gives a pause_id, parent directories are supplemented.
48
49             say parse_distname('ISHIGAKI/Dist-0.01.tar.gz')->{cpan_path};
50             # I/IS/ISHIGAKI/Dist-0.01.tar.gz
51
52       pause_id
53           The pause_id of the distribution. Contrary to the above, this is
54           empty if you don't give a pause_id.
55
56             say parse_distname('Dist-0.01.tar.gz')->{pause_id};
57             # (undef, not LOCAL)
58
59       subdir
60           A PAUSE distribution may be put into a subdirectory under the
61           author directory. If the name contains such a subdirectory, it's
62           kept here.
63
64             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{subdir};
65             # sub
66
67           Perl 6 distributions are (almost) always put under Perl6/
68           subdirectory under each author's directory (with a few exceptions).
69
70       name_and_version
71           The name and version of the distribution, without an extension and
72           directory parts, which should not be empty as long as the
73           distribution has an extension that PAUSE accepts.
74
75             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{name_and_version};
76             # Dist-0.01
77
78       name
79           The name part of the distribution. This may be empty if no valid
80           name is found
81
82             say parse_distname('AUTHOR/sub/Dist-0.01.tar.gz')->{name};
83             # Dist
84
85             say parse_distname('AUTHOR/v0.1.tar.gz')->{name};
86             # (empty)
87
88       version
89           The version part of the distribution. This also may be empty, and
90           this may not always be a valid version, and may have a following
91           part such as "-TRIAL".
92
93             say parse_distname('AUTHOR/Dist.tar.gz')->{version};
94             # (undef)
95
96             say parse_distname('AUTHOR/Dist-0.01-TRIAL.tar.gz')->{version};
97             # 0.01-TRIAL
98
99       version_number
100           The first numerical part of the version. This also may be empty,
101           and this may not always be a valid version.
102
103             say parse_distname('AUTHOR/Dist-0.01-TRIAL.tar.gz')->{version_number};
104             # 0.01
105
106             say parse_distname('AUTHOR/Dist-0_0_1.tar.gz')->{version_number};
107             # 0_0_1
108
109       extension
110           The extension of the distribution. If no valid extension is found,
111           parse_distname returns false (undef).
112
113       is_perl6
114           For convenience, if subdir exists and it starts with Perl6/, this
115           becomes true.
116
117       is_dev
118           If the version looks like "\d+.\d+_\d+", or contains "-TRIAL", this
119           becomes true. PAUSE treats such a distribution as a developer's
120           release and doesn't list it in its indices.
121

METHODS

123       For compatibility with CPAN::DistnameInfo, Parse::Distname has the same
124       methods/accessors, so you can use it as a drop-in replacement.
125
126       In addition, "is_perl6" and "version_number" are available.
127

SEE ALSO

129       CPAN::DistnameInfo
130

AUTHOR

132       Kenichi Ishigaki, <ishigaki@cpan.org>
133

135       This software is copyright (c) 2018 by Kenichi Ishigaki.
136
137       This is free software; you can redistribute it and/or modify it under
138       the same terms as the Perl 5 programming language system itself.
139
140
141
142perl v5.34.1                      2022-04-28                Parse::Distname(3)
Impressum