---
name: "Dpkg::Substvars"
section: "3"
platform: "linux"
package: "libdpkg-perl"
version: "1.18.25"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/Dpkg::Substvars"
---

# Dpkg::Substvars(3)

handle variable substitution in strings

## NAME

Dpkg::Substvars - handle variable substitution in strings

## DESCRIPTION

It provides some an object which is able to substitute variables in strings.

## METHODS

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

  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.

- $s-\>set($key, $value)

  Add/replace a substitution.

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

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

- $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).

- $s-\>get($key)

  Get the value of a given substitution.

- $s-\>delete($key)

  Remove a given substitution.

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

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

- $s-\>no\_warn($key)

  Obsolete function, use *mark\_as\_used()* instead.

- $s-\>load($file)

  Add new substitutions read from `$file`.

- $s-\>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.

- $s-\>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.

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

  Defines architecture variables: ${Arch}.

  This will never be warned about when unused.

- $s-\>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.

- $newstring = $s-\>substvars($string)

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

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

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

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

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

- $s-\>filter(remove =\> $rmfunc)

  - $s-\>filter(keep =\> $keepfun)

  Filter the substitution variables, either removing or keeping all those that return true when `$rmfunc`-\>($key) or `$keepfunc`-\>($key) is called.

- $s-\>save($file)

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

- "$s"

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

- $str = $s-\>output($fh)

  Print all substitutions variables except the automatic ones in the filehandle and return the content written.

## CHANGES

### Version 1.05 (dpkg 1.18.11)

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

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

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

### Version 1.04 (dpkg 1.18.0)

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

### Version 1.03 (dpkg 1.17.11)

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

### Version 1.02 (dpkg 1.16.5)

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

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

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

### Version 1.01 (dpkg 1.16.4)

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

### Version 1.00 (dpkg 1.15.6)

Mark the module as public.