NAME

Quiq::Option - Verarbeitung von Programm- und Methoden-Optionen

BASE CLASS

Quiq::Object

METHODS

Klassenmethoden

extract() - Extrahiere Optionen aus Argumentliste

Synopsis

$opt = $class->extract(@opt,\@args,@keyVal); # Options-Objekt
$class->extract(@opt,\@args,@keyVal);        # Options-Variablen

Options

-dontExtract => $bool (Default: 0)

Entferne die Optionen nicht aus der Argumentliste.

-mode => 'strict'|'sloppy' (Default: 'strict')

Im Falle von -mode=>'strict' (dem Default), wird eine Exception ausgelöst, wenn eine unbekannte Option vorkommt. Im Falle von -mode=>'sloppy' wird das Argument stillschweigend übergangen.

-properties => $bool (Default: 0)

Argumentliste aus Schlüssel/Wert-Paaren, bei denen die Schlüssel nicht mit einem Bindestrich (-) beginnen. Eine Unterscheidung zwischen Optionen und Argumenten gibt es nicht.

-simpleMessage => $bool (Default: 0)

Wirf im Falle eines Fehlers eine einzeilige Fehlermeldung als Exception.

Description

Extrahiere die Optionen @keyVal aus der Argumentliste @args und weise sie im Void-Kontext Variablen zu oder im Skalar-Kontext einem Optionsobjekt.

Schreibweisen für eine Option

Eine Option kann auf verschiedene Weisen angegeben werden.

Als Programm-Optionen:

--log-level=5    (ein Argument)
--logLevel=5     (mixed case)

Als Methoden-Optionen:

-log-level 5     (zwei Argumente)
-logLevel 5      (mixed case)

Die Schreibweise mit zwei Bindestrichen wird typischerweise bei Programmaufrufen angegeben. Die Option besteht aus einem Argument, bei dem der Wert durch ein Gleichheitszeichen vom Optionsnamen getrennt angegeben ist.

Die Schreibweise mit einem Bindestrich wird typischerweise bei Methodenaufrufen angegeben. In Perl ist bei einem Bindestrich kein Quoting nötig. Die Option besteht aus zwei Argumenten.

Beide Schreibweisen sind gleichberechtigt, so dass derselbe Code sowohl Programm- als auch Methodenoptionen verarbeiten kann.

Ist -properties=>1 gesetzt, ist die Argumentliste eine Abfolge Schlüssel/Wert-Paaren ohne Bindestrich als Options-Kennzeichen:

a 1 b 2 c 3

Examples

• Instantiierung eines Options-Objekts:

  sub meth {
      my $self = shift;
      # @_: @args
  
      my $opt = Quiq::Option->extract(\@_,
          -logLevel => 1,
          -verbose => 0,
      );
      ...
  
      if ($opt->verbose) {
          ...
      }
  }

  Das gelieferte Options-Objekt $opt ist eine Quiq::Hash-Instanz. Die Schlüssel haben keine führenden Bindestriche. Eine Abfrage des Optionswerts ist per Methode möglich:

  $verbose = $opt->verbose;

• Setzen von Options-Variablen:

  sub meth {
      my $self = shift;
      # @_: @args
  
      my $logLevel = 1;
      my $verbose = 0;
  
      Quiq::Option->extract(\@_,
          -logLevel => \$logLevel,
          -verbose => \$verbose,
      );
      ...
  
      if ($verbose) {
          ...
      }
  }

• Optionen bei Programmaufruf:

  $ prog --log-level=2 --verbose file.txt

• Optionen bei Methodenaufruf:

  $prog->begin(-logLevel=>2,-verbose=>1,'file.txt');

• Abfrage einer Option:

  $logLevel = $opt->logLevel;

• Abfrage mehrerer Optionen:

  ($verbose,$logLevel) = $opt->get('verbose','logLevel');

extractAll() - Extrahiere alle Optionen als Liste

Synopsis

@opts|$optA = $class->extractAll(\@arr);

Description

Extrahiere alle Option/Wert-Paare aus @arr und liefere diese als Liste zurück. Im Skalarkontext liefere eine Referenz auf die Liste.

extractMulti() - Extrahiere Mehrwert-Optionen

Synopsis

$class->extractMulti(@opt,\@arr,$key=>$ref,...);

Options

-sloppy => $bool (Default: 0)

Übergehe unbekannte Optionen.

Description

Extrahiere aus Array @arr die Werte zu den angegebenen Schlüsseln $key und weise diese an die Variablen-Referenzen $ref zu. Die Methode liefert keinen Wert zurück.

Eine Referenz kann eine Skalar- oder eine Arrayreferenz sein. Im Fall einer Skalarreferenz wird der Wert zugewiesen. Im Falle einer Array-Referenz werden mehrere aufeinanderfolgende Werte in dem Array gesammelt.

Für das Hinzufügen einer Default-Option, siehe Beispiel.

Example

# Optionen

my @select;
my @from;
my @where;
my $limit;

unshift @_,'-select'; # Default-Option

Quiq::Option->extractMulti(\@_,
    -select => \@select,
    -from => \@from,
    -where => \@where,
    -limit => \$limit,
);

unless (@from) {
    die "FROM-Klausel fehlt\n";
}
unless (@select) {
    @select = ('*');
}

VERSION

1.222

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.

cpanm Quiq

perl -MCPAN -e shell
install Quiq