1Dpkg::Substvars(3perl)           libdpkg-perl           Dpkg::Substvars(3perl)
2
3
4

NAME

6       Dpkg::Substvars - handle variable substitution in strings
7

DESCRIPTION

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

METHODS

12       $s = Dpkg::Substvars->new($file)
13               Create a new object that can do substitutions. By default it
14               contains generic substitutions like ${Newline}, ${Space},
15               ${Tab}, ${dpkg:Version} and ${dpkg:Upstream-Version}.
16
17               Additional substitutions will be read from the $file passed as
18               parameter.
19
20               It keeps track of which substitutions were actually used (only
21               counting substvars(), not get()), and warns about unused
22               substvars when asked to. The substitutions that are always
23               present are not included in these warnings.
24
25       $s->set($key, $value)
26               Add/replace a substitution.
27
28       $s->set_as_used($key, $value)
29               Add/replace a substitution and mark it as used (no warnings
30               will be produced even if unused).
31
32       $s->set_as_auto($key, $value)
33               Add/replace a substitution and mark it as used and automatic
34               (no warnings will be produced even if unused).
35
36       $s->get($key)
37               Get the value of a given substitution.
38
39       $s->delete($key)
40               Remove a given substitution.
41
42       $s->mark_as_used($key)
43               Prevents warnings about a unused substitution, for example if
44               it is provided by default.
45
46       $s->parse($fh, $desc)
47               Add new substitutions read from the filehandle. $desc is used
48               to identify the filehandle in error messages.
49
50               Returns the number of substitutions that have been parsed with
51               success.
52
53       $s->load($file)
54               Add new substitutions read from $file.
55
56       $s->set_version_substvars($sourceversion, $binaryversion)
57               Defines ${binary:Version}, ${source:Version} and
58               ${source:Upstream-Version} based on the given version strings.
59
60               These will never be warned about when unused.
61
62       $s->set_arch_substvars()
63               Defines architecture variables: ${Arch}.
64
65               This will never be warned about when unused.
66
67       $s->set_vendor_substvars()
68               Defines vendor variables: ${vendor:Name} and ${vendor:Id}.
69
70               These will never be warned about when unused.
71
72       $s->set_desc_substvars()
73               Defines source description variables: ${source:Synopsis} and
74               ${source:Extended-Description}.
75
76               These will never be warned about when unused.
77
78       $s->set_field_substvars($ctrl, $prefix)
79               Defines field variables from a Dpkg::Control object, with each
80               variable having the form "${$prefix:$field}".
81
82               They will never be warned about when unused.
83
84       $newstring = $s->substvars($string)
85               Substitutes variables in $string and return the result in
86               $newstring.
87
88       $s->warn_about_unused()
89               Issues warning about any variables that were set, but not used.
90
91       $s->set_msg_prefix($prefix)
92               Define a prefix displayed before all warnings/error messages
93               output by the module.
94
95       $s->filter(remove => $rmfunc)
96       $s->filter(keep => $keepfun)
97               Filter the substitution variables, either removing or keeping
98               all those that return true when $rmfunc->($key) or
99               $keepfunc->($key) is called.
100
101       "$s"    Return a string representation of all substitutions variables
102               except the automatic ones.
103
104       $str = $s->output([$fh])
105               Return all substitutions variables except the automatic ones.
106               If $fh is passed print them into the filehandle.
107
108       $s->save($file)
109               Store all substitutions variables except the automatic ones in
110               the indicated file.
111

CHANGES

113   Version 2.01 (dpkg 1.21.8)
114       New feature: Add support for optional substitution variables.
115
116   Version 2.00 (dpkg 1.20.0)
117       Remove method: $s->no_warn().
118
119       New method: $s->set_vendor_substvars().
120
121   Version 1.06 (dpkg 1.19.0)
122       New method: $s->set_desc_substvars().
123
124   Version 1.05 (dpkg 1.18.11)
125       Obsolete substvar: Emit an error on Source-Version substvar usage.
126
127       New return: $s->parse() now returns the number of parsed substvars.
128
129       New method: $s->set_field_substvars().
130
131   Version 1.04 (dpkg 1.18.0)
132       New method: $s->filter().
133
134   Version 1.03 (dpkg 1.17.11)
135       New method: $s->set_as_auto().
136
137   Version 1.02 (dpkg 1.16.5)
138       New argument: Accept a $binaryversion in $s->set_version_substvars(),
139       passing a single argument is still supported.
140
141       New method: $s->mark_as_used().
142
143       Deprecated method: $s->no_warn(), use $s->mark_as_used() instead.
144
145   Version 1.01 (dpkg 1.16.4)
146       New method: $s->set_as_used().
147
148   Version 1.00 (dpkg 1.15.6)
149       Mark the module as public.
150
151
152
1531.21.21                           2023-07-19            Dpkg::Substvars(3perl)