Difference between revisions of "xmlconf/ru"

From Lazarus wiki
(Запись, получение и удаление значений)
(property Modified: Boolean read FModified)
Line 127: Line 127:
 
<syntaxhighlight lang="pascal">property Modified: Boolean read FModified; (public)</syntaxhighlight>
 
<syntaxhighlight lang="pascal">property Modified: Boolean read FModified; (public)</syntaxhighlight>
  
Allows you to see if the xmldocument has been modified, and hence, needs to be flushed.  ''However, flush does nothing if the document is not modified, so it is easier just to call flush anyway.''
 
 
Позволяет узнать, был ли изменен xmldocument и, следовательно, необходимо ли его очистить.  
 
Позволяет узнать, был ли изменен xmldocument и, следовательно, необходимо ли его очистить.  
  
«Однако flush ничего не делает, если документ не изменен, поэтому в любом случае проще просто вызвать flush».
+
''Однако процедура <code>Flush</code> ничего не делает, если документ не изменен, поэтому в любом случае проще просто вызвать процедуру <code>Flush</code>''.
  
 
==Example==
 
==Example==

Revision as of 04:55, 4 August 2021

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".

Warning-icon.png

Предупреждение: некоторые другие компоненты 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.