1/****************************************************************************
2**
3** Copyright (C) 2020 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \group xml-tools
30    \title XML Classes
31
32    \brief Classes that support XML.
33
34    These classes are relevant to XML users.
35
36    \generatelist{related}
37*/
38
39/*!
40    \page xml-processing.html
41    \title XML Processing
42
43    \brief An Overview of the XML processing facilities in Qt.
44
45    Qt provides two general-purpose sets of APIs to read and write well-formed
46    XML: \l{XML Streaming}{stream based} and
47    \l{Working with the DOM Tree}{DOM based}.
48
49    Qt also provides specific support for some XML dialects. For instance, the
50    Qt SVG module provides the QSvgRenderer and QSvgGenerator classes to read
51    and write a subset of SVG, an XML-based file
52    format. Qt also provides helper functions that may be useful to
53    those working with XML and XHTML: see Qt::escape() and
54    Qt::convertFromPlainText().
55
56    \section1 Topics:
57
58    \list
59    \li \l {Classes for XML Processing}
60    \li \l {An Introduction to Namespaces}
61    \li \l {XML Streaming}
62    \li \l {Working with the DOM Tree}
63    \endlist
64
65    \section1 Classes for XML Processing
66
67    These classes are relevant to XML users.
68
69    \annotatedlist xml-tools
70*/
71
72/*!
73    \page xml-namespaces.html
74    \title An Introduction to Namespaces
75    \target namespaces
76
77    \nextpage XML Streaming
78
79    Parts of the Qt XML module documentation assume that you are familiar
80    with XML namespaces. Here we present a brief introduction; skip to
81    \l{#namespacesConventions}{Qt XML documentation conventions}
82    if you already know this material.
83
84    Namespaces are a concept introduced into XML to allow a more modular
85    design. With their help data processing software can easily resolve
86    naming conflicts in XML documents.
87
88    Consider the following example:
89
90    \snippet code/doc_src_qtxml.qdoc 6
91
92    Here we find three different uses of the name \e title. If you wish to
93    process this document you will encounter problems because each of the
94    \e titles should be displayed in a different manner -- even though
95    they have the same name.
96
97    The solution would be to have some means of identifying the first
98    occurrence of \e title as the title of a book, i.e. to use the \e
99    title element of a book namespace to distinguish it from, for example,
100    the chapter title, e.g.:
101    \snippet code/doc_src_qtxml.qdoc 7
102
103    \e book in this case is a \e prefix denoting the namespace.
104
105    Before we can apply a namespace to element or attribute names we must
106    declare it.
107
108    Namespaces are URIs like \e http://www.example.com/fnord/book/. This
109    does not mean that data must be available at this address; the URI is
110    simply used to provide a unique name.
111
112    We declare namespaces in the same way as attributes; strictly speaking
113    they \e are attributes. To make for example \e
114    http://www.example.com/fnord/ the document's default XML namespace \e
115    xmlns we write
116
117    \snippet code/doc_src_qtxml.qdoc 8
118
119    To distinguish the \e http://www.example.com/fnord/book/ namespace from
120    the default, we must supply it with a prefix:
121
122    \snippet code/doc_src_qtxml.qdoc 9
123
124    A namespace that is declared like this can be applied to element and
125    attribute names by prepending the appropriate prefix and a ":"
126    delimiter. We have already seen this with the \e book:title element.
127
128    Element names without a prefix belong to the default namespace. This
129    rule does not apply to attributes: an attribute without a prefix does
130    not belong to any of the declared XML namespaces at all. Attributes
131    always belong to the "traditional" namespace of the element in which
132    they appear. A "traditional" namespace is not an XML namespace, it
133    simply means that all attribute names belonging to one element must be
134    different. Later we will see how to assign an XML namespace to an
135    attribute.
136
137    Due to the fact that attributes without prefixes are not in any XML
138    namespace there is no collision between the attribute \e title (that
139    belongs to the \e author element) and for example the \e title element
140    within a \e chapter.
141
142    Let's clarify this with an example:
143    \snippet code/doc_src_qtxml.qdoc 10
144
145    Within the \e document element we have two namespaces declared. The
146    default namespace \e http://www.example.com/fnord/ applies to the \e
147    book element, the \e chapter element, the appropriate \e title element
148    and of course to \e document itself.
149
150    The \e book:author and \e book:title elements belong to the namespace
151    with the URI \e http://www.example.com/fnord/book/.
152
153    The two \e book:author attributes \e title and \e name have no XML
154    namespace assigned. They are only members of the "traditional"
155    namespace of the element \e book:author, meaning that for example two
156    \e title attributes in \e book:author are forbidden.
157
158    In the above example we circumvent the last rule by adding a \e title
159    attribute from the \e http://www.example.com/fnord/ namespace to \e
160    book:author: the \e fnord:title comes from the namespace with the
161    prefix \e fnord that is declared in the \e book:author element.
162
163    Clearly the \e fnord namespace has the same namespace URI as the
164    default namespace. So why didn't we simply use the default namespace
165    we'd already declared? The answer is quite complex:
166    \list
167    \li attributes without a prefix don't belong to any XML namespace at
168    all, not even to the default namespace;
169    \li additionally omitting the prefix would lead to a \e title-title clash;
170    \li writing it as \e xmlns:title would declare a new namespace with the
171    prefix \e title instead of applying the default \e xmlns namespace.
172    \endlist
173
174    With the Qt XML classes elements and attributes can be accessed in two
175    ways: either by referring to their qualified names consisting of the
176    namespace prefix and the "real" name (or \e local name) or by the
177    combination of local name and namespace URI.
178
179    More information on XML namespaces can be found at
180    \l http://www.w3.org/TR/REC-xml-names/.
181
182    \target namespacesConventions
183    \section1 Conventions Used in the Qt XML Documentation
184
185    The following terms are used to distinguish the parts of names within
186    the context of namespaces:
187    \list
188    \li  The \e {qualified name}
189        is the name as it appears in the document. (In the above example \e
190        book:title is a qualified name.)
191    \li  A \e {namespace prefix} in a qualified name
192        is the part to the left of the ":". (\e book is the namespace prefix in
193        \e book:title.)
194    \li  The \e {local part} of a name (also referred to as the \e {local
195        name}) appears to the right of the ":". (Thus \e title is the
196        local part of \e book:title.)
197    \li  The \e {namespace URI} ("Uniform Resource Identifier") is a unique
198        identifier for a namespace. It looks like a URL
199        (e.g. \e http://www.example.com/fnord/ ) but does not require
200        data to be accessible by the given protocol at the named address.
201    \endlist
202
203    Elements without a ":" (like \e chapter in the example) do not have a
204    namespace prefix. In this case the local part and the qualified name
205    are identical (i.e. \e chapter).
206
207    \sa {DOM Bookmarks Example}
208*/
209
210/*!
211    \page xml-streaming.html
212    \title XML Streaming
213
214    \previouspage An Introduction to Namespaces
215    \nextpage Working with the DOM Tree
216
217    Qt provides two classes for reading and writing XML through a simple streaming
218    API:  QXmlStreamReader and QXmlStreamWriter.
219
220    A stream reader reports an XML document as a stream
221    of tokens. This differs from SAX as SAX applications provide handlers to
222    receive XML events from the parser whereas the QXmlStreamReader drives the
223    loop, pulling tokens from the reader when they are needed.
224    This pulling approach makes it possible to build recursive descent parsers,
225    allowing XML parsing code to be split into different methods or classes.
226
227    QXmlStreamReader is a well-formed XML 1.0 parser that excludes external
228    parsed entities. Hence, data provided by the stream reader adheres to the
229    W3C's criteria for well-formed XML, as long as no error occurs. Otherwise,
230    functions such as \l{QXmlStreamReader::atEnd()}{atEnd()},
231    \l{QXmlStreamReader::error()}{error()} and \l{QXmlStreamReader::hasError()}
232    {hasError()} can be used to check and view the errors.
233
234    An example of QXmlStreamReader implementation would be the \c XbelReader in
235    \l{QXmlStream Bookmarks Example}, which wraps a QXmlStreamReader.
236    The constructor takes \a treeWidget as a parameter and the class has Xbel
237    specific functions:
238
239    \snippet streambookmarks/xbelreader.h 1
240
241    \dots
242    \snippet streambookmarks/xbelreader.h 2
243    \dots
244
245    The \c read() function accepts a QIODevice and sets it with
246    \l{QXmlStreamReader::setDevice()}{setDevice()}. The
247    \l{QXmlStreamReader::raiseError()}{raiseError()} function is used to
248    display a custom error message, inidicating that the file's version
249    is incorrect.
250
251    \snippet streambookmarks/xbelreader.cpp 1
252
253    The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML
254    writer with a simple streaming API. QXmlStreamWriter operates on a
255    QIODevice and has specialized functions for all XML tokens or events you
256    want to write, such as \l{QXmlStreamWriter::writeDTD()}{writeDTD()},
257    \l{QXmlStreamWriter::writeCharacters()}{writeCharacters()},
258    \l{QXmlStreamWriter::writeComment()}{writeComment()} and so on.
259
260    To write XML document with QXmlStreamWriter, you start a document with the
261    \l{QXmlStreamWriter::writeStartDocument()}{writeStartDocument()} function
262    and end it with \l{QXmlStreamWriter::writeEndDocument()}
263    {writeEndDocument()}, which implicitly closes all remaining open tags.
264    Element tags are opened with \l{QXmlStreamWriter::writeStartDocument()}
265    {writeStartDocument()} and followed by
266    \l{QXmlStreamWriter::writeAttribute()}{writeAttribute()} or
267    \l{QXmlStreamWriter::writeAttributes()}{writeAttributes()},
268    element content, and then \l{QXmlStreamWriter::writeEndDocument()}
269    {writeEndDocument()}. Also, \l{QXmlStreamWriter::writeEmptyElement()}
270    {writeEmptyElement()} can be used to write empty elements.
271
272    Element content comprises characters, entity references or nested elements.
273    Content can be written with \l{QXmlStreamWriter::writeCharacters()}
274    {writeCharacters()}, a function that also takes care of escaping all
275    forbidden characters and character sequences,
276    \l{QXmlStreamWriter::writeEntityReference()}{writeEntityReference()},
277    or subsequent calls to \l{QXmlStreamWriter::writeStartElement()}
278    {writeStartElement()}.
279
280    The \c XbelWriter class from \l{QXmlStream Bookmarks Example} wraps a
281    QXmlStreamWriter. Its \c writeFile() function illustrates the core
282    functions of QXmlStreamWriter mentioned above:
283
284    \snippet streambookmarks/xbelwriter.cpp 1
285*/
286
287/*!
288    \page xml-dom.tml
289    \title Working with the DOM Tree
290    \target dom
291
292    \previouspage XML Streaming
293
294    DOM Level 2 is a W3C Recommendation for XML interfaces that maps the
295    constituents of an XML document to a tree structure. The specification
296    of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}.
297
298    \target domIntro
299    \section1 Introduction to DOM
300
301    DOM provides an interface to access and change the content and
302    structure of an XML file. It makes a hierarchical view of the document
303    (a tree view). Thus -- in contrast to the streaming API provided
304    by QXmlStreamReader -- an object
305    model of the document is resident in memory after parsing which makes
306    manipulation easy.
307
308    All DOM nodes in the document tree are subclasses of \l QDomNode. The
309    document itself is represented as a \l QDomDocument object.
310
311    Here are the available node classes and their potential child classes:
312
313    \list
314    \li \l QDomDocument: Possible children are
315            \list
316            \li \l QDomElement (at most one)
317            \li \l QDomProcessingInstruction
318            \li \l QDomComment
319            \li \l QDomDocumentType
320            \endlist
321    \li \l QDomDocumentFragment: Possible children are
322            \list
323            \li \l QDomElement
324            \li \l QDomProcessingInstruction
325            \li \l QDomComment
326            \li \l QDomText
327            \li \l QDomCDATASection
328            \li \l QDomEntityReference
329            \endlist
330    \li \l QDomDocumentType: No children
331    \li \l QDomEntityReference: Possible children are
332            \list
333            \li \l QDomElement
334            \li \l QDomProcessingInstruction
335            \li \l QDomComment
336            \li \l QDomText
337            \li \l QDomCDATASection
338            \li \l QDomEntityReference
339            \endlist
340    \li \l QDomElement: Possible children are
341            \list
342            \li \l QDomElement
343            \li \l QDomText
344            \li \l QDomComment
345            \li \l QDomProcessingInstruction
346            \li \l QDomCDATASection
347            \li \l QDomEntityReference
348            \endlist
349    \li \l QDomAttr: Possible children are
350            \list
351            \li \l QDomText
352            \li \l QDomEntityReference
353            \endlist
354    \li \l QDomProcessingInstruction: No children
355    \li \l QDomComment: No children
356    \li \l QDomText: No children
357    \li \l QDomCDATASection: No children
358    \li \l QDomEntity: Possible children are
359            \list
360            \li \l QDomElement
361            \li \l QDomProcessingInstruction
362            \li \l QDomComment
363            \li \l QDomText
364            \li \l QDomCDATASection
365            \li \l QDomEntityReference
366            \endlist
367    \li \l QDomNotation: No children
368    \endlist
369
370    With \l QDomNodeList and \l QDomNamedNodeMap two collection classes
371    are provided: \l QDomNodeList is a list of nodes,
372    and \l QDomNamedNodeMap is used to handle unordered sets of nodes
373    (often used for attributes).
374
375    The \l QDomImplementation class allows the user to query features of the
376    DOM implementation.
377
378    To get started please refer to the \l QDomDocument documentation.
379    You might also want to take a look at the \l{DOM Bookmarks Example},
380    which illustrates how to read and write an XML bookmark file (XBEL)
381    using DOM.
382*/
383