Dpkg::Substvars(3perl)

💖 NAME 💖

okay so bestie, welcome to Dpkg::Substvars — the libdpkg-perl module that literally handles variable substitution in strings. that's it, that's the whole vibe. ✨

---

🦋 DESCRIPTION 🦋

it gives you a class that is able to substitute variables in strings. no cap. that's literally its whole job and it does it beautifully. 💅

---

🎀 METHODS 🎀

• $sv = Dpkg::Substvars->new($file) — creates a brand new object that can do substitutions. by default it comes pre-loaded with generic substitutions like ${Newline}, ${Space}, ${Tab}, ${dpkg:Version} and ${dpkg:Upstream-Version} — like, freebies, bestie 🫶

any additional substitutions get read from the $file you pass as a parameter.

it also keeps track of which substitutions were actually used — and lowkey important: it only counts substvars(), not get() — and it warns you about unused substvars when you ask it to. the substitutions that are always present? yeah, those don't get included in these warnings. special treatment, honestly iconic. 👑

• $sv->set($key, $value) — add or replace a substitution. simple as that. ✨
• $sv->set_as_used($key, $value) — add or replace a substitution and mark it as used, so no warnings will be produced even if it's unused. we love a pre-cleared alibi. 🙈
• $sv->set_as_auto($key, $value) — add or replace a substitution and mark it as used and automatic (again, no warnings even if unused) — but here's the twist: it will not be emitted into the substvars file. main character energy, refuses to be seen in the file. 💀
• $sv->set_as_optional($key, $value) — add or replace a substitution and mark it as used and optional (no warnings will be produced even if unused). chill vibes only. 🌸
• $sv->set_as_required($key, $value) — add or replace a substitution and mark it as required. and bestie, listen: an error will be produced if it is not used. this one is not playing around. 🔥
• $sv->set_as_implicit($key, $value) — add or replace a substitution and mark it as implicit, where a field will be automatically instantiated if not already present. sneaky but helpful. 🧚
• $value = $sv->get($key) — get the value of a given substitution. (remember, this does not count as "used" — iykyk 👀)
• $value = $sv->delete($key) — remove a given substitution. bye bestie 💜
• $sv->mark_as_used($key) — prevents warnings about an unused substitution, like for example if it's provided by default. basically "she's fine, she's with me." 🫶
• $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. slay, a countable result. ⭐

• $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. protected status. 🛡️

• $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. fancy 💅

• @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 returns the result in $newstring. this is the one that counts for usage tracking, don't forget 😭
• $sv->warn_about_unused() — issues warnings about any variables that were set, but not used. the vibe check, basically. 💀
• $sv->set_msg_prefix($prefix) — defines a prefix displayed before all warnings/error messages output by the module.
• $sv->filter(%opts) — filters 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" — returns a string representation of all substitutions variables except the automatic ones.
• $string = $sv->output([$fh]) — returns all substitutions variables except the automatic ones. if $fh is passed, prints them into the filehandle.
• $sv->save($file) — stores all substitutions variables except the automatic ones in the indicated file. saving the non-auto girlies to disk, periodt. 💾

---

🌈 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. (she's old news, bestie — use the new one 🙈)

🌟 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. it's official, she's out in the world 💖

---

okay that's the whole page bestie, go substitute some variables and slay 💅

and that's a wrap! this page is from libdpkg-perl, version 1.23.11-dirty, dated 2026-09-09 — mwah, ty for reading, ily, bye 🫶🌈💜