---
name: "Dpkg::Substvars"
section: "3perl"
platform: "linux"
package: "dpkg"
version: "1.23.11-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Dpkg::Substvars/3perl"
---

# Dpkg::Substvars(3perl)

handle variable substitution in strings

## NAME

Dpkg::Substvars - handle variable substitution in strings

## DESCRIPTION

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

## 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**

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

  - **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

### Version 2.04 (dpkg 1.23.0)

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)

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

### Version 2.02 (dpkg 1.22.7)

New feature: Add support for required substitution variables.

### Version 2.01 (dpkg 1.21.8)

New feature: Add support for optional substitution variables.

### Version 2.00 (dpkg 1.20.0)

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

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

### Version 1.06 (dpkg 1.19.0)

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

### Version 1.05 (dpkg 1.18.11)

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)

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

### Version 1.03 (dpkg 1.17.11)

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

### Version 1.02 (dpkg 1.16.5)

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)

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

### Version 1.00 (dpkg 1.15.6)

Mark the module as public.