Dpkg::Substvars(3perl) libdpkg-perl Dpkg::Substvars(3perl)

# [NAME](#NAME)

Dpkg::Substvars - handle variable substitution in strings

# [DESCRIPTION](#DESCRIPTION)

It provides a class which is able to substitute variables in strings.

# [METHODS](#METHODS)

$sv = 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}.

Additional substitutions will be read from the $file passed as parameter.

It keeps track of which substitutions were actually used (only counting **substvars()**, not **get()**), and warns about unused substvars when asked to. The substitutions that are always present are not included in these warnings.

$sv->set($key, $value)

Add/replace a substitution.

$sv->set\_as\_used($key, $value)

Add/replace a substitution and mark it as used (no warnings will be produced even if unused).

$sv->set\_as\_auto($key, $value)

Add/replace a substitution and mark it as used and automatic (no warnings will be produced even if unused), and will not be emitted into the substvars file.

$sv->set\_as\_optional($key, $value)

Add/replace a substitution and mark it as used and optional (no warnings will be produced even if unused).

$sv->set\_as\_required($key, $value)

Add/replace a substitution and mark it as required (an error will be produced if it is not used).

$sv->set\_as\_implicit($key, $value)

Add/replace a substitution and mark it as implicit, where a field will be automatically instantiated if not already present.

$value = $sv->get($key)

Get the value of a given substitution.

$value = $sv->delete($key)

Remove a given substitution.

$sv->mark\_as\_used($key)

Prevents warnings about a unused substitution, for example if it is provided by default.

$count = $sv->parse($fh, $desc)

Add new substitutions read from the filehandle. $desc is used to identify the filehandle in error messages.

Returns the number of substitutions that have been parsed with success.

$sv->load($file)

Add new substitutions read from $file.

$sv->set\_version\_substvars($sourceversion, $binaryversion)

Defines ${binary:Version}, ${source:Version} and ${source:Upstream-Version} based on the given version strings.

These will never be warned about when unused.

$sv->**set\_arch\_substvars()**

Defines architecture variables: ${Arch}.

This will never be warned about when unused.

$sv->**set\_vendor\_substvars()**

Defines vendor variables: ${vendor:Name} and ${vendor:Id}.

These will never be warned about when unused.

$sv->**set\_desc\_substvars()**

Defines source description variables: ${source:Synopsis} and ${source:Extended-Description}.

These will never be warned about when unused.

$sv->set\_field\_substvars($ctrl, $prefix)

Defines field variables from a Dpkg::Control object, with each variable having the form "${$prefix:$field}".

They will never be warned about when unused.

@substvars = $sv->**get\_implicit\_substvars()**

Returns a list of implicit substitution variables to be used by the calling program, by appending them to specific text.

$newstring = $sv->substvars($string)

Substitutes variables in $string and return the result in $newstring.

$sv->**warn\_about\_unused()**

Issues warning about any variables that were set, but not used.

$sv->set\_msg\_prefix($prefix)

Define a prefix displayed before all warnings/error messages output by the module.

$sv->filter(%opts)

Filter the substitution variables.

Options:

[**remove**](#remove)

A function returning a boolean, used to decide whether to remove a substitution variable, executed as $opts{remove}->($var).

[**keep**](#keep)

A function returning a boolean, used to decide whether to keep the substitution variable, executed as $opts{keep}->($var).

$string = "$sv"

Return a string representation of all substitutions variables except the automatic ones.

$string = $sv->output(\[$fh])

Return all substitutions variables except the automatic ones. If $fh is passed print them into the filehandle.

$sv->save($file)

Store all substitutions variables except the automatic ones in the indicated file.

# [CHANGES](#CHANGES)

## [Version 2.04 (dpkg 1.23.0)](#Version_2.04_%28dpkg_1.23.0%29)

New feature: Add support for implicit substitution variables.

New method: $sv->**set\_as\_implicit()**, $sv->**get\_implicit\_substvars()**.

## [Version 2.03 (dpkg 1.22.15)](#Version_2.03_%28dpkg_1.22.15%29)

New methods: $sv->**set\_as\_optional()**, $sv->**set\_as\_required()**.

## [Version 2.02 (dpkg 1.22.7)](#Version_2.02_%28dpkg_1.22.7%29)

New feature: Add support for required substitution variables.

## [Version 2.01 (dpkg 1.21.8)](#Version_2.01_%28dpkg_1.21.8%29)

New feature: Add support for optional substitution variables.

## [Version 2.00 (dpkg 1.20.0)](#Version_2.00_%28dpkg_1.20.0%29)

Remove method: $sv->**no\_warn()**.

New method: $sv->**set\_vendor\_substvars()**.

## [Version 1.06 (dpkg 1.19.0)](#Version_1.06_%28dpkg_1.19.0%29)

New method: $sv->**set\_desc\_substvars()**.

## [Version 1.05 (dpkg 1.18.11)](#Version_1.05_%28dpkg_1.18.11%29)

Obsolete substvar: Emit an error on Source-Version substvar usage.

New return: $sv->**parse()** now returns the number of parsed substvars.

New method: $sv->**set\_field\_substvars()**.

## [Version 1.04 (dpkg 1.18.0)](#Version_1.04_%28dpkg_1.18.0%29)

New method: $sv->**filter()**.

## [Version 1.03 (dpkg 1.17.11)](#Version_1.03_%28dpkg_1.17.11%29)

New method: $sv->**set\_as\_auto()**.

## [Version 1.02 (dpkg 1.16.5)](#Version_1.02_%28dpkg_1.16.5%29)

New argument: Accept a $binaryversion in $sv->**set\_version\_substvars()**, passing a single argument is still supported.

New method: $sv->**mark\_as\_used()**.

Deprecated method: $sv->**no\_warn()**, use $sv->**mark\_as\_used()** instead.

## [Version 1.01 (dpkg 1.16.4)](#Version_1.01_%28dpkg_1.16.4%29)

New method: $sv->**set\_as\_used()**.

## [Version 1.00 (dpkg 1.15.6)](#Version_1.00_%28dpkg_1.15.6%29)

Mark the module as public.

2026-09-09 1.23.11-dirty

---

Document: Dpkg::Substvars(3perl) from dpkg 1.23.11-r1 (Chainguard OS)
Source: https://git.dpkg.org/git/dpkg/dpkg.git