.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dpkg::Control::FieldsCore 3perl"
.TH Dpkg::Control::FieldsCore 3perl 2024-01-19 1.22.3 libdpkg-perl
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Dpkg::Control::FieldsCore \- manage (list of official) control fields
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The modules contains a list of field names with associated meta-data explaining
in which type of control information they are allowed. The types are the
CTRL_* constants exported by Dpkg::Control.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .IP "$f = field_capitalize($field_name)" 4
.el .IP "\f(CW$f\fR = field_capitalize($field_name)" 4
.IX Item "$f = field_capitalize($field_name)"
Returns the field name properly capitalized. All characters are lowercase,
except the first of each word (words are separated by a hyphen in field names).
.ie n .IP "$bool = field_is_official($fname)" 4
.el .IP "\f(CW$bool\fR = field_is_official($fname)" 4
.IX Item "$bool = field_is_official($fname)"
Returns true if the field is official and known.
.ie n .IP "$bool = field_is_allowed_in($fname, @types)" 4
.el .IP "\f(CW$bool\fR = field_is_allowed_in($fname, \f(CW@types\fR)" 4
.IX Item "$bool = field_is_allowed_in($fname, @types)"
Returns true (1) if the field \f(CW$fname\fR is allowed in all the types listed in
the list. Note that you can use type sets instead of individual types (ex:
CTRL_FILE_CHANGES | CTRL_CHANGELOG).
.Sp
field_allowed_in(A|B, C) returns true only if the field is allowed in C
and either A or B.
.Sp
Undef is returned for non-official fields.
.ie n .IP "$new_field = field_transfer_single($from, $to, $field)" 4
.el .IP "\f(CW$new_field\fR = field_transfer_single($from, \f(CW$to\fR, \f(CW$field\fR)" 4
.IX Item "$new_field = field_transfer_single($from, $to, $field)"
If appropriate, copy the value of the field named \f(CW$field\fR taken from the
\&\f(CW$from\fR Dpkg::Control object to the \f(CW$to\fR Dpkg::Control object.
.Sp
Official fields are copied only if the field is allowed in both types of
objects. Custom fields are treated in a specific manner. When the target
is not among CTRL_DSC, CTRL_DEB or CTRL_FILE_CHANGES, then they
are always copied as is (the X\- prefix is kept). Otherwise they are not
copied except if the target object matches the target destination encoded
in the field name. The initial X denoting custom fields can be followed by
one or more letters among "S" (Source: corresponds to CTRL_DSC), "B"
(Binary: corresponds to CTRL_DEB) or "C" (Changes: corresponds to
CTRL_FILE_CHANGES).
.Sp
Returns undef if nothing has been copied or the name of the new field
added to \f(CW$to\fR otherwise.
.ie n .IP "@field_list = field_transfer_all($from, $to)" 4
.el .IP "\f(CW@field_list\fR = field_transfer_all($from, \f(CW$to\fR)" 4
.IX Item "@field_list = field_transfer_all($from, $to)"
Transfer all appropriate fields from \f(CW$from\fR to \f(CW$to\fR. Calls
\&\fBfield_transfer_single()\fR on all fields available in \f(CW$from\fR.
.Sp
Returns the list of fields that have been added to \f(CW$to\fR.
.ie n .IP "@field_list = field_ordered_list($type)" 4
.el .IP "\f(CW@field_list\fR = field_ordered_list($type)" 4
.IX Item "@field_list = field_ordered_list($type)"
Returns an ordered list of fields for a given type of control information.
This list can be used to output the fields in a predictable order.
The list might be empty for types where the order does not matter much.
.ie n .IP "($source, $version) = field_parse_binary_source($ctrl)" 4
.el .IP "($source, \f(CW$version\fR) = field_parse_binary_source($ctrl)" 4
.IX Item "($source, $version) = field_parse_binary_source($ctrl)"
Parse the \fBSource\fR field in a binary package control stanza. The field
contains the source package name where it was built from, and optionally
a space and the source version enclosed in parenthesis if it is different
from the binary version.
.Sp
Returns a list with the \f(CW$source\fR name, and the source \f(CW$version\fR, or undef
or an empty list when \f(CW$ctrl\fR does not contain a binary package control stanza.
Neither \f(CW$source\fR nor \f(CW$version\fR are validated, but that can be done with
\&\fBDpkg::Package::pkg_name_is_illegal()\fR and \fBDpkg::Version::version_check()\fR.
.ie n .IP "@field_list = \fBfield_list_src_dep()\fR" 4
.el .IP "\f(CW@field_list\fR = \fBfield_list_src_dep()\fR" 4
.IX Item "@field_list = field_list_src_dep()"
List of fields that contains dependencies-like information in a source
Debian package.
.ie n .IP "@field_list = \fBfield_list_pkg_dep()\fR" 4
.el .IP "\f(CW@field_list\fR = \fBfield_list_pkg_dep()\fR" 4
.IX Item "@field_list = field_list_pkg_dep()"
List of fields that contains dependencies-like information in a binary
Debian package. The fields that express real dependencies are sorted from
the stronger to the weaker.
.ie n .IP "$dep_type = field_get_dep_type($field)" 4
.el .IP "\f(CW$dep_type\fR = field_get_dep_type($field)" 4
.IX Item "$dep_type = field_get_dep_type($field)"
Return the type of the dependency expressed by the given field. Can
either be "normal" for a real dependency field (Pre-Depends, Depends, ...)
or "union" for other relation fields sharing the same syntax (Conflicts,
Breaks, ...). Returns undef for fields which are not dependencies.
.ie n .IP "$sep_type = field_get_sep_type($field)" 4
.el .IP "\f(CW$sep_type\fR = field_get_sep_type($field)" 4
.IX Item "$sep_type = field_get_sep_type($field)"
Return the type of the field value separator. Can be one of FIELD_SEP_UNKNOWN,
FIELD_SEP_SPACE, FIELD_SEP_COMMA or FIELD_SEP_LINE.
.ie n .IP "field_register($field, $allowed_types, %opts)" 4
.el .IP "field_register($field, \f(CW$allowed_types\fR, \f(CW%opts\fR)" 4
.IX Item "field_register($field, $allowed_types, %opts)"
Register a new field as being allowed in control information of specified
types. \f(CW%opts\fR is optional.
.ie n .IP "$bool = field_insert_after($type, $ref, @fields)" 4
.el .IP "\f(CW$bool\fR = field_insert_after($type, \f(CW$ref\fR, \f(CW@fields\fR)" 4
.IX Item "$bool = field_insert_after($type, $ref, @fields)"
Place field after another one ($ref) in output of control information of
type \f(CW$type\fR.
.Sp
Return true if the field was inserted, otherwise false.
.ie n .IP "$bool = field_insert_before($type, $ref, @fields)" 4
.el .IP "\f(CW$bool\fR = field_insert_before($type, \f(CW$ref\fR, \f(CW@fields\fR)" 4
.IX Item "$bool = field_insert_before($type, $ref, @fields)"
Place field before another one ($ref) in output of control information of
type \f(CW$type\fR.
.Sp
Return true if the field was inserted, otherwise false.
.SH CHANGES
.IX Header "CHANGES"
.SS "Version 1.02 (dpkg 1.22.0)"
.IX Subsection "Version 1.02 (dpkg 1.22.0)"
Deprecate argument: \fBfield_transfer_single()\fR implicit argument usage.
.SS "Version 1.01 (dpkg 1.21.0)"
.IX Subsection "Version 1.01 (dpkg 1.21.0)"
New function: \fBfield_parse_binary_source()\fR.
.SS "Version 1.00 (dpkg 1.17.0)"
.IX Subsection "Version 1.00 (dpkg 1.17.0)"
Mark the module as public.