Difference between revisions of "xmlwrite"
(New page: Writes a DOM structure as XML data into a file or stream. It can deal both with XML files and XML fragments. At the moment it supports only the UTF-8 output encoding. Please note that the ...) |
m (Fixed syntax highlighting; deleted category included in page template) |
||
(6 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | Writes a DOM structure as XML data into a file or stream. It can deal both with | + | {{xmlwrite}} |
− | XML files and XML fragments. | + | |
− | At the moment it supports only the UTF-8 output encoding. | + | Writes a DOM structure as XML data into a file or stream. It can deal both with XML files and XML fragments. |
− | + | ||
− | + | == Declarations == | |
+ | |||
+ | Declarations excerpted from XMLWrite.pas. | ||
+ | |||
+ | <syntaxhighlight lang=pascal> | ||
+ | procedure WriteXMLFile(doc: TXMLDocument; const AFileName: String); overload; | ||
+ | procedure WriteXMLFile(doc: TXMLDocument; var AFile: Text); overload; | ||
+ | procedure WriteXMLFile(doc: TXMLDocument; AStream: TStream); overload; | ||
+ | |||
+ | procedure WriteXML(Element: TDOMNode; const AFileName: String); overload; | ||
+ | procedure WriteXML(Element: TDOMNode; var AFile: Text); overload; | ||
+ | procedure WriteXML(Element: TDOMNode; AStream: TStream); overload; | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | == Encodings == | ||
+ | |||
+ | At the moment it supports only the [[UTF-8]] output encoding. The encoding label is not written because it is optional for UTF-8. | ||
+ | |||
+ | == Character escaping == | ||
+ | |||
+ | The writer provides proper character escaping as required by XML: | ||
* for normal text nodes, the following replacements will be done: | * for normal text nodes, the following replacements will be done: | ||
− | ** '<' => '<' | + | ** '<' => '&lt;' |
− | ** '>' => '>' | + | ** '>' => '&gt;' |
− | ** '&' => '&' | + | ** '&' => '&amp;' |
− | * For attribute values, additionally '"' gets replaced by '"', and characters #9, #10 and #13 are escaped using numerical references. | + | * For attribute values, additionally '"' (#34) gets replaced by '&quot;', and characters #9, #10 and #13 are escaped using numerical references. |
− | * Single apostrophes (')don't need to get converted, as values are already written using "" quotes. | + | * Single apostrophes (') don't need to get converted, as values are already written using "" quotes. |
+ | |||
+ | The [[xmlread|XML reader]] (in xmlread.pp) will convert these entity references back to their original characters. | ||
+ | |||
+ | == Exceptions == | ||
+ | |||
+ | Will raise EConvertError if any DOM node contains an unpaired UTF-16 surrogate in its name or value. | ||
+ | |||
+ | == End-of-line handling == | ||
+ | |||
+ | At the moment always uses [[End of Line|line endings]] which are default for the target platform (#13#10 for Windows, #10 for Linux). Moreover, any #13, #10 or #13#10 in input data is treated as a single line-ending. | ||
+ | |||
+ | == Notes == | ||
+ | |||
+ | * The sets of WriteXML() and WriteXMLFile() procedures duplicate each other, one of them is actually redundant. | ||
− | |||
− | |||
Back to [[fcl-xml]] overview. | Back to [[fcl-xml]] overview. | ||
+ | |||
+ | |||
+ | == See also == | ||
+ | |||
+ | * [[xmlread]] |
Latest revision as of 09:13, 3 March 2020
│
English (en) │
Writes a DOM structure as XML data into a file or stream. It can deal both with XML files and XML fragments.
Declarations
Declarations excerpted from XMLWrite.pas.
procedure WriteXMLFile(doc: TXMLDocument; const AFileName: String); overload;
procedure WriteXMLFile(doc: TXMLDocument; var AFile: Text); overload;
procedure WriteXMLFile(doc: TXMLDocument; AStream: TStream); overload;
procedure WriteXML(Element: TDOMNode; const AFileName: String); overload;
procedure WriteXML(Element: TDOMNode; var AFile: Text); overload;
procedure WriteXML(Element: TDOMNode; AStream: TStream); overload;
Encodings
At the moment it supports only the UTF-8 output encoding. The encoding label is not written because it is optional for UTF-8.
Character escaping
The writer provides proper character escaping as required by XML:
- for normal text nodes, the following replacements will be done:
- '<' => '<'
- '>' => '>'
- '&' => '&'
- For attribute values, additionally '"' (#34) gets replaced by '"', and characters #9, #10 and #13 are escaped using numerical references.
- Single apostrophes (') don't need to get converted, as values are already written using "" quotes.
The XML reader (in xmlread.pp) will convert these entity references back to their original characters.
Exceptions
Will raise EConvertError if any DOM node contains an unpaired UTF-16 surrogate in its name or value.
End-of-line handling
At the moment always uses line endings which are default for the target platform (#13#10 for Windows, #10 for Linux). Moreover, any #13, #10 or #13#10 in input data is treated as a single line-ending.
Notes
- The sets of WriteXML() and WriteXMLFile() procedures duplicate each other, one of them is actually redundant.
Back to fcl-xml overview.