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)});
38 just return the argument if it is a hashref otherwise return an empty
40 hashref. Useful in conjunction with parse to return just the default
41 values if argument is not a hash ref
42
44 A simplified non-object oriented interface is provided. These routines
45 are exported into the callers namespace by default.
46 parse( \%defaults, \%user_options)
48 This will parse user options by using the defaults. The following
49 settings are used for parsing: The options are case-sensitive, a
50 default synonym table is consulted (see "Default Synonyms"),
51 minimum-matching is turned on, and translation of values is not
52 performed.
53 A hash (not hash reference) containing the processed options is
55 returned.
56 %options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});
58 iparse( \%defaults, \%user_options)
60 Same as "parse" but matching is case insensitive
61 Default Synonyms
63 The following default synonyms are available in the non-OO interface:
64 COLOR => COLOUR
66 COLOUR => COLOR
67 CENTER => CENTRE
68 CENTRE => CENTER
69
71 The following methods are available to PDL::Options objects.
72 new()
74 Constructor. Creates the object. With an optional argument can also
75 set the default options.
76 extend (\%options)
78 This will copy the existing options object and extend it with the
79 requested extra options.
80 defaults( \%defaults )
82 Method to set or return the current defaults. The argument should
83 be a reference to a hash. The hash reference is returned if no
84 arguments are supplied.
85 The current values are reset whenever the defaults are changed.
87 add_synonym (\%synonyms)
89 Method to add another synonym to an option set The argument should
90 be a reference to a hash.
91 add_translation (\%translation)
93 Method to add another translation rule to an option set. The
94 argument should be a reference to a hash.
95 synonyms( \%synonyms )
97 Method to set or return the current synonyms. The argument should
98 be a reference to a hash. The hash reference is returned if no
99 arguments are supplied.
100 This allows you to provide alternate keywords (such as allowing
102 'COLOR' as an option when your defaults uses 'COLOUR').
103 current
105 Returns the current state of the options. This is returned as a
106 hash reference (although it is not a reference to the actual hash
107 stored in the object). If full_options() is true the full options
108 hash is returned, if full_options() is false only the modified
109 options are returned (as set by the last call to options()).
110 clear_current
112 This routine clears the 'state' of the "PDL::Options" object so
113 that the next call to current will return an empty list
114 translation
116 Provide translation of options to more specific values that are
117 recognised by the program. This allows, for example, the automatic
118 translation of the string 'red' to '#ff0000'.
119 This method can be used to setup the dictionary and is hash
121 reference with the following structure:
122 OPTIONA => {
124 'string1' => decode1,
125 'string2' => decode2
126 },
127 OPTIONB => {
128 's4' => decodeb1,
129 }
130 etc....
131 Where OPTION? corresponds to the top level option name as stored in
133 the defaults array (eg LINECOLOR) and the anonymous hashes provide
134 the translation from string1 ('red') to decode1 ('#ff0000').
135 An options string will be translated automatically during the main
137 options() processing if autotrans() is set to true. Else
138 translation can be initiated by the user using the translate()
139 method.
140 incremental
142 Specifies whether the user defined options will be treated as
143 additions to the current state of the object (1) or modifications
144 to the default values only (0).
145 Can be used to set or return this value. Default is false.
147 full_options
149 Governs whether a complete set of options is returned (ie defaults
150 + expanded user options), true, or if just the expanded user
151 options are returned, false (ie the values specified by the user).
152 This can be useful when you are only interested in the changes to
154 the options rather than knowing the full state. (For example, if
155 defaults contains keys for COLOUR and LINESTYLE and the user
156 supplied a key of COL, you may simply be interested in the
157 modification to COLOUR rather than the state of LINESTYLE and
158 COLOUR.)
159 Default is true.
161 casesens
163 Specifies whether the user defined options will be processed
164 independent of case (0) or not (1). Default is to be case
165 insensitive.
166 Can be used to set or return this value.
168 minmatch
170 Specifies whether the user defined options will be minimum matched
171 with the defaults (1) or whether the user defined options should
172 match the default keys exactly. Defaults is true (1).
173 If a particular key matches exactly (within the constraints imposed
175 bby case sensitivity) this key will always be taken as correct even
176 if others are similar. For example COL would match COL and COLOUR
177 but this implementation will always return COL in this case (note
178 that for CO it will return both COL and COLOUR and pick one at
179 random.
180 Can be used to set or return this value.
182 autotrans
184 Specifies whether the user defined options will be processed via
185 the translate() method immediately following the main options
186 parsing. Default is to autotranslate (1).
187 Can be used to set or return this value.
189 casesenstrans
191 Specifies whether the keys in the options hash will be matched
192 insensitive of case (0) during translation() or not (1). Default is
193 to be case insensitive.
194 Can be used to set or return this value.
196 minmatchtrans
198 Specifies whether the keys in the options hash will be minimum
199 matched during translation(). Default is false (0).
200 If a particular key matches exactly (within the constraints imposed
202 bby case sensitivity) this key will always be taken as correct even
203 if others are similar. For example COL would match COL and COLOUR
204 but this implementation will always return COL in this case (note
205 that for CO it will return both COL and COLOUR and pick one at
206 random.
207 Can be used to set or return this value.
209 warnonmissing
211 Turn on or off the warning message printed when an options is not
212 in the options hash. This can be convenient when a user passes a
213 set of options that has to be parsed by several different option
214 objects down the line.
215 debug
217 Turn on or off debug messages. Default is off (0). Can be used to
218 set or return this value.
219 options
221 Takes a set of user-defined options (as a reference to a hash) and
222 merges them with the current state (or the defaults; depends on the
223 state of incremental()).
224 The user-supplied keys will be compared with the defaults. Case
226 sensitivity and minimum matching can be configured using the
227 mimatch() and casesens() methods.
228 A warning is raised if keys present in the user options are not
230 present in the defaults unless warnonmissing is set.
231 A reference to a hash containing the merged options is returned.
233 $merged = $opt->options( { COL => 'red', Width => 1});
235 The state of the object can be retrieved after this by using the
237 current() method or by using the options() method with no
238 arguments. If full_options() is true, all options are returned
239 (options plus overrides), if full_options() is false then only the
240 modified options are returned.
241 Synonyms are supported if they have been configured via the
243 synonyms() method.
244 translate
246 Translate the current option values (eg those set via the options()
247 method) using the provided translation().
248 This method updates the current state of the object and returns the
250 updated options hash as a reference.
251 $ref = $opt->translate;
253
255 Two examples are shown. The first uses the simplified interface and the
256 second uses the object-oriented interface.
257
259 use PDL::Options (':Func');
260 %options = parse( {
262 LINE => 1,
263 COLOUR => 'red',
264 },
265 {
266 COLOR => 'blue'
267 }
268 );
269 This will return a hash containing
271 %options = (
273 LINE => 1,
274 COLOUR => 'blue'
275 )
276
278 The following example will try to show the main points:
279 use PDL::Options ();
281 # Create new object and supply defaults
283 $opt = new PDL::Options( { Colour => 'red',
284 LineStyle => 'dashed',
285 LineWidth => 1
286 }
287 );
288 # Create synonyms
290 $opt->synonyms( { Color => 'Colour' } );
291 # Create translation dictionary
293 $opt->translation( { Colour => {
294 'blue' => '#0000ff',
295 'red' => '#ff0000',
296 'green'=> '#00ff00'
297 },
298 LineStyle => {
299 'solid' => 1,
300 'dashed' => 2,
301 'dotted' => 3
302 }
303 }
304 );
305 # Generate and parse test hash
307 $options = $opt->options( { Color => 'green',
308 lines => 'solid',
309 }
310 );
311 When this code is run, $options will be the reference to a hash
313 containing the following:
314 Colour => '#00ff00',
316 LineStyle => 1,
317 LineWidth => 1
318 If full_options() was set to false (0), $options would be a reference
320 to a hash containing:
321 Colour => '#00ff00',
323 LineStyle => 1
324 Minimum matching and case insensitivity can be configured for both the
326 initial parsing and for the subsequent translating. The translation can
327 be turned off if not desired.
328 Currently synonyms are not available for the translation although this
330 could be added quite simply.
331
333 Copyright (C) Tim Jenness 1998 (t.jenness@jach.hawaii.edu). All rights
334 reserved. There is no warranty. You are allowed to redistribute this
335 software / documentation under certain conditions. For details, see the
336 file COPYING in the PDL distribution. If this file is separated from
337 the PDL distribution, the copyright notice should be included in the
338 file.
339perl v5.34.0 2021-08-16 Options(3)