xmlwrapp
errors.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2010-2013 Vaclav Slavik <vslavik@gmail.com>
3  * All Rights Reserved
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name of the Author nor the names of its contributors
16  * may be used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
23  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30  * SUCH DAMAGE.
31  */
32 
33 /**
34  @file
35 
36  This file contains errors-handling classes: xml::exception and
37  xml::error_handler and derived classes.
38  */
39 
40 #ifndef _xmlwrapp_errors_h_
41 #define _xmlwrapp_errors_h_
42 
43 // xmlwrapp includes
44 #include "xmlwrapp/export.h"
45 
46 #include <stdexcept>
47 #include <string>
48 #include <list>
49 
50 /// XML library namespace
51 namespace xml
52 {
53 
54 class error_messages;
55 
56 /**
57  This exception class is thrown by xmlwrapp for all runtime XML-related
58  errors.
59 
60  @note C++ runtime may still thrown other errors when used from xmlwrapp.
61  Also, std::bad_alloc() is thrown in out-of-memory situations.
62 
63  @since 0.7.0
64  */
65 class XMLWRAPP_API exception : public std::runtime_error
66 {
67 public:
68  explicit exception(const std::string& what);
69  explicit exception(const error_messages& what);
70 };
71 
72 
73 /**
74  The xml::error_handler class is used to handle libxml2 errors and warnings
75  emitted during parsing, validation etc.
76 
77  Although you can derive a custom handler from it, the specializations
78  included in xmlwrapp should suffice for most uses: throw_on_error and
79  throw_on_error_or_warning throw on issues, error_messages collects errors
80  and warnings without throwing.
81 
82  @since 0.7.0
83  */
84 class XMLWRAPP_API error_handler
85 {
86 public:
87  virtual ~error_handler() {}
88 
89  /// Called by xmlwrapp to report an error.
90  virtual void on_error(const std::string& msg) = 0;
91 
92  /// Called by xmlwrapp to report a warning.
93  virtual void on_warning(const std::string& msg) = 0;
94 };
95 
96 
97 /**
98  Specialization of error_handler that throws on any error.
99 
100  @see throw_on_error
101  */
103 {
104 public:
105  void on_error(const std::string& msg) { throw exception(msg); }
106  void on_warning(const std::string&) {}
107 };
108 
109 /**
110  Specialization of error_handler that throws on any error or warning.
111 
112  @see throw_on_error_or_warning
113  */
115 {
116 public:
117  void on_warning(const std::string& msg) { on_error(msg); }
118 };
119 
120 /// Error handler object that throws on any error.
121 extern XMLWRAPP_API error_handler_throw_on_error throw_on_error;
122 
123 /// Error handler object that throws on any error or warning.
124 extern XMLWRAPP_API error_handler_throw_on_error_or_warning throw_on_error_or_warning;
125 
126 
127 /**
128  Single message in error_messages.
129 
130  @since 0.7.0
131  */
132 class XMLWRAPP_API error_message
133 {
134 public:
135  /// A type for different type of errors
137  {
138  type_error, ///< error
139  type_warning ///< warning
140  };
141 
142  /**
143  Create a new xml::error_message object.
144 
145  @param message The error message.
146  @param msg_type The error type.
147  */
148  error_message(const std::string& message, message_type msg_type)
149  : message_(message), type_(msg_type)
150  {}
151 
152  /// Get the error message type.
153  message_type type() const { return type_; }
154 
155  /// Get the error message.
156  const std::string& message() const { return message_; }
157 
158 private:
159  std::string message_;
160  message_type type_;
161 };
162 
163 
164 /**
165  The xml::error_messages class is used to store all the error messages
166  which are collected while parsing or validating an XML document.
167 
168  @since 0.7.0
169  */
170 class XMLWRAPP_API error_messages : public error_handler
171 {
172 public:
173  /// A type to store multiple messages
174  typedef std::list<error_message> messages_type;
175 
176  error_messages() : has_errors_(false), has_warnings_(false) {}
177 
178  /// Get the error messages.
179  const messages_type& messages() const { return messages_; }
180 
181  /**
182  Convenience function to find if there are any messages at all.
183  */
184  bool empty() const
185  {
186  return messages_.empty();
187  }
188 
189  /**
190  Check if there are warnings in the error messages.
191 
192  @return true if there is at least one warning in the error messages.
193  It does not consider errors.
194  */
195  bool has_warnings() const { return has_warnings_; }
196 
197  /**
198  Check if there are any errors.
199  */
200  bool has_errors() const { return has_errors_; }
201 
202 
203  /**
204  Convert error messages into a single printable string.
205 
206  The returned string is typically multiline, with the messages
207  separated with newlines ('\n').
208  */
209  std::string print() const;
210 
211 
212 
213  // Implementation of error_handler methods:
214  void on_error(const std::string& msg);
215  void on_warning(const std::string& msg);
216 
217 protected:
218  /// Called by print() to format a single message.
219  virtual std::string format_for_print(const error_message& msg) const;
220 
221 private:
222  messages_type messages_;
223  bool has_errors_;
224  bool has_warnings_;
225 };
226 
227 
228 } // namespace xml
229 
230 #endif // _xmlwrapp_errors_h_