Quiq::Parameters - Verarbeitung von Programm- und Methodenparametern
Quiq::Object
# 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);
Der erste Parameter entscheidet, ob die Optionswerte an ein Optionsobjekt (0) oder an Variablen (1) zugewiesen werden.
Die Parameter sind Attribut/Wert-Paare, die in @optRef bzw. @optVal spezifiziert sind. Argumente gibt es nicht.
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.
undef
Parameterliste, z.B. @ARGV oder @_.
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.
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.
Wie @optVal, nur dass anstelle des Defaultwerts eine Variablenreferenz angegeben ist. An diese Variable wird der Optionswert zugewiesen.
Array-Objekt mit den (maximal $maxArgs) Argumenten aus @params.
Hash-Objekt mit den Optionen aus @params gemäß @optVal.
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); }
Die nachfolgenden Methoden sind auf Basis der Methode extract() implementiert. Sie realsieren Vereinfachungen für bestimmte Anwendungsfälle.
$class->extractPropertiesToVariables(\@params,@optRef);
Parameterliste, z.B. @_.
Liste der Properties (und Optionen) und ihrer Variablenreferenzen.
Nichts.
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.
Methode, die eine WikiMedia-Tabelle generiert. Die Tabelleneigenschaften werden als Property/Wert-Paare übergeben:
sub table { my $self = shift; # @_: @keyVal my $alignA = []; my $bodyBackground = '#ffffff'; my $caption = undef; my $rowA = []; my $titleBackground = '#e8e8e8'; my $titleA = []; my $valueCb = undef; Quiq::Parameters->extractPropertiesToVariables(\@_, alignments => \$alignA, bodyBackground => \$bodyBackground, caption => \$caption, rows => \$rowA, titleBackground => \$titleBackground, titles => \$titleA, valueCallback => \$valueCb, ); ... }
@args | $argA = $class->extractToVariables(\@params,$minArgs,$maxArgs,@optRef);
Mindestanzahl an Argumenten.
$ maxArgs Maximale Anzahl an Argumenten, undef bedeutet beliebig viele.
Liste der Optionen und ihrer Variablenreferenzen.
Referenz auf die Liste der extrahierten Argumente.
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.
Konstruktor mit einer variablen Anzahl an Argumenten und zwei Optionen:
sub new { my $class = shift; # @_: $url,@opt -or- $url,$user,$passw,@opt my $color = 1; my $debug = 0; my $argA = Quiq::Parameters->extractToVariables(\@_,1,3, -color => \$color, -debug => \$debug, ); my ($url,$user,$password) = @$argA; ... }
1.130
Frank Seitz, http://fseitz.de/
Copyright (C) 2019 Frank Seitz
This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Quiq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Quiq
CPAN shell
perl -MCPAN -e shell install Quiq
For more information on module installation, please visit the detailed CPAN module installation guide.