/ 
Prty-1.111
River stage zero No dependents
/ Prty::ContentProcessor

NAME

Prty::ContentProcessor - Prozessor für Abschnitts-Dateien

BASE CLASS

Prty::Hash

SYNOPSIS

use Prty::ContentProcessor;

$cop = Prty::ContentProcessor->new('.mytool');
$cop->registerType('MyTool::A','a','A','A');
$cop->registerType('MyTool::B','b','B','A');
...
$cop->load(@paths)->commit;

for my $ent ($cop->entities) {
    $cop->msg($ent->name);
}

DESCRIPTION

Ein Objekt der Klasse repräsentiert einen Prozessor für Entitäts-Dateien. Die Dateien bestehen aus einer Folge von Abschnitten, die von einem Abschnitts-Parser (s. Klasse Prty::Section::Parser) geparsed und zu Abschnitts-Objekten instantiiert werden.

Der Prozessor delegiert die Verarbeitung der Abschnitts-Objekte an die per registerType() registierten Entitäts-Klassen (Plugin-Schnittstelle). Diese bauen aus den Abschnitts-Objekten Entitäts-Strukturen auf, aus denen die Ausgabedateien generiert werden. Die Entitäts-Klassen sind nicht Teil des ContentProzessors.

Bei Anwendung der Operation "commit"() wird der Quelltext jeder Entität gegen den Stand im Storage verglichen. Im Falle einer Änderung wird die Entität als geändert gekennzeichnet, d.h. ihre Ausgabedateien müssen neu generiert werden.

Das Resultat der Ausführung ist eine Menge von Entitäts-Objekten plus ihrem Änderungs-Status. Die Menge der Entitäts-Objekte kann mit der Methode "entities"() abgefragt werden.

Universelles Plugin

Ein Universelles Plugin kann definiert werden, indem bei "registerType"() nur $pluginClass und $extension als Argumente angegeben werden. An diese Plugin-Klasse werden alle (Haupt-)Abschnitts-Objekte delegiert, für die kein Plugin definiert ist. Logischerweise kann es höchstens ein Universelles Plugin geben. Für ein Universelles Plugin findet keine Attribut-Validierung in der Basisklassenmethode create() statt. Das Konzept ist in erster Linie für allgemeine Programme wie z.B. Testprogramme gedacht.

Ausgaben

Der Umfang an Ausgaben wird mit der Konstruktor-Option -verbosity=>$level eingestellt. Default ist 1.

Die Methode msg() schreibt eine Ausgabe nach STDERR. Der erste Parameter gibt den Verbosity-Level an. Ist dieser größer als der eingestellte Verbosity-Level, unterbleibt die Ausgabe.

$cop->msg(2,$text);

Ist kein Level angegeben, erfolgt die Ausgabe immer:

$cop->msg($text);

Der Meldungstext $text kann printf-Formatelemente enthalten, diese werden wie bei printf durch die zusätzlich angegebenen Argumente ersetzt:

$cop->msg($text,@args);

EXAMPLES

Füge alle Entitäts-Definitionen im Storage zu einem einzigen Datenstrom zusammen und schreibe diesen nach STDOUT (z.B. für Refactoring):

$cop->load->fetch('-');

Übertrage alle Entitäts-Definitionen im Storage in Verzeichnis $dir (das Verzeichnis hat die gleiche Struktur wie das Verzeichnis def im Storage):

$cop->load->fetch->($dir);

Liste alle Entitäten vom Typ $type auf:

$cop->load;
for my $ent ($cop->entities($type)) {
    $cop->msg($ent->name);
}

METHODS

Konstruktor

new() - Instantiiere ContentProcessor

Synopsis

$cop = $class->new($storage,@opt);

Description

Instantiiere ein ContentProcessor-Objekt und liefere eine Referenz auf dieses Objekt zurück.

Arguments

$storage

Das Storage-Verzeichnis, z.B. '.storage'.

Options

-verbosity => 0|1|2 (Default: 1)

Umfang der Laufzeit-Meldungen.

Returns

ContentProcessor-Objekt

Sub-Abschnitte

processSubSection() - Verarbeite Sub-Abschnitt einer Entität

Synopsis

$cop->processSubSection($fileEnt,$ent,$mainSec,$sec);

Arguments

$fileEnt

Entität, die Träger des gesamten Quelltextes ist. Diese ist im Quelltext mit [] gekennzeichnet.

$ent

Die aktuelle Entität. Kann identisch zu $fileEnt oder eine Sub-Entität (z.B. (File) oder (ProgramClass)) sein.

$mainSec

Die Entität oder Sub-Entität, der die mit <> gekennzeichneten Abschnitte zugeordnet werden.

$sec

Der aktuelle Abschnitt.

Returns

nichts

Plugins

registerType() - Registriere Entitäts-Typ

Synopsis

$cop->registerType($pluginClass,$extension,$entityType,$sectionType,@keyVal);
$cop->registerType($pluginClass,$extension); # universelles Plugin

Description

Registriere Plugin-Klasse $pluginClass für Abschnitts-Objekte des Typs $sectionType und den Eigenschaften @keyVal.

Entsprechende Dateien werden an der Extension $extension erkannt. Als Typ-Bezeichner für Entitäten dieses Typs vereinbaren wir $entityType.

Die Plugin-Klasse wird automatisch geladen, falls sie noch nicht vorhanden ist (sie kann für Tests also auch "inline", d.h. im Quelltext des rufenden Code, definiert werden).

Die Plugin-Definition wird intern auf einem Hash-Objekt gespeichert, das vom ContentProcessor mit den instantiierten Entitäten verbunden wird.

Es kann auch ein Universelles Plugin definiert werden (siehe Abschnitt "Universelles Plugin").

Arguments

$pluginClass

Name der Plugin-Klasse, z.B. 'Program::Shell'.

$extension

Datei-Erweiterung für Dateien dieses Typs, ohne Punkt, z.B. 'prg'.

$entityType

Entitätstyp-Bezeichner, z.B. 'Program' oder 'Class/Perl'.

$sectionType

Abschnitts-Bezeichner ohne Klammerung, z.B. 'Program'.

@keyVal

Abschnitts-Attribute, die über den Abschnitts-Bezeichner hinaus den Dateityp kennzeichnen, z.B. Language=>'Perl'.

Returns

nichts

Operationen

commit() - Übertrage Veränderungen in den Storage

Synopsis

$cop = $cop->commit;

Description

Vergleiche den Quelltext jeder Entität gegen den Quelltext im Storage und übertrage etwaige Änderungen dorthin. Geänderte Entitäten werden in der in der Datenbank als geändert gekennzeichnet.

Returns

ContentProcessor-Objekt (für Method-Chaining)

fetch() - Erzeuge Verzeichnisstruktur mit Entitäts-Definitionen

Synopsis

$cop = $cop->fetch($dir,$layout,@opt);

Description

Übertrage alle Entitäts-Definitionen in Verzeichnis $dir (oder STDOUT, s.u.) gemäß Layout $layout. Per Differenzbildung wird dabei ein konsistenter Stand hergestellt. Existiert Verzeichnis $dir nicht, wird es angelegt. Andernfalls wird eine Rückfrage gestellt, ob das Verzeichnis überschrieben werden soll (siehe auch Option --overwrite).

Wird als Verzeichnis ein Bindestrich (-) angegeben, werden die Entitäts-Definitionen nach STDOUT geschrieben.

Die Methode bezieht die zu schreibenden Dateien von der Methode "fetchFiles"(), an die der Parameter $layout weiter gereicht wird. Die Methode kann in abgeleiteten Klassen überschrieben werden, um andere Strukturen zu generieren.

Arguments

$dir

Verzeichnis, in welches die Entitäts-Definitionen geschrieben werden.

$layout

Bezeichnung für das Verzeichnis-Layout. Dieser Parameter wird von fetchFiles() der Basisklasse nicht genutzt und ist daher hier nicht dokumentiert. Siehe Dokumentation bei den Subklassen.

Options

-overwrite => $bool (Default: 0)

Stelle keine Rückfrage, wenn Verzeichnis $dir bereits existiert.

Returns

ContentProcessor-Objekt (für Method-Chaining)

init() - Erzeuge Storage

Synopsis

$cop = $cop->init;

Description

Erzeuge den Storage, falls er nicht existiert. Existiert er bereits, hat der Aufruf keinen Effekt.

Returns

ContentProcessor-Objekt (für Method-Chaining)

load() - Lade Entitäts-Definitionen

Synopsis

$cop = $cop->load;
$cop = $cop->load(@paths);

Description

Lade die Entitäts-Dateien der Pfade @paths. Ist @path leer, also kein Path angegeben, werden die Entitäts-Dateien aus dem Storage geladen.

Die Methode kann beliebig oft aufgerufen werden, aber nur der erste Aufruf lädt die Dateien. Alle weiteren Aufrufe sind Null-Operationen.

Arguments

@paths

Liste der Verzeichnisse und Dateien. Pfad '-' bedeutet STDIN.

Returns

ContentProcessor-Objekt (für Method-Chaining)

Entitäten

entities() - Liefere Menge von Entities

Synopsis

@entities | $entityA = $cop->entities;
@entities | $entityA = $cop->entities($type);

Description

Liefere die Liste aller geladenen Entities oder aller geladenen Entities vom Typ $type. Bei der Abfrage der Entities eines Typs werden die Entities nach Name sortiert geliefert.

Arguments

$type

Abschnitts-Typ.

Returns

Liste von Entitäten. Im Skalarkontext eine Referenz auf die Liste.

Dateien

fetchFiles() - Liste der Dateien für fetch

Synopsis

@files = $cop->fetchFiles;
@files = $cop->fetchFiles($layout);

Description

Liefere die Liste der Dateien, die von der Methode "fetch"() geschrieben werden. Jede Datei wird durch ein zweielementiges Array repräsentiert, bestehend aus einem Datei-Pfad sowie dem Datei-Inhalt. Der Datei-Inhalt kann als String oder String-Referenz angegeben sein.

Diese (Basisklassen-)Methode liefert für jede Entität die Datei-Definiton

[$ent->entityFile, $ent->sourceRef]

Damit erzeugt die Methode fetch() die gleiche Struktur wie der ContentProcessor im Storage-Verzeichnis def.

Die Methode kann in abgeleiteten Klassen überschrieben werden, um die Verzeichnisstruktur zu ändern und/oder den Inhalt der Dateien anders zusammenzustellen (z.B. mehrere Entity-Definitionen in einer Datei zusammenzufassen). In abgeleiteten Klassen können verschiedene Layouts durch das Argument $layout unterschieden werden.

Arguments

$layout

Bezeichner für eine bestimmte Abfolge und/oder Inhalt der Dateien.

Returns

Array mit zweielementigen Arrays

Statistik

info() - Informationszeile

Synopsis

$str = $cop->info;

Description

Liefere eine Informationszeile mit statistischen Informationen, die am Ende der Verarbeitung ausgegeben werden kann.

Returns

Zeichenkette

Intern

entityTypes() - Liste der Abschnitts-Typen

Synopsis

@types | $typeA = $cop->entityTypes;

Description

Liefere die Liste der Abschnitts-Typen (Bezeichner), die per registerType() registriert wurden.

Returns

Liste von Abschnitts-Typen. Im Skalarkontext eine Referenz auf die Liste.

extensionRegex() - Regex zum Auffinden von Eingabe-Dateien

Synopsis

$regex = $cop->extensionRegex;

Description

Liefere den regulären Ausdruck, der die Dateinamen matcht, die vom ContentProcessor verarbeitet werden. Der Regex wird genutzt, wenn ein Verzeichnis nach Eingabe-Dateien durchsucht wird.

Returns

Kompilierter Regex

findFiles() - Finde Entitäts-Dateien in Verzeichnis

Synopsis

@files | $fileA = $cop->findFiles($dir);

Description

Durchsuche Verzeichnis $dir nach Entitäts-Dateien unter Verwendung des Regex, der von "extensionRegex"() geliefert wird.

Arguments

$dir

Das Verzeichnis, das nach Dateien durchsucht wird.

Returns

Liste der Datei-Pfade (Strings). Im Skalarkontext eine Referenz auf die Liste.

msg() - Gib Information aus

Synopsis

$cop->msg($text,@args);
$cop->msg($level,$text,@args);

Description

Gib Information $text auf STDERR aus, wenn $level kleinergleich dem beim Konstruktor vorgebenen Verbosity-Level ist. Der Text kann printf-Platzhalter enthalten, die durch die Argumente @args ersetzt werden.

Zusätzlich wird der Platzhalter %T durch die aktuelle Ausführungsdauer in Sekunden ersetzt.

Arguments

$level

Der Verbosity-Level, ab dem die Information ausgegeben wird.

$text

Text, der ausgegeben werden soll.

@args

Argumente, die für printf-Platzhalter in $text eingesetzt werden.

Returns

nichts

plugin() - Ermittele Plugin zu Abschnitts-Objekt

Synopsis

$plg = $cop->plugin($sec);

Description

Ermittele das Plugin zu Abschnitts-Objekt $sec. Existiert kein Plugin zu dem Abschnitts-Objekt, liefere undef.

Arguments

$sec

Abschnitts-Objekt

Returns

Plugin-Objekt

needsTestDb() - Persistenter Hash für Test-Status

Synopsis

$h = $cop->needsTestDb;

Description

Liefere eine Referenz auf den persistenten Hash, der den Status von Entitäten speichert.

Returns

Hash-Referenz (persistenter Hash)

needsUpdateDb() - Persistenter Hash für Entitäts-Status

Synopsis

$h = $cop->needsUpdateDb;

Description

Liefere eine Referenz auf den persistenten Hash, der den Status von Entitäten speichert.

Returns

Hash-Referenz (persistenter Hash)

storage() - Pfad zum oder innerhalb des Storage

Synopsis

$path = $cop->storage;
$path = $cop->storage($subPath);

Description

Liefere den Pfad des Storage, ggf. ergänzt um den Sub-Pfad $subPath.

Arguments

$subPath

Ein Sub-Pfad innerhalb des Storage.

Returns

Pfad

VERSION

1.111

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.