pdr Referenz
Momentan stehen folgende Typen von Datenquellen zur
Verfügung:
|
diese Datenquellen arbeiten mit
Ausdrücken
|
|
diese beiden Datenquellen
arbeiten mit
verschiedenen, spezifischen Datenformaten
|
Eingabe per Kommandozeile
Die
einfachste (und zugleich unkomfortabelste) Eingabemöglichkeit ist
die Kommandozeile, d.h. der Aufruf von pdr selbst.
Hierzu muß nichts speziell konfiguriert werden.
pdr besitzt den Kommandozeilenparameter -e bzw. --expression, der die Angabe genau
eines Ausdrucks erlaubt. Dieser Parameter ist mehrfach verwendbar.
Ferner werden alle hinter pdr eingegebenen Zeichen, die nicht Teil oder
Argument eines Kommandozeilenparameters sind, zu einem Ausdruck
zusammengefaßt und gemeinsam ausgewertet (siehe dort).
Besitzt der angegebene Ausdruck keinen Zeitstempel werden die aktuellen
Werte für Datum und Uhrzeit benutzt.
Tritt bei der Verarbeitung ein Fehler auf, weil der Ausdruck nicht
korrekt war, so gibt pdr eine Meldung aus. Eine Übernahme des
Ausdrucks in die rejections
erfolgt nicht.
Eingabe per Mail (POP3 und
IMAP)
Bei der Abfrage von e-mail-Postfächern wird davon
ausgegangen, daß der Benutzer anfallende Daten mit einem anderen
Programm oder einem Mobiltelefon an ein e-mail-Postfach sendet und diese
dort liegenbleiben (d.h. nicht anderweitig abgeholt werden). Diese
e-mails müssen folgende Eigenschaften aufweisen:
- ein eindeutiges subject
- einen verwertbaren Zeitstempel (dafür sorgt normalerweise der
SMTP-Server beim Senden)
- reines, zusammenhängendes Text-Format (kein HTML, RTF
o.ä.)
- Text ausschließlich in Ausdrücken
Ist für pdr eine e-mail-Datenquelle konfiguriert, so wird sie
beim nächsten Aufruf automatisch abgefragt. pdr schaut dann nach,
ob sich mails im Postfach befinden, prüft deren subject und wertet passende e-mails der
Reihe nach aus, wobei jede Zeile als jeweils ein Ausdruck interpretiert
wird. Besitzt eine Zeile einen eigenen Zeitstempel, so besitzt dieser
Priorität, ansonsten gilt für alle Zeilen implizit der
Zeitstempel der e-mail-Nachricht. Das ist insofern praktisch, weil man
üblicherweise in einzeiligen e-mails nie einen Zeitstempel manuell
eingeben muß.
Hier einmal ein vollständiger e-mail-Quelltext:
From: superhero <MyMail@gmx.net>
To: MyMail@gmx.net
Subject: Q
Date: Thu, 04 Feb 2010 17:56:11 +0100
Message-ID: <87pr4ley8k.fsf@castor.ch>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
5.3 8i
Die meisten Werte in den Headerzeilen kann man in der Regel aus
default-Einstellungen entnehmen. Date und Message-ID setzt der Server hinzu,
MIME-Version und
Content-Type stammen vom
verwendeten e-mail-Client. Die einzigen Texte, die man wirklich tippen
muß, sind das subject (es
empfiehlt sich darum, das subject so kurz wie möglich zu
vereinbaren, hier der einzelne Buchstabe Q) sowie der Inhalt der Nachricht
(letzte Zeile).
Auf POP3-Servern werden verarbeitete e-mails anschließend
unabhängig vom Erfolg der Verarbeitung automatisch gelöscht,
so daß sie später nicht ein zweites Mal verarbeitet werden.
Dieses automatische Löschen kann bei der Konfiguration der
Datenquelle unterbunden werden. Für IMAP-Server kann konfigurert
werden, ob pdr die mails nach der Verarbeitung löschen oder als
gelesen markieren soll. Letzteres ist praktisch, wenn man die
verarbeiteten mails auf dem Server noch archivieren will.
Tritt bei der Verarbeitung ein Fehler auf, weil ein Ausdruck nicht
korrekt war o.ä., so gelangen die betreffenden Ausdrücke in
die rejections und müssen
nachbearbeitet werden. pdr gibt in diesem Falle eine Meldung aus.
Eingabe
per Twitter
Es ist vielleicht der eleganteste Weg zur Dateneingabe,
einen dafür eingerichteten Twitter-Account zu benutzen. Für
Twitter existiert auf fast jeder Plattform ein geeignetes Frontend,
insbesondere auf Mobiltelefonen, so daß die Dateneingabe sehr
einfach wird. Twitter vergibt die notwendigen Zeitstempel automatisch,
der Benutzer muß nichts weiter als seine expressions eingeben.
pdr holt jeweils diejenigen Daten aus dem feed, die jünger sind als
der Zeitpunkt, als der feed das letzte Mal abgefragt wurde. Hat pdr den
feed noch nie abgefragt, so werden alle Daten aus dem feed geholt, die
jünger als der jüngste Datenwert in der Datenbank sind.
Tritt bei der Verarbeitung ein Fehler auf, weil ein Ausdruck nicht
korrekt war o.ä., so gelangen die betreffenden Ausdrücke in
die rejections und müssen
nachbearbeitet werden. pdr gibt in diesem Falle eine Meldung aus.
Hinweise
- Es ist ratsam, den Twitter-Account zu schützen, einerseits um die Daten
nicht öffentlich zu machen, andererseits um Störungen des
feeds durch Kommentare zu vermeiden. Diese Option ist im
Twitter-Benutzeraccount unter Einstellungen, Konto, unten
"Tweetsicherheit [x] Schütze meine Tweets" zu machen.
- Ein geschützter Twitter-Account macht eine Authentifizierung nötig. Diese
Authentifizierung erfolgt, wenn pdr zum ersten Mal auf einen
Twitter-Account zugreift. Dabei werden zwei private Schlüssel
beschafft und lokal abgelegt, so daß die Authentifizierung beim
nächsten Mal nicht noch einmal ausgeführt werden
muß.
- Leider erfordert Twitter die Authentifizierung mit einem
interaktiven Schritt: der
Benutzer bekommt in seinem Webbrowser eine Twitter-eigene Webseite
präsentiert, auf der er mindestens einen Button drücken
muß. Dann erscheint eine siebenstellige Nummer, eine PIN, die er
in pdr eintippen muß. Aus diesem Grunde ist im Moment des ersten
Zugriffs auf einen Twitter-Account die Angabe eines Browsers
nötig (Kommandozeilenparameter --browser).
- Wenn die Authentifizierung erfolgreich abgeschlossen wurde,
verhält sich eine Twitter-Datenquelle wie jede andere.
Eingabe per Identi.ca
Prinzipiell gilt alles, was zu Twitter gesagt wurde, auch für
Identi.ca. Viele Twitter-Frontends können sich auch mit Identi.ca
verbinden.
Eingabe über
Textdateien
Bei der Verwendung von Textdateien zur Eingabe wird jede
Zeile als Ausdruck interpretiert. Dieses Verfahren ist nützlich,
wenn man über einen gewissen Zeitraum Daten sammeln, aber nicht
online übermitteln kann. Man schreibt die Ausdrücke einfach
mit einem Editor Ausdruck für Ausdruck, d.h. Zeile für Zeile
in eine Textdatei.
Zeilen, die innerhalb solcher Textdateien mit # beginnen, werden nicht
ausgewertet.
Tritt bei der Verarbeitung ein Fehler auf, bleibt die gesamte Datei
unverarbeitet. Eine Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete Textdateien werden, sofern sie in der
Konfigurationsdatei als Datenquelle angegeben sind, automatisch
gelöscht, damit sie nicht ein zweites Mal verarbeitet werden.
Dieses Löschen kann bei der Konfiguration unterbunden werden.
Eingabe über
CSV-Dateien
Die Abkürzung CSV steht für "comma separated values", durch Komma
getrennte Werte. Das Komma ist nicht ganz wörtlich zu nehmen, pdr
akzeptiert das Komma, das Semikolon und den Tabulator als Separator
zwischen den Werten.
Es gibt zwei Möglichkeiten, pdr mitzuteilen, welcher
kommaseparierter Datenwert in welche collection gelangen soll:
- über eine Steuerzeile in der CSV-Datei, die den Datenzeilen
vorangeht
- über eine Steuerzeile in der Konfigurationsdatei, die
für die gesamte CSV-Datei gilt
Im ersten Fall besitzt eine von pdr verwendbare CSV-Datei folgende
Struktur:
Steuerzeile
Datenzeile1
[...]
DatenzeileN
Steuerzeile
Datenzeile1
[...]
DatenzeileN
[...]
Diese Art der Verwendung von Steuerzeilen ist ungewöhnlich, liefert
aber die gewünschte Flexibilität und Offenheit. In der Regel
kann man sie sehr leicht einfügen, entweder von Hand oder über
ein Programm wie sed. Im
zweiten Fall enthielte die CSV-Datei wie erwartet nur Datenzeilen.
Eine Steuerzeile hat folgenden
Aufbau:
[# pdr] datetime [Separator
collection]+
z.B.
# pdr datetime, *, n, l; h;
q»p, #
(» soll ein Tabulator
sein)
Dies ist eine Steuerzeile für nachfolgende Datenzeilen mit jeweils
einem Zeitstempel und sieben weiteren Werten für die collections *, n, l, h, q, p und #.
Jede Steuerzeile wird innerhalb einer CSV-Datei an ihrer Einleitung
# pdr erkannt, bei Angabe
der Steuerzeile in der Konfigurationsdatei ist diese Kennung nicht
erforderlich. Das folgende Schlüsselwort datetime kennzeichnet die Lage des
Zeitstempels auf den Datenzeilen. Es muß nicht am Anfang stehen,
jedoch auf jeder Zeile enthalten sein - Datenwerte ohne Zeitstempel sind
nicht denkbar. Im Beispiel ist zu sehen, daß verschiedene
Separatoren innerhalb einer Zeile benutzt werden können.
Datenzeilen, die zu dieser Steuerzeile passen, hätten damit
folgendes Aussehen:
2008-10-11 12:31:38, 5.2, 7, 8;
42.3; 12»96, erste
Messung
2008-10-12 12:48:08, 6.1, , 8; 53.1; 16»93,
2008-10-13 12:43:57, 5.8, 7, 7; 34.2; 15»94, dritte Messung
In der zweiten Zeile fehlen Werte für die collections n und # - im Fall fehlender Werte erfolgen
einfach keine Eingaben.
Besitzt man CSV-Dateien, die mehr Werte enthalten, als man in
collections importieren will,
so kann man auf der Steuerzeile Auslassungen vereinbaren:
# pdr datetime, a, b, , , , c,
d, e
Hier werden hinter dem Zeitstempel zwei collections gelesen, dann jeweils drei
Datenwerte auf den Datenzeilen ausgelassen, und dann die restlichen drei
collections gelesen.
Zeilen, die innerhalb von CSV-Dateien mit dem Symbol # beginnen, werden als Kommentar
betrachtet und nicht weiter ausgewertet.
Beim Einfügen von Werten in die Datenbank wird eine gesamte
CSV-Datei in einer einzigen Transaktion behandelt. Wenn dabei ein Fehler
auftritt, beispielsweise weil ein Datenwert nicht zum Typ der in der
Steuerzeile vereinbarten collection paßt, so wird die gesamte
Datei verworfen. Es kann nicht passieren, daß eine Datei zur
Hälfte eingelesen wird und zur anderen Hälfte nicht und man
hinterher gar keine rechte Kontrolle mehr darüber hat. Eine
Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete CSV-Dateien werden, sofern sie in der
Konfigurationsdatei als Datenquelle angegeben sind, automatisch
gelöscht, damit sie nicht ein zweites Mal verarbeitet werden.
Dieses Löschen kann bei der Konfiguration unterbunden werden.
Eingabe über
XML-Dateien
pdr bietet die Möglichkeit, XML-Dateien einzulesen.
Diese Dateien sind wohlstrukturiert, les- und editierbar, und sind damit
ideal zum Austausch von Daten zwischen verschiedenen Softwaresystemen
geeignet. pdr definiert zunächst ein eigenes, absichtlich sehr
einfaches Format. Der entsprechende Programmteil ist aber dafür
ausgelegt, nach entsprechender Erweiterung auch andere XML-Formate zu
lesen.
Das pdr-XML-Format
Das Format ist vollständig abgelegt in
der Datei pdr.xsd:
<?xml version="1.0" encoding="iso-8859-1" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
<xsd:annotation>
<xsd:documentation xml:lang="en">
pdr XML input file definition (C) T.M.
Bremgarten 2010-01-31
</xsd:documentation>
</xsd:annotation>
<xsd:element name="pdr">
<xsd:complexType>
<xsd:sequence>
<xsd:element
name="collection" type="collection" minOccurs="0"
maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="collection">
<xsd:sequence>
<xsd:element name="item" minOccurs="0"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:attribute name="datetime" type="xs:string" />
<xsd:attribute name="value" type="xs:string" />
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xs:string"
use="required" />
<xsd:attribute name="type"
type="collection_type" use="required" />
<xsd:attribute name="purpose" type="xs:string"
/>
</xsd:complexType>
</xsd:schema>
Diese Definition erlaubt Dateien, die folgendes Aussehen haben:
<?xml version="1.0" encoding="ISO-8859-1"?>
<pdr>
<collection name="#" type="text">
<item datetime="2001-07-09 18:27:11"
value="erste Messung"/>
<item
date
time
="2001-
07
-10
07:52:01" value="zweite Messung"/>
<item
date
time
="2001-
07
-10
10:07:00" value="dritte Messung"/>
[...]
</collection>
<collection name="*" type="numeric">
<item
date
time
="2001-
07
-12
13:57:01" value="9.3"/>
<item
date
time
="2001-
07
-12
14:46:45" value="5.6"/>
<item
date
time
="2001-
07
-12
18:25:36" value="5.7"/>
[...]
</collection>
<collection name="l" type="numeric">
<item
date
time
="2001-
07
-03
21:41:58" value="7"/>
<item
date
time
="2001-
07
-04
21:48:43" value="8"/>
<item
date
time
="2001-
07
-05
21:50:49" value="7"/>
[...]
</collection>
</pdr>
Das Format ist beinahe selbsterklärend. Die Daten der collections werden direkt lesbar angegeben
und genau so eingelesen.
Beim Einfügen von Werten in die Datenbank wird eine gesamte
XML-Datei in einer einzigen Transaktion behandelt. Wenn dabei ein Fehler
auftritt, beispielsweise weil ein Datenwert nicht zum Typ der
angegebenen collection
paßt, so wird die gesamte Datei verworfen. Es kann nicht
passieren, daß eine Datei zur Hälfte eingelesen wird und zur
anderen Hälfte nicht und man hinterher gar keine rechte Kontrolle
mehr darüber hat. Eine Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete XML-Dateien werden, sofern sie in der
Konfigurationsdatei als Datenquelle angegeben sind, automatisch
gelöscht, damit sie nicht ein zweites Mal verarbeitet werden.
Dieses Löschen kann bei der Konfiguration unterbunden werden.
(weitere XML-Formate)
...