.\" Automatically generated by Pod::Man 4.14 (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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Substvars 3perl"
.TH Dpkg::Substvars 3perl "2023-05-11" "1.21.22" "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::Substvars \- handle variable substitution in strings
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
It provides a class which is able to substitute variables in strings.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$s = Dpkg::Substvars\->new($file)" 8
.el .IP "\f(CW$s\fR = Dpkg::Substvars\->new($file)" 8
.IX Item "$s = Dpkg::Substvars->new($file)"
Create a new object that can do substitutions. By default it contains
generic substitutions like ${Newline}, ${Space}, ${Tab}, ${dpkg:Version}
and ${dpkg:Upstream\-Version}.
.Sp
Additional substitutions will be read from the \f(CW$file\fR passed as parameter.
.Sp
It keeps track of which substitutions were actually used (only counting
\&\fBsubstvars()\fR, not \fBget()\fR), and warns about unused substvars when asked to. The
substitutions that are always present are not included in these warnings.
.ie n .IP "$s\->set($key, $value)" 8
.el .IP "\f(CW$s\fR\->set($key, \f(CW$value\fR)" 8
.IX Item "$s->set($key, $value)"
Add/replace a substitution.
.ie n .IP "$s\->set_as_used($key, $value)" 8
.el .IP "\f(CW$s\fR\->set_as_used($key, \f(CW$value\fR)" 8
.IX Item "$s->set_as_used($key, $value)"
Add/replace a substitution and mark it as used (no warnings will be produced
even if unused).
.ie n .IP "$s\->set_as_auto($key, $value)" 8
.el .IP "\f(CW$s\fR\->set_as_auto($key, \f(CW$value\fR)" 8
.IX Item "$s->set_as_auto($key, $value)"
Add/replace a substitution and mark it as used and automatic (no warnings
will be produced even if unused).
.ie n .IP "$s\->get($key)" 8
.el .IP "\f(CW$s\fR\->get($key)" 8
.IX Item "$s->get($key)"
Get the value of a given substitution.
.ie n .IP "$s\->delete($key)" 8
.el .IP "\f(CW$s\fR\->delete($key)" 8
.IX Item "$s->delete($key)"
Remove a given substitution.
.ie n .IP "$s\->mark_as_used($key)" 8
.el .IP "\f(CW$s\fR\->mark_as_used($key)" 8
.IX Item "$s->mark_as_used($key)"
Prevents warnings about a unused substitution, for example if it is provided by
default.
.ie n .IP "$s\->parse($fh, $desc)" 8
.el .IP "\f(CW$s\fR\->parse($fh, \f(CW$desc\fR)" 8
.IX Item "$s->parse($fh, $desc)"
Add new substitutions read from the filehandle. \f(CW$desc\fR is used to identify
the filehandle in error messages.
.Sp
Returns the number of substitutions that have been parsed with success.
.ie n .IP "$s\->load($file)" 8
.el .IP "\f(CW$s\fR\->load($file)" 8
.IX Item "$s->load($file)"
Add new substitutions read from \f(CW$file\fR.
.ie n .IP "$s\->set_version_substvars($sourceversion, $binaryversion)" 8
.el .IP "\f(CW$s\fR\->set_version_substvars($sourceversion, \f(CW$binaryversion\fR)" 8
.IX Item "$s->set_version_substvars($sourceversion, $binaryversion)"
Defines ${binary:Version}, ${source:Version} and
${source:Upstream\-Version} based on the given version strings.
.Sp
These will never be warned about when unused.
.ie n .IP "$s\->\fBset_arch_substvars()\fR" 8
.el .IP "\f(CW$s\fR\->\fBset_arch_substvars()\fR" 8
.IX Item "$s->set_arch_substvars()"
Defines architecture variables: ${Arch}.
.Sp
This will never be warned about when unused.
.ie n .IP "$s\->\fBset_vendor_substvars()\fR" 8
.el .IP "\f(CW$s\fR\->\fBset_vendor_substvars()\fR" 8
.IX Item "$s->set_vendor_substvars()"
Defines vendor variables: ${vendor:Name} and ${vendor:Id}.
.Sp
These will never be warned about when unused.
.ie n .IP "$s\->\fBset_desc_substvars()\fR" 8
.el .IP "\f(CW$s\fR\->\fBset_desc_substvars()\fR" 8
.IX Item "$s->set_desc_substvars()"
Defines source description variables: ${source:Synopsis} and
${source:Extended\-Description}.
.Sp
These will never be warned about when unused.
.ie n .IP "$s\->set_field_substvars($ctrl, $prefix)" 8
.el .IP "\f(CW$s\fR\->set_field_substvars($ctrl, \f(CW$prefix\fR)" 8
.IX Item "$s->set_field_substvars($ctrl, $prefix)"
Defines field variables from a Dpkg::Control object, with each variable
having the form \*(L"${$prefix:$field}\*(R".
.Sp
They will never be warned about when unused.
.ie n .IP "$newstring = $s\->substvars($string)" 8
.el .IP "\f(CW$newstring\fR = \f(CW$s\fR\->substvars($string)" 8
.IX Item "$newstring = $s->substvars($string)"
Substitutes variables in \f(CW$string\fR and return the result in \f(CW$newstring\fR.
.ie n .IP "$s\->\fBwarn_about_unused()\fR" 8
.el .IP "\f(CW$s\fR\->\fBwarn_about_unused()\fR" 8
.IX Item "$s->warn_about_unused()"
Issues warning about any variables that were set, but not used.
.ie n .IP "$s\->set_msg_prefix($prefix)" 8
.el .IP "\f(CW$s\fR\->set_msg_prefix($prefix)" 8
.IX Item "$s->set_msg_prefix($prefix)"
Define a prefix displayed before all warnings/error messages output
by the module.
.ie n .IP "$s\->filter(remove => $rmfunc)" 8
.el .IP "\f(CW$s\fR\->filter(remove => \f(CW$rmfunc\fR)" 8
.IX Item "$s->filter(remove => $rmfunc)"
.PD 0
.ie n .IP "$s\->filter(keep => $keepfun)" 8
.el .IP "\f(CW$s\fR\->filter(keep => \f(CW$keepfun\fR)" 8
.IX Item "$s->filter(keep => $keepfun)"
.PD
Filter the substitution variables, either removing or keeping all those
that return true when \f(CW$rmfunc\fR\->($key) or \f(CW$keepfunc\fR\->($key) is called.
.ie n .IP """$s""" 8
.el .IP "``$s''" 8
.IX Item "$s"
Return a string representation of all substitutions variables except the
automatic ones.
.ie n .IP "$str = $s\->output([$fh])" 8
.el .IP "\f(CW$str\fR = \f(CW$s\fR\->output([$fh])" 8
.IX Item "$str = $s->output([$fh])"
Return all substitutions variables except the automatic ones. If \f(CW$fh\fR
is passed print them into the filehandle.
.ie n .IP "$s\->save($file)" 8
.el .IP "\f(CW$s\fR\->save($file)" 8
.IX Item "$s->save($file)"
Store all substitutions variables except the automatic ones in the
indicated file.
.SH "CHANGES"
.IX Header "CHANGES"
.SS "Version 2.01 (dpkg 1.21.8)"
.IX Subsection "Version 2.01 (dpkg 1.21.8)"
New feature: Add support for optional substitution variables.
.SS "Version 2.00 (dpkg 1.20.0)"
.IX Subsection "Version 2.00 (dpkg 1.20.0)"
Remove method: \f(CW$s\fR\->\fBno_warn()\fR.
.PP
New method: \f(CW$s\fR\->\fBset_vendor_substvars()\fR.
.SS "Version 1.06 (dpkg 1.19.0)"
.IX Subsection "Version 1.06 (dpkg 1.19.0)"
New method: \f(CW$s\fR\->\fBset_desc_substvars()\fR.
.SS "Version 1.05 (dpkg 1.18.11)"
.IX Subsection "Version 1.05 (dpkg 1.18.11)"
Obsolete substvar: Emit an error on Source-Version substvar usage.
.PP
New return: \f(CW$s\fR\->\fBparse()\fR now returns the number of parsed substvars.
.PP
New method: \f(CW$s\fR\->\fBset_field_substvars()\fR.
.SS "Version 1.04 (dpkg 1.18.0)"
.IX Subsection "Version 1.04 (dpkg 1.18.0)"
New method: \f(CW$s\fR\->\fBfilter()\fR.
.SS "Version 1.03 (dpkg 1.17.11)"
.IX Subsection "Version 1.03 (dpkg 1.17.11)"
New method: \f(CW$s\fR\->\fBset_as_auto()\fR.
.SS "Version 1.02 (dpkg 1.16.5)"
.IX Subsection "Version 1.02 (dpkg 1.16.5)"
New argument: Accept a \f(CW$binaryversion\fR in \f(CW$s\fR\->\fBset_version_substvars()\fR,
passing a single argument is still supported.
.PP
New method: \f(CW$s\fR\->\fBmark_as_used()\fR.
.PP
Deprecated method: \f(CW$s\fR\->\fBno_warn()\fR, use \f(CW$s\fR\->\fBmark_as_used()\fR instead.
.SS "Version 1.01 (dpkg 1.16.4)"
.IX Subsection "Version 1.01 (dpkg 1.16.4)"
New method: \f(CW$s\fR\->\fBset_as_used()\fR.
.SS "Version 1.00 (dpkg 1.15.6)"
.IX Subsection "Version 1.00 (dpkg 1.15.6)"
Mark the module as public.