Saving document

From 7e7153457722ff2272bf094cca5387bd2e2ebd71 Mon Sep 17 00:00:00 2001 From: "arseny.kapoulkine@gmail.com" Date: Sun, 29 Apr 2012 22:51:21 +0000 Subject: docs: Regenerated HTML documentation git-svn-id: http://pugixml.googlecode.com/svn/trunk@908 99668b35-9821-0410-8761-19e4c4f06640 --- docs/manual/saving.html | 110 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 95 insertions(+), 15 deletions(-) (limited to 'docs/manual/saving.html') 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 @@ Saving document - - + +

-pugixml 1.0 manual | +pugixml 1.2 manual | Overview | Installation | Document: @@ -37,6 +37,7 @@

Saving a single subtree

+

Customizing document declaration

Often after creating a new document or loading the existing one and processing @@ -52,8 +53,9 @@

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 ":anonymous". + are properly escaped (unless format_no_escapes + flag is set). In order to guard against forgotten node/attribute names, empty + node/attribute names are printed as ":anonymous". For well-formed output, make sure all node and attribute names are set to meaningful values.

@@ -179,11 +181,11 @@

In order to output the document via some custom transport, for example sockets, - you should create an object which implements xml_writer_file + you should create an object which implements xml_writer interface and pass it to save - function. xml_writer_file::write - function is called with a buffer as an input, where data - points to buffer start, and size + function. xml_writer::write function is called with a buffer + as an input, where data points + to buffer start, and size is equal to the buffer size in bytes. write implementation must write the buffer to the transport; it can not save the passed buffer pointer, as the buffer contents will change after write returns. The buffer contains the @@ -192,9 +194,8 @@

write function is called with relatively large blocks (size is usually several kilobytes, except for - the first block with BOM, which is output only if format_write_bom - 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.

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 parse_ws_pcdata flag, to preserve the original document formatting as much as possible. This flag - is off by default. + is off by default.

+ + +

+ format_no_escapes 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. &) 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 on + by default.

@@ -337,6 +350,16 @@ functions: they never output the BOM. This flag is off by default. +

+ format_save_file_text changes + the file mode when using save_file + 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 + off by default. +

Additionally, there is one predefined option mask: @@ -435,10 +458,67 @@

+

+

+ Customizing document declaration +

+

+ When you are saving the document using xml_document::save() or xml_document::save_file(), a default XML document declaration is + output, if format_no_declaration + 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. +

+

+ + + + + +

	Note
	+ 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 parse_declaration + to the parsing flags; the resulting document will contain the original + declaration node, which will be output during saving. +

+

+ Declaration node is a node with type node_declaration; + 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. +

+

+ This is an example that shows how to create a custom declaration node (samples/save_declaration.cpp): +

+

+ +

+

// get a test document
+pugi::xml_document doc;
+doc.load("<foo bar='baz'><call>hey</call></foo>");
+
+// add a custom declaration node
+pugi::xml_node decl = doc.prepend_child(pugi::node_declaration);
+decl.append_attribute("version") = "1.0";
+decl.append_attribute("encoding") = "UTF-8";
+decl.append_attribute("standalone") = "no";
+
+// <?xml version="1.0" encoding="UTF-8" standalone="no"?> 
+// <foo bar="baz">
+//         <call>hey</call>
+// </foo>
+doc.save(std::cout);
+std::cout << std::endl;
+

+

+

+

- @@ -446,7 +526,7 @@

-pugixml 1.0 manual | +pugixml 1.2 manual | Overview | Installation | Document: -- cgit v1.2.3