diff options
Diffstat (limited to 'docs/manual/saving.html')
| -rw-r--r-- | docs/manual/saving.html | 110 |
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 < and &, - 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 (', &, <, >) and all non-printable characters + (those with codepoint values less than 32) are converted to XML escape + sequences (i.e. &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 < 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">"<foo bar='baz'><call>hey</call></foo>"</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">// <?xml version="1.0" encoding="UTF-8" standalone="no"?> +</span><span class="comment">// <foo bar="baz"> +</span><span class="comment">// <call>hey</call> +</span><span class="comment">// </foo> +</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"><<</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 © 2010 Arseny Kapoulkine<p> +<td align="right"><div class="copyright-footer">Copyright © 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: |