Frank Seitz
and 1 contributors

NAME

Prty::Section::Object - Abschnitts-Objekt

BASE CLASS

Prty::Object

DESCRIPTION

Ein Objekt der Klasse repräsentiert einen "Abschnitt". Abschnitte werden von Prty::Section::Parser geparst und instantiiert.

Ein Abschnittsobjekt gibt Auskunft über den Inhalt des Abschnitts und dessen "Ort" (Dateiname und Zeilennummer). Das Objekt ist readonly, d.h. die Objekteigenschaften können gelesen aber nicht gesetzt werden.

Abschnittsobjekte können in einer hierarchischen Beziehung stehen. Ein Abschnitts-Objekt kann Unter-Abschnitte haben.

ATTRIBUTES

[0] type

Abschnitts-Bezeichner.

[1] brackets

Klammerung des Abschnittsbezeichners.

[2] keyA

Liste der Schlüssel.

[3] keyValH

Attribut-Hash.

[4] content

Inhalt des Abschnitts.

[5] source

Quelltext des Abschnitts.

[6] file

Name der Quelldatei.

[7] line

Zeilennummer in Quelldatei.

METHODS

Konstruktor

new() - Konstruktor

Synopsis

    $sec = $class->new($type,$keyValH);
    $sec = $class->new($type,$keyValH,$keyA,$content,$source,$file,$line);

Description

Instantiiere ein Abschnittsobjekt und liefere eine Referenz auf das Objekt zurück.

Arguments

$type

Abschnitts-Typ einschließlich Klammern (sofern vorhanden).

$keyValH

Referenz auf Schlüssel/Wert-Hash.

$keyA

Referenz auf Schlüssel-Array.

$content

Inhalt.

$source

Quelltext des Abschnitts.

$file

Name der Datei, die den Abschnitt enthält. Im Falle von STDIN ist ist der Dateiname "-", im Falle einer In-Memory-Datei ist der Dateiname "(source)".

$line

Zeilennummer, an der der Abschnitt in der Datei beginnt.

Returns

Referenz auf Abschnitts-Objekt

Abschnittsinformation

type() - Liefere/Setze Abschnittsbezeichner

Synopsis

    $type = $sec->type;
    $type = $sec->type($type);

Description

Liefere den Abschnittsbezeichner. Ist Parameter $type angegeben, setze den Abschnittsbezeichner auf diesen Wert.

Returns

Abschnittsbezeichner (String)

brackets() - Liefere/setze Klammerung

Synopsis

    $brackets = $sec->brackets;
    $brackets = $sec->brackets($brackets);

Description

Liefere die Klammerung um den Abschnittsbezeichner, sofern vorhanden. Ist der Abschnittsbezeichner nicht geklammert, liefere einen Leerstring. Ist Parameter $brackets angegeben, setze die Klammerung auf diesen Wert.

Returns

Klammerpaar (String)

Details

Die Klamerung um den Abschnitts-Bezeichner ist optional. Sie besteht aus der öffnenden und schließenden Klammer, ist also "[]", "<>" oder "()" oder "{}".

fullType() - Liefere Abschnittsbezeichner mit Klammerung

Synopsis

    $fullType = $sec->fullType;

Description

Liefere den vollständigen Abschnittsbezeichner einschließlich der Klammern.

keys() - Liefere die Liste der Schlüssel

Synopsis

    $keyA|@keys = $sec->keys;

Description

Liefere die Liste der Schlüssel. Im Skalarkontext liefere eine Referenz auf die Liste.

keyValHash() - Liefere den Attributhash

Synopsis

    $hash|@arr = $sec->keyValHash;

Returns

Im Sklarkontext liefere eine Referenz auf den Attribut-Hash. Im Arraykontext liefere die Liste der Attribut/Wert-Paare.

content() - Liefere/Setze Inhalt

Synopsis

    $content = $sec->content;
    $content = $sec->content($content);

Returns

Inhalt (String)

contentRef() - Liefere Referenz auf den Inhalt

Synopsis

    $ref = $sec->contentRef;

Returns

Referenz auf Inhalt (String-Referenz)

contentNL() - Liefere Inhalt mit Newline

Synopsis

    $contentN = $sec->contentNL;

Returns

Inhalt mit Newline (String)

file() - Liefere Dateiname

Synopsis

    $file = $sec->file;

Returns

Dateiname (String)

mtime() - Liefere Zeitpunkt der letzten Änderung der Datei

Synopsis

    $mtime = $sec->mtime;

Returns

Integer (Epoch-Wert)

line() - Liefere Zeilennummer

Synopsis

    $n = $sec->line;

Returns

Zeilennummer (Integer)

fileInfo() - Liefere Dateiname und Zeilennummer in einem Aufruf

Synopsis

    ($file,$line) = $sec->fileInfo;

Returns

Dateiname (String) und Zeilennummer (Integer)

Quelltext

source() - Liefere Quelltext

Synopsis

    $source = $sec->source;

Returns

Quelltext (String)

sourceRef() - Liefere Referenz auf Quelltext

Synopsis

    $ref = $sec->sourceRef;

Returns

Skalar-Referenz

deleteSource() - Lösche Quelltext

Synopsis

    $sec->deleteSource;

Returns

nichts

transferSource() - Übertrage Quelltext von Sub-Abschnitten auf Abschnitt

Synopsis

    $sec->transferSource;

Description

Füge die Quelltexte aller Sub-Abschnitte von Abschnitt $sec zum Abschnitt hinzu. Die Quelltexte der Sub-Abschnitte werden von diesen gelöscht.

Returns

nichts

removeEofMarker() - Entferne "# eof" von Quelltext und Content

Synopsis

    $sec->removeEofMarker;

Returns

nichts

Attribute

append() - Füge Zeichenkette zu Wert hinzu

Synopsis

    $val = $sec->append($key=>$str);

Description

Füge Zeichenkette $str zum Wert des Schlüssels $key hinzu und liefere den resultierenden Wert zurück.

Arguments

$key

Schlüssel, dessen Wert ergänzt wird.

Returns

Wert (String)

get() - Liefere Wert zu Schlüssel

Synopsis

    $val = $sec->get($key);
    @vals = $sec->get(@keys);

Description

Liefere den Wert zu Schlüssel $key bzw. die liste der Werte zu den Schlüsseln @keys. Beginnt der $key mit einem Großbuchstaben, ist es ein fataler Fehler, wenn zu dem Schlüssel mehrere Werte existieren. Solche Schlüssel müssen mit $obj->"getArray"() abgefragt werden.

Arguments

$key bzw. @keys

Schlüssel, deren Wert geliefert wird.

Returns

Wert (Skalar-Kontext) oder Wertliste (Array-Kontext)

getArray() - Liefere Wertliste zu Schlüssel

Synopsis

    $arr|@arr = $sec->getArray($key);

Description

Liefere die Wertliste von Schlüssel $key.

Arguments

$key

Schlüssel dessen Wertliste geliefert wird.

Returns

Wert bzw. Werte

getBool() - Liefere boolschen Wert zu Schlüssel

Synopsis

    $bool = $sec->getBool($key);
    $bool = $sec->getBool($key,$default);

Description

Liefere boolschen Wert zu Schlüssel $key.

Arguments

$key

Schlüssel, dessen Wert geliefert wird.

$default

Defaultwert, wenn Attribut nicht gesetzt

Returns

Wert (Skalar)

getMandatory() - Liefere Wert eines Pflichtattributs

Synopsis

    $val = $sec->getMandatory($key);

Description

Wie $sec->"get"(), nur dass ein Wert existieren muss, sonst wird eine Exception geworfen.

Arguments

$key

Schlüssel, dessen Wert geliefert wird.

Returns

Wert (Skalar)

getRef() - Liefere Referenz auf Schlüsselwert

Synopsis

    $ref = $sec->getRef($key);

search() - Suche Attributwert

Synopsis

    ($key,$val) = $sec->search(\@sections,\@keys);

Description

Durchsuche die Liste der Abschnitts-Objekte ($self,@sections) nach dem ersten Attribut aus @keys, das einen Wert besitzt und liefere das Schlüssel/Wert-Paar zurück. Ist der Wert 'NULL', wird '' (Leerstring) geliefert. Auf diese Weise kann auf "höherer Ebene" definierter Wert außer Kraft gesetzt werden.

try() - Werte abfragen ohne Exception

Synopsis

    $val = $sec->try($key);
    @vals = $sec->try(@keys);

Description

Wie "get"(), nur dass im Falle eines unerlaubten Schlüssels keine Exception geworfen, sondern undef geliefert wird.

memoize() - Ermittele Wert und cache ihn auf Attribut

Synopsis

    $val = $sec->memoize($key,$sub);

Description

Die Methode liefert den Wert des Attributs $key. Ist kein Wert definiert (Wert ist undef), wird die Methode $sec->$sub($key) gerufen, der Wert berechnet und auf dem Attribut $key gespeichert. Weitere Aufrufe liefern diesen Wert, ohne dass er neu berechnet wird.

Die Methode ist nützlich, um in Objektmethoden eingebettet zu werden, die einen berechneten Wert liefern, der nicht immer wieder neu gerechnet werden soll.

Example

    sub name {
        return shift->memoize('name',sub {
            my ($self,$key) = @_;
            my $name = $self->get(ucfirst $key);
            $name =~ s/^\W+//;
            $name =~ s|\W+|/|g;
            return $name;
        });
    }

memoizeWeaken() - Ermittele schwache Referenz

Synopsis

    $val = $sec->memoizeWeaken($key,$sub);

Description

Die Methode ist identisch zu $sec->"memoize"(), nur dass eine Referenz ermittelt und automatisch zu einer schwachen Referenz gemacht wird.

set() - Setze Schlüssel auf Wert

Synopsis

    $sec->set(@keyVal);

Arguments

@keyVal

Schlüssel/Wert-Paare, die gesetzt werden.

Returns

nichts

setDefault() - Setze Defaultwert

Synopsis

    $sec->setDefault(@keyVal);

Description

Setze Schlüssel ohne Wert, d.h. wenn der Wert ein Leerstring ist, setze ihn auf den angegebenen Defaultwert.

Arguments

@keyVal

Liste der Schlüssel/Wert-Paare.

Returns

nichts

Example

    $sec->setDefault(
        Width=>1000,
        EntityMenuWidth=>345,
        BorderWidth=>1,
        PackageMenuHeight=>34,
    );

push() - Füge Element zu Arraykomponente hinzu

Synopsis

    $sec->push($key,$val);

Description

Füge Wert $val zur Arraykomponente $key hinzu. Die Methode liefert keinen Wert zurück.

Arguments

$key

Arraykomponente.

$val

Wert, der zum Array am Ende hinzugefügt wird.

weaken() - Erzeuge schwache Referenz

Synopsis

    $ref = $sec->weaken($key);
    $ref = $sec->weaken($key=>$ref);

Description

Mache die Referenz von Schlüssel $key zu einer schwachen Referenz und liefere sie zurück. Ist eine Referenz $ref als Parameter angegeben, setze die Referenz zuvor.

validate() - Prüfe und ergänze Attribute

Synopsis

    $sec->validate($contentAllowed,\@keys);

Description

Die Methode finalisiert das Abschnittsobjekt in folgender Weise:

  • Sie prüft, dass wenn kein Content erlaubt ist, keiner existiert.

  • Sie prüft, dass nur Schlüssel im Objekt vorkommen, die in @keys vorkommen. Kommt ein anderer Schlüssel im Objekt vor, wird eine Exception geworfen.

  • Sie fügt Schlüssel aus @keys zum Objekt hinzu, die das Objekt nicht hat.

Arguments

$contentAllowed

Wenn falsch, erlaubt der Abschnitt keinen Content (außer "# eof" als Dateiende-Markierung).

@keys

Liste der zulässigen Abschnittsattribute

Returns

Nichts

lockKeys() - Locke die Keys des Attribut-Hash

Synopsis

    $sec->lockKeys;

Fehler

error() - Wirf eine Exception mit Dateiname und Zeilennummer

Synopsis

    $sec->error($msg,@keyVal);

Description

Die Methode wirft eine Exception mit dem Fehlertext $msg und den als Schlüssel/Wert-Paare angegebenen Informationen @keyVal. Ferner wird von der Methode der Dateiname und die Zeilennummer des Abschnitts ergnzt. Die Exception beinhaltet keinen Stacktrace.

Arguments

$msg

Die Fehlermeldung.

@keyVal

Detailinformation zum Fehler.

Returns

Die Methode kehrt nicht zurück

Automatische Akzessor-Methoden

AUTOLOAD() - Erzeuge Akzessor-Methode

Synopsis

    $val = $this->AUTOLOAD;
    $val = $this->AUTOLOAD($val);

Description

Erzeuge beim ersten Aufruf eine Akzessor-Methode für einen Schlüssel des Schlüssel/Wert-Hashs und führe den betreffenden Methodenaufruf durch.

VERSION

1.108

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2017 Frank Seitz

LICENSE

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