Debian Codegraph @

Debconf/Question.pm

raw
1 #!/usr/bin/perl
2
3 =head1 NAME
4
5 Debconf::Question - Question object
6
7 =cut
8
9 package Debconf::Question;
10 use warnings;
11 use strict;
12 use Debconf::Db;
13 use Debconf::Template;
14 use Debconf::Iterator;
15 use Debconf::Log qw(:all);
16
17 =head1 DESCRIPTION
18
19 This is a an object that represents a Question. Each Question has some
20 associated data (which is stored in a backend database). To get at this data,
21 just use $question->fieldname to read a field, and $question->fieldname(value)
22 to write a field. Any field names at all can be used, the convention is to
23 lower-case their names. If a field that is not defined is read, and a field by
24 the same name exists on the Template the Question is mapped to, the value of
25 that field will be returned instead.
26
27 =head1 FIELDS
28
29 =over 4
30
31 =item name
32
33 Holds the name of the Question.
34
35 =item priority
36
37 Holds the priority of the Question.
38
39 =back
40
41 =cut
42
43 use fields qw(name priority);
44
45 # Class data
46 our %question;
47
48 =head1 CLASS METHODS
49
50 =over 4
51
52 =item new(name, owner, type)
53
54 The name of the question to create, an owner for the question, and the
55 type of question it is must be passed to this function.
56
57 New questions default to having their seen flag set to "false".
58
59 =cut
60
61 sub new {
62 my Debconf::Question $this=shift;
63 my $name=shift;
64 my $owner=shift;
65 my $type=shift || die "no type given for question";
66 die "A question called \"$name\" already exists"
67 if exists $question{$name};
68 unless (ref $this) {
69 $this = fields::new($this);
70 }
71 $this->{name}=$name;
72 # This is what actually creates the question in the db.
73 return unless defined $this->addowner($owner, $type);
74 $this->flag('seen', 'false');
75 return $question{$name}=$this;
76 }
77
78 =item get(name)
79
80 Get an existing question. It will be pulled out of the database if
81 necessary.
82
83 =cut
84
85 sub get {
86 my Debconf::Question $this=shift;
87 my $name=shift;
88 return $question{$name} if exists $question{$name};
89 if ($Debconf::Db::config->exists($name)) {
90 $this = fields::new($this);
91 $this->{name}=$name;
92 return $question{$name}=$this;
93 }
94 return;
95 }
96
97 =item iterator
98
99 Returns an iterator object that will iterate over all existing questions,
100 returning a new question object each time it is called.
101
102 =cut
103
104 sub iterator {
105 my $this=shift;
106
107 my $real_iterator=$Debconf::Db::config->iterator;
108 return Debconf::Iterator->new(callback => sub {
109 return unless my $name=$real_iterator->iterate;
110 return $this->get($name);
111 });
112 }
113
114 =back
115
116 =head1 METHODS
117
118 =over 4
119
120 =cut
121
122 # This is a helper function that expands variables in a string.
123 sub _expand_vars {
124 my $this=shift;
125 my $text=shift;
126
127 return '' unless defined $text;
128
129 my @vars=$Debconf::Db::config->variables($this->{name});
130
131 my $rest=$text;
132 my $result='';
133 my $variable;
134 my $varval;
135 my $escape;
136 while ($rest =~ m/^(.*?)(\\)?\$\{([^{}]+)\}(.*)$/sg) {
137 $result.=$1; # copy anything before the variable
138 $escape=$2;
139 $variable=$3;
140 $rest=$4; # continue trying to expand rest of text
141 if (defined $escape && length $escape) {
142 # escaped variable is not changed, though the
143 # escape is removed.
144 $result.="\${$variable}";
145 }
146 else {
147 $varval=$Debconf::Db::config->getvariable($this->{name}, $variable);
148 $result.=$varval if defined($varval); # expand the variable
149 }
150 }
151 $result.=$rest; # add on anything that's left.
152
153 return $result;
154 }
155
156 =item description
157
158 Returns the description of this Question. This value is taken from the Template
159 the Question is mapped to, and then any substitutions in the description are
160 expanded.
161
162 =cut
163
164 sub description {
165 my $this=shift;
166 return $this->_expand_vars($this->template->description);
167 }
168
169 =item extended_description
170
171 Returns the extended description of this Question. This value is taken from the
172 Template the Question is mapped to, and then any substitutions in the extended
173 description are expanded.
174
175 =cut
176
177 sub extended_description {
178 my $this=shift;
179 return $this->_expand_vars($this->template->extended_description);
180 }
181
182 =item choices
183
184 Returns the choices field of this Question. This value is taken from the
185 Template the Question is mapped to, and then any substitutions in it
186 are expanded.
187
188 =cut
189
190 sub choices {
191 my $this=shift;
192
193 return $this->_expand_vars($this->template->choices);
194 }
195
196 =item choices_split
197
198 This takes the result of the choices method and simply splits it up into
199 individual choices and returns them as a list.
200
201 =cut
202
203 sub choices_split {
204 my $this=shift;
205
206 my @items;
207 my $item='';
208 for my $chunk (split /(\\[, ]|,\s+)/, $this->choices) {
209 if ($chunk=~/^\\([, ])$/) {
210 $item.=$1;
211 } elsif ($chunk=~/^,\s+$/) {
212 push @items, $item;
213 $item='';
214 } else {
215 $item.=$chunk;
216 }
217 }
218 push @items, $item if $item ne '';
219 return @items;
220 }
221
222 =item variable
223
224 Set/get a variable. Pass in the variable name, and an optional value to set
225 it to. The value of the variable is returned.
226
227 =cut
228
229 sub variable {
230 my $this=shift;
231 my $var=shift;
232
233 if (@_) {
234 return $Debconf::Db::config->setvariable($this->{name}, $var, shift);
235 }
236 else {
237 return $Debconf::Db::config->getvariable($this->{name}, $var);
238 }
239 }
240
241 =item flag
242
243 Set/get a flag. Pass in the flag name, and an optional value ("true" or
244 "false") to set it to. The value of the flag is returned.
245
246 =cut
247
248 sub flag {
249 my $this=shift;
250 my $flag=shift;
251
252 # This deprecated flag is now automatically mapped to the inverse of
253 # the "seen" flag.
254 if ($flag eq 'isdefault') {
255 debug developer => "The isdefault flag is deprecated, use the seen flag instead";
256 if (@_) {
257 my $value=(shift eq 'true') ? 'false' : 'true';
258 $Debconf::Db::config->setflag($this->{name}, 'seen', $value);
259 }
260 return ($Debconf::Db::config->getflag($this->{name}, 'seen') eq 'true') ? 'false' : 'true';
261 }
262
263 if (@_) {
264 return $Debconf::Db::config->setflag($this->{name}, $flag, shift);
265 }
266 else {
267 return $Debconf::Db::config->getflag($this->{name}, $flag);
268 }
269 }
270
271 =item value
272
273 Get the current value of this Question. Will return the default value
274 from the template if no value is set. Pass in parameter to set the value.
275
276 =cut
277
278 sub value {
279 my $this = shift;
280
281 unless (@_) {
282 my $ret=$Debconf::Db::config->getfield($this->{name}, 'value');
283 return $ret if defined $ret;
284 return $this->template->default if ref $this->template;
285 } else {
286 return $Debconf::Db::config->setfield($this->{name}, 'value', shift);
287 }
288 }
289
290 =item value_split
291
292 This takes the result of the value method and simply splits it up into
293 individual values and returns them as a list.
294
295 =cut
296
297 sub value_split {
298 my $this=shift;
299
300 my $value=$this->value;
301 $value='' if ! defined $value;
302 my @items;
303 my $item='';
304 for my $chunk (split /(\\[, ]|,\s+)/, $value) {
305 if ($chunk=~/^\\([, ])$/) {
306 $item.=$1;
307 } elsif ($chunk=~/^,\s+$/) {
308 push @items, $item;
309 $item='';
310 } else {
311 $item.=$chunk;
312 }
313 }
314 push @items, $item if $item ne '';
315 return @items;
316 }
317
318 =item addowner
319
320 Add an owner to the list of owners of this Question. Pass the owner name
321 and the type of the Question. Adding an owner that is already listed has
322 no effect.
323
324 =cut
325
326 sub addowner {
327 my $this=shift;
328
329 return $Debconf::Db::config->addowner($this->{name}, shift, shift);
330 }
331
332 =item removeowner
333
334 Remove an owner from the list of owners of this Question. Pass the owner name
335 to remove.
336
337 =cut
338
339 sub removeowner {
340 my $this=shift;
341
342 my $template=$Debconf::Db::config->getfield($this->{name}, 'template');
343 return unless $Debconf::Db::config->removeowner($this->{name}, shift);
344 # If that made the question go away, the question no longer owns
345 # the template, and remove this object from the class's cache.
346 if (length $template and
347 not $Debconf::Db::config->exists($this->{name})) {
348 $Debconf::Db::templates->removeowner($template, $this->{name});
349 delete $question{$this->{name}};
350 }
351 }
352
353 =item owners
354
355 Returns a single string listing all owners of this Question, separated by
356 commas followed by spaces.
357
358 =cut
359
360 sub owners {
361 my $this=shift;
362
363 return join(", ", sort($Debconf::Db::config->owners($this->{name})));
364 }
365
366 =item template
367
368 Get/set the template used by this object. If a parameter is passed in, it
369 is the _name_ of the template to associate with this object.
370
371 Returns a template object.
372
373 =cut
374
375 sub template {
376 my $this=shift;
377 if (@_) {
378 # If the template is not changed from the current one, do
379 # nothing. This avoids deleting the template entirely by
380 # removing its last owner.
381 my $oldtemplate=$Debconf::Db::config->getfield($this->{name}, 'template');
382 my $newtemplate=shift;
383 if (not defined $oldtemplate or $oldtemplate ne $newtemplate) {
384 # This question no longer owns the template it used to, if any.
385 $Debconf::Db::templates->removeowner($oldtemplate, $this->{name})
386 if defined $oldtemplate and length $oldtemplate;
387
388 $Debconf::Db::config->setfield($this->{name}, 'template', $newtemplate);
389
390 # Register this question as an owner of the template.
391 $Debconf::Db::templates->addowner($newtemplate, $this->{name},
392 $Debconf::Db::templates->getfield($newtemplate, "type"));
393 }
394 }
395 return Debconf::Template->get(
396 $Debconf::Db::config->getfield($this->{name}, 'template'));
397 }
398
399 =item name
400
401 Returns the name of the question.
402
403 =cut
404
405 sub name {
406 my $this=shift;
407
408 return $this->{name};
409 }
410
411 =item priority
412
413 Holds the priority the question is asked at.
414
415 =cut
416
417 sub priority {
418 my $this=shift;
419
420 $this->{priority}=shift if @_;
421
422 return $this->{priority};
423 }
424
425 =item AUTOLOAD
426
427 Handles all fields except name, by creating accessor methods for them the
428 first time they are accessed. Fields are first looked for in the db, and
429 failing that, the associated Template is queried for fields.
430
431 Lvalues are not supported.
432
433 =cut
434
435 sub AUTOLOAD {
436 (my $field = our $AUTOLOAD) =~ s/.*://;
437
438 no strict 'refs';
439 *$AUTOLOAD = sub {
440 my $this=shift;
441
442 if (@_) {
443 return $Debconf::Db::config->setfield($this->{name}, $field, shift);
444 }
445 my $ret=$Debconf::Db::config->getfield($this->{name}, $field);
446 unless (defined $ret) {
447 # Fall back to template values.
448 $ret = $this->template->$field() if ref $this->template;
449 }
450 if (defined $ret) {
451 if ($field =~ /^(?:description|extended_description|choices)-/i) {
452 return $this->_expand_vars($ret);
453 } else {
454 return $ret;
455 }
456 }
457 };
458 goto &$AUTOLOAD;
459 }
460
461 # Do nothing
462 sub DESTROY {
463 }
464
465 =back
466
467 =head1 AUTHOR
468
469 Joey Hess <[email protected]>
470
471 =cut
472
473 1