/ 
Quiq-1.220
River stage zero No dependents
/ Quiq::Parameters

NAME

Quiq::Parameters - Verarbeitung von Programm- und Methodenparametern

BASE CLASS

Quiq::Object

METHODS

Universelle Methode

extract() - Extrahiere Optionen und Argumente

Synopsis

# Options/Property-Werte an Variablen zuweisen
$argA = $class->extract(1,$properties,$encoding,\@params,
    $maxArgs,@optRef);

# Options/Property-Wertpaare per Optionsobjekt zurückgeben
($argA,$opt) = $class->extract(0,$properties,$encoding,\@params,
    $maxArgs,@optVal);

Arguments

$varMode (0 oder 1)

Legt fest, ob die Optionswerte an ein Optionsobjekt (0) oder an Variablen (1) zugewiesen werden.

$properties (0 oder 1)

Die Parameter sind Attribut/Wert-Paare, die in @optRef bzw. @optVal spezifiziert sind. Argumente gibt es nicht.

$encoding

Programm-Parameter müssen ggf. dekodiert werden. Dies geschieht, wenn mit diesem Parameter ein Encoding vereinbart wird. Sollen die Parameter nicht dekodiert werden, was bei der Verarbeitung von Methodenparametern typischerweise der Fall ist, wird undef angegeben.

@params

Parameterliste, z.B. @ARGV oder @_.

$maxArgs

Anzahl der maximal zu extrahierenden Argumente (Argument = Parameter, der nicht mit einem Bindestrich beginnt). Die Anzahl der tatsächlich extrahierten Argumente kann niedriger sein, wenn weniger Argumente vorhanden sind. Sind mehr Argumente in @params vorhanden, bleiben die überzähligen Argumente in @params stehen. undef bedeutet eine unbegrenzte Anzahl.

@optVal

Liste der Optionen (Option = Parameter, der mit einem Bindestrich beginnt) und ihrer Defaultwerte. Optionen und ihre Werte, die in der Liste nicht vorkommen, werden nicht extrahiert.

@optRef

Wie @optVal, nur dass anstelle des Defaultwerts eine Variablenreferenz angegeben ist. An diese Variable wird der Optionswert zugewiesen.

Returns

$argA

Array-Objekt mit den (maximal $maxArgs) Argumenten aus @params.

$opt

Hash-Objekt mit den Optionen aus @params gemäß @optVal.

Description

Extrahiere Argumente und Optionen aus der Parameterliste @params. Enthält die Parameterliste mehr Argumente oder Optionen als vorgegeben sind, bleiben diese in @params stehen. Dies eröffnet die Möglichkeit, Argumente und Optionen über mehrere Aufrufebenen sukzessive zu verarbeiten.

Fehlerbehandlung

Die Methode kennt keine Fehler. Überzählige Argumente oder Optionen, die nicht in der Optionsliste @optVal (bzw. @optRef) vorkommen, bleiben in @params, werden also nicht extrahiert. Die Anzahl der Argumente $maxArgs ist eine maximale Anzahl, die unterschritten werden kann.

Es obliegt dem Aufrufer, durch Tests auf @params und @$argA zu prüfen, ob beim Aufruf des Programms oder der Methode zu viele Parameter (= @params wurde nicht komplett geleert) oder zu wenige Parameter (= @$argA enthält nicht genügend Elemente) übergeben wurden.

Eine mögliche Wrapper-Methode für eine finale Parameterverarbeitung, die bei zu wenig/zu vielen Argumenten oder nicht vereinbarten Optionen eine Exception wirft:

sub parameters {
    my ($self,$varMode,$properties,$encoding,$paramA,$minArgs,
        $maxArgs) = splice @_,0,6;

    my ($argA,$opt) = Quiq::Parameters->extract($varMode,$properties,
        $encoding,$paramA,$maxArgs,@_);
    if (@$paramA) {
        die "ERROR: Unexpected parameter(s): @$paramA\n";
    }
    elsif (@$argA < $minArgs) {
        die "ERROR: Too few arguments\n";
    }

    if ($varMode) {
        return wantarray? @$argA: $argA;
    }

    return ($argA,$opt);
}

Spezialisierte Methoden

Die nachfolgenden Methoden sind auf Basis der Methode extract() implementiert. Sie realsieren Vereinfachungen für bestimmte Anwendungsfälle.

extractPropertiesToObject() - Extrahiere Properties und weise sie an Hash-Objekt zu

Synopsis

$opt = $class->extractPropertiesToObject(\@params,@propVal);

Arguments

@params

Parameterliste, z.B. @_.

@propVal

Liste der Properties (und Optionen) und ihrer Defaultwerte.

Returns

Hash-Objekt mit Eigenschaften (und Optionen)

Description

Extrahiere Properties (und Optionen) aus der Parameterliste @params. Enthält die Parameterliste unbekannte Properties (oder Optionen), wird eine Exception geworfen. Die Methode wird typischerweise zur Verarbeitung von Methodenparametern genutzt.

Example

Methode, die eine WikiMedia-Tabelle generiert. Die Tabelleneigenschaften werden als Property/Wert-Paare übergeben:

sub table {
    my $self = shift;
    # @_: @keyVal

    my $opt = Quiq::Parameters->extractPropertiesToObject(\@_,
        alignments => [],
        bodyBackground => '#ffffff',
        caption => undef,
        rows => [],
        titleBackground => '#e8e8e8',
        titles => [],
        valueCallback => undef,
    );
    ...
}

extractPropertiesToVariables() - Extrahiere Properties und weise sie an Variablen zu

Synopsis

$class->extractPropertiesToVariables(\@params,@propRef);

Arguments

@params

Parameterliste, z.B. @_.

@propRef

Liste der Properties (und ggf. Optionen) und ihrer Variablenreferenzen.

Description

Extrahiere Properties (und ggf. Optionen) aus der Parameterliste @params. Enthält die Parameterliste unbekannte Properties (oder Optionen) wird eine Exception geworfen. Die Methode wird typischerweise zur Verarbeitung von Methodenparametern genutzt.

extractToObject() - Extrahiere Parameter und speichere Optionen in Objekt

Synopsis

($argA,$opt) = $class->extractToObject(\@params,$minArgs,$maxArgs,@optVal);

Arguments

@params

Parameterliste, z.B. @_.

$minArgs

Mindestanzahl an Argumenten.

$maxArgs

Maximale Anzahl an Argumenten, undef bedeutet beliebig viele.

@optVal

Liste der Optionen und ihrer Defaultwerte.

Returns

$argA

Referenz auf die Liste der extrahierten Argumente.

$opt

Hash-Objekt mit den Optionen aus @params gemäß @optVal.

Description

Extrahiere Argumente und Optionen aus der Parameterliste @params. Enthält die Parameterliste unbekannte Optionen oder zu wenige oder zu viele Argumente, wird eine Exception geworfen.

VERSION

1.220

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.