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