xmlconf/ru

│ English (en) │ русский (ru) │

Модуль XMLConf предоставляет компонент TXMLConfig. Он использует объект TXMLDocument для чтения и записи XML-файла, но происходит непосредственно от TComponent.

Отказ от ответственности

Эта документация не является официальной, она основана на обычном процессе 1) изучения исходного кода; 2) экспериментирования; 3) размышлений: «Интересно, это ли имел в виду автор?»

Свойства и процедуры

property Filename

property Filename: String (published)

Имя XML-файла. Установка другого имени файла:

• Очищает текущий xml-файл.
• Освобождает объект xmldocument
• Если Filename существует и StartEmpty имеет значение false:
  • Новый xmldocument создается путем чтения файла, который должен иметь тот же root элемент, что и RootName, в противном случае возникает исключение.
  • В противном случае создается новый объект xmldocument с корневым элементом RootName

Я не проверял это экспериментально, но похоже, что пустой xmldocument создается (в памяти) при создании компонента, и это можно изменить. Однако его нельзя сохранить, пока у него не будет имени файла - нет имени файла по умолчанию - следовательно, все изменения неизбежно будут потеряны, когда имя файла будет установлено.

property StartEmpty

property StartEmpty: Boolean (published)

Определяет, читается ли существующий xmlfile из Filename.

• По умолчанию false - читается существующий файл.

property RootName

property RootName: DOMString (published)

Имя root элемента в файле. Должно соответствовать значению в файле при чтении существующего файла.

• По умолчанию - 'CONFIG'. Проще всего оставить это в покое, если у вас нет веской причины это менять.

procedure Flush

procedure Flush (public)

Записывает файл xml - если задано имя файла.

procedure Clear

procedure Clear (public)

Воссоздает xmldocument как пустой документ.

constructor Create

constructor Create(AOwner: TComponent) (public)

destructor Destroy

destructor Destroy (public)

Работа с ключами и путями

XMLConfig поддерживает «стек» путей (как массив широких строк). Общий путь к элементу может быть <rootName>/key1/key2/key3/key4/value="some_value".

Это будет выглядеть в файле в виде

<CONFIG>
  <key1>
    <key2>
      <key3>
        <key4 value="some_value"/>
      </key3>
    </key2>
  </key1>
</CONFIG>

(пренебрегая любыми другими элементами). Однако стек путей может содержать пути, а не только узлы, поэтому он может состоять как из четырех элементов глубиной key1;key2; key3;key4, так и точно так же только двух элементов key1/key2;key3/key4, или трех элементов key1;key2/key3;key4.

Кроме того, при чтении или установке значения можно указать полный путь, так что можно полностью игнорировать «стек» пути и указать полный путь (после RootName) для каждого значения. У каждого значения есть эффективный путь, а стек путей - это просто удобный способ добраться до конкретного эффективного пути.

procedure OpenKey

procedure OpenKey(const aPath: WideString) (public)

"Помещает" aPath в стек. Если текущий путь был <RootName>/key1 и aPath = key2/key3, после вызова OpenKey текущий путь будет <RootName>/key1/key2/key3.

procedure CloseKey

procedure CloseKey (public)

"Выталкивает" верхний путь из стека. Обратите внимание, что это последний введенный путь, а НЕ верхний(предыдущий) элемент. Таким образом, после приведенного выше примера OpenKey, за которым следует вызов CloseKey, стек возвращается к <RootName>/key1, а не <RootName>/key1/key2.

procedure ResetKey

procedure ResetKey (public)

Полностью очищает стек. Эффективный путь возвращается к <RootName>

Получение, установка и удаление значений

Все значения фактически читаются и записываются как строки, а другие перегруженные типы предоставляют определенные переводы 'AsString'.

function GetValue: WideString / procedure SetValue(const APath: WideString; const AValue: WideString)

function  GetValue(const APath: WideString; const ADefault: WideString): WideString (public)

procedure SetValue(const APath: WideString; const AValue: WideString) (public)

Устанавливает или получает строковое значение из RootName / Текущий_путь_из_стэка / APath. Путь создается, если он не существует в сеттере, и ADefault возвращается, если путь не существует в геттере.

function GetValue: Integer / procedure SetValue(const APath: WideString; AValue: Integer)

function GetValue(const APath: WideString; ADefault: Integer): Integer; (public)

procedure SetValue(const APath: WideString; AValue: Integer); (public)

Целочисленные значения преобразуются в/из строк с помощью функций IntToStr и strToIntDef.

function GetValue: Boolean / procedure SetValue(const APath: WideString; AValue: Boolean)

function  GetValue(const APath: WideString; ADefault: Boolean): Boolean; (public)

procedure SetValue(const APath: WideString; AValue: Boolean); (public)

Логические значения сохраняются как "True" или "False".

Предупреждение: некоторые другие компоненты FCL/LCL XML (например, производные от TCustomPropertyStorage, такие как TXMLPropStorage) хранят логические значения с использованием целочисленных значений, несмотря на использование XMLConifg в качестве компонента хранения. Это, конечно, проблема только в том случае, если вы используете одни и те же файлы из обоих компонентов или переключаетесь с одного на другой во время разработки, как это сделал я

.

procedure SetDeleteValue(const APath: WideString; const AValue, DefValue: WideString) / procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Integer) / procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Boolean)

procedure SetDeleteValue(const APath: WideString; const AValue, DefValue: WideString); (public)

procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Integer); (public)

procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Boolean); (public)

Если AValue = DefValue, элемент удаляется. В противном случае устанавливается значение AValue.

Я не использовал это, но предположительно мог бы использовать для хранения, например, значений свойств с четко определенными значениями по умолчанию, только если они отличаются от значений по умолчанию.

procedure DeletePath(const APath: WideString)

procedure DeletePath(const APath: WideString); (public)

Удаляет все за пределами пути APath

procedure DeleteValue(const APath: WideString)

procedure DeleteValue(const APath: WideString); (public)

Удаляет значение, указанное APath. Если APath не указывает значение, он ничего не делает

property Modified: Boolean read FModified

property Modified: Boolean read FModified; (public)

Позволяет узнать, был ли изменен xmldocument и, следовательно, необходимо ли его очистить.

Однако процедура Flush ничего не делает, если документ не изменен, поэтому в любом случае проще просто вызвать процедуру Flush.

Example

The following sequence of instructions:

  XmlConfig1.Filename := FILE_NAME ;        // reads the file if it already exists, but...
  XmlConfig1.Clear ;                        // if the file already exists, clear the data, we want to start from scratch
  XmlConfig1.SetValue ('L1/L2/L3', '333') ; // add a few data
  XmlConfig1.SetValue ('L1/L2/L4', '44') ;
  XmlConfig1.SetValue ('L1/L2/L3', '33') ;  // this will overwrite the previous value
  XmlConfig1.OpenKey  ('L1/L2') ;           // from now on, all keys will be relative to L1/L2
  XmlConfig1.SetValue ('Lm', 'mm') ;        // these will be added in L1/L2
  XmlConfig1.SetValue ('Lm/Ln', 'nn') ;
  XmlConfig1.SetValue ('/Lx/Ly', 'yy') ;    // but because of the initial "/", this will be added to the root
  XmlConfig1.CloseKey ;
  XmlConfig1.SetValue ('L6/L7', '77') ;     // L6 will be deleted
  XmlConfig1.SetValue ('L9', '99') ;
  XmlConfig1.SetValue ('L9/L99', '9999') ;  // the previous L9 was an attibute, this one will be a node
  XmlConfig1.DeletePath ('L6') ;
  XmlConfig1.Flush ;

will give this XML:

  <?xml version="1.0" encoding="utf-8"?>
  <CONFIG L9="99">
    <L1>
      <L2 L3="33" L4="44" Lm="mm">
        <Lm Ln="nn"/>
      </L2>
    </L1>
    <Lx Ly="yy"/>
    <L9 L99="9999"/>
  </CONFIG>

Note that the last item in the aPath parameter for SetValue is actually an attribute: XmlConfig1.SetValue ('L1/L2/L3', '333') actually sets attribute L3 for element L1/L2.

---

See also

• XMLConf/TXMLConf is provided by the fcl-xml package.