summaryrefslogtreecommitdiff
path: root/docs/manual/saving.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual/saving.html')
-rw-r--r--docs/manual/saving.html110
1 files changed, 95 insertions, 15 deletions
diff --git a/docs/manual/saving.html b/docs/manual/saving.html
index abaf9f2..2be70cb 100644
--- a/docs/manual/saving.html
+++ b/docs/manual/saving.html
@@ -4,15 +4,15 @@
<title>Saving document</title>
<link rel="stylesheet" href="../pugixml.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
-<link rel="home" href="../manual.html" title="pugixml 1.0">
-<link rel="up" href="../manual.html" title="pugixml 1.0">
+<link rel="home" href="../manual.html" title="pugixml 1.2">
+<link rel="up" href="../manual.html" title="pugixml 1.2">
<link rel="prev" href="modify.html" title="Modifying document data">
<link rel="next" href="xpath.html" title="XPath">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.0</a> manual |
+<a href="http://pugixml.org/">pugixml 1.2</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document:
@@ -37,6 +37,7 @@
<dt><span class="section"><a href="saving.html#manual.saving.subtree"> Saving a single subtree</a></span></dt>
<dt><span class="section"><a href="saving.html#manual.saving.options"> Output options</a></span></dt>
<dt><span class="section"><a href="saving.html#manual.saving.encoding"> Encodings</a></span></dt>
+<dt><span class="section"><a href="saving.html#manual.saving.declaration"> Customizing document declaration</a></span></dt>
</dl></div>
<p>
Often after creating a new document or loading the existing one and processing
@@ -52,8 +53,9 @@
<p>
Before writing to the destination the node/attribute data is properly formatted
according to the node type; all special XML symbols, such as &lt; and &amp;,
- are properly escaped. In order to guard against forgotten node/attribute names,
- empty node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>.
+ are properly escaped (unless <a class="link" href="saving.html#format_no_escapes">format_no_escapes</a>
+ flag is set). In order to guard against forgotten node/attribute names, empty
+ node/attribute names are printed as <code class="computeroutput"><span class="string">":anonymous"</span></code>.
For well-formed output, make sure all node and attribute names are set to meaningful
values.
</p>
@@ -179,11 +181,11 @@
</pre>
<p>
In order to output the document via some custom transport, for example sockets,
- you should create an object which implements <code class="computeroutput"><span class="identifier">xml_writer_file</span></code>
+ you should create an object which implements <code class="computeroutput"><span class="identifier">xml_writer</span></code>
interface and pass it to <code class="computeroutput"><span class="identifier">save</span></code>
- function. <code class="computeroutput"><span class="identifier">xml_writer_file</span><span class="special">::</span><span class="identifier">write</span></code>
- function is called with a buffer as an input, where <code class="computeroutput"><span class="identifier">data</span></code>
- points to buffer start, and <code class="computeroutput"><span class="identifier">size</span></code>
+ function. <code class="computeroutput"><span class="identifier">xml_writer</span><span class="special">::</span><span class="identifier">write</span></code> function is called with a buffer
+ as an input, where <code class="computeroutput"><span class="identifier">data</span></code> points
+ to buffer start, and <code class="computeroutput"><span class="identifier">size</span></code>
is equal to the buffer size in bytes. <code class="computeroutput"><span class="identifier">write</span></code>
implementation must write the buffer to the transport; it can not save the
passed buffer pointer, as the buffer contents will change after <code class="computeroutput"><span class="identifier">write</span></code> returns. The buffer contains the
@@ -192,9 +194,8 @@
<p>
<code class="computeroutput"><span class="identifier">write</span></code> function is called
with relatively large blocks (size is usually several kilobytes, except for
- the first block with BOM, which is output only if <a class="link" href="saving.html#format_write_bom">format_write_bom</a>
- is set, and last block, which may be small), so there is often no need for
- additional buffering in the implementation.
+ the last block that may be small), so there is often no need for additional
+ buffering in the implementation.
</p>
<p>
This is a simple example of custom writer for saving document data to STL
@@ -310,7 +311,19 @@
to be read by humans; also it can be useful if the document was parsed
with <a class="link" href="loading.html#parse_ws_pcdata">parse_ws_pcdata</a> flag, to
preserve the original document formatting as much as possible. This flag
- is <span class="bold"><strong>off</strong></span> by default.
+ is <span class="bold"><strong>off</strong></span> by default. <br><br>
+
+ </li>
+<li class="listitem">
+ <a name="format_no_escapes"></a><code class="literal">format_no_escapes</code> disables output
+ escaping for attribute values and PCDATA contents. If this flag is on,
+ special symbols (', &amp;, &lt;, &gt;) and all non-printable characters
+ (those with codepoint values less than 32) are converted to XML escape
+ sequences (i.e. &amp;amp;) during output. If this flag is off, no text
+ processing is performed; therefore, output XML can be malformed if output
+ contents contains invalid symbols (i.e. having a stray &lt; in the PCDATA
+ will make the output malformed). This flag is <span class="bold"><strong>on</strong></span>
+ by default.
</li>
</ul></div>
<p>
@@ -337,6 +350,16 @@
functions: they never output the BOM. This flag is <span class="bold"><strong>off</strong></span>
by default.
</li>
+<li class="listitem">
+ <a name="format_save_file_text"></a><code class="literal">format_save_file_text</code> changes
+ the file mode when using <code class="computeroutput"><span class="identifier">save_file</span></code>
+ function. By default, file is opened in binary mode, which means that
+ the output file will contain platform-independent newline \n (ASCII 10).
+ If this flag is on, file is opened in text mode, which on some systems
+ changes the newline format (i.e. on Windows you can use this flag to
+ output XML documents with \r\n (ASCII 13 10) newlines. This flag is
+ <span class="bold"><strong>off</strong></span> by default.
+ </li>
</ul></div>
<p>
Additionally, there is one predefined option mask:
@@ -435,10 +458,67 @@
</p></td></tr>
</table></div>
</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="manual.saving.declaration"></a><a class="link" href="saving.html#manual.saving.declaration" title="Customizing document declaration"> Customizing document declaration</a>
+</h3></div></div></div>
+<p>
+ When you are saving the document using <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">xml_document</span><span class="special">::</span><span class="identifier">save_file</span><span class="special">()</span></code>, a default XML document declaration is
+ output, if <code class="computeroutput"><span class="identifier">format_no_declaration</span></code>
+ is not speficied and if the document does not have a declaration node. However,
+ the default declaration is not customizable. If you want to customize the
+ declaration output, you need to create the declaration node yourself.
+ </p>
+<div class="note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ By default the declaration node is not added to the document during parsing.
+ If you just need to preserve the original declaration node, you have to
+ add the flag <a class="link" href="loading.html#parse_declaration">parse_declaration</a>
+ to the parsing flags; the resulting document will contain the original
+ declaration node, which will be output during saving.
+ </p></td></tr>
+</table></div>
+<p>
+ Declaration node is a node with type <a class="link" href="dom.html#node_declaration">node_declaration</a>;
+ it behaves like an element node in that it has attributes with values (but
+ it does not have child nodes). Therefore setting custom version, encoding
+ or standalone declaration involves adding attributes and setting attribute
+ values.
+ </p>
+<p>
+ This is an example that shows how to create a custom declaration node (<a href="../samples/save_declaration.cpp" target="_top">samples/save_declaration.cpp</a>):
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// get a test document
+</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_document</span> <span class="identifier">doc</span><span class="special">;</span>
+<span class="identifier">doc</span><span class="special">.</span><span class="identifier">load</span><span class="special">(</span><span class="string">"&lt;foo bar='baz'&gt;&lt;call&gt;hey&lt;/call&gt;&lt;/foo&gt;"</span><span class="special">);</span>
+
+<span class="comment">// add a custom declaration node
+</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">xml_node</span> <span class="identifier">decl</span> <span class="special">=</span> <span class="identifier">doc</span><span class="special">.</span><span class="identifier">prepend_child</span><span class="special">(</span><span class="identifier">pugi</span><span class="special">::</span><span class="identifier">node_declaration</span><span class="special">);</span>
+<span class="identifier">decl</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"version"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"1.0"</span><span class="special">;</span>
+<span class="identifier">decl</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"encoding"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"UTF-8"</span><span class="special">;</span>
+<span class="identifier">decl</span><span class="special">.</span><span class="identifier">append_attribute</span><span class="special">(</span><span class="string">"standalone"</span><span class="special">)</span> <span class="special">=</span> <span class="string">"no"</span><span class="special">;</span>
+
+<span class="comment">// &lt;?xml version="1.0" encoding="UTF-8" standalone="no"?&gt;
+</span><span class="comment">// &lt;foo bar="baz"&gt;
+</span><span class="comment">// &lt;call&gt;hey&lt;/call&gt;
+</span><span class="comment">// &lt;/foo&gt;
+</span><span class="identifier">doc</span><span class="special">.</span><span class="identifier">save</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">);</span>
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
-<td align="right"><div class="copyright-footer">Copyright &#169; 2010 Arseny Kapoulkine<p>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2012 Arseny Kapoulkine<p>
Distributed under the MIT License
</p>
</div></td>
@@ -446,7 +526,7 @@
<hr>
<table width="100%"><tr>
<td>
-<a href="http://pugixml.org/">pugixml 1.0</a> manual |
+<a href="http://pugixml.org/">pugixml 1.2</a> manual |
<a href="../manual.html">Overview</a> |
<a href="install.html">Installation</a> |
Document: