.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Dpkg::Substvars 3"
.TH Dpkg::Substvars 3 "2017-05-17" "1.18.24" "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 some an object 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
\&\fIsubstvars()\fR, not \fIget()\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\->no_warn($key)" 8
.el .IP "\f(CW$s\fR\->no_warn($key)" 8
.IX Item "$s->no_warn($key)"
Obsolete function, use \fImark_as_used()\fR instead.
.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\->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\->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\->\fIset_arch_substvars()\fR" 8
.el .IP "\f(CW$s\fR\->\fIset_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\->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\->\fIwarn_about_unused()\fR" 8
.el .IP "\f(CW$s\fR\->\fIwarn_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\->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.
.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)"
Print all substitutions variables except the automatic ones in the
filehandle and return the content written.
.SH "CHANGES"
.IX Header "CHANGES"
.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\->\fIparse()\fR now returns the number of parsed substvars.
.PP
New method: \f(CW$s\fR\->\fIset_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\->\fIfilter()\fR.
.SS "Version 1.03 (dpkg 1.17.11)"
.IX Subsection "Version 1.03 (dpkg 1.17.11)"
New method: \f(CW$s\fR\->\fIset_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\->\fIset_version_substvars()\fR,
passing a single argument is still supported.
.PP
New method: \f(CW$s\fR\->\fImark_as_used()\fR.
.PP
Deprecated method: \f(CW$s\fR\->\fIno_warn()\fR, use \f(CW$s\fR\->\fImark_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\->\fIset_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.