Provided by: pdl_2.018-1ubuntu4_amd64 bug

NAME

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

SYNOPSIS

         use PDL::Options;

         %hash = parse( \%defaults, \%user_options);

         use PDL::Options ();

         $opt = new PDL::Options;
         $opt = new PDL::Options ( \%defaults );

         $opt->defaults ( \%defaults );
         $opt->synonyms ( { 'COLOR' => 'COLOUR' } );

         $hashref = $opt->defaults;

         $opt->options ( \%user_options );

         $hashref = $opt->options;

         $opt->incremental(1);
         $opt->full_options(0);

DESCRIPTION

       Object to simplify option passing for PerlDL subroutines.  Allows you to merge a user
       defined options with defaults.  A simplified (non-OO) interface is provided.

Utility functions

   ifhref
         parse({Ext => 'TIF', ifhref($opt)});

       just return the argument if it is a hashref otherwise return an empty hashref. Useful in
       conjunction with parse to return just the default values if argument is not a hash ref

NON-OO INTERFACE

       A simplified non-object oriented interface is provided.  These routines are exported into
       the callers namespace by default.

       parse( \%defaults, \%user_options)
           This will parse user options by using the defaults.  The following settings are used
           for parsing: The options are case-sensitive, a default synonym table is consulted (see
           "Default Synonyms"), minimum-matching is turned on, and translation of values is not
           performed.

           A hash (not hash reference) containing the processed options is returned.

             %options = parse( { LINE => 1, COLOUR => 'red'}, { COLOR => 'blue'});

       iparse( \%defaults, \%user_options)
           Same as "parse" but matching is case insensitive

   Default Synonyms
       The following default synonyms are available in the non-OO interface:

         COLOR  => COLOUR
         COLOUR => COLOR
         CENTER => CENTRE
         CENTRE => CENTER

METHODS

       The following methods are available to PDL::Options objects.

       new()
           Constructor. Creates the object. With an optional argument can also set the default
           options.

       extend (\%options)
           This will copy the existing options object and extend it with the requested extra
           options.

       defaults( \%defaults )
           Method to set or return the current defaults. The argument should be a reference to a
           hash. The hash reference is returned if no arguments are supplied.

           The current values are reset whenever the defaults are changed.

       add_synonym (\%synonyms)
           Method to add another synonym to an option set The argument should be a reference to a
           hash.

       add_translation (\%translation)
           Method to add another translation rule to an option set.  The argument should be a
           reference to a hash.

       synonyms( \%synonyms )
           Method to set or return the current synonyms. The argument should be a reference to a
           hash. The hash reference is returned if no arguments are supplied.

           This allows you to provide alternate keywords (such as allowing 'COLOR' as an option
           when your defaults uses 'COLOUR').

       current
           Returns the current state of the options. This is returned as a hash reference
           (although it is not a reference to the actual hash stored in the object). If
           full_options() is true the full options hash is returned, if full_options() is false
           only the modified options are returned (as set by the last call to options()).

       clear_current
           This routine clears the 'state' of the "PDL::Options" object so that the next call to
           current will return an empty list

       translation
           Provide translation of options to more specific values that are recognised by the
           program. This allows, for example, the automatic translation of the string 'red' to
           '#ff0000'.

           This method can be used to setup the dictionary and is hash reference with the
           following structure:

               OPTIONA => {
                           'string1' => decode1,
                           'string2' => decode2
                           },
               OPTIONB => {
                           's4' => decodeb1,
                          }
               etc....

           Where OPTION? corresponds to the top level option name as stored in the defaults array
           (eg LINECOLOR) and the anonymous hashes provide the translation from string1 ('red')
           to decode1 ('#ff0000').

           An options string will be translated automatically during the main options()
           processing if autotrans() is set to true. Else translation can be initiated by the
           user using the translate() method.

       incremental
           Specifies whether the user defined options will be treated as additions to the current
           state of the object (1) or modifications to the default values only (0).

           Can be used to set or return this value.  Default is false.

       full_options
           Governs whether a complete set of options is returned (ie defaults + expanded user
           options), true, or if just the expanded user options are returned, false (ie the
           values specified by the user).

           This can be useful when you are only interested in the changes to the options rather
           than knowing the full state. (For example, if defaults contains keys for COLOUR and
           LINESTYLE and the user supplied a key of COL, you may simply be interested in the
           modification to COLOUR rather than the state of LINESTYLE and COLOUR.)

           Default is true.

       casesens
           Specifies whether the user defined options will be processed independent of case (0)
           or not (1). Default is to be case insensitive.

           Can be used to set or return this value.

       minmatch
           Specifies whether the user defined options will be minimum matched with the defaults
           (1) or whether the user defined options should match the default keys exactly.
           Defaults is true (1).

           If a particular key matches exactly (within the constraints imposed bby case
           sensitivity) this key will always be taken as correct even if others are similar. For
           example COL would match COL and COLOUR but this implementation will always return COL
           in this case (note that for CO it will return both COL and COLOUR and pick one at
           random.

           Can be used to set or return this value.

       autotrans
           Specifies whether the user defined options will be processed via the translate()
           method immediately following the main options parsing. Default is to autotranslate
           (1).

           Can be used to set or return this value.

       casesenstrans
           Specifies whether the keys in the options hash will be matched insensitive of case (0)
           during translation() or not (1). Default is to be case insensitive.

           Can be used to set or return this value.

       minmatchtrans
           Specifies whether the keys in the options hash  will be minimum matched during
           translation(). Default is false (0).

           If a particular key matches exactly (within the constraints imposed bby case
           sensitivity) this key will always be taken as correct even if others are similar. For
           example COL would match COL and COLOUR but this implementation will always return COL
           in this case (note that for CO it will return both COL and COLOUR and pick one at
           random.

           Can be used to set or return this value.

       warnonmissing
           Turn on or off the warning message printed when an options is not in the options hash.
           This can be convenient when a user passes a set of options that has to be parsed by
           several different option objects down the line.

       debug
           Turn on or off debug messages. Default is off (0).  Can be used to set or return this
           value.

       options
           Takes a set of user-defined options (as a reference to a hash) and merges them with
           the current state (or the defaults; depends on the state of incremental()).

           The user-supplied keys will be compared with the defaults.  Case sensitivity and
           minimum matching can be configured using the mimatch() and casesens() methods.

           A warning is raised if keys present in the user options are not present in the
           defaults unless warnonmissing is set.

           A reference to a hash containing the merged options is returned.

             $merged = $opt->options( { COL => 'red', Width => 1});

           The state of the object can be retrieved after this by using the current() method or
           by using the options() method with no arguments.  If full_options() is true, all
           options are returned (options plus overrides), if full_options() is false then only
           the modified options are returned.

           Synonyms are supported if they have been configured via the synonyms() method.

       translate
           Translate the current option values (eg those set via the options() method) using the
           provided translation().

           This method updates the current state of the object and returns the updated options
           hash as a reference.

               $ref = $opt->translate;

EXAMPLE

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

Non-OO

          use PDL::Options (':Func');

          %options = parse( {
                          LINE => 1,
                          COLOUR => 'red',
                         },
                         {
                          COLOR => 'blue'
                         }
                       );

       This will return a hash containing

           %options = (
                        LINE => 1,
                        COLOUR => 'blue'
                      )

Object oriented

       The following example will try to show the main points:

          use PDL::Options ();

          # Create new object and supply defaults
          $opt = new PDL::Options(   { Colour => 'red',
                                       LineStyle => 'dashed',
                                       LineWidth => 1
                                     }
                                  );

          # Create synonyms
          $opt->synonyms( { Color => 'Colour' } );

          # Create translation dictionary
          $opt->translation( { Colour => {
                                'blue' => '#0000ff',
                                'red'  => '#ff0000',
                                'green'=> '#00ff00'
                                       },
                               LineStyle => {
                                'solid' => 1,
                                'dashed' => 2,
                                'dotted' => 3
                                }
                             }
                           );

          # Generate and parse test hash
          $options = $opt->options( { Color => 'green',
                                      lines => 'solid',
                                     }
                                  );

       When this code is run, $options will be the reference to a hash containing the following:

          Colour => '#00ff00',
          LineStyle => 1,
          LineWidth => 1

       If full_options() was set to false (0), $options would be a reference to a hash
       containing:

          Colour => '#00ff00',
          LineStyle => 1

       Minimum matching and case insensitivity can be configured for both the initial parsing and
       for the subsequent translating. The translation can be turned off if not desired.

       Currently synonyms are not available for the translation although this could be added
       quite simply.

AUTHOR

       Copyright (C) Tim Jenness 1998 (t.jenness@jach.hawaii.edu).  All rights reserved. There is
       no warranty. You are allowed to redistribute this software / documentation under certain
       conditions. For details, see the file COPYING in the PDL distribution. If this file is
       separated from the PDL distribution, the copyright notice should be included in the file.