1Options(3) User Contributed Perl Documentation Options(3)
2
6 PDL::Options - simplifies option passing by hash in PerlDL
7
9 use PDL::Options;
10 %hash = parse( \%defaults, \%user_options);
12 use PDL::Options ();
14 $opt = new PDL::Options;
16 $opt = new PDL::Options ( \%defaults );
17 $opt->defaults ( \%defaults );
19 $opt->synonyms ( { 'COLOR' => 'COLOUR' } );
20 $hashref = $opt->defaults;
22 $opt->options ( \%user_options );
24 $hashref = $opt->options;
26 $opt->incremental(1);
28 $opt->full_options(0);
29
31 Object to simplify option passing for PerlDL subroutines. Allows you
32 to merge a user defined options with defaults. A simplified (non-OO)
33 interface is provided.
34
36 ifhref
37 parse({Ext => 'TIF', ifhref($opt)});
39 just return the argument if it is a hashref otherwise return an empty
41 hashref. Useful in conjunction with parse to return just the default
42 values if argument is not a hash ref
43
45 A simplified non-object oriented interface is provided. These routines
46 are exported into the callers namespace by default.
47 parse( \%defaults, \%user_options)
49 This will parse user options by using the defaults. The following
50 settings are used for parsing: The options are case-sensitive, a
51 default synonym table is consulted (see "Default Synonyms"), mini‐
52 mum-matching is turned on, and translation of values is not per‐
53 formed.
54 A hash (not hash reference) containing the processed options is
56 returned.
57 %options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});
59 iparse( \%defaults, \%user_options)
61 Same as "parse" but matching is case insensitive
62 Default Synonyms
64 The following default synonyms are available in the non-OO interface:
66 COLOR => COLOUR
68 COLOUR => COLOR
69 CENTER => CENTRE
70 CENTRE => CENTER
71
73 The following methods are available to PDL::Options objects.
74 new()
76 Constructor. Creates the object. With an optional argument can also
77 set the default options.
78 extend (\%options)
80 This will copy the existing options object and extend it with the
81 requested extra options.
82 defaults( \%defaults )
84 Method to set or return the current defaults. The argument should
85 be a reference to a hash. The hash reference is returned if no
86 arguments are supplied.
87 The current values are reset whenever the defaults are changed.
89 add_synonym (\%synonyms)
91 Method to add another synonym to an option set The argument should
92 be a reference to a hash.
93 add_translation (\%translation)
95 Method to add another translation rule to an option set. The argu‐
96 ment should be a reference to a hash.
97 synonyms( \%synonyms )
99 Method to set or return the current synonyms. The argument should
100 be a reference to a hash. The hash reference is returned if no
101 arguments are supplied.
102 This allows you to provide alternate keywords (such as allowing
104 'COLOR' as an option when your defaults uses 'COLOUR').
105 current
107 Returns the current state of the options. This is returned as a
108 hash reference (although it is not a reference to the actual hash
109 stored in the object). If full_options() is true the full options
110 hash is returned, if full_options() is false only the modified
111 options are returned (as set by the last call to options()).
112 clear_current
114 This routine clears the 'state' of the "PDL::Options" object so
115 that the next call to current will return an empty list
116 translation
118 Provide translation of options to more specific values that are
119 recognised by the program. This allows, for example, the automatic
120 translation of the string 'red' to '#ff0000'.
121 This method can be used to setup the dictionary and is hash refer‐
123 ence with the following structure:
124 OPTIONA => {
126 'string1' => decode1,
127 'string2' => decode2
128 },
129 OPTIONB => {
130 's4' => decodeb1,
131 }
132 etc....
133 Where OPTION? corresponds to the top level option name as stored in
135 the defaults array (eg LINECOLOR) and the anonymous hashes provide
136 the translation from string1 ('red') to decode1 ('#ff0000').
137 An options string will be translated automatically during the main
139 options() processing if autotrans() is set to true. Else transla‐
140 tion can be initiated by the user using the translate() method.
141 incremental
143 Specifies whether the user defined options will be treated as addi‐
144 tions to the current state of the object (1) or modifications to
145 the default values only (0).
146 Can be used to set or return this value. Default is false.
148 full_options
150 Governs whether a complete set of options is returned (ie defaults
151 + expanded user options), true, or if just the expanded user
152 options are returned, false (ie the values specified by the user).
153 This can be useful when you are only interested in the changes to
155 the options rather than knowing the full state. (For example, if
156 defaults contains keys for COLOUR and LINESTYLE and the user sup‐
157 plied a key of COL, you may simply be interested in the modifica‐
158 tion to COLOUR rather than the state of LINESTYLE and COLOUR.)
159 Default is true.
161 casesens
163 Specifies whether the user defined options will be processed inde‐
164 pendent of case (0) or not (1). Default is to be case insensitive.
165 Can be used to set or return this value.
167 minmatch
169 Specifies whether the user defined options will be minimum matched
170 with the defaults (1) or whether the user defined options should
171 match the default keys exactly. Defaults is true (1).
172 If a particular key matches exactly (within the constraints imposed
174 bby case sensitivity) this key will always be taken as correct even
175 if others are similar. For example COL would match COL and COLOUR
176 but this implementation will always return COL in this case (note
177 that for CO it will return both COL and COLOUR and pick one at ran‐
178 dom.
179 Can be used to set or return this value.
181 autotrans
183 Specifies whether the user defined options will be processed via
184 the translate() method immediately following the main options pars‐
185 ing. Default is to autotranslate (1).
186 Can be used to set or return this value.
188 casesenstrans
190 Specifies whether the keys in the options hash will be matched
191 insensitive of case (0) during translation() or not (1). Default is
192 to be case insensitive.
193 Can be used to set or return this value.
195 minmatchtrans
197 Specifies whether the keys in the options hash will be minimum
198 matched during translation(). Default is false (0).
199 If a particular key matches exactly (within the constraints imposed
201 bby case sensitivity) this key will always be taken as correct even
202 if others are similar. For example COL would match COL and COLOUR
203 but this implementation will always return COL in this case (note
204 that for CO it will return both COL and COLOUR and pick one at ran‐
205 dom.
206 Can be used to set or return this value.
208 warnonmissing
210 Turn on or off the warning message printed when an options is not
211 in the options hash. This can be convenient when a user passes a
212 set of options that has to be parsed by several different option
213 objects down the line.
214 debug
216 Turn on or off debug messages. Default is off (0). Can be used to
217 set or return this value.
218 options
220 Takes a set of user-defined options (as a reference to a hash) and
221 merges them with the current state (or the defaults; depends on the
222 state of incremental()).
223 The user-supplied keys will be compared with the defaults. Case
225 sensitivity and minimum matching can be configured using the
226 mimatch() and casesens() methods.
227 A warning is raised if keys present in the user options are not
229 present in the defaults unless warnonmissing is set.
230 A reference to a hash containing the merged options is returned.
232 $merged = $opt->options( { COL => 'red', Width => 1});
234 The state of the object can be retrieved after this by using the
236 current() method or by using the options() method with no argu‐
237 ments. If full_options() is true, all options are returned
238 (options plus overrides), if full_options() is false then only the
239 modified options are returned.
240 Synonyms are supported if they have been configured via the syn‐
242 onyms() method.
243 translate
245 Translate the current option values (eg those set via the options()
246 method) using the provided translation().
247 This method updates the current state of the object and returns the
249 updated options hash as a reference.
250 $ref = $opt->translate;
252
254 Two examples are shown. The first uses the simplified interface and the
255 second uses the object-oriented interface.
256
258 use PDL::Options (':Func');
259 %options = parse( {
261 LINE => 1,
262 COLOUR => 'red',
263 },
264 {
265 COLOR => 'blue'
266 }
267 );
268 This will return a hash containg
270 %options = (
272 LINE => 1,
273 COLOUR => 'blue'
274 )
275
277 The following example will try to show the main points:
278 use PDL::Options ();
280 # Create new object and supply defaults
282 $opt = new PDL::Options( { Colour => 'red',
283 LineStyle => 'dashed',
284 LineWidth => 1
285 }
286 );
287 # Create synonyms
289 $opt->synonyms( { Color => 'Colour' } );
290 # Create translation dictionary
292 $opt->translation( { Colour => {
293 'blue' => '#0000ff',
294 'red' => '#ff0000',
295 'green'=> '#00ff00'
296 },
297 LineStyle => {
298 'solid' => 1,
299 'dashed' => 2,
300 'dotted' => 3
301 }
302 }
303 );
304 # Generate and parse test hash
306 $options = $opt->options( { Color => 'green',
307 lines => 'solid',
308 }
309 );
310 When this code is run, $options will be the reference to a hash con‐
312 taining the following:
313 Colour => '#00ff00',
315 LineStyle => 1,
316 LineWidth => 1
317 If full_options() was set to false (0), $options would be a reference
319 to a hash containing:
320 Colour => '#00ff00',
322 LineStyle => 1
323 Minimum matching and case insensitivity can be configured for both the
325 initial parsing and for the subsequent translating. The translation can
326 be turned off if not desired.
327 Currently synonyms are not available for the translation although this
329 could be added quite simply.
330
332 Copyright (C) Tim Jenness 1998 (t.jenness@jach.hawaii.edu). All rights
333 reserved. There is no warranty. You are allowed to redistribute this
334 software / documentation under certain conditions. For details, see the
335 file COPYING in the PDL distribution. If this file is separated from
336 the PDL distribution, the copyright notice should be included in the
337 file.
338perl v5.8.8 2004-09-07 Options(3)