Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Options(3)	      User Contributed Perl Documentation	    Options(3)

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.

perl v5.32.0			  2018-05-05			    Options(3)

NAME | SYNOPSIS | DESCRIPTION | Utility functions | NON-OO INTERFACE | METHODS | EXAMPLE | Non-OO | Object oriented | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDL::Options&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help