scripts/Dpkg/Control.pm

   1 # Copyright © 2007-2009 Raphaël Hertzog <hertzog@debian.org>
   2 #
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 2 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  15
  16 =encoding utf8
  17
  18 =head1 NAME
  19
  20 Dpkg::Control - parse and manipulate official control-like information
  21
  22 =head1 DESCRIPTION
  23
  24 The Dpkg::Control object is a smart version of L<Dpkg::Control::Hash>.
  25 It associates a type to the control information. That type can be
  26 used to know what fields are allowed and in what order they must be
  27 output.
  28
  29 The types are constants that are exported by default. Here's the full
  30 list:
  31
  32 =over 4
  33
  34 =item CTRL_UNKNOWN
  35
  36 This type is the default type, it indicates that the type of control
  37 information is not yet known.
  38
  39 =item CTRL_INFO_SRC
  40
  41 Corresponds to the first stanza in a F<debian/control> file in
  42 a Debian source package.
  43
  44 =item CTRL_INFO_PKG
  45
  46 Corresponds to subsequent stanza in a F<debian/control> file
  47 in a Debian source package.
  48
  49 =item CTRL_REPO_RELEASE
  50
  51 Corresponds to a F<Release> file in a repository.
  52
  53 =item CTRL_INDEX_SRC
  54
  55 Corresponds to a stanza in a F<Sources> file of a source package
  56 repository.
  57
  58 =item CTRL_INDEX_PKG
  59
  60 Corresponds to a stanza in a F<Packages> file of a binary package
  61 repository.
  62
  63 =item CTRL_PKG_SRC
  64
  65 Corresponds to a .dsc file of a Debian source package.
  66
  67 =item CTRL_PKG_DEB
  68
  69 Corresponds to the F<control> file generated by dpkg-gencontrol
  70 (F<DEBIAN/control>) and to the same file inside .deb packages.
  71
  72 =item CTRL_FILE_BUILDINFO
  73
  74 Corresponds to a .buildinfo file.
  75
  76 =item CTRL_FILE_CHANGES
  77
  78 Corresponds to a .changes file.
  79
  80 =item CTRL_FILE_VENDOR
  81
  82 Corresponds to a vendor file in $Dpkg::CONFDIR/origins/.
  83
  84 =item CTRL_FILE_STATUS
  85
  86 Corresponds to a stanza in dpkg's F<status> file ($Dpkg::ADMINDIR/status).
  87
  88 =item CTRL_CHANGELOG
  89
  90 Corresponds to the output of dpkg-parsechangelog.
  91
  92 =item CTRL_COPYRIGHT_HEADER
  93
  94 Corresponds to the header stanza in a F<debian/copyright> file in
  95 machine readable format.
  96
  97 =item CTRL_COPYRIGHT_FILES
  98
  99 Corresponds to a files stanza in a F<debian/copyright> file in
 100 machine readable format.
 101
 102 =item CTRL_COPYRIGHT_LICENSE
 103
 104 Corresponds to a license stanza in a F<debian/copyright> file in
 105 machine readable format.
 106
 107 =item CTRL_TESTS
 108
 109 Corresponds to a package tests control file in F<debian/tests/control>.
 110
 111 =back
 112
 113 =cut
 114
 115 package Dpkg::Control 1.03;
 116
 117 use strict;
 118 use warnings;
 119
 120 our @EXPORT = qw(
 121     CTRL_UNKNOWN
 122     CTRL_INFO_SRC
 123     CTRL_INFO_PKG
 124     CTRL_INDEX_SRC
 125     CTRL_INDEX_PKG
 126     CTRL_REPO_RELEASE
 127     CTRL_PKG_SRC
 128     CTRL_PKG_DEB
 129     CTRL_FILE_BUILDINFO
 130     CTRL_FILE_CHANGES
 131     CTRL_FILE_VENDOR
 132     CTRL_FILE_STATUS
 133     CTRL_CHANGELOG
 134     CTRL_COPYRIGHT_HEADER
 135     CTRL_COPYRIGHT_FILES
 136     CTRL_COPYRIGHT_LICENSE
 137     CTRL_TESTS
 138 );
 139
 140 use Exporter qw(import);
 141
 142 use Dpkg::Gettext;
 143 use Dpkg::ErrorHandling;
 144 use Dpkg::Control::Types;
 145 use Dpkg::Control::Hash;
 146 use Dpkg::Control::Fields;
 147
 148 use parent qw(Dpkg::Control::Hash);
 149
 150 =head1 METHODS
 151
 152 All the methods of L<Dpkg::Control::Hash> are available. Those listed below
 153 are either new or overridden with a different behavior.
 154
 155 =over 4
 156
 157 =item $c = Dpkg::Control->new(%opts)
 158
 159 If the "type" option is given, it's used to setup default values
 160 for other options. See set_options() for more details.
 161
 162 =cut
 163
 164 sub new {
 165     my ($this, %opts) = @_;
 166     my $class = ref($this) || $this;
 167
 168     my $self = Dpkg::Control::Hash->new();
 169     bless $self, $class;
 170     $self->set_options(%opts);
 171
 172     return $self;
 173 }
 174
 175 =item $c->set_options(%opts)
 176
 177 Changes the value of one or more options. If the "type" option is changed,
 178 it is used first to define default values for others options. The option
 179 "allow_pgp" is set to 1 for CTRL_PKG_SRC, CTRL_FILE_CHANGES and
 180 CTRL_REPO_RELEASE and to 0 otherwise. The option "drop_empty" is set to 0
 181 for CTRL_INFO_PKG and CTRL_INFO_SRC and to 1 otherwise. The option "name"
 182 is set to a textual description of the type of control information.
 183
 184 The output order is also set to match the ordered list returned by
 185 Dpkg::Control::Fields::field_ordered_list($type).
 186
 187 =cut
 188
 189 sub set_options {
 190     my ($self, %opts) = @_;
 191     if (exists $opts{type}) {
 192         my $t = $opts{type};
 193         $$self->{allow_pgp} = ($t & (CTRL_PKG_SRC | CTRL_FILE_CHANGES | CTRL_REPO_RELEASE)) ? 1 : 0;
 194         $$self->{drop_empty} = ($t & (CTRL_INFO_PKG | CTRL_INFO_SRC)) ?  0 : 1;
 195         if ($t == CTRL_INFO_SRC) {
 196             $$self->{name} = g_('general section of control info file');
 197         } elsif ($t == CTRL_INFO_PKG) {
 198             $$self->{name} = g_("package's section of control info file");
 199         } elsif ($t == CTRL_CHANGELOG) {
 200             $$self->{name} = g_('parsed version of changelog');
 201         } elsif ($t == CTRL_COPYRIGHT_HEADER) {
 202             $$self->{name} = g_('header stanza of copyright file');
 203         } elsif ($t == CTRL_COPYRIGHT_FILES) {
 204             $$self->{name} = g_('files stanza of copyright file');
 205         } elsif ($t == CTRL_COPYRIGHT_HEADER) {
 206             $$self->{name} = g_('license stanza of copyright file');
 207         } elsif ($t == CTRL_TESTS) {
 208             $$self->{name} = g_("package's tests control file");
 209         } elsif ($t == CTRL_REPO_RELEASE) {
 210             $$self->{name} = sprintf(g_("repository's %s file"), 'Release');
 211         } elsif ($t == CTRL_INDEX_SRC) {
 212             $$self->{name} = sprintf(g_("stanza in repository's %s file"), 'Sources');
 213         } elsif ($t == CTRL_INDEX_PKG) {
 214             $$self->{name} = sprintf(g_("stanza in repository's %s file"), 'Packages');
 215         } elsif ($t == CTRL_PKG_SRC) {
 216             $$self->{name} = sprintf(g_('%s file'), '.dsc');
 217         } elsif ($t == CTRL_PKG_DEB) {
 218             $$self->{name} = g_('control info of a .deb package');
 219         } elsif ($t == CTRL_FILE_BUILDINFO) {
 220             $$self->{name} = g_('build information file');
 221         } elsif ($t == CTRL_FILE_CHANGES) {
 222             $$self->{name} = sprintf(g_('%s file'), '.changes');
 223         } elsif ($t == CTRL_FILE_VENDOR) {
 224             $$self->{name} = g_('vendor file');
 225         } elsif ($t == CTRL_FILE_STATUS) {
 226             $$self->{name} = g_("stanza in dpkg's status file");
 227         }
 228         $self->set_output_order(field_ordered_list($opts{type}));
 229     }
 230
 231     # Options set by the user override default values
 232     $$self->{$_} = $opts{$_} foreach keys %opts;
 233 }
 234
 235 =item $c->get_type()
 236
 237 Returns the type of control information stored. See the type parameter
 238 set during new().
 239
 240 =cut
 241
 242 sub get_type {
 243     my $self = shift;
 244     return $$self->{type};
 245 }
 246
 247 =back
 248
 249 =head1 CHANGES
 250
 251 =head2 Version 1.03 (dpkg 1.18.11)
 252
 253 New type: CTRL_FILE_BUILDINFO.
 254
 255 =head2 Version 1.02 (dpkg 1.18.8)
 256
 257 New type: CTRL_TESTS.
 258
 259 =head2 Version 1.01 (dpkg 1.18.5)
 260
 261 New types: CTRL_REPO_RELEASE, CTRL_COPYRIGHT_HEADER, CTRL_COPYRIGHT_FILES,
 262 CTRL_COPYRIGHT_LICENSE.
 263
 264 =head2 Version 1.00 (dpkg 1.15.6)
 265
 266 Mark the module as public.
 267
 268 =cut
 269
 270 1;