Dpkg::Source::Package: add extraction functions to the supported API

Add the extraction part of Dpkg::Source::Package to the supported API.
It's useful to extract source packages without having to depend on
dpkg-source (and hence dpkg-dev).

Suggested-by: Niels Thykier

debian/changelog

@@ -25,6 +25,9 @@ dpkg (1.16.1) UNRELEASED; urgency=low
     have no clear use case yet. It can always be added later on.
     Also drop the source line since it duplicates other fields.
     Closes: #619131
+  * Add the extraction part of Dpkg::Source::Package to the supported API.
+    Useful to extract source packages without having to depend on dpkg-source
+    (and hence dpkg-dev).
 
   [ Guillem Jover ]
   * Install deb-src-control(5) man pages in dpkg-dev. Closes: #620520

scripts/Dpkg/Source/Package.pm

@@ -15,10 +15,27 @@
 
 package Dpkg::Source::Package;
 
+=encoding utf8
+
+=head1 NAME
+
+Dpkg::Source::Package - manipulate Debian source packages
+
+=head1 DESCRIPTION
+
+This module provides an object that can manipulate Debian source
+packages. While it supports both the extraction and the creation
+of source packages, the only API that is officially supported
+is the one that supports the extraction of the source package.
+
+=head1 FUNCTIONS
+
+=cut
+
 use strict;
 use warnings;
 
-our $VERSION = "0.01";
+our $VERSION = "1.0";
 
 use Dpkg::Gettext;
 use Dpkg::ErrorHandling;
@@ -93,6 +110,41 @@ _darcs
 {arch}
 );
 
+=over 4
+
+=item $p = Dpkg::Source::Package->new(filename => $dscfile, options => {})
+
+Creates a new object corresponding to the source package described
+by the file $dscfile.
+
+The options hash supports the following options:
+
+=over 8
+
+=item skip_debianization
+
+If set to 1, do not apply Debian changes on the extracted source package.
+
+=item skip_patches
+
+If set to 1, do not apply Debian-specific patches. This options is
+specific for source packages using format "2.0" and "3.0 (quilt)".
+
+=item require_valid_signature
+
+If set to 1, the check_signature() method will be stricter and will error
+out if the signature can't be verified.
+
+=item copy_orig_tarballs
+
+If set to 1, the extraction will copy the upstream tarballs next the
+target directory. This is useful if you want to be able to rebuild the
+source package after its extraction.
+
+=back
+
+=cut
+
 # Object methods
 sub new {
     my ($this, %args) = @_;
@@ -189,16 +241,37 @@ sub upgrade_object_type {
     }
 }
 
+=item $p->get_filename()
+
+Returns the filename of the DSC file.
+
+=cut
+
 sub get_filename {
     my ($self) = @_;
     return $self->{'basedir'} . $self->{'filename'};
 }
 
+=item $p->get_files()
+
+Returns the list of files referenced by the source package. The filenames
+usually do not have any path information.
+
+=cut
+
 sub get_files {
     my ($self) = @_;
     return $self->{'checksums'}->get_files();
 }
 
+=item $p->check_checksums()
+
+Verify the checksums embedded in the DSC file. It requires the presence of
+the other files constituting the source package. If any inconsistency is
+discovered, it immediately errors out.
+
+=cut
+
 sub check_checksums {
     my ($self) = @_;
     my $checksums = $self->{'checksums'};
@@ -243,11 +316,28 @@ sub find_original_tarballs {
     return @tar;
 }
 
+=item $bool = $p->is_signed()
+
+Returns 1 if the DSC files contains an embedded OpenPGP signature.
+Otherwise returns 0.
+
+=cut
+
 sub is_signed {
     my $self = shift;
     return $self->{'is_signed'};
 }
 
+=item $p->check_signature()
+
+Implement the same OpenPGP signature check that dpkg-source does.
+In case of problems, it prints a warning or errors out.
+
+If the object has been created with the "require_valid_signature" option,
+then any problem will result in a fatal error.
+
+=cut
+
 sub check_signature {
     my ($self) = @_;
     my $dsc = $self->get_filename();
@@ -307,6 +397,13 @@ sub parse_cmdline_option {
     return 0;
 }
 
+=item $p->extract($targetdir)
+
+Extracts the source package in the target directory $targetdir. Beware
+that if $targetdir already exists, it will be erased.
+
+=cut
+
 sub extract {
     my $self = shift;
     my $newdirectory = $_[0];
@@ -450,5 +547,13 @@ sub write_dsc {
     close(DSC);
 }
 
+=back
+
+=head1 AUTHOR
+
+Raphaël Hertzog, E<lt>hertzog@debian.orgE<gt>
+
+=cut
+
 # vim: set et sw=4 ts=8
 1;