xmlwrite: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: xmlwrite
| Old | New | Line | |
|---|---|---|---|
| 1 | + | Writes a DOM structure as XML data into a file or stream. It can deal both with XML files and XML fragments. | |
| 2 | + | ||
| 3 | + | ## Declarations | |
| 4 | + | ||
| 5 | + | Declarations excerpted from XMLWrite.pas. | |
| 6 | + | ||
| 7 | + | ``` pascal | |
| 8 | + | procedure WriteXMLFile(doc: TXMLDocument; const AFileName: String); overload; | |
| 9 | + | procedure WriteXMLFile(doc: TXMLDocument; var AFile: Text); overload; | |
| 10 | + | procedure WriteXMLFile(doc: TXMLDocument; AStream: TStream); overload; | |
| 11 | + | ||
| 12 | + | procedure WriteXML(Element: TDOMNode; const AFileName: String); overload; | |
| 13 | + | procedure WriteXML(Element: TDOMNode; var AFile: Text); overload; | |
| 14 | + | procedure WriteXML(Element: TDOMNode; AStream: TStream); overload; | |
| 15 | + | ``` | |
| 16 | + | ||
| 17 | + | ## Encodings | |
| 18 | + | ||
| 19 | + | At the moment it supports only the [[UTF-8]] output encoding. The encoding label is not written because it is optional for UTF-8. | |
| 20 | + | ||
| 21 | + | ## Character escaping | |
| 22 | + | ||
| 23 | + | The writer provides proper character escaping as required by XML: | |
| 24 | + | ||
| 25 | + | - for normal text nodes, the following replacements will be done: | |
| 26 | + | - '\<' =\> '\<' | |
| 27 | + | - '\>' =\> '\>' | |
| 28 | + | - '&' =\> '\&' | |
| 29 | + | - For attribute values, additionally '"' (#34) gets replaced by '\"', and characters \#9, \#10 and \#13 are escaped using numerical references. | |
| 30 | + | - Single apostrophes (') don't need to get converted, as values are already written using "" quotes. | |
| 31 | + | ||
| 32 | + | The [[xmlread|XML reader]] (in xmlread.pp) will convert these entity references back to their original characters. | |
| 33 | + | ||
| 34 | + | ## Exceptions | |
| 35 | + | ||
| 36 | + | Will raise EConvertError if any DOM node contains an unpaired UTF-16 surrogate in its name or value. | |
| 37 | + | ||
| 38 | + | ## End-of-line handling | |
| 39 | + | ||
| 40 | + | 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. | |
| 41 | + | ||
| 42 | + | ## Notes | |
| 43 | + | ||
| 44 | + | - The sets of WriteXML() and WriteXMLFile() procedures duplicate each other, one of them is actually redundant. | |
| 45 | + | ||
| 46 | + | Back to [[fcl-xml]] overview. | |
| 47 | + | ||
| 48 | + | ## See also | |
| 49 | + | ||
| 50 | + | - [[xmlread]] | |
| 51 | + | ||
| 52 | + | --- | |
| 53 | + | *From the Free Pascal wiki, page "xmlwrite", as it stood on 2020-03-03 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |