view release on metacpan or  search on metacpan

lib/Config/Manager/Conf.pm  view on Meta::CPAN

Wert in Anfuehrungszeichen gesetzt ist, werden enthaltene Anfuehrungszeichen
NICHT besonders gekennzeichnet (also KEINE Verdopplung oder Voranstellen eines
Backslashes).

Schluessel-Wert-Paare vor der ersten Abschnittsueberschrift gehoeren zum
Abschnitt "DEFAULT". Dieser wird bei Bedarf automatisch angelegt, aber sonst
wie jeder andere Abschnitt behandelt.

=item *

Substitution:

Der Wert kann Verweise auf andere Schluessel-Wert-Paare enthalten; jeder
Verweis wird durch den betreffenden Wert ersetzt. Ein Verweis besteht aus
einem "$" (Dollar) und dem gewuenschten Schluessel. Es wird nur im aktuellen
und im DEFAULT-Abschnitt gesucht (in dieser Reihenfolge). Schluessel eines
anderen Abschnitts muessen durch den Abschnittsnamen qualifiziert werden;
Der Abschnitt muss in "[...]" und der Schluessel (d.h. der Variablenname)
kann in "{...}" eingefasst werden, dadurch sind beide Angaben sicher
voneinander getrennt und auch leichter lesbar.

Das Einfassen des Variablennamens in "{...}" (geschweifte Klammern) ist
notwendig, wenn es danach mit einem Buchstaben, einer Ziffer, einem
Unterstrich oder einem Bindestrich weitergeht (es waere sonst unklar,
wo der Variablenname (bzw. die Substitution) aufhoert und wo der Text
weitergeht).

Somit sind auch verschachtelte Substitutionen moeglich: Der Name des Abschnitts
und/oder der Schluessel koennen ihrerseits aus einer Substitution bestehen
(dies wird im folgenden "Indirektion" genannt, weil der jeweilige Name nicht
als literaler String angegeben, sondern aus dem Inhalt der spezifizierten
Konfigurationskonstanten ermittelt wird).

Wenn man den Dollar als Zeichen braucht, stellt man ihm einen weiteren Dollar
voran, um seine Sonderbedeutung fuer die Substitution aufzuheben.

=item *

Besondere Abschnitte:

Der Abschnitt "ENV" erlaubt lesenden Zugriff auf Umgebungsvariablen. Diese
Werte koennen nicht geaendert werden (weder mit set() noch aus einer Datei).

(Es ist jedoch technisch moeglich, wenn auch stark abzuraten, solche Werte
direkt in den Perl-Hash "%ENV" zu schreiben und damit auch in die Umgebung.)

Der Abschnitt "SPECIAL" enthaelt die Schluessel YEAR (vierstelliges Jahr),
YY (zweistelliges Jahr), CC (Jahrhundert), MONTH, DAY, YDAY (fortlaufende
Nummerierung der Tage eines Jahres); OS (Betriebssystem), SCOPE (wie in der
Methode init() angegeben), HOME (wie von "getpwnam()" fuer den Benutzer aus
WHOAMI zurueckgeliefert, falls dieser Systemaufruf implementiert ist, ansonsten
"undef" und entsprechende Fehlermeldung) sowie WHOAMI (der erste Wert, der
in der Umgebung fuer USERNAME, LOGNAME, USER oder LOGIN gefunden wurde). Die
Werte werden vom System gesetzt; der Abschnitt "SPECIAL" kann nicht aus einer
Datei eingelesen werden. Es ist aber moeglich, die Datumsangaben durch set()
zu ueberschreiben (koennte fuer den Test von Tools nuetzlich sein); OS, SCOPE,
HOME und WHOAMI sind auch mit set() nicht aenderbar.

Die Zeitangaben werden zum Zeitpunkt des Aufrufs der new()- bzw. der
init()-Methode gesetzt und aendern sich ab da nicht mehr; d.h. sie
werden bei aufeinanderfolgenden Abfragen NICHT mehr auf den jeweils
aktuellen Wert gesetzt. (Der Benutzer kann dies aber wie gesagt
ggfs. selbst, mit Hilfe der set()-Methode, tun.)

=back

=head1 ANMERKUNG

Diese Klasse ist als geschachtelter Hash implementiert, und zwar hat man je
Abschnitt-Schluessel-Paar folgende Eintraege:

   $$self{$section}{$key}{'source'};
   $$self{$section}{$key}{'line'};
   $$self{$section}{$key}{'value'};
   $$self{$section}{$key}{'state'};

Hierbei bedeutet:

   source - Datenquelle (z.B. Dateiname)
   line   - Zeilennummer in der Datei (optional)
   value  - Wert des Schluessels
   state  - Verarbeitungszustand des Wertes:
            'raw'     = Substitution noch nicht durchgefuehrt
            'pending' = Substitution wird gerade durchgefuehrt
            'cached'  = Subsitution wurde erfolgreich durchgefuehrt

Weiterhin enthaelt

   $$self{'<error>'}

die aktuellste Fehlermeldung. Die spitzen Klammern verhindern Konflikte mit
Abschnittsnamen (Abschnitte beginnen grundsaetzlich mit einem Buchstaben).

Alle oeffentlichen Methoden sind so ausgelegt, dass sie nicht nur auf einer
Instanz, sondern auch auf der Klasse aufgerufen werden koennen; in letzterem
Fall wird die Methode auf der Default-Instanz ausgefuehrt.

=head1 BEKANNTE FEHLER

Diese Klasse ist nicht thread-sicher: Bei der Variablensubstitution muessen
Zyklen erkannt werden, und dies funktioniert nicht zuverlaessig, wenn mehrere
Threads gleichzeitig eine Variable auswerten.

Es wird immer nur der letzte aufgetretene Fehler gespeichert. Treten mehrere
Fehler nacheinander auf, ist nur die jeweils letzte Fehlermeldung abrufbar.

Man erhaelt eine Endlosschleife, wenn in einer Datei eine NEXTCONF-Anweisung
direkt oder indirekt auf die Datei selbst verweist.

Doppelte Eintraege innerhalb eines Abschnitts werden nur erkannt, wenn der
erste dieser Eintraege tatsaechlich wirksam ist (d.h. nicht durch einen Eintrag
in einer frueher eingelesenen Datei verdeckt wird).

=head1 DATENSTRUKTUREN

=over 4

=item *

C<$anchor>