scripts/Dpkg/Source/Format.pm

   1 # Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
   2 # Copyright © 2008-2018 Guillem Jover <guillem@debian.org>
   3 #
   4 # This program is free software; you can redistribute it and/or modify
   5 # it under the terms of the GNU General Public License as published by
   6 # the Free Software Foundation; either version 2 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU General Public License
  15 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  16
  17 =encoding utf8
  18
  19 =head1 NAME
  20
  21 Dpkg::Source::Format - manipulate debian/source/format files
  22
  23 =head1 DESCRIPTION
  24
  25 This module provides a class that can manipulate Debian source
  26 package F<debian/source/format> files.
  27
  28 =cut
  29
  30 package Dpkg::Source::Format 1.00;
  31
  32 use strict;
  33 use warnings;
  34
  35 use Dpkg::Gettext;
  36 use Dpkg::ErrorHandling;
  37
  38 use parent qw(Dpkg::Interface::Storable);
  39
  40 =head1 METHODS
  41
  42 =over 4
  43
  44 =item $f = Dpkg::Source::Format->new(%opts)
  45
  46 Creates a new object corresponding to a source package's
  47 F<debian/source/format> file.
  48
  49 Options:
  50
  51 =over
  52
  53 =item B<filename>
  54
  55 Set the filename to use to parse and set the format.
  56
  57 =item B<format>
  58
  59 Set and validate the format to use instead of loading the default file,
  60 if no filename has been specified.
  61
  62 =back
  63
  64 =cut
  65
  66 sub new {
  67     my ($this, %opts) = @_;
  68     my $class = ref($this) || $this;
  69     my $self = {
  70         filename => undef,
  71         major => undef,
  72         minor => undef,
  73         variant => undef,
  74     };
  75     bless $self, $class;
  76
  77     if (exists $opts{filename}) {
  78         $self->load($opts{filename}, compression => 0);
  79     } elsif ($opts{format}) {
  80         $self->set($opts{format});
  81     }
  82     return $self;
  83 }
  84
  85 =item $f->set_from_parts($major[, $minor[, $variant]])
  86
  87 Sets the source format from its parts. The $major part is mandatory.
  88 The $minor and $variant parts are optional.
  89
  90 B<Notice>: This function performs no validation.
  91
  92 =cut
  93
  94 sub set_from_parts {
  95     my ($self, $major, $minor, $variant) = @_;
  96
  97     $self->{major} = $major;
  98     $self->{minor} = $minor // 0;
  99     $self->{variant} = $variant;
 100 }
 101
 102 =item ($major, $minor, $variant) = $f->set($format)
 103
 104 Sets (and validates) the source $format specified. Will return the parsed
 105 format parts as a list, the optional $minor and $variant parts might be
 106 undef.
 107
 108 =cut
 109
 110 sub set {
 111     my ($self, $format) = @_;
 112
 113     if ($format =~ /^(\d+)(?:\.(\d+))?(?:\s+\(([a-z0-9]+)\))?$/) {
 114         my ($major, $minor, $variant) = ($1, $2, $3);
 115
 116         $self->set_from_parts($major, $minor, $variant);
 117
 118         return ($major, $minor, $variant);
 119     } else {
 120         error(g_("source package format '%s' is invalid"), $format);
 121     }
 122 }
 123
 124 =item ($major, $minor, $variant) = $f->get()
 125
 126 =item $format = $f->get()
 127
 128 Gets the source format, either as properly formatted scalar, or as a list
 129 of its parts, where the optional $minor and $variant parts might be undef.
 130
 131 =cut
 132
 133 sub get {
 134     my $self = shift;
 135
 136     if (wantarray) {
 137         return ($self->{major}, $self->{minor}, $self->{variant});
 138     } else {
 139         my $format = "$self->{major}.$self->{minor}";
 140         $format .= " ($self->{variant})" if defined $self->{variant};
 141
 142         return $format;
 143     }
 144 }
 145
 146 =item $count = $f->parse($fh, $desc)
 147
 148 Parse the source format string from $fh, with filehandle description $desc.
 149
 150 =cut
 151
 152 sub parse {
 153     my ($self, $fh, $desc) = @_;
 154
 155     my $format = <$fh>;
 156     chomp $format if defined $format;
 157     error(g_('%s is empty'), $desc)
 158         unless defined $format and length $format;
 159
 160     $self->set($format);
 161
 162     return 1;
 163 }
 164
 165 =item $count = $f->load($filename)
 166
 167 Parse $filename contents for a source package format string.
 168
 169 =item $str = $f->output([$fh])
 170
 171 =item "$f"
 172
 173 Returns a string representing the source package format version.
 174 If $fh is set, it prints the string to the filehandle.
 175
 176 =cut
 177
 178 sub output {
 179     my ($self, $fh) = @_;
 180
 181     my $str = $self->get();
 182
 183     print { $fh } "$str\n" if defined $fh;
 184
 185     return $str;
 186 }
 187
 188 =item $f->save($filename)
 189
 190 Save the source package format into the given $filename.
 191
 192 =back
 193
 194 =head1 CHANGES
 195
 196 =head2 Version 1.00 (dpkg 1.19.3)
 197
 198 Mark the module as public.
 199
 200 =cut
 201
 202 1;