1Options(3)            User Contributed Perl Documentation           Options(3)
2
3
4

NAME

6       PDL::Options - simplifies option passing by hash in PerlDL
7

SYNOPSIS

9         use PDL::Options;
10
11         %hash = parse( \%defaults, \%user_options);
12
13         use PDL::Options ();
14
15         $opt = new PDL::Options;
16         $opt = new PDL::Options ( \%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

DESCRIPTION

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

Utility functions

36   ifhref
37         parse({Ext => 'TIF', ifhref($opt)});
38
39       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

NON-OO INTERFACE

44       A simplified non-object oriented interface is provided.  These routines
45       are exported into the callers namespace by default.
46
47       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
54           A hash (not hash reference) containing the processed options is
55           returned.
56
57             %options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});
58
59       iparse( \%defaults, \%user_options)
60           Same as "parse" but matching is case insensitive
61
62   Default Synonyms
63       The following default synonyms are available in the non-OO interface:
64
65         COLOR  => COLOUR
66         COLOUR => COLOR
67         CENTER => CENTRE
68         CENTRE => CENTER
69

METHODS

71       The following methods are available to PDL::Options objects.
72
73       new()
74           Constructor. Creates the object. With an optional argument can also
75           set the default options.
76
77       extend (\%options)
78           This will copy the existing options object and extend it with the
79           requested extra options.
80
81       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
86           The current values are reset whenever the defaults are changed.
87
88       add_synonym (\%synonyms)
89           Method to add another synonym to an option set The argument should
90           be a reference to a hash.
91
92       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
96       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
101           This allows you to provide alternate keywords (such as allowing
102           'COLOR' as an option when your defaults uses 'COLOUR').
103
104       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
111       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
115       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
120           This method can be used to setup the dictionary and is hash
121           reference with the following structure:
122
123               OPTIONA => {
124                           'string1' => decode1,
125                           'string2' => decode2
126                           },
127               OPTIONB => {
128                           's4' => decodeb1,
129                          }
130               etc....
131
132           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
136           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
141       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
146           Can be used to set or return this value.  Default is false.
147
148       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
153           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
160           Default is true.
161
162       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
167           Can be used to set or return this value.
168
169       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
174           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
181           Can be used to set or return this value.
182
183       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
188           Can be used to set or return this value.
189
190       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
195           Can be used to set or return this value.
196
197       minmatchtrans
198           Specifies whether the keys in the options hash  will be minimum
199           matched during translation(). Default is false (0).
200
201           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
208           Can be used to set or return this value.
209
210       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
216       debug
217           Turn on or off debug messages. Default is off (0).  Can be used to
218           set or return this value.
219
220       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
225           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
229           A warning is raised if keys present in the user options are not
230           present in the defaults unless warnonmissing is set.
231
232           A reference to a hash containing the merged options is returned.
233
234             $merged = $opt->options( { COL => 'red', Width => 1});
235
236           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
242           Synonyms are supported if they have been configured via the
243           synonyms() method.
244
245       translate
246           Translate the current option values (eg those set via the options()
247           method) using the provided translation().
248
249           This method updates the current state of the object and returns the
250           updated options hash as a reference.
251
252               $ref = $opt->translate;
253

EXAMPLE

255       Two examples are shown. The first uses the simplified interface and the
256       second uses the object-oriented interface.
257

Non-OO

259          use PDL::Options (':Func');
260
261          %options = parse( {
262                          LINE => 1,
263                          COLOUR => 'red',
264                         },
265                         {
266                          COLOR => 'blue'
267                         }
268                       );
269
270       This will return a hash containing
271
272           %options = (
273                        LINE => 1,
274                        COLOUR => 'blue'
275                      )
276

Object oriented

278       The following example will try to show the main points:
279
280          use PDL::Options ();
281
282          # Create new object and supply defaults
283          $opt = new PDL::Options(   { Colour => 'red',
284                                       LineStyle => 'dashed',
285                                       LineWidth => 1
286                                     }
287                                  );
288
289          # Create synonyms
290          $opt->synonyms( { Color => 'Colour' } );
291
292          # 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
306          # Generate and parse test hash
307          $options = $opt->options( { Color => 'green',
308                                      lines => 'solid',
309                                     }
310                                  );
311
312       When this code is run, $options will be the reference to a hash
313       containing the following:
314
315          Colour => '#00ff00',
316          LineStyle => 1,
317          LineWidth => 1
318
319       If full_options() was set to false (0), $options would be a reference
320       to a hash containing:
321
322          Colour => '#00ff00',
323          LineStyle => 1
324
325       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
329       Currently synonyms are not available for the translation although this
330       could be added quite simply.
331

AUTHOR

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.
339
340
341
342perl v5.34.0                      2021-08-16                        Options(3)
Impressum