NCBI C++ ToolKit
libxml2_xmlwrapp.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 /* $Id: libxml2_xmlwrapp.hpp 101294 2023-11-28 14:10:36Z satskyse $
2  * ===========================================================================
3  *
4  * PUBLIC DOMAIN NOTICE
5  * National Center for Biotechnology Information
6  *
7  * This software/database is a "United States Government Work" under the
8  * terms of the United States Copyright Act. It was written as part of
9  * the author's official duties as a United States Government employee and
10  * thus cannot be copyrighted. This software/database is freely available
11  * to the public for use. The National Library of Medicine and the U.S.
12  * Government have not placed any restriction on its use or reproduction.
13  *
14  * Although all reasonable efforts have been taken to ensure the accuracy
15  * and reliability of the software and data, the NLM and the U.S.
16  * Government do not and cannot warrant the performance or results that
17  * may be obtained by using this software or data. The NLM and the U.S.
18  * Government disclaim all warranties, express or implied, including
19  * warranties of performance, merchantability or fitness for any particular
20  * purpose.
21  *
22  * Please cite the author in any work or product based on this material.
23  *
24  * ===========================================================================
25  *
26  * Author: Sergey Satskiy, NCBI
27  * Credits: Denis Vakatov, NCBI (API design)
28  *
29  */
30 
31 
32 /** @file
33  * Extension to work with raw libxml2 objects
34 **/
35 
36 #ifndef _xmlwrapp_libxml2_xmlwrapp_hpp_
37 #define _xmlwrapp_libxml2_xmlwrapp_hpp_
38 
39 
42 
43 // Forward declaration
44 #include <libxml/tree.h>
45 #include <libxml/parser.h>
46 
47 
48 namespace xml {
49 
50 /// Extension to the xml::document class which allows working with raw libxml2
51 /// documents.
52 class libxml2_document : public document
53 {
54  public:
55  /**
56  * Create a new document using the given raw libxml2 object.
57  * Use it at your own risk.
58  *
59  * @param raw_doc
60  * Raw libxml2 document.
61  * If passed NULL, then an exception will be thrown.
62  * @param ownership
63  * Whether to grab the libxml2 document ownership or not. If the
64  * ownership is grabbed then the object will be freed in the
65  * destructor.
66  * @author Denis Vakatov, NCBI
67  **/
68  libxml2_document(xmlDoc * raw_doc, ownership_type ownership);
69 
70  /**
71  * Create a new XML document with the default settings. The new
72  * document will contain a root node with a name of "blank".
73  * The document ownership is set to type_own.
74  *
75  * @author Peter Jones
76  **/
77  libxml2_document(void);
78 
79  /**
80  * Create a new XML document object by parsing the given XML file.
81  * The document ownership is set to type_own.
82  *
83  * @param filename
84  * The XML file name.
85  * @param messages
86  * A pointer to the object where all the warnings are collected.
87  * If NULL then no messages will be collected.
88  * @param how
89  * How to treat warnings (default: warnings are not treated as
90  * errors). If warnings are treated as errors then an exception
91  * is thrown in case of both errors and/or warnings. If warnings
92  * are not treated as errors then an exception will be thrown
93  * only when there are errors.
94  * @exception Throws xml::parser_exception in case of parsing errors
95  * and std::exception in case of other problems.
96  * @author Sergey Satskiy, NCBI
97  **/
98  libxml2_document(const char* filename, error_messages* messages,
101 
102  /**
103  * Create a new XML documant object by parsing the given XML from a
104  * memory buffer.
105  * The document ownership is set to type_own.
106  *
107  * @param data
108  * The XML memory buffer.
109  * @param size
110  * Size of the memory buffer.
111  * @param messages
112  * A pointer to the object where all the warnings are collected.
113  * If NULL then no messages will be collected.
114  * @param how
115  * How to treat warnings (default: warnings are not treated as
116  * errors). If warnings are treated as errors then an exception
117  * is thrown in case of both errors and/or warnings. If warnings
118  * are not treated as errors then an exception will be thrown
119  * only when there are errors.
120  * @exception Throws xml::parser_exception in case of parsing errors
121  * and std::exception in case of other problems.
122  * @author Sergey Satskiy, NCBI
123  **/
124  libxml2_document(const char* data, size_type size,
125  error_messages* messages,
128 
129  /**
130  * Create a new XML document and set the name of the root element
131  * to the given text.
132  * The document ownership is set to type_own.
133  *
134  * @param root_name
135  * What to set the name of the root element to.
136  * @author Peter Jones
137  **/
138  explicit libxml2_document(const char *root_name);
139 
140  /**
141  * Create a new XML document and set the root node.
142  * The document ownership is set to type_own.
143  *
144  * @param n
145  * The node to use as the root node. n will be copied.
146  * @author Peter Jones
147  **/
148  explicit libxml2_document(const node &n);
149 
150  /**
151  * Creates a new XML document using the document_proxy,
152  * i.e. essentially xslt results. (see CXX-2458).
153  * The document ownership is set to type_own.
154  *
155  * @param doc_proxy
156  * XSLT results
157  * @author Denis Vakatov
158  **/
159  libxml2_document(const document_proxy & doc_proxy);
160 
161  /**
162  * Creates a new XML document by parsing the given XML from a stream.
163  * The document ownership is set to type_own.
164  *
165  * @param stream
166  * The stream to read XML document from.
167  * @param messages
168  * A pointer to the object where all the warnings are collected.
169  * If NULL then no messages will be collected.
170  * @param how
171  * How to treat warnings (default: warnings are not treated as
172  * errors). If warnings are treated as errors then an exception
173  * is thrown in case of both errors and/or warnings. If warnings
174  * are not treated as errors then an exception will be thrown
175  * only when there are errors.
176  * @exception Throws xml::parser_exception in case of parsing errors
177  * and std::exception in case of other problems.
178  * @author Denis Vakatov
179  **/
180  libxml2_document(std::istream & stream,
181  error_messages * messages,
184 
185  /**
186  * Moving constructor.
187  * @param other The other libxml2 document.
188  **/
190 
191  /**
192  * Moving assignment.
193  * @param other The other libxml2 document.
194  **/
196 
197  /**
198  * Provides a raw libxml2 document.
199  *
200  * @return
201  * Raw libxml2 document
202  * @author Denis Vakatov, NCBI
203  **/
204  xmlDoc * get_raw_doc(void);
205 
206  /**
207  * Set a raw libxml2 document.
208  * If the previous document was owned by the object, then it 'll be
209  * destroyed.
210  *
211  * @param raw_doc
212  * Raw libxml2 document to manage from now on.
213  * If passed NULL, then an exception will be thrown.
214  * If passed the same libxml2 document as the object has then this
215  * method behaves as set_ownership(...).
216  * @param ownersip
217  * Whether to take the ownersip over the 'raw_doc'
218  * @author Greg Schuler, NCBI
219  **/
220  void set_raw_doc(xmlDoc * raw_doc, ownership_type ownership);
221 
222  /**
223  * Provides the document ownership type.
224  *
225  * @return
226  * type_own if the document is owned by the object, i.e. will be freed
227  * in the destructor.
228  **/
229  ownership_type get_ownership(void) const;
230 
231  /**
232  * Set the document ownership.
233  *
234  * @param ownership
235  * The new ownership. If it is 'type_own' then the libxml2 document
236  * will be freed in the destructor.
237  **/
238  void set_ownership(ownership_type ownership);
239 
240  private:
243 };
244 
245 }
246 
247 #endif
248 
The xml::document_proxy class to be a relay between XSLT results and the document.
The xml::document class is used to hold the XML tree and various bits of information about it.
Definition: document.hpp:80
size_type size(void) const
Returns the number of child nodes of this document.
Definition: document.cpp:683
std::size_t size_type
size type
Definition: document.hpp:83
The xml::error_messages class is used to store all the error message which are collected while parsin...
Definition: errors.hpp:137
Extension to the xml::document class which allows working with raw libxml2 documents.
xmlDoc * get_raw_doc(void)
Provides a raw libxml2 document.
libxml2_document & operator=(const libxml2_document &)
void set_raw_doc(xmlDoc *raw_doc, ownership_type ownership)
Set a raw libxml2 document.
ownership_type get_ownership(void) const
Provides the document ownership type.
libxml2_document(const libxml2_document &)
void set_ownership(ownership_type ownership)
Set the document ownership.
libxml2_document(void)
Create a new XML document with the default settings.
libxml2_document & operator=(libxml2_document &&other)
Moving assignment.
The xml::node class is used to hold information about one XML node.
Definition: node.hpp:106
char data[12]
Definition: iconv.c:80
yy_size_t n
This file contains the definition of the xml::document class.
XML library namespace.
Definition: attributes.hpp:57
ownership_type
Used to specify if xmlwrapp should grab the ownership of various objects.
Definition: ownership.hpp:43
warnings_as_errors_type
A type for different approaches to process warnings.
Definition: errors.hpp:259
@ type_warnings_not_errors
Do not treat warnings as errors.
Definition: errors.hpp:261
Ownership enumeration for various objects.
Modified on Thu May 30 12:29:44 2024 by modify_doxy.py rev. 669887