CXI-Basis-Programmierreferenz / Version 2 / Datenspeicherung / CxiNode / Typübergreifende Funktionen /

SetFromStringOrFile - String oder Datei in Block konvertieren

CxiError CxiNode :: SetFromStringOrFile (const char *items, CxiLong options = 0)
CxiError cxiSetFromStringOrFile (CxiHandle self, const char *items, CxiLong options)

Setzt Variablen des Blocks aus einem String oder aus Dateien

items:
String mit Variablennamen und -werten und Dateinamen (siehe Text)

options:
Optionen (siehe Text), normalerweise 0

return:
0 ok, sonst Fehler

Diese Funktion übernimmt Variablenwerte aus einem String in einen Block oder CXI-Baum. Auf SetFromStringOrFile basiert einer der Konstruktoren der Klasse CxiTree.

Der übergebene String (items) besteht aus Einzelkomponenten, die jeweils durch ein Semikolon (;) abgeschlossen werden. Jede Komponente definiert eine Variable und besteht aus einem Variablennamen, dem ein Gleichheitszeichen (=) folgt, der Wert der Variablen schließt sich an. Die Funktion bestimmt den Typ automatisch aus der gewählten Darstellung.

Die Schlüsselworte TRUE, ON, YES und FALSE, OFF, NO definieren logische Variablen, z.B. "FERTIG=TRUE;ERROR=YES;".

Das Schlüsselwort NIL definiert eine Variable ohne Wert, z.B. "PLATZHALTER=NIL;".

Ein leerer Wert führt zur Löschung der Variablen, z.B. "ERROR=;ALLESDA=;".

Besteht der Wert aus einem optionalen Vorzeichen ('+' oder '-') und ansonsten nur Ziffern, so definiert dies eine numerische Variable, z.B. "ANZAHL=12;ERRNO=1;RETCODE=-3;".

Besteht der Wert aus einem optionalen Vorzeichen ('+' oder '-'), der Kennung '0x' oder '0X' und ansonsten nur Hex-Ziffern, so definiert dies ab Version 2.07 ebenfalls eine numerische Variable, z.B. "INTERRUPT=0xF1;ADR=0x0040006c;".

Der spezielle Wert '{' beginnt einen Unterbaum, z.B. "SUBTREE={VAR1=1;SUBSUBTREE={DUMMY=HALLO;};VAR2=2;}". Die Definition des Unterbaums endet bei der zugehörigen '}'. Unterbäume sind schachtelbar. Nach '{' und '}' kann jeweils ein Semikolon angegeben werden, dies ist optional. Vor der schließenden Klammer '}' muss unbedingt ein Semikolon stehen! Das Semikolon wird wie bei einem C-Compiler als Abschlusszeichen einer Anweisung betrachtet, nicht als Trennzeichen zwischen ihnen. Folgen mehrere '}' unmittelbar aufeinander, so muss nur vor der ersten zwingend ein Semikolon stehen, vor den anderen ist es optional.

Beginnt der Wert mit einfachen oder doppelten Anführungszeichen, wird eine Stringvariable erzeugt, z.B. "NAME='Hugo, der Erste';PLZ='49632';". Als Abschlusszeichen muss das gleiche Zeichen wie am Anfang benutzt werden, das jeweils andere Anführungszeichen kann frei im String verwendet werden. Innerhalb des Strings werden keine Steuer- und Trennzeichen erkannt. Die umschließenden Anführungszeichen werden nicht als Teil des Strings abgespeichert.

Kann der Wert keiner bisherigen Gruppe zugeordnet werden, wird er als String aufgefasst, z.B. "NACHNAME=Meyer;VORNAME=Hugo;TITEL=Dr. rer. nat.;ORT=Essen;".

Eine Stringliste wird erzeugt, indem mehrere Werte mit oder ohne Anführungszeichen durch Komma getrennt aufgeführt werden, z.B. "Teilnehmer=Hugo,Egon,Sonstige Teilnehmer,'Hallo, Welt';". Nach dem letzten Wert kann optional noch ein Komma folgen.

Wird nur ein Name ohne Gleichheitszeichen angegeben, so wird der Name als Dateiname aufgefasst und der Inhalt dieser Datei (CXI-Binärformat) eingefügt, z.B. "VORLAGE.CXI;DATA={testdat.cxi;}". Folgt dem Dateinamen ein Abschnittsname in eckigen Klammern, wird im Gegensatz dazu die Datei als Textdatei aufgefasst und der Inhalt des entsprechenden Abschnitts dieser Datei eingefügt, jede Zeile des Abschnitts wird dabei mit der Funktion SetFromLine verarbeitet. Es ist zulässig, den Dateinamen wegzulassen, es wird dann die Standard-INI-Datei gelesen, z.B. "[SYSTEM];DATA={testdat.ini[SUBTREE];}". Tritt ein Fehler beim Lesen der Datei auf und ist die Option cxiOptScanDiagnosis angegeben, werden Variablen in den Block eingefügt, die die Fehlerursache beschreiben.

Auch das letzte Element des Parameters items sollte mit einem Semikolon abgeschlossen sein, dies ist jedoch nicht zwingend. Mehrere aufeinander folgende Semikolons gelten wie eins. Leerzeichen werden an keiner Stelle ignoriert, sondern als Teil des Variablennamens oder -wertes berücksichtigt.

Ist die Option cxiOptScanStringOnly angegeben, werden alle Angaben der Form Variable=Wert als Strings aufgefasst.

Eine sehr ähnliche Funktion ist SetFromLine, diese unterscheidet sich hauptsächlich in der Interpretation von Leerzeichen und Semikolons von SetFromStringOrFile.

Hinweis:
Textdateien (INI-Dateien) sind zur Konfiguration und als Initialisierung von CXI-Objekten vorgesehen. Sie können nicht benutzt werden, um die Daten von CXI-Objekten abzuspeichern, da hierbei wesentliche Informationen verloren gehen würden. Es existiert daher auch kein 'CxiTreeIniFile', um direkt CxiTree-Objekte in Textdateien zu verwalten. Wenn Änderungen an INI-Dateien notwendig sind, können jedoch ab Version 2.11 die folgenden Tool-Funktionen eingesetzt werden:
ReadIniFileString - Lesen eines Eintrags (String)
WriteIniFileString - Schreiben eines Eintrags (String)
UpdateIniFile - Schreiben eines Eintrags (allgemein)

Portabilität:
Diese Funktion ist in allen unterstützten Systemen verfügbar. Die Hex-Darstellung von Zahlen ist ab Version 2.07 verfügbar. Die Schlüsselworte ON, YES, OFF und NO werden ab Version 2.08 erkannt.

Siehe auch:
SetFromString - String in Block konvertieren
SetFromLine - Zeile in Block konvertieren
CxiTree-Konstruktor mit Syntaxbeschreibung und Beispiel