scripts/Dpkg/Control/FieldsCore.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::FieldsCore - manage (list of official) control fields
  21
  22 =head1 DESCRIPTION
  23
  24 The modules contains a list of field names with associated meta-data explaining
  25 in which type of control information they are allowed. The types are the
  26 CTRL_* constants exported by L<Dpkg::Control>.
  27
  28 =cut
  29
  30 package Dpkg::Control::FieldsCore 1.02;
  31
  32 use strict;
  33 use warnings;
  34
  35 our @EXPORT = qw(
  36     field_capitalize
  37     field_is_official
  38     field_is_allowed_in
  39     field_transfer_single
  40     field_transfer_all
  41     field_parse_binary_source
  42     field_list_src_dep
  43     field_list_pkg_dep
  44     field_get_dep_type
  45     field_get_sep_type
  46     field_ordered_list
  47     field_register
  48     field_insert_after
  49     field_insert_before
  50     FIELD_SEP_UNKNOWN
  51     FIELD_SEP_SPACE
  52     FIELD_SEP_COMMA
  53     FIELD_SEP_LINE
  54 );
  55
  56 use Exporter qw(import);
  57
  58 use Dpkg::Gettext;
  59 use Dpkg::ErrorHandling;
  60 use Dpkg::Control::Types;
  61
  62 use constant {
  63     ALL_PKG => CTRL_INFO_PKG | CTRL_INDEX_PKG | CTRL_PKG_DEB | CTRL_FILE_STATUS,
  64     ALL_SRC => CTRL_INFO_SRC | CTRL_INDEX_SRC | CTRL_PKG_SRC,
  65     ALL_FILE_MANIFEST => CTRL_FILE_BUILDINFO | CTRL_FILE_CHANGES,
  66     ALL_CHANGES => CTRL_FILE_CHANGES | CTRL_CHANGELOG,
  67     ALL_COPYRIGHT => CTRL_COPYRIGHT_HEADER | CTRL_COPYRIGHT_FILES | CTRL_COPYRIGHT_LICENSE,
  68 };
  69
  70 use constant {
  71     FIELD_SEP_UNKNOWN => 0,
  72     FIELD_SEP_SPACE => 1,
  73     FIELD_SEP_COMMA => 2,
  74     FIELD_SEP_LINE => 4,
  75 };
  76
  77 # The canonical list of fields.
  78
  79 # Note that fields used only in dpkg's available file are not listed.
  80 # Deprecated fields of dpkg's status file are also not listed.
  81 our %FIELDS = (
  82     'acquire-by-hash' => {
  83         name => 'Acquire-By-Hash',
  84         allowed => CTRL_REPO_RELEASE,
  85     },
  86     'architecture' => {
  87         name => 'Architecture',
  88         allowed => (ALL_PKG | ALL_SRC | ALL_FILE_MANIFEST | CTRL_TESTS) & (~CTRL_INFO_SRC),
  89         separator => FIELD_SEP_SPACE,
  90     },
  91     'architectures' => {
  92         name => 'Architectures',
  93         allowed => CTRL_REPO_RELEASE,
  94         separator => FIELD_SEP_SPACE,
  95     },
  96     'auto-built-package' => {
  97         name => 'Auto-Built-Package',
  98         allowed => ALL_PKG & ~CTRL_INFO_PKG,
  99         separator => FIELD_SEP_SPACE,
 100     },
 101     'binary' => {
 102         name => 'Binary',
 103         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | ALL_FILE_MANIFEST,
 104         # XXX: This field values are separated either by space or comma
 105         # depending on the context.
 106         separator => FIELD_SEP_SPACE | FIELD_SEP_COMMA,
 107     },
 108     'binary-only' => {
 109         name => 'Binary-Only',
 110         allowed => ALL_CHANGES,
 111     },
 112     'binary-only-changes' => {
 113         name => 'Binary-Only-Changes',
 114         allowed => CTRL_FILE_BUILDINFO,
 115     },
 116     'breaks' => {
 117         name => 'Breaks',
 118         allowed => ALL_PKG,
 119         separator => FIELD_SEP_COMMA,
 120         dependency => 'union',
 121         dep_order => 7,
 122     },
 123     'bugs' => {
 124         name => 'Bugs',
 125         allowed => (ALL_PKG | CTRL_INFO_SRC | CTRL_FILE_VENDOR) & (~CTRL_INFO_PKG),
 126     },
 127     'build-architecture' => {
 128         name => 'Build-Architecture',
 129         allowed => CTRL_FILE_BUILDINFO,
 130     },
 131     'build-conflicts' => {
 132         name => 'Build-Conflicts',
 133         allowed => ALL_SRC,
 134         separator => FIELD_SEP_COMMA,
 135         dependency => 'union',
 136         dep_order => 4,
 137     },
 138     'build-conflicts-arch' => {
 139         name => 'Build-Conflicts-Arch',
 140         allowed => ALL_SRC,
 141         separator => FIELD_SEP_COMMA,
 142         dependency => 'union',
 143         dep_order => 5,
 144     },
 145     'build-conflicts-indep' => {
 146         name => 'Build-Conflicts-Indep',
 147         allowed => ALL_SRC,
 148         separator => FIELD_SEP_COMMA,
 149         dependency => 'union',
 150         dep_order => 6,
 151     },
 152     'build-date' => {
 153         name => 'Build-Date',
 154         allowed => CTRL_FILE_BUILDINFO,
 155     },
 156     'build-depends' => {
 157         name => 'Build-Depends',
 158         allowed => ALL_SRC,
 159         separator => FIELD_SEP_COMMA,
 160         dependency => 'normal',
 161         dep_order => 1,
 162     },
 163     'build-depends-arch' => {
 164         name => 'Build-Depends-Arch',
 165         allowed => ALL_SRC,
 166         separator => FIELD_SEP_COMMA,
 167         dependency => 'normal',
 168         dep_order => 2,
 169     },
 170     'build-depends-indep' => {
 171         name => 'Build-Depends-Indep',
 172         allowed => ALL_SRC,
 173         separator => FIELD_SEP_COMMA,
 174         dependency => 'normal',
 175         dep_order => 3,
 176     },
 177     'build-essential' => {
 178         name => 'Build-Essential',
 179         allowed => ALL_PKG,
 180     },
 181     'build-kernel-version' => {
 182         name => 'Build-Kernel-Version',
 183         allowed => CTRL_FILE_BUILDINFO,
 184     },
 185     'build-origin' => {
 186         name => 'Build-Origin',
 187         allowed => CTRL_FILE_BUILDINFO,
 188     },
 189     'build-path' => {
 190         name => 'Build-Path',
 191         allowed => CTRL_FILE_BUILDINFO,
 192     },
 193     'build-profiles' => {
 194         name => 'Build-Profiles',
 195         allowed => CTRL_INFO_PKG,
 196         separator => FIELD_SEP_SPACE,
 197     },
 198     'build-tainted-by' => {
 199         name => 'Build-Tainted-By',
 200         allowed => CTRL_FILE_BUILDINFO,
 201         separator => FIELD_SEP_SPACE,
 202     },
 203     'built-for-profiles' => {
 204         name => 'Built-For-Profiles',
 205         allowed => ALL_PKG | CTRL_FILE_CHANGES,
 206         separator => FIELD_SEP_SPACE,
 207     },
 208     'built-using' => {
 209         name => 'Built-Using',
 210         allowed => ALL_PKG,
 211         separator => FIELD_SEP_COMMA,
 212         dependency => 'union',
 213         dep_order => 10,
 214     },
 215     'butautomaticupgrades' => {
 216         name => 'ButAutomaticUpgrades',
 217         allowed => CTRL_REPO_RELEASE,
 218     },
 219     'changed-by' => {
 220         name => 'Changed-By',
 221         allowed => CTRL_FILE_CHANGES,
 222     },
 223     'changelogs' => {
 224         name => 'Changelogs',
 225         allowed => CTRL_REPO_RELEASE,
 226     },
 227     'changes' => {
 228         name => 'Changes',
 229         allowed => ALL_CHANGES,
 230     },
 231     'checksums-md5' => {
 232         name => 'Checksums-Md5',
 233         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | ALL_FILE_MANIFEST,
 234     },
 235     'checksums-sha1' => {
 236         name => 'Checksums-Sha1',
 237         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | ALL_FILE_MANIFEST,
 238     },
 239     'checksums-sha256' => {
 240         name => 'Checksums-Sha256',
 241         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | ALL_FILE_MANIFEST,
 242     },
 243     'classes' => {
 244         name => 'Classes',
 245         allowed => CTRL_TESTS,
 246         separator => FIELD_SEP_COMMA,
 247     },
 248     'closes' => {
 249         name => 'Closes',
 250         allowed => ALL_CHANGES,
 251         separator => FIELD_SEP_SPACE,
 252     },
 253     'codename' => {
 254         name => 'Codename',
 255         allowed => CTRL_REPO_RELEASE,
 256     },
 257     'comment' => {
 258         name => 'Comment',
 259         allowed => ALL_COPYRIGHT,
 260     },
 261     'components' => {
 262         name => 'Components',
 263         allowed => CTRL_REPO_RELEASE,
 264         separator => FIELD_SEP_SPACE,
 265     },
 266     'conffiles' => {
 267         name => 'Conffiles',
 268         allowed => CTRL_FILE_STATUS,
 269         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 270     },
 271     'config-version' => {
 272         name => 'Config-Version',
 273         allowed => CTRL_FILE_STATUS,
 274     },
 275     'conflicts' => {
 276         name => 'Conflicts',
 277         allowed => ALL_PKG,
 278         separator => FIELD_SEP_COMMA,
 279         dependency => 'union',
 280         dep_order => 6,
 281     },
 282     'copyright' => {
 283         name => 'Copyright',
 284         allowed => CTRL_COPYRIGHT_HEADER | CTRL_COPYRIGHT_FILES,
 285     },
 286     'date' => {
 287         name => 'Date',
 288         allowed => ALL_CHANGES | CTRL_REPO_RELEASE,
 289     },
 290     'depends' => {
 291         name => 'Depends',
 292         allowed => ALL_PKG | CTRL_TESTS,
 293         separator => FIELD_SEP_COMMA,
 294         dependency => 'normal',
 295         dep_order => 2,
 296     },
 297     'description' => {
 298         name => 'Description',
 299         allowed => ALL_SRC | ALL_PKG | CTRL_FILE_CHANGES | CTRL_REPO_RELEASE,
 300     },
 301     'disclaimer' => {
 302         name => 'Disclaimer',
 303         allowed => CTRL_COPYRIGHT_HEADER,
 304     },
 305     'directory' => {
 306         name => 'Directory',
 307         allowed => CTRL_INDEX_SRC,
 308     },
 309     'distribution' => {
 310         name => 'Distribution',
 311         allowed => ALL_CHANGES,
 312     },
 313     'enhances' => {
 314         name => 'Enhances',
 315         allowed => ALL_PKG,
 316         separator => FIELD_SEP_COMMA,
 317         dependency => 'union',
 318         dep_order => 5,
 319     },
 320     'environment' => {
 321         name => 'Environment',
 322         allowed => CTRL_FILE_BUILDINFO,
 323         separator => FIELD_SEP_LINE,
 324     },
 325     'essential' => {
 326         name => 'Essential',
 327         allowed => ALL_PKG,
 328     },
 329     'features' => {
 330         name => 'Features',
 331         allowed => CTRL_TESTS,
 332         separator => FIELD_SEP_SPACE,
 333     },
 334     'filename' => {
 335         name => 'Filename',
 336         allowed => CTRL_INDEX_PKG,
 337         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 338     },
 339     'files' => {
 340         name => 'Files',
 341         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | CTRL_FILE_CHANGES | CTRL_COPYRIGHT_FILES,
 342         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 343     },
 344     'format' => {
 345         name => 'Format',
 346         allowed => CTRL_PKG_SRC | CTRL_INDEX_SRC | ALL_FILE_MANIFEST | CTRL_COPYRIGHT_HEADER,
 347     },
 348     'homepage' => {
 349         name => 'Homepage',
 350         allowed => ALL_SRC | ALL_PKG,
 351     },
 352     'installed-build-depends' => {
 353         name => 'Installed-Build-Depends',
 354         allowed => CTRL_FILE_BUILDINFO,
 355         separator => FIELD_SEP_COMMA,
 356         dependency => 'union',
 357         dep_order => 12,
 358     },
 359     'installed-size' => {
 360         name => 'Installed-Size',
 361         allowed => ALL_PKG & ~CTRL_INFO_PKG,
 362     },
 363     'installer-menu-item' => {
 364         name => 'Installer-Menu-Item',
 365         allowed => ALL_PKG,
 366     },
 367     'kernel-version' => {
 368         name => 'Kernel-Version',
 369         allowed => ALL_PKG,
 370     },
 371     'label' => {
 372         name => 'Label',
 373         allowed => CTRL_REPO_RELEASE,
 374     },
 375     'license' => {
 376         name => 'License',
 377         allowed => ALL_COPYRIGHT,
 378     },
 379     'origin' => {
 380         name => 'Origin',
 381         allowed => (ALL_PKG | ALL_SRC | CTRL_REPO_RELEASE) & (~CTRL_INFO_PKG),
 382     },
 383     'maintainer' => {
 384         name => 'Maintainer',
 385         allowed => CTRL_PKG_DEB | CTRL_INDEX_PKG | CTRL_FILE_STATUS | ALL_SRC  | ALL_CHANGES,
 386     },
 387     'md5sum' => {
 388         # XXX: Wrong capitalization due to historical reasons.
 389         name => 'MD5sum',
 390         allowed => CTRL_INDEX_PKG | CTRL_REPO_RELEASE,
 391         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 392     },
 393     'multi-arch' => {
 394         name => 'Multi-Arch',
 395         allowed => ALL_PKG,
 396     },
 397     'no-support-for-architecture-all' => {
 398         name => 'No-Support-for-Architecture-all',
 399         allowed => CTRL_REPO_RELEASE,
 400     },
 401     'notautomatic' => {
 402         name => 'NotAutomatic',
 403         allowed => CTRL_REPO_RELEASE,
 404     },
 405     'package' => {
 406         name => 'Package',
 407         allowed => ALL_PKG | CTRL_INDEX_SRC,
 408     },
 409     'package-list' => {
 410         name => 'Package-List',
 411         allowed => ALL_SRC & ~CTRL_INFO_SRC,
 412         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 413     },
 414     'package-type' => {
 415         name => 'Package-Type',
 416         allowed => ALL_PKG,
 417     },
 418     'parent' => {
 419         name => 'Parent',
 420         allowed => CTRL_FILE_VENDOR,
 421     },
 422     'pre-depends' => {
 423         name => 'Pre-Depends',
 424         allowed => ALL_PKG,
 425         separator => FIELD_SEP_COMMA,
 426         dependency => 'normal',
 427         dep_order => 1,
 428     },
 429     'priority' => {
 430         name => 'Priority',
 431         allowed => CTRL_INFO_SRC | CTRL_INDEX_SRC | ALL_PKG,
 432     },
 433     'protected' => {
 434         name => 'Protected',
 435         allowed => ALL_PKG,
 436     },
 437     'provides' => {
 438         name => 'Provides',
 439         allowed => ALL_PKG,
 440         separator => FIELD_SEP_COMMA,
 441         dependency => 'union',
 442         dep_order => 9,
 443     },
 444     'recommends' => {
 445         name => 'Recommends',
 446         allowed => ALL_PKG,
 447         separator => FIELD_SEP_COMMA,
 448         dependency => 'normal',
 449         dep_order => 3,
 450     },
 451     'replaces' => {
 452         name => 'Replaces',
 453         allowed => ALL_PKG,
 454         separator => FIELD_SEP_COMMA,
 455         dependency => 'union',
 456         dep_order => 8,
 457     },
 458     'restrictions' => {
 459         name => 'Restrictions',
 460         allowed => CTRL_TESTS,
 461         separator => FIELD_SEP_SPACE,
 462     },
 463     'rules-requires-root' => {
 464         name => 'Rules-Requires-Root',
 465         allowed => CTRL_INFO_SRC,
 466         separator => FIELD_SEP_SPACE,
 467     },
 468     'section' => {
 469         name => 'Section',
 470         allowed => CTRL_INFO_SRC | CTRL_INDEX_SRC | ALL_PKG,
 471     },
 472     'sha1' => {
 473         # XXX: Wrong capitalization due to historical reasons.
 474         name => 'SHA1',
 475         allowed => CTRL_INDEX_PKG | CTRL_REPO_RELEASE,
 476         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 477     },
 478     'sha256' => {
 479         # XXX: Wrong capitalization due to historical reasons.
 480         name => 'SHA256',
 481         allowed => CTRL_INDEX_PKG | CTRL_REPO_RELEASE,
 482         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 483     },
 484     'size' => {
 485         name => 'Size',
 486         allowed => CTRL_INDEX_PKG,
 487         separator => FIELD_SEP_LINE | FIELD_SEP_SPACE,
 488     },
 489     'source' => {
 490         name => 'Source',
 491         allowed => (ALL_PKG | ALL_SRC | ALL_CHANGES | CTRL_COPYRIGHT_HEADER | CTRL_FILE_BUILDINFO) &
 492                    (~(CTRL_INDEX_SRC | CTRL_INFO_PKG)),
 493     },
 494     'standards-version' => {
 495         name => 'Standards-Version',
 496         allowed => ALL_SRC,
 497     },
 498     'static-built-using' => {
 499         name => 'Static-Built-Using',
 500         allowed => ALL_PKG,
 501         separator => FIELD_SEP_COMMA,
 502         dependency => 'union',
 503         dep_order => 11,
 504     },
 505     'status' => {
 506         name => 'Status',
 507         allowed => CTRL_FILE_STATUS,
 508         separator => FIELD_SEP_SPACE,
 509     },
 510     'subarchitecture' => {
 511         name => 'Subarchitecture',
 512         allowed => ALL_PKG,
 513     },
 514     'suite' => {
 515         name => 'Suite',
 516         allowed => CTRL_REPO_RELEASE,
 517     },
 518     'suggests' => {
 519         name => 'Suggests',
 520         allowed => ALL_PKG,
 521         separator => FIELD_SEP_COMMA,
 522         dependency => 'normal',
 523         dep_order => 4,
 524     },
 525     'tag' => {
 526         name => 'Tag',
 527         allowed => ALL_PKG,
 528         separator => FIELD_SEP_COMMA,
 529     },
 530     'task' => {
 531         name => 'Task',
 532         allowed => ALL_PKG,
 533     },
 534     'test-command' => {
 535         name => 'Test-Command',
 536         allowed => CTRL_TESTS,
 537     },
 538     'tests' => {
 539         name => 'Tests',
 540         allowed => CTRL_TESTS,
 541         separator => FIELD_SEP_SPACE,
 542     },
 543     'tests-directory' => {
 544         name => 'Tests-Directory',
 545         allowed => CTRL_TESTS,
 546     },
 547     'testsuite' => {
 548         name => 'Testsuite',
 549         allowed => ALL_SRC,
 550         separator => FIELD_SEP_COMMA,
 551     },
 552     'testsuite-triggers' => {
 553         name => 'Testsuite-Triggers',
 554         allowed => ALL_SRC,
 555         separator => FIELD_SEP_COMMA,
 556     },
 557     'timestamp' => {
 558         name => 'Timestamp',
 559         allowed => CTRL_CHANGELOG,
 560     },
 561     'triggers-awaited' => {
 562         name => 'Triggers-Awaited',
 563         allowed => CTRL_FILE_STATUS,
 564         separator => FIELD_SEP_SPACE,
 565     },
 566     'triggers-pending' => {
 567         name => 'Triggers-Pending',
 568         allowed => CTRL_FILE_STATUS,
 569         separator => FIELD_SEP_SPACE,
 570     },
 571     'uploaders' => {
 572         name => 'Uploaders',
 573         allowed => ALL_SRC,
 574         separator => FIELD_SEP_COMMA,
 575     },
 576     'upstream-name' => {
 577         name => 'Upstream-Name',
 578         allowed => CTRL_COPYRIGHT_HEADER,
 579     },
 580     'upstream-contact' => {
 581         name => 'Upstream-Contact',
 582         allowed => CTRL_COPYRIGHT_HEADER,
 583     },
 584     'urgency' => {
 585         name => 'Urgency',
 586         allowed => ALL_CHANGES,
 587     },
 588     'valid-until' => {
 589         name => 'Valid-Until',
 590         allowed => CTRL_REPO_RELEASE,
 591     },
 592     'vcs-browser' => {
 593         name => 'Vcs-Browser',
 594         allowed => ALL_SRC,
 595     },
 596     'vcs-arch' => {
 597         name => 'Vcs-Arch',
 598         allowed => ALL_SRC,
 599     },
 600     'vcs-bzr' => {
 601         name => 'Vcs-Bzr',
 602         allowed => ALL_SRC,
 603     },
 604     'vcs-cvs' => {
 605         name => 'Vcs-Cvs',
 606         allowed => ALL_SRC,
 607     },
 608     'vcs-darcs' => {
 609         name => 'Vcs-Darcs',
 610         allowed => ALL_SRC,
 611     },
 612     'vcs-git' => {
 613         name => 'Vcs-Git',
 614         allowed => ALL_SRC,
 615     },
 616     'vcs-hg' => {
 617         name => 'Vcs-Hg',
 618         allowed => ALL_SRC,
 619     },
 620     'vcs-mtn' => {
 621         name => 'Vcs-Mtn',
 622         allowed => ALL_SRC,
 623     },
 624     'vcs-svn' => {
 625         name => 'Vcs-Svn',
 626         allowed => ALL_SRC,
 627     },
 628     'vendor' => {
 629         name => 'Vendor',
 630         allowed => CTRL_FILE_VENDOR,
 631     },
 632     'vendor-url' => {
 633         name => 'Vendor-Url',
 634         allowed => CTRL_FILE_VENDOR,
 635     },
 636     'version' => {
 637         name => 'Version',
 638         allowed => (ALL_PKG | ALL_SRC | CTRL_FILE_BUILDINFO | ALL_CHANGES | CTRL_REPO_RELEASE) &
 639                     (~(CTRL_INFO_SRC | CTRL_INFO_PKG)),
 640     },
 641 );
 642
 643 my @src_vcs_fields = qw(
 644     vcs-browser
 645     vcs-arch
 646     vcs-bzr
 647     vcs-cvs
 648     vcs-darcs
 649     vcs-git
 650     vcs-hg
 651     vcs-mtn
 652     vcs-svn
 653 );
 654
 655 my @src_dep_fields = qw(
 656     build-depends
 657     build-depends-arch
 658     build-depends-indep
 659     build-conflicts
 660     build-conflicts-arch
 661     build-conflicts-indep
 662 );
 663 my @bin_dep_fields = qw(
 664     pre-depends
 665     depends
 666     recommends
 667     suggests
 668     enhances
 669     conflicts
 670     breaks
 671     replaces
 672     provides
 673     built-using
 674     static-built-using
 675 );
 676
 677 my @src_test_fields = qw(
 678     testsuite
 679     testsuite-triggers
 680 );
 681
 682 my @src_checksums_fields = qw(
 683     checksums-md5
 684     checksums-sha1
 685     checksums-sha256
 686 );
 687 my @bin_checksums_fields = qw(
 688     md5sum
 689     sha1
 690     sha256
 691 );
 692
 693 our %FIELD_ORDER = (
 694     CTRL_INFO_SRC() => [
 695         qw(
 696             source
 697             section
 698             priority
 699             maintainer
 700             uploaders
 701             origin
 702             bugs
 703         ),
 704         @src_vcs_fields,
 705         qw(
 706             homepage
 707             standards-version
 708             rules-requires-root
 709         ),
 710         @src_dep_fields,
 711         @src_test_fields,
 712         qw(
 713             description
 714         ),
 715     ],
 716     CTRL_INFO_PKG() => [
 717         qw(
 718             package
 719             package-type
 720             section
 721             priority
 722             architecture
 723             subarchitecture
 724             multi-arch
 725             essential
 726             protected
 727             build-essential
 728             build-profiles
 729             built-for-profiles
 730             kernel-version
 731         ),
 732         @bin_dep_fields,
 733         qw(
 734             homepage
 735             installer-menu-item
 736             task
 737             tag
 738             description
 739         ),
 740     ],
 741     CTRL_PKG_SRC() => [
 742         qw(
 743             format
 744             source
 745             binary
 746             architecture
 747             version
 748             origin
 749             maintainer
 750             uploaders
 751             homepage
 752             description
 753             standards-version
 754         ),
 755         @src_vcs_fields,
 756         @src_test_fields,
 757         @src_dep_fields,
 758         qw(
 759             package-list
 760         ),
 761         @src_checksums_fields,
 762         qw(
 763             files
 764         ),
 765     ],
 766     CTRL_PKG_DEB() => [
 767         qw(
 768             package
 769             package-type
 770             source
 771             version
 772             kernel-version
 773             built-for-profiles
 774             auto-built-package
 775             architecture
 776             subarchitecture
 777             installer-menu-item
 778             build-essential
 779             essential
 780             protected
 781             origin
 782             bugs
 783             maintainer
 784             installed-size
 785         ),
 786         @bin_dep_fields,
 787         qw(
 788             section
 789             priority
 790             multi-arch
 791             homepage
 792             description
 793             tag
 794             task
 795         ),
 796     ],
 797     CTRL_INDEX_SRC() => [
 798         qw(
 799             format
 800             package
 801             binary
 802             architecture
 803             version
 804             priority
 805             section
 806             origin
 807             maintainer
 808             uploaders
 809             homepage
 810             description
 811             standards-version
 812         ),
 813         @src_vcs_fields,
 814         @src_test_fields,
 815         @src_dep_fields,
 816         qw(
 817             package-list
 818             directory
 819         ),
 820         @src_checksums_fields,
 821         qw(
 822             files
 823         ),
 824     ],
 825     CTRL_INDEX_PKG() => [
 826         qw(
 827             package
 828             package-type
 829             source
 830             version
 831             kernel-version
 832             built-for-profiles
 833             auto-built-package
 834             architecture
 835             subarchitecture
 836             installer-menu-item
 837             build-essential
 838             essential
 839             protected
 840             origin
 841             bugs
 842             maintainer
 843             installed-size
 844         ),
 845         @bin_dep_fields,
 846         qw(
 847             filename
 848             size
 849         ),
 850         @bin_checksums_fields,
 851         qw(
 852             section
 853             priority
 854             multi-arch
 855             homepage
 856             description
 857             tag
 858             task
 859         ),
 860     ],
 861     CTRL_REPO_RELEASE() => [
 862         qw(
 863             origin
 864             label
 865             suite
 866             version
 867             codename
 868             changelogs
 869             date
 870             valid-until
 871             notautomatic
 872             butautomaticupgrades
 873             acquire-by-hash
 874             no-support-for-architecture-all
 875             architectures
 876             components
 877             description
 878         ),
 879         @bin_checksums_fields
 880     ],
 881     CTRL_CHANGELOG() => [
 882         qw(
 883             source
 884             binary-only
 885             version
 886             distribution
 887             urgency
 888             maintainer
 889             timestamp
 890             date
 891             closes
 892             changes
 893         ),
 894     ],
 895     CTRL_COPYRIGHT_HEADER() => [
 896         qw(
 897             format
 898             upstream-name
 899             upstream-contact
 900             source
 901             disclaimer
 902             comment
 903             license
 904             copyright
 905         ),
 906     ],
 907     CTRL_COPYRIGHT_FILES() => [
 908         qw(
 909             files
 910             copyright
 911             license
 912             comment
 913         ),
 914     ],
 915     CTRL_COPYRIGHT_LICENSE() => [
 916         qw(
 917             license
 918             comment
 919         ),
 920     ],
 921     CTRL_FILE_BUILDINFO() => [
 922         qw(
 923             format
 924             source
 925             binary
 926             architecture
 927             version
 928             binary-only-changes
 929         ),
 930         @src_checksums_fields,
 931         qw(
 932             build-origin
 933             build-architecture
 934             build-kernel-version
 935             build-date
 936             build-path
 937             build-tainted-by
 938             installed-build-depends
 939             environment
 940         ),
 941     ],
 942     CTRL_FILE_CHANGES() => [
 943         qw(
 944             format
 945             date
 946             source
 947             binary
 948             binary-only
 949             built-for-profiles
 950             architecture
 951             version
 952             distribution
 953             urgency
 954             maintainer
 955             changed-by
 956             description
 957             closes
 958             changes
 959         ),
 960         @src_checksums_fields,
 961         qw(
 962             files
 963         ),
 964     ],
 965     CTRL_FILE_VENDOR() => [
 966         qw(
 967             vendor
 968             vendor-url
 969             bugs
 970             parent
 971         ),
 972     ],
 973     CTRL_FILE_STATUS() => [
 974         # Same as fieldinfos in lib/dpkg/parse.c
 975         qw(
 976             package
 977             essential
 978             protected
 979             status
 980             priority
 981             section
 982             installed-size
 983             origin
 984             maintainer
 985             bugs
 986             architecture
 987             multi-arch
 988             source
 989             version
 990             config-version
 991             replaces
 992             provides
 993             depends
 994             pre-depends
 995             recommends
 996             suggests
 997             breaks
 998             conflicts
 999             enhances
1000             conffiles
1001             description
1002             triggers-pending
1003             triggers-awaited
1004         ),
1005         # These are allowed here, but not tracked by lib/dpkg/parse.c.
1006         qw(
1007             auto-built-package
1008             build-essential
1009             built-for-profiles
1010             built-using
1011             static-built-using
1012             homepage
1013             installer-menu-item
1014             kernel-version
1015             package-type
1016             subarchitecture
1017             tag
1018             task
1019         ),
1020     ],
1021     CTRL_TESTS() => [
1022         qw(
1023             test-command
1024             tests
1025             tests-directory
1026             architecture
1027             restrictions
1028             features
1029             classes
1030             depends
1031         ),
1032     ],
1033 );
1034
1035 =head1 FUNCTIONS
1036
1037 =over 4
1038
1039 =item $f = field_capitalize($field_name)
1040
1041 Returns the field name properly capitalized. All characters are lowercase,
1042 except the first of each word (words are separated by a hyphen in field names).
1043
1044 =cut
1045
1046 sub field_capitalize($) {
1047     my $field = lc(shift);
1048
1049     # Use known fields first.
1050     return $FIELDS{$field}{name} if exists $FIELDS{$field};
1051
1052     # Generic case
1053     return join '-', map { ucfirst } split /-/, $field;
1054 }
1055
1056 =item $bool = field_is_official($fname)
1057
1058 Returns true if the field is official and known.
1059
1060 =cut
1061
1062 sub field_is_official($) {
1063     my $field = lc shift;
1064
1065     return exists $FIELDS{$field};
1066 }
1067
1068 =item $bool = field_is_allowed_in($fname, @types)
1069
1070 Returns true (1) if the field $fname is allowed in all the types listed in
1071 the list. Note that you can use type sets instead of individual types (ex:
1072 CTRL_FILE_CHANGES | CTRL_CHANGELOG).
1073
1074 field_allowed_in(A|B, C) returns true only if the field is allowed in C
1075 and either A or B.
1076
1077 Undef is returned for non-official fields.
1078
1079 =cut
1080
1081 sub field_is_allowed_in($@) {
1082     my ($field, @types) = @_;
1083     $field = lc $field;
1084
1085     return unless exists $FIELDS{$field};
1086
1087     return 0 if not scalar(@types);
1088     foreach my $type (@types) {
1089         next if $type == CTRL_UNKNOWN; # Always allowed
1090         return 0 unless $FIELDS{$field}{allowed} & $type;
1091     }
1092     return 1;
1093 }
1094
1095 =item $new_field = field_transfer_single($from, $to, $field)
1096
1097 If appropriate, copy the value of the field named $field taken from the
1098 $from L<Dpkg::Control> object to the $to L<Dpkg::Control> object.
1099
1100 Official fields are copied only if the field is allowed in both types of
1101 objects. Custom fields are treated in a specific manner. When the target
1102 is not among CTRL_PKG_SRC, CTRL_PKG_DEB or CTRL_FILE_CHANGES, then they
1103 are always copied as is (the X- prefix is kept). Otherwise they are not
1104 copied except if the target object matches the target destination encoded
1105 in the field name. The initial X denoting custom fields can be followed by
1106 one or more letters among "S" (Source: corresponds to CTRL_PKG_SRC), "B"
1107 (Binary: corresponds to CTRL_PKG_DEB) or "C" (Changes: corresponds to
1108 CTRL_FILE_CHANGES).
1109
1110 Returns undef if nothing has been copied or the name of the new field
1111 added to $to otherwise.
1112
1113 =cut
1114
1115 sub field_transfer_single($$;$) {
1116     my ($from, $to, $field) = @_;
1117     if (not defined $field) {
1118         warnings::warnif('deprecated',
1119             'using Dpkg::Control::Fields::field_transfer_single() with an ' .
1120             'an implicit field argument is deprecated');
1121         $field = $_;
1122     }
1123     my ($from_type, $to_type) = ($from->get_type(), $to->get_type());
1124     $field = field_capitalize($field);
1125
1126     if (field_is_allowed_in($field, $from_type, $to_type)) {
1127         $to->{$field} = $from->{$field};
1128         return $field;
1129     } elsif ($field =~ /^X([SBC]*)-/i) {
1130         my $dest = $1;
1131         if (($dest =~ /B/i and $to_type == CTRL_PKG_DEB) or
1132             ($dest =~ /S/i and $to_type == CTRL_PKG_SRC) or
1133             ($dest =~ /C/i and $to_type == CTRL_FILE_CHANGES))
1134         {
1135             my $new = $field;
1136             $new =~ s/^X([SBC]*)-//i;
1137             $to->{$new} = $from->{$field};
1138             return $new;
1139         } elsif ($to_type != CTRL_PKG_DEB and
1140                  $to_type != CTRL_PKG_SRC and
1141                  $to_type != CTRL_FILE_CHANGES)
1142         {
1143             $to->{$field} = $from->{$field};
1144             return $field;
1145         }
1146     } elsif (not field_is_allowed_in($field, $from_type)) {
1147         warning(g_("unknown information field '%s' in input data in %s"),
1148                 $field, $from->get_option('name') || g_('control information'));
1149     }
1150     return;
1151 }
1152
1153 =item @field_list = field_transfer_all($from, $to)
1154
1155 Transfer all appropriate fields from $from to $to. Calls
1156 field_transfer_single() on all fields available in $from.
1157
1158 Returns the list of fields that have been added to $to.
1159
1160 =cut
1161
1162 sub field_transfer_all($$) {
1163     my ($from, $to) = @_;
1164     my (@res, $res);
1165     foreach my $k (keys %$from) {
1166         $res = field_transfer_single($from, $to, $k);
1167         push @res, $res if $res and defined wantarray;
1168     }
1169     return @res;
1170 }
1171
1172 =item @field_list = field_ordered_list($type)
1173
1174 Returns an ordered list of fields for a given type of control information.
1175 This list can be used to output the fields in a predictable order.
1176 The list might be empty for types where the order does not matter much.
1177
1178 =cut
1179
1180 sub field_ordered_list($) {
1181     my $type = shift;
1182
1183     if (exists $FIELD_ORDER{$type}) {
1184         return map { $FIELDS{$_}{name} } @{$FIELD_ORDER{$type}};
1185     }
1186     return ();
1187 }
1188
1189 =item ($source, $version) = field_parse_binary_source($ctrl)
1190
1191 Parse the B<Source> field in a binary package control stanza. The field
1192 contains the source package name where it was built from, and optionally
1193 a space and the source version enclosed in parenthesis if it is different
1194 from the binary version.
1195
1196 Returns a list with the $source name, and the source $version, or undef
1197 or an empty list when $ctrl does not contain a binary package control stanza.
1198 Neither $source nor $version are validated, but that can be done with
1199 Dpkg::Package::pkg_name_is_illegal() and Dpkg::Version::version_check().
1200
1201 =cut
1202
1203 sub field_parse_binary_source($) {
1204     my $ctrl = shift;
1205     my $ctrl_type = $ctrl->get_type();
1206
1207     if ($ctrl_type != CTRL_INDEX_PKG and
1208         $ctrl_type != CTRL_PKG_DEB and
1209         $ctrl_type != CTRL_FILE_CHANGES and
1210         $ctrl_type != CTRL_FILE_BUILDINFO and
1211         $ctrl_type != CTRL_FILE_STATUS) {
1212         return;
1213     }
1214
1215     my ($source, $version);
1216
1217     # For .changes and .buildinfo the Source field always exists,
1218     # and there is no Package field.
1219     if (exists $ctrl->{'Source'}) {
1220         $source = $ctrl->{'Source'};
1221         if ($source =~ m/^([^ ]+) +\(([^)]*)\)$/) {
1222             $source = $1;
1223             $version = $2;
1224         } else {
1225             $version = $ctrl->{'Version'};
1226         }
1227     } else {
1228         $source = $ctrl->{'Package'};
1229         $version = $ctrl->{'Version'};
1230     }
1231
1232     return ($source, $version);
1233 }
1234
1235 =item @field_list = field_list_src_dep()
1236
1237 List of fields that contains dependencies-like information in a source
1238 Debian package.
1239
1240 =cut
1241
1242 sub field_list_src_dep() {
1243     my @list = map {
1244         $FIELDS{$_}{name}
1245     } sort {
1246         $FIELDS{$a}{dep_order} <=> $FIELDS{$b}{dep_order}
1247     } grep {
1248         field_is_allowed_in($_, CTRL_PKG_SRC) and
1249         exists $FIELDS{$_}{dependency}
1250     } keys %FIELDS;
1251     return @list;
1252 }
1253
1254 =item @field_list = field_list_pkg_dep()
1255
1256 List of fields that contains dependencies-like information in a binary
1257 Debian package. The fields that express real dependencies are sorted from
1258 the stronger to the weaker.
1259
1260 =cut
1261
1262 sub field_list_pkg_dep() {
1263     my @list = map {
1264         $FIELDS{$_}{name}
1265     } sort {
1266         $FIELDS{$a}{dep_order} <=> $FIELDS{$b}{dep_order}
1267     } grep {
1268         field_is_allowed_in($_, CTRL_PKG_DEB) and
1269         exists $FIELDS{$_}{dependency}
1270     } keys %FIELDS;
1271     return @list;
1272 }
1273
1274 =item $dep_type = field_get_dep_type($field)
1275
1276 Return the type of the dependency expressed by the given field. Can
1277 either be "normal" for a real dependency field (Pre-Depends, Depends, ...)
1278 or "union" for other relation fields sharing the same syntax (Conflicts,
1279 Breaks, ...). Returns undef for fields which are not dependencies.
1280
1281 =cut
1282
1283 sub field_get_dep_type($) {
1284     my $field = lc shift;
1285
1286     return unless exists $FIELDS{$field};
1287     return $FIELDS{$field}{dependency} if exists $FIELDS{$field}{dependency};
1288     return;
1289 }
1290
1291 =item $sep_type = field_get_sep_type($field)
1292
1293 Return the type of the field value separator. Can be one of FIELD_SEP_UNKNOWN,
1294 FIELD_SEP_SPACE, FIELD_SEP_COMMA or FIELD_SEP_LINE.
1295
1296 =cut
1297
1298 sub field_get_sep_type($) {
1299     my $field = lc shift;
1300
1301     return $FIELDS{$field}{separator} if exists $FIELDS{$field}{separator};
1302     return FIELD_SEP_UNKNOWN;
1303 }
1304
1305 =item field_register($field, $allowed_types, %opts)
1306
1307 Register a new field as being allowed in control information of specified
1308 types. %opts is optional.
1309
1310 =cut
1311
1312 sub field_register($$;@) {
1313     my ($field, $types, %opts) = @_;
1314
1315     $field = lc $field;
1316     $FIELDS{$field} = {
1317         name => field_capitalize($field),
1318         allowed => $types,
1319         %opts
1320     };
1321
1322     return;
1323 }
1324
1325 =item $bool = field_insert_after($type, $ref, @fields)
1326
1327 Place field after another one ($ref) in output of control information of
1328 type $type.
1329
1330 Return true if the field was inserted, otherwise false.
1331
1332 =cut
1333
1334 sub field_insert_after($$@) {
1335     my ($type, $field, @fields) = @_;
1336
1337     return 0 if not exists $FIELD_ORDER{$type};
1338
1339     ($field, @fields) = map { lc } ($field, @fields);
1340     @{$FIELD_ORDER{$type}} = map {
1341         ($_ eq $field) ? ($_, @fields) : $_
1342     } @{$FIELD_ORDER{$type}};
1343
1344     return 1;
1345 }
1346
1347 =item $bool = field_insert_before($type, $ref, @fields)
1348
1349 Place field before another one ($ref) in output of control information of
1350 type $type.
1351
1352 Return true if the field was inserted, otherwise false.
1353
1354 =cut
1355
1356 sub field_insert_before($$@) {
1357     my ($type, $field, @fields) = @_;
1358
1359     return 0 if not exists $FIELD_ORDER{$type};
1360
1361     ($field, @fields) = map { lc } ($field, @fields);
1362     @{$FIELD_ORDER{$type}} = map {
1363         ($_ eq $field) ? (@fields, $_) : $_
1364     } @{$FIELD_ORDER{$type}};
1365
1366     return 1;
1367 }
1368
1369 =back
1370
1371 =head1 CHANGES
1372
1373 =head2 Version 1.02 (dpkg 1.22.0)
1374
1375 Deprecate argument: field_transfer_single() implicit argument usage.
1376
1377 =head2 Version 1.01 (dpkg 1.21.0)
1378
1379 New function: field_parse_binary_source().
1380
1381 =head2 Version 1.00 (dpkg 1.17.0)
1382
1383 Mark the module as public.
1384
1385 =cut
1386
1387 1;