<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
laz2_XMLWrite
====================================================================
-->
<module name="laz2_XMLWrite">
<short>
Provides routines used to write XML content to a file, text file, or stream.
</short>
<descr>
<p>
<file>laz2_xmlwrite.pas</file> provides procedures and types used to write XML 
content to a file, text file, or stream. laz2_xmlwrite.pas has classes in its 
implementation section that are used to perform serialization of XML content 
to the storage destination.
</p>
<p>
Copyright (c) 1999-2000 by Sebastian Guenther, sg@freepascal.org <br/>
Modified in 2006 by Sergei Gorelkin, sergei_gorelkin@mail.ru <br/>
Converted to use UTF-8 instead of widestrings by Mattias Gaertner.
</p>
<p>
<file>laz2_xmlwrite.pas</file> is part of the <file>LazUtils</file> package.
</p>
</descr>

<!-- unresolved externals -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="LazUTF8"/>
<element name="laz2_DOM"/>
<element name="laz2_XMLUtils"/>

<!-- enumeration type Visibility: default -->
<element name="TXMLWriterFlag">
<short>
Represent options enabled when writing XML content.
</short>
<descr>
<var>TXMLWriterFlag</var> is an enumerated type with values that represent 
options enabled when writing XML content. Values in TXMLWriterFlag are stored 
in the <var>TXMLWriterFlags</var> set type, and passed as an argument to the 
WriteXMLFile and WriteXML routines.
</descr>
<seealso>
<link id="TXMLWriterFlags"/>
<ink id="WriteXMLFile"/>
<ink id="WriteXML"/>
</seealso>
</element>
<!-- enumeration value Visibility: default -->
<element name="TXMLWriterFlag.xwfAllowNullCharsInAttributeValue">
<short>
Enables writing encoded #0.  Without this flag an error will be raised. Please 
note that enabling this option, and writing a null character, will produce an 
XML document that cannot be handled by a validating XML processor. As per the 
XML specifications, the null character (#0) (#$00) (&amp;x0;) (ASCII NULL) is 
never valid in the content of an XML document. ReadXMLFile in the 
<file>lazutils</file> package will handle the value.
</short>
</element>
<element name="TXMLWriterFlag.xwfSpecialCharsInAttributeValue">
<short>
Enables writing unencoded #1..#32 (including Carriage Return) characters in 
attribute values. Without this flag they will be encoded to their numeric 
character entity &amp;xD; instead. Please note that enabling this option, and 
writing an attribute value in this range, will produce an XML document that 
cannot be handled by a validating XML 1.0 processor. The values are also 
discouraged for XML 1.1 processors. ReadXMLFile in the 
<file>lazutils</file> package will handle the value.
</short>
</element>
<element name="TXMLWriterFlag.xwfPreserveWhiteSpace">
<short>Preserves whitespace in DOM Text nodes.</short>
</element>

<!-- set type Visibility: default -->
<element name="TXMLWriterFlags">
<short>Set type used to store TXMLWriterFlag values.</short>
<descr>
<p>
<var>TXMLWriterFlags</var> is a set type used to store 0 or more values from 
the <var>TXMLWriterFlag</var> enumeration. TXMLWriterFlags indicates the 
options enabled when writing XML content. TXMLWriterFlags is the type passed 
as an argument to the <var>WriteXMLFile</var> procedure.
</p>
</descr>
<seealso>
<link id="TXMLWriterFlag"/>
<link id="WriteXMLFile"/>
</seealso>
</element>

<!-- procedure Visibility: default -->
<element name="WriteXMLFile">
<short>
Writes an XML document to a file, text file, or stream.
</short>
<descr>
<p>
<var>WriteXMLFile</var> is an overloaded procedure used to write an XML 
document to a file, text file, or stream. Overloaded variants provide the 
implementation details for each of the destinations, and create either 
TTextXMLWriter or TStreamXMLWriter class instances to store the XML document.
</p>
<p>
AFileName indicates the file name on the local file system where the XML 
content is stored. AFileName can contain UTF-8 encoded values, and must 
represent a valid file name. If the file in AFileName already exists, an 
exception will be raised.
</p>
<p>
Flags contains values from the TXMLWriterFlag enumeration. Use Flags to 
enable XML writing options in the routine. The default value for the argument 
is an empty set (<b>[]</b>), and indicates that no options are enabled in the 
routine. Please note that use of TXMLWriterFlag options like 
xwfAllowNullCharsInAttributeValue and xwfSpecialCharsInAttributeValue can 
result in an XML document that cannot be handled by a validating XML 
processor. The ReadXMLFile routine in <file>LazUtils</file> will accept and 
handle the values.
</p>
</descr>
<seealso>
<link id="WriteXML"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="WriteXMLFile.doc">
<short>XML document written in the routine.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXMLFile.AFileName">
<short>File name where the XML content is stored.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXMLFile.AFile">
<short>Text file type where the content is written.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXMLFile.AStream">
<short>Stream where the XML document is stored.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXMLFile.Flags">
<short>Options enabled when writing the XML content.</short>
</element>

<!-- procedure Visibility: default -->
<element name="WriteXML">
<short>
Writes a DOM Node to a file, text file, or stream.
</short>
<descr>
<p>
<var>WriteXML</var> is an overloaded procedure used to write a DOM Node to a 
file, text file, or stream. WriteXML calls one of the overloaded WriteXMLFile 
routines for a specific destination.
</p>
<p>
Element is a TDOMNode parameter that represents the DOM Document Node with 
the XML content written in the method. WriteXML ensures that Element is cast 
to a TXMLDocument type when calling the WriteXMLFile routine.
</p>
<p>
AFileName indicates the file name on the local file system where the XML 
content is stored. AFileName can contain UTF-8 encoded values, and must 
represent a valid file name. If the file in AFileName already exists, an 
exception will be raised.
</p>
<p>
Flags contains values from the TXMLWriterFlag enumeration. Use Flags to 
enable XML writing options in the routine. The default value for the argument 
is an empty set (<b>[]</b>), and indicates that no options are enabled in the 
routine. Please note that use of TXMLWriterFlag options like 
xwfAllowNullCharsInAttributeValue and xwfSpecialCharsInAttributeValue can 
result in an XML document that cannot be handled by a validating XML 
processor. The ReadXMLFile routine in <file>LazUtils</file> will accept and 
handle the values.
</p>
</descr>
<seealso>
<link id="WriteXMLFile"/>
</seealso>
</element>

<!-- argument Visibility: default -->
<element name="WriteXML.Element">
<short>DOM Node with the XML content written in the method.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXML.AFileName">
<short>File name where the XML content is stored.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXML.AFile">
<short>Text file type where the content is written.</short>
</element>

<!-- argument Visibility: default -->
<element name="WriteXML.AStream">
<short>Stream where the XML document is stored.</short>
</element>

<element name="WriteXML.Flags">
<short>Options enabled when writing the XML content.</short>
</element>

</module>
<!-- laz2_XMLWrite -->

</package>
</fpdoc-descriptions>