document OpenBSD::PackageName

2 files changed, 65 insertions, 1 deletions

diff --git a/usr.sbin/pkg_add/Makefile b/usr.sbin/pkg_add/Makefile
index db3b8551a3d..36158e6585b 100644
--- a/usr.sbin/pkg_add/Makefile
+++ b/usr.sbin/pkg_add/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.26 2005/08/07 16:25:35 espie Exp $
+# $OpenBSD: Makefile,v 1.27 2005/08/17 08:17:44 espie Exp $
 
 .include <bsd.own.mk>
 
@@ -49,6 +49,7 @@ LIBBASE=/usr/libdata/perl5
 PODS= \
     OpenBSD::IdCache \
     OpenBSD::Mtree \
+    OpenBSD::PackageName \
     OpenBSD::PackingElement \
     OpenBSD::PackingList \
     OpenBSD::PkgCfl \
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod b/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod
new file mode 100644
index 00000000000..a2d9e910726
--- /dev/null
+++ b/usr.sbin/pkg_add/pod/OpenBSD::PackageName.pod
@@ -0,0 +1,63 @@
+$OpenBSD: OpenBSD::PackageName.pod,v 1.1 2005/08/17 08:17:44 espie Exp $
+
+=head1 NAME
+
+OpenBSD::PackageName - package names handling
+
+=head1 SYNOPSIS
+
+   use OpenBSD::PackageName;
+
+   $pkgname = OpenBSD::PackageName::url2pkgname($url);
+
+   ($stem, $version, @flavors) = OpenBSD::PackageName::splitname($pkgname);
+   $stem = OpenBSD::PackageName::splitstem($pkgname);
+
+   OpenBSD::PackageName::is_stem($stem) == 1 
+   OpenBSD::PackageName::is_stem($pkgname) == 0;
+
+   @candidates = OpenBSD::PackageName::findstem($stem, @pkgnames);
+   # alternate interface
+   $h = OpenBSD::PackageName::compile_stemlist(@pkgnames);
+   @candidates = $h->findstem($stem);
+
+=head1 DESCRIPTION
+
+C<OpenBSD::PackageName> is the canonical interface to package names
+handling.
+
+=over 4
+
+=item C<OpenBSD::PackageName::url2pkgname($url)>
+
+strip an C<$url> of path elements and C<.tgz> suffixes, yield a canonicalized
+package name.
+
+=item C<OpenBSD::PackageName::splitname($pkgname)>
+
+split a C<$pkgname> into a C<$stem>, a C<$version> number, and a (possibly
+empty) list of C<@flavors> components.  If the name contains no identifiable
+version, C<$version> will be C<undef>.
+
+=item C<OpenBSD::PackageName::splitstem($pkgname)>
+
+short version of C<splitname> that extracts only the C<$stem>.
+
+=item C<OpenBSD::PackageName::is_stem($string)>
+
+check whether a C<$string> is a valid stem, as opposed to a full package name.
+Useful for commands that take either full names or stems, and need to
+reconstruct the full name from the stem.
+
+=item C<OpenBSD::PackageName::findstem($stem, @pkgnames)>
+
+look up a C<$stem> into a list of C<@pkgnames>. Return a list of candidates
+for further processing.
+
+=item C<OpenBSD::PackageName::compile_stemlist(@pkgnames)>
+
+alternate interface that is faster when lots of look ups are involved.
+Compile a list of C<@pkgnames> into an object C<$h> that can be queried
+using C<$h-E<gt>finstem($stem)>.
+
+=back