blib/lib/PDL/Options.pm

filter: Statementstmt 63.7% 167 / 262 Branchbran 41.6% 45 / 108 Conditioncond 40.0% 6 / 15 MC/DCmcdc 30.0% 3 / 10 Subroutinesub 70.9% 22 / 31 Podpod 88.8% 24 / 27 totaltotal 58.9% 267 / 453 CC 125 SCAR 22.2
CC
125
Cov
57%
add_synonym
20.0
add_synonym
20.0
add_translation
20.0
CRAP 9.2
« blib/lib/PDL/PP/PDLCode.pm ↑ Summary blib/lib/PDL/Exporter.pm »
1 package PDL::Options;
2  
3 =head1 NAME
4  
5 PDL::Options - simplifies option passing by hash in PerlDL
6  
7 =head1 SYNOPSIS
8  
9 use PDL::Options;
10  
11 %hash = parse( \%defaults, \%user_options);
12  
13 use PDL::Options ();
14  
15 $opt = PDL::Options->new;
16 $opt = PDL::Options->new( \%defaults );
17  
18 $opt->defaults ( \%defaults );
19 $opt->synonyms ( { 'COLOR' => 'COLOUR' } );
20  
21 $hashref = $opt->defaults;
22  
23 $opt->options ( \%user_options );
24  
25 $hashref = $opt->options;
26  
27 $opt->incremental(1);
28 $opt->full_options(0);
29  
30 =head1 DESCRIPTION
31  
32 Object to simplify option passing for PerlDL subroutines.
33 Allows you to merge a user defined options with defaults.
34 A simplified (non-OO) interface is provided.
35  
36 =cut
37  
38 71 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
39 71 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
40 71 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 71 require Exporter;
43  
44 # difference to 0.91 is that added CENTRE/CENTER as default
45 # synonymns (patch by Diab Jerius [ #469110 ])
46 71 our $VERSION = '0.92';
47 71 $VERSION = eval $VERSION;
48  
49 71 our @ISA = qw(Exporter);
50  
51 71 our %EXPORT_TAGS = (
52 'Func' => [qw/
53 parse iparse ifhref
54 /]
55 );
56  
57 71 Exporter::export_tags('Func');
58  
59 # List of default synonyms
60 71 our %DEF_SYNS = (
61 COLOR => 'COLOUR',
62 COLOUR => 'COLOR',
63 CENTER => 'CENTRE',
64 CENTRE => 'CENTER',
65 );
66  
67 71 my $default = {
68 WarnOnMissing => 1,
69 FullOptions => 1,
70 DEBUG => 0,
71 };
72  
73 =head1 Utility functions
74  
75 =head2 ifhref
76  
77 parse({Ext => 'TIF', ifhref($opt)});
78  
79 just return the argument if it is a hashref otherwise return
80 an empty hashref. Useful in conjunction with parse to return
81 just the default values if argument is not a hash ref
82  
83 =head1 NON-OO INTERFACE
84  
85 A simplified non-object oriented interface is provided.
86 These routines are exported into the callers namespace by default.
87  
88 =over 4
89  
90 =item parse( \%defaults, \%user_options)
91  
92 This will parse user options by using the defaults. The following
93 settings are used for parsing: The options are case-sensitive, a
94 default synonym table is consulted (see L</Default Synonyms>),
95 minimum-matching is turned on, and translation of values is not performed.
96  
97 A hash (not hash reference) containing the processed options is returned.
98  
99 %options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});
100  
101 =item iparse( \%defaults, \%user_options)
102  
103 Same as C<parse> but matching is case insensitive
104  
105 =cut
106  
107 97 ▶sub ifhref {
Subroutine ifhref: called CC=3 SCAR=14.2
Pod documented
108 0 ▶ my ($href) = @_;
Subroutine ifhref: not called CC=3 SCAR=14.2
Pod documented
109 0 ▶ return defined $href && ref $href eq 'HASH' ? $href : {};
Branch: 2 branches
BranchTrueFalseTotal
defined $href && ref $href eq 'HASH' ? : 18 79 97
defined $href && ref $href eq 'HASH' ? : 0 0 0
Condition50%3/6
defined $href and ref $href eq "HASH"
!ll&&!rl&&r
78118
defined $href and ref $href eq "HASH"
!ll&&!rl&&r
000
MC/DC100%2/2
defined $href and ref $href eq "HASH"
defined $href ref $href eq "HASH"
MC/DC0%0/2
defined $href and ref $href eq "HASH"
defined $href ref $href eq "HASH"
Truth table100%3/3
A and B
A= defined $hrefB= ref $href eq "HASH"
ABresult
0X0
100
111
Truth table0%0/3
A and B
A= defined $hrefB= ref $href eq "HASH"
ABresult
0X0
100
111
110 }
111  
112 0 ▶sub parse { return _parse(1,@_) }
Subroutine parse: not called CC=1 SCAR=6.9
Pod documented
113 26 ▶sub iparse { return _parse(0,@_) }
Subroutine iparse: called CC=1 SCAR=0.0
Pod documented
114  
115 26 ▶sub _parse {
Subroutine _parse: called CC=4 SCAR=14.0
116  
117 26 ▶ croak 'Usage: parse( \%defaults, \%user )' if scalar(@_) != 3;
Branch: 1 branch
BranchTrueFalseTotal
if scalar @_ != 3 0 26 26
118  
119 26 my $casechk = shift;
120 26 my $defaults = shift;
121 26 ▶ croak ("First argument is not a hash reference")
Branch: 1 branch
BranchTrueFalseTotal
unless ref $defaults eq "HASH" 0 26 26
122 unless ref($defaults) eq "HASH";
123  
124 26 my $user = shift;
125 26 ▶ croak ("Second argument is not a hash reference")
Branch: 1 branch
BranchTrueFalseTotal
unless ref $user eq "HASH" 0 26 26
126 unless ref($user) eq "HASH";
127  
128 # Create new object
129 26 my $opt = PDL::Options->new( $defaults );
130  
131 # Set up default behaviour
132 26 $opt->minmatch(1);
133 26 $opt->casesens($casechk);
134 26 $opt->synonyms( \%DEF_SYNS );
135  
136 # Process the options
137 26 my $optref = $opt->options( $user );
138  
139 26 return %$optref;
140 }
141  
142  
143 =back
144  
145 =head2 Default Synonyms
146  
147 The following default synonyms are available in the non-OO interface:
148  
149 COLOR => COLOUR
150 COLOUR => COLOR
151 CENTER => CENTRE
152 CENTRE => CENTER
153  
154 =head1 METHODS
155  
156 The following methods are available to PDL::Options objects.
157  
158 =over 4
159  
160 =item new()
161  
162 Constructor. Creates the object. With an optional argument can also
163 set the default options.
164  
165 =cut
166  
167 72 ▶sub new {
Subroutine new: called CC=3 SCAR=11.0
Pod documented
168  
169 72 my $proto = shift;
170 72 ▶ my $class = ref($proto) || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
0720
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
171  
172 72 my $opt = {};
173  
174 # Set up object structure
175 72 $opt->{DEFAULTS} = {}; # Default options
176 72 $opt->{CURRENT} = {}; # Current options
177 72 $opt->{CurrKeys} = []; # list of selected keys if full_options(0)
178 72 $opt->{SYNONYMS} = {}; # List of synonyms
179 72 $opt->{INC} = 0; # Flag to decide whether we are incremental on cur
180 72 $opt->{CaseSens} = 0; # Are options case sensitive
181 72 $opt->{MinMatch} = 1; # Minimum matching on keys
182 72 $opt->{Translation} = {};# Translation from eg 'RED' to 1
183 72 $opt->{AutoTranslate}= 1;# Automatically translate options when processing
184 72 $opt->{MinMatchTrans} = 0; # Min matching during translation
185 72 $opt->{CaseSensTrans} = 0; # Case sensitive during translation
186 # Return full options list
187 72 $opt->{FullOptions} = $default->{FullOptions};
188 # Whether to warn for options that are invalid or not
189 72 $opt->{WarnOnMissing}= $default->{WarnOnMissing};
190 72 $opt->{DEBUG} = $default->{DEBUG}; # Turn on debug messages
191  
192 # Bless into class
193 72 bless ( $opt, $class);
194  
195 # If we were passed arguments, pass to defaults method
196 72 ▶ if (@_) { $opt->defaults( @_ ); }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 72 0 72
197  
198 72 return $opt;
199 }
200  
201 =item extend (\%options)
202  
203 This will copy the existing options object and extend it with the
204 requested extra options.
205  
206 =cut
207  
208 0 ▶sub extend {
Subroutine extend: not called CC=2 SCAR=17.9
Pod documented
209  
210 0 my ($self, $opt)=@_;
211  
212 0 my $class = ref($self);
213 0 my $h = {%{$self}};
214 0 ▶ croak ("Argument is not reference to hash!\n") unless ref($opt) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $opt eq "HASH" 0 0 0
215 #
216 # The next step is to perform a deep copy of the hash
217 # references since we might want to change these without
218 # changing the originals.
219 #
220 0 $h->{SYNONYMS}={%{$self->{SYNONYMS}}};
221 0 $h->{Translation}={%{$self->{Translation}}};
222 0 $h->{CurrKeys}=[@{$self->{CurrKeys}}];
223 #
224 # Create the extended option list.
225 #
226 0 my %all_options = (%{$opt}, %{$self->{DEFAULTS}});
227  
228 # Bless it
229 0 bless ($h, $class);
230  
231 # And parse the default options
232 0 $h->defaults(\%all_options);
233  
234 0 return $h;
235  
236 }
237  
238 # =item change_defaults (\%options)
239  
240 # This will merge the options given with the defaults hash and hence change
241 # the default hash. This is not normally a good idea, but in certain dynamic
242 # situations you might want to adjust a default parameter for future calls
243 # to the routine.
244  
245 # =cut
246  
247 # sub change_defaults {
248  
249 # my $self=shift;
250  
251 # my $arg = shift;
252 # croak("Argument is not a hash reference!\n") unless ref($arg) eq 'HASH';
253  
254 # my $defs = $self->defaults($arg);
255  
256 # $self->defaults($)
257  
258  
259 # }
260  
261  
262 =item defaults( \%defaults )
263  
264 Method to set or return the current defaults. The argument should be
265 a reference to a hash. The hash reference is returned if no arguments
266 are supplied.
267  
268 The current values are reset whenever the defaults are changed.
269  
270 =cut
271  
272 212 ▶sub defaults {
Subroutine defaults: called CC=3 SCAR=11.0
Pod documented
273 212 my $self = shift;
274  
275 212 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 72 140 212
276 72 my $arg = shift;
277 72 ▶ croak("Argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 72 72
278 72 $self->{DEFAULTS} = $arg;
279  
280 # Reset the current state (making sure that I disconnect the
281 # hashes
282 72 my %hash = %$arg;
283 72 $self->curr_full(\%hash);
284  
285 }
286  
287 # Decouple the hash to protect it from being modified outside the
288 # object
289 212 my %hash = %{$self->{DEFAULTS}};
290 212 return \%hash;
291  
292 }
293  
294 =item add_synonym (\%synonyms)
295  
296 Method to add another synonym to an option set
297 The argument should be a reference to a hash.
298  
299 =cut
300  
301 0 ▶sub add_synonym {
Subroutine add_synonym: not called CC=4 SCAR=30.0
Pod documented
302 0 my $self=shift;
303 0 ▶ return unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
304 0 my $arg = shift;
305 0 ▶ croak("Synonym argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 0 0
306  
307 0 foreach (keys %$arg) {
308 0 $self->{SYNONYMS}{$_}=$arg->{$_};
309 }
310 0 my %hash = %{$self->{SYNONYMS}};
311 0 return \%hash;
312  
313 }
314  
315 =item add_translation (\%translation)
316  
317 Method to add another translation rule to an option set.
318 The argument should be a reference to a hash.
319  
320 =cut
321  
322  
323 0 ▶sub add_translation {
Subroutine add_translation: not called CC=4 SCAR=30.0
Pod documented
324 0 my $self = shift;
325 0 ▶ return unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
326 0 my $arg = shift;
327 0 ▶ croak("Translation argument is not a hash reference") unless ref($arg) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 0 0
328  
329 0 foreach (keys %$arg) {
330 0 $self->{Translation}{$_}=$arg->{$_};
331 }
332 0 my %hash = %{$self->{Translation}};
333  
334 0 return \%hash;
335  
336 }
337  
338 =item synonyms( \%synonyms )
339  
340 Method to set or return the current synonyms. The argument should be
341 a reference to a hash. The hash reference is returned if no arguments
342 are supplied.
343  
344 This allows you to provide alternate keywords (such as allowing
345 'COLOR' as an option when your defaults uses 'COLOUR').
346  
347 =cut
348  
349 178 ▶sub synonyms {
Subroutine synonyms: called CC=3 SCAR=11.0
Pod documented
350 178 my $self = shift;
351  
352 178 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 38 140 178
353 38 my $arg = shift;
354 38 ▶ croak("Argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 38 38
355 38 $self->{SYNONYMS} = $arg;
356 }
357  
358 # Decouple the hash to protect it from being modified outside the
359 # object
360 178 my %hash = %{$self->{SYNONYMS}};
361 178 return \%hash;
362  
363 }
364  
365  
366 =item current
367  
368 Returns the current state of the options. This is returned
369 as a hash reference (although it is not a reference to the
370 actual hash stored in the object). If full_options() is true
371 the full options hash is returned, if full_options() is false
372 only the modified options are returned (as set by the last call
373 to options()).
374  
375 =cut
376  
377 170 ▶sub current {
Subroutine current: called CC=4 SCAR=22.3
Pod documented
378 170 my $self = shift;
379  
380 170 ▶ if ($self->full_options) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->full_options) { } 170 0 170
381 170 return $self->curr_full;
382 } else {
383 0 my @keys = $self->curr_keys;
384 0 my %hash = ();
385 0 my $curr = $self->curr_full;
386  
387 0 foreach my $key (@keys) {
388 0 ▶ $hash{$key} = $$curr{$key} if exists $$curr{$key};
Branch: 1 branch
BranchTrueFalseTotal
if exists $curr->{$key} 0 0 0
389 }
390 0 return \%hash;
391 }
392 }
393  
394 =item clear_current
395  
396 This routine clears the 'state' of the C<PDL::Options> object so that
397 the next call to current will return an empty list
398  
399 =cut
400  
401 0 ▶sub clear_current {
Subroutine clear_current: not called CC=1 SCAR=6.9
Pod documented
402 0 my $self = shift;
403 0 @{$self->{CurrKeys}}=();
404 }
405  
406  
407 # Method to set the 'mini' state of the object
408 # This is just a list of the keys in %defaults that were selected
409 # by the user. current() returns the hash with these keys if
410 # called with full_options(0).
411 # Not publicising this
412  
413 140 ▶sub curr_keys {
Subroutine curr_keys: called CC=2 SCAR=6.9
Pod undocumented
414 140 my $self = shift;
415 140 ▶ if (@_) { @{$self->{CurrKeys}} = @_; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 57 83 140
416 140 return @{$self->{CurrKeys}};
417 }
418  
419 # Method to set the full state of the object
420 # Not publicising this
421  
422 662 ▶sub curr_full {
Subroutine curr_full: called CC=3 SCAR=11.0
Pod undocumented
423 662 my $self = shift;
424  
425 662 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 352 310 662
426 352 my $arg = shift;
427 352 ▶ croak("Argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 352 352
428 352 $self->{CURRENT} = $arg;
429 }
430  
431 # Decouple the hash
432 662 my %hash = %{$self->{CURRENT}};
433 662 return \%hash;
434  
435 }
436  
437  
438 =item translation
439  
440 Provide translation of options to more specific values that are
441 recognised by the program. This allows, for example, the automatic
442 translation of the string 'red' to '#ff0000'.
443  
444 This method can be used to setup the dictionary and is hash reference
445 with the following structure:
446  
447 OPTIONA => {
448 'string1' => decode1,
449 'string2' => decode2
450 },
451 OPTIONB => {
452 's4' => decodeb1,
453 }
454 etc....
455  
456 Where OPTION? corresponds to the top level option name as stored in
457 the defaults array (eg LINECOLOR) and the anonymous hashes provide
458 the translation from string1 ('red') to decode1 ('#ff0000').
459  
460 An options string will be translated automatically during the main options()
461 processing if autotrans() is set to true. Else translation can be
462 initiated by the user using the translate() method.
463  
464 =cut
465  
466 140 ▶sub translation {
Subroutine translation: called CC=3 SCAR=14.2
Pod documented
467 140 my $self = shift;
468  
469 140 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 140 140
470 0 my $arg = shift;
471 0 ▶ croak("Argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 0 0
472 0 $self->{Translation} = $arg;
473 }
474  
475 # Decouple the hash to protect it from being modified outside the
476 # object
477 140 my %hash = %{$self->{Translation}};
478 140 return \%hash;
479  
480 }
481  
482  
483 =item incremental
484  
485 Specifies whether the user defined options will be treated as additions
486 to the current state of the object (1) or modifications to the default
487 values only (0).
488  
489 Can be used to set or return this value.
490 Default is false.
491  
492 =cut
493  
494 140 ▶sub incremental {
Subroutine incremental: called CC=2 SCAR=7.6
Pod documented
495 140 my $self = shift;
496 0 ▶ if (@_) { $self->{INC} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 140 140
497 140 return $self->{INC};
498 }
499  
500 =item full_options
501  
502 Governs whether a complete set of options is returned (ie defaults
503 + expanded user options), true, or if just the expanded user
504 options are returned, false (ie the values specified by the user).
505  
506 This can be useful when you are only interested in the changes to
507 the options rather than knowing the full state. (For example, if
508 defaults contains keys for COLOUR and LINESTYLE and the user supplied
509 a key of COL, you may simply be interested in the modification to
510 COLOUR rather than the state of LINESTYLE and COLOUR.)
511  
512 Default is true.
513  
514 =cut
515  
516 170 ▶sub full_options {
Subroutine full_options: called CC=2 SCAR=7.6
Pod documented
517 170 my $self = shift;
518 0 ▶ if (@_) { $self->{FullOptions} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 170 170
519 170 return $self->{FullOptions};
520  
521 }
522  
523 =item casesens
524  
525 Specifies whether the user defined options will be processed independent
526 of case (0) or not (1). Default is to be case insensitive.
527  
528 Can be used to set or return this value.
529  
530 =cut
531  
532 143 ▶sub casesens {
Subroutine casesens: called CC=2 SCAR=6.9
Pod documented
533 143 my $self = shift;
534 143 ▶ if (@_) { $self->{CaseSens} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 27 116 143
535 143 return $self->{CaseSens};
536 }
537  
538 =item minmatch
539  
540 Specifies whether the user defined options will be minimum matched
541 with the defaults (1) or whether the user defined options should match
542 the default keys exactly. Defaults is true (1).
543  
544 If a particular key matches exactly (within the constraints imposed
545 bby case sensitivity) this key will always be taken as correct even
546 if others are similar. For example COL would match COL and COLOUR but
547 this implementation will always return COL in this case (note that
548 for CO it will return both COL and COLOUR and pick one at random.
549  
550 Can be used to set or return this value.
551  
552 =cut
553  
554 143 ▶sub minmatch {
Subroutine minmatch: called CC=2 SCAR=6.9
Pod documented
555 143 my $self = shift;
556 143 ▶ if (@_) { $self->{MinMatch} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 27 116 143
557 143 return $self->{MinMatch};
558 }
559  
560  
561 =item autotrans
562  
563 Specifies whether the user defined options will be processed via
564 the translate() method immediately following the main options
565 parsing. Default is to autotranslate (1).
566  
567 Can be used to set or return this value.
568  
569 =cut
570  
571 140 ▶sub autotrans {
Subroutine autotrans: called CC=2 SCAR=7.6
Pod documented
572 140 my $self = shift;
573 0 ▶ if (@_) { $self->{AutoTranslate} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 140 140
574 140 return $self->{AutoTranslate};
575 }
576  
577  
578 =item casesenstrans
579  
580 Specifies whether the keys in the options hash will be matched insensitive
581 of case (0) during translation() or not (1). Default is to be case insensitive.
582  
583 Can be used to set or return this value.
584  
585 =cut
586  
587 0 ▶sub casesenstrans {
Subroutine casesenstrans: not called CC=2 SCAR=17.9
Pod documented
588 0 my $self = shift;
589 0 ▶ if (@_) { $self->{CaseSensTrans} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 0 0
590 0 return $self->{CaseSensTrans};
591 }
592  
593 =item minmatchtrans
594  
595 Specifies whether the keys in the options hash will be minimum matched
596 during translation(). Default is false (0).
597  
598 If a particular key matches exactly (within the constraints imposed
599 bby case sensitivity) this key will always be taken as correct even
600 if others are similar. For example COL would match COL and COLOUR but
601 this implementation will always return COL in this case (note that
602 for CO it will return both COL and COLOUR and pick one at random.
603  
604 Can be used to set or return this value.
605  
606 =cut
607  
608 0 ▶sub minmatchtrans {
Subroutine minmatchtrans: not called CC=2 SCAR=17.9
Pod documented
609 0 my $self = shift;
610 0 ▶ if (@_) { $self->{MinMatchTrans} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 0 0
611 0 return $self->{MinMatchTrans};
612 }
613  
614  
615 =item warnonmissing
616  
617 Turn on or off the warning message printed when an options is not in
618 the options hash. This can be convenient when a user passes a set of
619 options that has to be parsed by several different option objects down
620 the line.
621  
622 =cut
623  
624 0 ▶sub warnonmissing {
Subroutine warnonmissing: not called CC=4 SCAR=30.0
Pod documented
625 0 my $self = shift;
626 0 ▶ if (ref $self) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self) { } 0 0 0
627 0 ▶ if (@_) { $self->{WarnOnMissing}=shift;}
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 0 0
628 0 return $self->{WarnOnMissing};
629 } else {
630 0 ▶ $default->{WarnOnMissing} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 0 0
631 0 return $default->{WarnOnMissing};
632 }
633 }
634  
635  
636 =item debug
637  
638 Turn on or off debug messages. Default is off (0).
639 Can be used to set or return this value.
640  
641 =cut
642  
643 111 ▶sub debug {
Subroutine debug: called CC=4 SCAR=18.7
Pod documented
644 111 my $self = shift;
645 111 ▶ if (ref $self) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self) { } 111 0 111
646 0 ▶ if (@_) { $self->{DEBUG} = shift; }
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 111 111
647 111 return $self->{DEBUG};
648 } else {
649 0 ▶ $default->{DEBUG} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 0 0
650 0 return $default->{DEBUG};
651 }
652 }
653  
654  
655 =item options
656  
657 Takes a set of user-defined options (as a reference to a hash)
658 and merges them with the current state (or the defaults; depends
659 on the state of incremental()).
660  
661 The user-supplied keys will be compared with the defaults.
662 Case sensitivity and minimum matching can be configured using
663 the mimatch() and casesens() methods.
664  
665 A warning is raised if keys present in the user options are not
666 present in the defaults unless warnonmissing is set.
667  
668 A reference to a hash containing the merged options is returned.
669  
670 $merged = $opt->options( { COL => 'red', Width => 1});
671  
672 The state of the object can be retrieved after this by using the
673 current() method or by using the options() method with no arguments.
674 If full_options() is true, all options are returned (options plus
675 overrides), if full_options() is false then only the modified
676 options are returned.
677  
678 Synonyms are supported if they have been configured via the synonyms()
679 method.
680  
681 =cut
682  
683 140 ▶sub options {
Subroutine options: called CC=12 SCAR=27.3
Pod documented
684  
685 140 my $self = shift;
686  
687 # If there is an argument do something clever
688 140 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 140 0 140
689  
690 # check that the arg is a hash
691 140 my $arg = shift;
692 140 ▶ croak("Argument is not a hash reference") unless ref($arg) eq "HASH";
Branch: 1 branch
BranchTrueFalseTotal
unless ref $arg eq "HASH" 0 140 140
693  
694 # Turn the options into a real hash
695 140 my %user = %$arg;
696  
697 # Now read in the base options
698 140 my $base;
699 140 ▶ if ($self->incremental) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->incremental) { } 0 140 140
700 0 $base = $self->curr_full;
701 } else {
702 140 $base = $self->defaults;
703 }
704  
705 # Turn into a real hash for convenience
706 140 my %base = %$base;
707  
708 # Store a list of all the expanded user keys
709 140 my @list = ();
710  
711 # Read in synonyms
712 140 my %syn = %{$self->synonyms};
713  
714 # Now go through the keys in the user hash and compare with
715 # the defaults
716 140 foreach my $userkey (sort keys %user) {
717  
718 # Check for matches in the default set
719 111 my @matched = $self->compare_with_list(0, $userkey, sort keys %base);
720  
721 # If we had no matches, check the synonyms list
722 111 ▶ if ($#matched == -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#matched == -1) 5 106 111
723 5 @matched = $self->compare_with_list(0, $userkey, sort keys %syn);
724  
725 # If we have matched then convert the key to the actual
726 # value stored in the object
727 5 ▶ for (my $i =0; $i <= $#matched; $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i <= $#matched) 5 5 10
728 5 $matched[$i] = $syn{$matched[$i]};
729 }
730 }
731  
732 # At this point we have matched the userkey to a key in the
733 # defaults list (or if not say so)
734 111 ▶ if ($#matched == -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#matched == -1) { } 0 111 111
735 0 ▶ print "Warning: $userkey is not a valid option\n" if $self->{WarnOnMissing};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"WarnOnMissing"} 0 0 0
736 } else {
737 111 ▶ if ( $#matched > 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#matched > 0) 0 111 111
738 0 print "Warning: Multiple matches for option $userkey\n";
739 0 print "Warning: Could be any of the following:\n";
740 0 print join("\n",@matched) . "\n";
741 0 print "Accepting the first match ($matched[0])\n";
742 }
743 # Modify the value in %base and keep track of a separate
744 # array containing only the matched keys
745 111 $base{$matched[0]} = $user{$userkey};
746 111 push(@list, $matched[0]);
747 111 ▶ print "Matched: $userkey for $matched[0]\n" if $self->debug;
Branch: 1 branch
BranchTrueFalseTotal
if $self->debug 0 111 111
748 }
749 }
750  
751 # Finished matching so set this as the current state of the
752 # object
753 140 $self->curr_keys(@list);
754 140 $self->curr_full(\%base);
755  
756 # Now process the values via the provided translation
757 # if required. Note that the current design means that
758 # We have to run this after we have set the current state.
759 # Otherwise the translation() method would not work directly
760 # and we would have to provide a public version and a private one.
761 # Note that translate updates the current state of the object
762 # So we don't need to catch the return value
763 140 ▶ $self->translate if $self->autotrans;
Branch: 1 branch
BranchTrueFalseTotal
if $self->autotrans 140 0 140
764  
765 }
766  
767 # Current state should now be in current.
768 # Simply return it
769 140 return $self->current;
770  
771 }
772  
773 =item translate
774  
775 Translate the current option values (eg those set via the options()
776 method) using the provided translation().
777  
778 This method updates the current state of the object and returns the
779 updated options hash as a reference.
780  
781 $ref = $opt->translate;
782  
783 =cut
784  
785 140 ▶sub translate {
Subroutine translate: called CC=6 SCAR=28.1
Pod documented
786 140 my $self = shift;
787  
788 140 my %trans = %{$self->translation};
789 140 my %opt = %{$self->curr_full}; # Process all options
790  
791 # Now need to go through each of the keys
792 # and if the corresponding key exists in the translation
793 # hash we need to check that a valid translation exists
794 140 foreach my $key ( sort grep defined $opt{$_}, keys %opt ) {
795 549 ▶ if (exists $trans{$key}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $trans{$key}) 0 549 549
796 # Okay so a translation might exist
797 # Now compare keys in the hash in the hash
798 0 my %subhash = %{$trans{$key}};
799  
800 my @matched =
801 0 $self->compare_with_list(1, $opt{$key}, sort keys %subhash);
802  
803 # At this point we have matched the userkey to a key in the
804 # dictionary. If there is no translation dont say anything
805 # since it may be a 'REAL' answer (ie 1 instead of 'red')
806  
807 0 ▶ if ($#matched > -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#matched > -1) 0 0 0
808 0 ▶ if ( $#matched > 0 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#matched > 0) 0 0 0
809 0 print "Warning: Multiple matches for $opt{$key} in option $key\n";
810 0 print "Warning: Could be any of the following:\n";
811 0 print join("\n",@matched) . "\n";
812 0 print "Accepting the first match ($matched[0])\n";
813  
814 }
815 # Modify the value in the options set
816 0 ▶ print "Translation: $opt{$key} translated to $subhash{$matched[0]}\n"
Branch: 1 branch
BranchTrueFalseTotal
if $self->debug 0 0 0
817 if $self->debug;
818 0 $opt{$key} = $subhash{$matched[0]};
819  
820 }
821  
822 }
823  
824 }
825  
826 # Update the current state
827 140 return $self->curr_full( \%opt );
828  
829 }
830  
831 # Private method to compare a key with a list of keys.
832 # The object controls whether case-sensitivity of minimum matching
833 # are required
834 # Arguments: flag to determine whether I am matchin options or translations
835 # this is needed since both methods are configurable with
836 # regards to minimum matching and case sensitivity.
837 # 0 - use $self->minmatch and $self->casesens
838 # 1 - use $self->minmatchtrans and $self->casesenstrans
839 # $key: Key to be compared
840 # @keys: List of keys
841 # Returns: Array of all keys that match $key taking into account the
842 # object state.
843 #
844 # There must be a more compact way of doing this
845  
846 116 ▶sub compare_with_list {
Subroutine compare_with_list: called CC=8 SCAR=24.9
Pod undocumented
847 116 my $self = shift;
848  
849 116 my $flag = shift;
850 116 my $key = shift;
851 116 ▶ confess "Called with undefined key" if !defined $key;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 0 116 116
852 116 my @list = @_;
853  
854 116 my @result = ();
855  
856 116 my ($casesens, $minmatch);
857 116 ▶ if ($flag == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($flag == 0) { } 116 0 116
858 116 $casesens = $self->casesens;
859 116 $minmatch = $self->minmatch;
860 } else {
861 0 $casesens = $self->casesenstrans;
862 0 $minmatch = $self->minmatchtrans;
863 }
864  
865 # Do matches
866  
867 # Case Sensitive
868 116 ▶ if ($casesens) {
Branch: 1 branch
BranchTrueFalseTotal
if ($casesens) { } 0 116 116
869  
870 # Always start with the exact match before proceding to minimum
871 # match.
872 # We want to make sure that we will always match on the
873 # exact match even if alternatives exist (eg COL will always
874 # match just COL if the keys are COL and COLOUR)
875 # Case insensitive
876 0 @result = grep { /^$key$/ } @list;
877  
878 # Proceed to minimum match if we detected nothing
879 # Minumum match/ Case sensitive
880 0 ▶ if ($#result == -1 && $minmatch) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#result == -1 and $minmatch) 0 0 0
Condition0%0/3
$#result == -1 and $minmatch
!ll&&!rl&&r
000
MC/DC0%0/2
$#result == -1 and $minmatch
$#result == -1 $minmatch
Truth table0%0/3
A and B
A= $#result == -1B= $minmatch
ABresult
0X0
100
111
881  
882 0 @result = grep { /^$key/ } @list;
883  
884 }
885  
886 } else {
887  
888 # We want to make sure that we will always match on the
889 # exact match even if alternatives exist (eg COL will always
890 # match just COL if the keys are COL and COLOUR)
891 # First do the exact match (case insensitive)
892 116 @result = grep { /^$key$/i } @list;
893 # If this match came up with something then we will use it
894 # Else we will try a minimum match (assuming flag is true)
895  
896 # Minumum match/ Case insensitive
897 116 ▶ if ($#result == -1 && $minmatch) {
Branch: 1 branch
BranchTrueFalseTotal
if ($#result == -1 and $minmatch) 17 99 116
Condition66%2/3
$#result == -1 and $minmatch
!ll&&!rl&&r
99017
MC/DC50%1/2
$#result == -1 and $minmatch
$#result == -1 $minmatch
Truth table66%2/3
A and B
A= $#result == -1B= $minmatch
ABresult
0X0
100
111
898  
899 17 @result = grep { /^$key/i } @list;
900  
901 }
902 }
903 116 return @result;
904 }
905  
906 =back
907  
908 =head1 EXAMPLE
909  
910 Two examples are shown. The first uses the simplified interface and
911 the second uses the object-oriented interface.
912  
913 =head1 Non-OO
914  
915 use PDL::Options (':Func');
916  
917 %options = parse( {
918 LINE => 1,
919 COLOUR => 'red',
920 },
921 {
922 COLOR => 'blue'
923 }
924 );
925  
926 This will return a hash containing
927  
928 %options = (
929 LINE => 1,
930 COLOUR => 'blue'
931 )
932  
933  
934 =head1 Object oriented
935  
936 The following example will try to show the main points:
937  
938 use PDL::Options ();
939  
940 # Create new object and supply defaults
941 $opt = PDL::Options->new( { Colour => 'red',
942 LineStyle => 'dashed',
943 LineWidth => 1
944 }
945 );
946  
947 # Create synonyms
948 $opt->synonyms( { Color => 'Colour' } );
949  
950 # Create translation dictionary
951 $opt->translation( { Colour => {
952 'blue' => '#0000ff',
953 'red' => '#ff0000',
954 'green'=> '#00ff00'
955 },
956 LineStyle => {
957 'solid' => 1,
958 'dashed' => 2,
959 'dotted' => 3
960 }
961 }
962 );
963  
964 # Generate and parse test hash
965 $options = $opt->options( { Color => 'green',
966 lines => 'solid',
967 }
968 );
969  
970 When this code is run, $options will be the reference to a hash
971 containing the following:
972  
973 Colour => '#00ff00',
974 LineStyle => 1,
975 LineWidth => 1
976  
977 If full_options() was set to false (0), $options would be a reference
978 to a hash containing:
979  
980 Colour => '#00ff00',
981 LineStyle => 1
982  
983 Minimum matching and case insensitivity can be configured for both
984 the initial parsing and for the subsequent translating. The translation
985 can be turned off if not desired.
986  
987 Currently synonyms are not available for the translation although this
988 could be added quite simply.
989  
990 =head1 AUTHOR
991  
992 Copyright (C) Tim Jenness 1998 (t.jenness@jach.hawaii.edu). All
993 rights reserved. There is no warranty. You are allowed to redistribute
994 this software / documentation under certain conditions. For details,
995 see the file COPYING in the PDL distribution. If this file is
996 separated from the PDL distribution, the copyright notice should be
997 included in the file.
998  
999 =cut
1000  
1001  
1002 71 1;
1003  
« blib/lib/PDL/PP/PDLCode.pm ↑ Summary blib/lib/PDL/Exporter.pm »