1$OpenBSD: PackageName.pod,v 1.1 2020/12/20 15:30:58 daniel Exp $
2
3=head1 NAME
4
5OpenBSD::PackageName - package names handling
6
7=head1 SYNOPSIS
8
9   use OpenBSD::PackageName;
10
11   $pkgname = OpenBSD::PackageName::url2pkgname($url);
12
13   ($stem, $version, @flavors) = OpenBSD::PackageName::splitname($pkgname);
14   $stem = OpenBSD::PackageName::splitstem($pkgname);
15
16   OpenBSD::PackageName::is_stem($stem) == 1;
17   OpenBSD::PackageName::is_stem($pkgname) == 0;
18
19   @candidates = OpenBSD::PackageName::findstem($stem, @pkgnames);
20   # alternate interface
21   $h = OpenBSD::PackageName::compile_stemlist(@pkgnames);
22   @candidates = $h->findstem($stem);
23
24=head1 DESCRIPTION
25
26C<OpenBSD::PackageName> is the canonical interface to package names
27handling.
28
29=over 4
30
31=item C<OpenBSD::PackageName::url2pkgname($url)>
32
33strip an C<$url> of path elements and C<.tgz> suffixes, yield a canonicalized
34package name.
35
36=item C<OpenBSD::PackageName::splitname($pkgname)>
37
38split a C<$pkgname> into a C<$stem>, a C<$version> number, and a (possibly
39empty) list of C<@flavors> components.  If the name contains no identifiable
40version, C<$version> will be C<undef>.
41
42=item C<OpenBSD::PackageName::splitstem($pkgname)>
43
44short version of C<splitname> that extracts only the C<$stem>.
45
46=item C<OpenBSD::PackageName::is_stem($string)>
47
48check whether a C<$string> is a valid stem, as opposed to a full package name.
49Useful for commands that take either full names or stems, and need to
50reconstruct the full name from the stem.
51
52=item C<OpenBSD::PackageName::findstem($stem, @pkgnames)>
53
54look up a C<$stem> into a list of C<@pkgnames>. Return a list of candidates
55for further processing.
56
57=item C<OpenBSD::PackageName::compile_stemlist(@pkgnames)>
58
59alternate interface that is faster when lots of look ups are involved.
60Compile a list of C<@pkgnames> into an object C<$h> that can be queried
61using C<$h-E<gt>findstem($stem)>.
62
63=back
64