pdr Referenz
Momentan stehen folgende Typen von Datenquellen zur Verfügung:
|
diese vier 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 jüngste Datenwert in der Datenbank. Damit ist es
möglich, nachträglich noch Datenmanipulation zu betreiben.
Diese werden bei einer neuen Abfrage nicht überschrieben.
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 ü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)
...