xmlwrapp
Lightweight C++ XML parsing library
init.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
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 the definition of the xml::init class.
37  */
38 
39 #ifndef _xmlwrapp_init_h_
40 #define _xmlwrapp_init_h_
41 
42 // xmlwrapp includes
43 #include "xmlwrapp/export.h"
44 
45 /// XML library namespace
46 namespace xml
47 {
48 
49 /**
50  The xml::init class is used to configure the XML parser.
51 
52  If you want to use and of the xml::init member functions, do so before
53  you start any threads or use any other part of xmlwrapp. The member
54  functions may alter global and/or static variables and affect the behavior
55  of subsequently created classes (and the parser in particular).
56  In other words, this class is not thread safe.
57 
58  @note In xmlwrapp versions prior to 0.6.0, this class was used to initialize
59  the library and exactly one instance had to be created before first
60  use. This is no longer true: user code doesn't have to create any
61  instances, but it @em can create as many instances as it wants.
62  */
63 class XMLWRAPP_API init
64 {
65 public:
66  init();
67  ~init();
68 
69  /**
70  RAII helper changing some global XML library flag only for the duration
71  of its lifetime.
72 
73  Example use:
74  @code
75  void some_function()
76  {
77  if ( whatever )
78  {
79  xml::init::change_flag change(&xml::init::substitute_entities, false);
80 
81  // entities are not substituted here
82  }
83 
84  // entities substitution flag reverted to its original value here
85  }
86  @endcode
87 
88  @since 0.9.1
89  */
91  {
92  public:
93  typedef bool (*change_func_t)(bool);
94 
95  /**
96  Constructor changes the flag using the specified function.
97 
98  The same function will be called from this object destructor to
99  restore the flag value.
100 
101  @param change_func one of xml::init static methods, such as
102  indent_output or remove_whitespace
103  @param flag the value of the flag to use
104  */
105  change_flag(change_func_t change_func, bool flag)
106  : change_func_(change_func),
107  flag_orig_((*change_func)(flag))
108  {
109  }
110 
111  /// Destructor restores the original flag value.
113  {
114  (*change_func_)(flag_orig_);
115  }
116 
117  private:
118  change_func_t const change_func_;
119  bool const flag_orig_;
120  };
121 
122  /**
123  This member function controls whether or not the XML parser should
124  add text nodes for indenting when generating XML text output from a
125  node tree. The default is true.
126 
127  @param flag True to turn on indenting, false to turn it off.
128  @return previous state of the flag.
129  */
130  static bool indent_output(bool flag);
131 
132  /**
133  This member function controls whether or not the XML parser should
134  remove ignorable whitespace around XML elements. The default
135  is false.
136 
137  @param flag True to remove whitespace, false to leave alone.
138  @return previous state of the flag.
139  */
140  static bool remove_whitespace(bool flag);
141 
142  /**
143  This member function controls whether or not the XML parser should
144  substitute entities while parsing. The default is true.
145 
146  @param flag True to turn on substitution, false to turn off.
147  @return previous state of the flag.
148  */
149  static bool substitute_entities(bool flag);
150 
151  /**
152  This member function controls whether or not the XML parser should
153  load external (DTD) subsets while parsing. This will only affect the
154  loading of the subsets, it does not cause files to be validated. The
155  default is true.
156 
157  @param flag True to turn on loading, false to turn it off.
158  @return previous state of the flag.
159  */
160  static bool load_external_subsets(bool flag);
161 
162  /**
163  This member function controls whether or not the XML parser should
164  validate every XML document that is parses with its DTD. The default
165  is false.
166 
167  @return flag True to turn on validation, false to turn it off.
168  @return previous state of the flag.
169  */
170  static bool validate_xml(bool flag);
171 
172 private:
173  init(const init&);
174  init& operator=(const init&);
175 
176  void init_library();
177  void shutdown_library();
178 
179  static int ms_counter;
180 };
181 
182 } // namespace xml
183 
184 // use a "nifty counter" to ensure that any source file that uses xmlwrapp
185 // will initialize the library prior to its first use
186 namespace
187 {
188  xml::init g_xmlwrapp_initializer;
189 }
190 
191 #endif // _xmlwrapp_init_h_
xml::init::substitute_entities
static bool substitute_entities(bool flag)
This member function controls whether or not the XML parser should substitute entities while parsing.
xml::init::change_flag
RAII helper changing some global XML library flag only for the duration of its lifetime.
Definition: init.h:91
xml::init::change_flag::change_flag
change_flag(change_func_t change_func, bool flag)
Constructor changes the flag using the specified function.
Definition: init.h:105
xml::init::load_external_subsets
static bool load_external_subsets(bool flag)
This member function controls whether or not the XML parser should load external (DTD) subsets while ...
xml::init::validate_xml
static bool validate_xml(bool flag)
This member function controls whether or not the XML parser should validate every XML document that i...
xml::init
The xml::init class is used to configure the XML parser.
Definition: init.h:64
xml
XML library namespace.
Definition: attributes.h:52
xml::init::change_flag::~change_flag
~change_flag()
Destructor restores the original flag value.
Definition: init.h:112
xml::init::indent_output
static bool indent_output(bool flag)
This member function controls whether or not the XML parser should add text nodes for indenting when ...
xml::init::remove_whitespace
static bool remove_whitespace(bool flag)
This member function controls whether or not the XML parser should remove ignorable whitespace around...