Quiq::ContentProcessor - Prozessor für Abschnitts-Dateien
Quiq::Hash
use Quiq::ContentProcessor; $cop = Quiq::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); }
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 Quiq::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.
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.
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);
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); }
$cop = $class->new($storage,@opt);
Das Storage-Verzeichnis, z.B. '.storage'.
Umfang der Laufzeit-Meldungen.
ContentProcessor-Objekt
Instantiiere ein ContentProcessor-Objekt und liefere eine Referenz auf dieses Objekt zurück.
$path = $cop->storage; $path = $cop->storage($subPath);
Ein Sub-Pfad innerhalb des Storage.
Pfad
Liefere den Pfad des Storage, ggf. ergänzt um den Sub-Pfad $subPath.
$cop->registerType($pluginClass,$extension,$entityType,$sectionType,@keyVal); $cop->registerType($pluginClass,$extension); # universelles Plugin
Name der Plugin-Klasse, z.B. 'Program::Shell'.
Datei-Erweiterung für Dateien dieses Typs, ohne Punkt, z.B. 'prg'.
Entitätstyp-Bezeichner, z.B. 'Program' oder 'Class/Perl'.
Abschnitts-Bezeichner ohne Klammerung, z.B. 'Program'.
Abschnitts-Attribute, die über den Abschnitts-Bezeichner hinaus den Dateityp kennzeichnen, z.B. Language=>'Perl'.
nichts
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).
@types | $typeA = $cop->entityTypes;
Liste von Abschnitts-Typen. Im Skalarkontext eine Referenz auf die Liste.
Liefere die Liste der Abschnitts-Typen (Bezeichner), die per registerType() registriert wurden.
$plg = $cop->plugin($sec);
Abschnitts-Objekt
Plugin-Objekt
Ermittele das Plugin zu Abschnitts-Objekt $sec. Existiert kein Plugin zu dem Abschnitts-Objekt, liefere undef.
undef
$cop = $cop->init;
ContentProcessor-Objekt (für Method-Chaining)
Erzeuge den Storage, falls er nicht existiert. Existiert er bereits, hat der Aufruf keinen Effekt.
$cop = $cop->commit(@opt);
Lade fehlende Entitäten aus dem Storage nach anstatt sie zum Löschen anzubieten.
Vergleiche den Quelltext jeder Entität gegen den Quelltext im Storage und übertrage etwaige Änderungen dorthin. Geänderte Entitäten werden in der Datenbank als geändert gekennzeichnet.
$cop = $cop->load; $cop = $cop->load(@paths);
Liste der Verzeichnisse und Dateien. Pfad '-' bedeutet STDIN.
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.
$cop = $cop->fetchToDir($dir,$layout,@opt);
Verzeichnis, in welches die Entitäts-Definitionen geschrieben werden.
Bezeichnung für das Verzeichnis-Layout. Dieser Parameter wird von filesToFetch() der Basisklasse nicht genutzt und ist daher hier nicht dokumentiert. Siehe Dokumentation bei den Subklassen.
Stelle keine Rückfrage, wenn Verzeichnis $dir bereits existiert.
Übertrage alle Entitäts-Definitionen in Verzeichnis $dir (oder nach 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 filesToFetch(), an die der Parameter $layout weiter gereicht wird. Die Methode kann in abgeleiteten Klassen überschrieben werden, um andere Strukturen zu generieren.
@files = $cop->filesToFetch; @files = $cop->filesToFetch($layout);
Bezeichner für eine bestimmte Abfolge und/oder Inhalt der Dateien.
Array mit zweielementigen Arrays
Liefere die Liste der Dateien, die von den Methode fetchToDir() und [ANCHOR NOT FOUND]() 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.
$regex = $cop->extensionRegex;
Kompilierter Regex
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.
@files | $fileA = $cop->findFiles($dir,@opt);
Verzeichnis, das nach Dateien durchsucht wird.
Lasse Pfade, deren letzte Komponente mit einem Punkt beginnt, aus. Auf diese Weise verhindern wir, dass Dot-Verzeichnissse durchsucht werden.
Liste der Datei-Pfade (Strings). Im Skalarkontext eine Referenz auf die Liste.
Durchsuche Verzeichnis $dir nach Entitäts-Dateien unter Verwendung des Regex, der von extensionRegex() geliefert wird.
@entities | $entityA = $cop->parseFiles(@files);
Liste der Dateien. '-' bedeutet STDIN.
Liste der Entitäten. Im Skalarkontext eine Referenz auf die Liste.
$cop->processSubSection($fileEnt,$ent,$mainSec,$sec);
Entität, die Träger des gesamten Quelltextes ist. Diese ist im Quelltext mit [] gekennzeichnet.
Die aktuelle Entität. Kann identisch zu $fileEnt oder eine Sub-Entität (z.B. (File) oder (ProgramClass)) sein.
Die Entität oder Sub-Entität, der die mit <> gekennzeichneten Abschnitte zugeordnet werden.
Der aktuelle Abschnitt.
@entities | $entityA = $cop->entities; @entities | $entityA = $cop->entities($type);
Abschnitts-Typ.
Liste von Entitäten. Im Skalarkontext eine Referenz auf die Liste.
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.
$h = $cop->needsTestDb;
Hash-Referenz (persistenter Hash)
Liefere eine Referenz auf den persistenten Hash, der den Status von Entitäten speichert.
$h = $cop->needsUpdateDb;
$str = $cop->info;
Zeichenkette
Liefere eine Informationszeile mit statistischen Informationen, die am Ende der Verarbeitung ausgegeben werden kann.
$cop->msg($text,@args); $cop->msg($level,$text,@args);
Der Verbosity-Level, ab dem die Information ausgegeben wird.
Text, der ausgegeben werden soll.
Argumente, die für printf-Platzhalter in $text eingesetzt werden.
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.
1.148
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.