# Opt reference

Triceps::Opt is not a class but a package with a set of functions that help with processing the arguments to the class constructors and other functions when these arguments are represented as options.

    &Triceps::Opt::parse($class, \%instance, \%optdescr, @opts);

Checks the options and copies their values into a class instance (or generally into a hash). Usually used with the class constructors, so the semantics of the arguments is oriented towards this usage. Confesses on errors.

    $class

is the calling class name, for the error messages.

    \%instance

is the reference to the object instance where to copy the options to.

    \%optdescr

is the reference to a hash describing the valid options.

    @opts

(all the remaining arguments) are the option name-value pairs passed through from the class constructor.

The entries in

    \%optdescr

are references to arrays, each of them describing an option. They are usually written in the form:

    optionName => [ $defaultValue, \&checkFunc ],

If there is no default value, it can be set to

    undef

.

    \&checkFunc

is a reference to a function that is used to check the option value. If the value is correct, the function returns, if incorrect, it confesses with a descriptive message. The default value is filled in for the missing options before the check function is called. If no checking is needed, the function reference may be

    undef

. The check function is called as:

    &$checkFunc($optionValue, $optionName, $class, $instance);

The class and instance are passed through from the arguments of

    parse()

.

A user-defined anonymous function can be used to combine multiple checking functions, for example:

    table => [ undef, sub {
    	&Triceps::Opt::ck_mandatory(@_);
    	&Triceps::Opt::ck_ref(@_, "Triceps::Table");
    } ],

A number of ready checking function is provided. When these functions require extra arguments, by convention they go after the common arguments, as shown for

    ck_ref()

above.

-     Triceps::Opt::ck_mandatory

  checks that the value is defined.

-     Triceps::Opt::ck_ref

  checks that the value is a reference to a particular class, or a class derived from it. Just give the class name as the extra argument. Or, to check that the reference is to array or hash, make the argument

      "ARRAY"

  or

      "HASH"

  . Or an empty string

      ""

  to check that it's not a reference at all. For the arrays and hashes it can also check the values contained in them for being references to the correct types: give that type as the second extra argument. But it doesn't go deeper than that, just one nesting level. It might be extended later, but for now one nesting level has been enough.

-     Triceps::Opt::ck_refscalar

  checks that the value is a reference to a scalar. This is designed to check the arguments which are used to return data back to the caller, and it would accept any previous value in that scalar: an actual scalar value, an

      undef

  or a reference, since it's about to be overwritten anyway.

The

    ck_ref()

and

    ck_refscalar()

allow the value to be undefined, so they can safely be used on the truly optional options. When I come up with more of the useful check functions, I'll add them.

    &Triceps::Opt::handleUnitTypeLabel($caller,
    	$nameUnit, \$refUnit,
    	$nameRowType, \$refRowType,
    	$nameLabel, \$refLabel);

A special post-processing that takes care of sorting out the compatibility of the options for the unit, input row type and the input label. Usually called after

    parse()

. Confesses on errors.

    $caller

is the description of the caller, for the error messages. The rest are the pairs of the option names and the references to the option values in the instance hash.

Treats the options for input row type and input label as mutually exclusive but with exactly one of them required. If the input row type is used then the unit option is also required. If the input label is used, the unit is optional, but if it's specified anyway, the unit in the option must match the unit of the input label. If the input label is used, the values for the input row type and the unit are extracted from the input label and set into the references.

    $which = &Triceps::Opt::checkMutuallyExclusive(
    	$caller, $mandatory, $optName1, optValue1, ...);

Checks a set of mutually exclusive options. Usually called after

    parse()

. Confesses on errors, returns the name of the only defined option on success. If no options are defined, returns

    undef

.

    $caller

is the description of the caller, for the error messages.

    $mandatory

is a flag telling that exactly one of the options must be defined; or the check will confess. The rest are the option name-value pairs (unlike

    handleUnitTypeLabel()

, these are values, not references to them).
Opt