From 35a201cc8ef0c3f5b2df88d2e528aabee1048348 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 18:47:09 +0200 Subject: Initial/Final commit --- libxml2-2.9.10/doc/library.html | 158 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 libxml2-2.9.10/doc/library.html (limited to 'libxml2-2.9.10/doc/library.html') diff --git a/libxml2-2.9.10/doc/library.html b/libxml2-2.9.10/doc/library.html new file mode 100644 index 0000000..a3e9a57 --- /dev/null +++ b/libxml2-2.9.10/doc/library.html @@ -0,0 +1,158 @@ + + +The parser interfaces
Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

The XML C parser and toolkit of Gnome

The parser interfaces

Developer Menu
API Indexes
Related links

This section is directly intended to help programmers getting bootstrapped +using the XML tollkit from the C language. It is not intended to be +extensive. I hope the automatically generated documents will provide the +completeness required, but as a separate set of documents. The interfaces of +the XML parser are by principle low level, Those interested in a higher level +API should look at DOM.

The parser interfaces for XML are +separated from the HTML parser +interfaces. Let's have a look at how the XML parser can be called:

Invoking the parser : the pull method

Usually, the first thing to do is to read an XML input. The parser accepts +documents either from in-memory strings or from files. The functions are +defined in "parser.h":

+
xmlDocPtr xmlParseMemory(char *buffer, int size);
+

Parse a null-terminated string containing the document.

+
+
+
xmlDocPtr xmlParseFile(const char *filename);
+

Parse an XML document contained in a (possibly compressed) + file.

+
+

The parser returns a pointer to the document structure (or NULL in case of +failure).

Invoking the parser: the push method

In order for the application to keep the control when the document is +being fetched (which is common for GUI based programs) libxml2 provides a +push interface, too, as of version 1.8.3. Here are the interface +functions:

xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
+                                         void *user_data,
+                                         const char *chunk,
+                                         int size,
+                                         const char *filename);
+int              xmlParseChunk          (xmlParserCtxtPtr ctxt,
+                                         const char *chunk,
+                                         int size,
+                                         int terminate);

and here is a simple example showing how to use the interface:

            FILE *f;
+
+            f = fopen(filename, "r");
+            if (f != NULL) {
+                int res, size = 1024;
+                char chars[1024];
+                xmlParserCtxtPtr ctxt;
+
+                res = fread(chars, 1, 4, f);
+                if (res > 0) {
+                    ctxt = xmlCreatePushParserCtxt(NULL, NULL,
+                                chars, res, filename);
+                    while ((res = fread(chars, 1, size, f)) > 0) {
+                        xmlParseChunk(ctxt, chars, res, 0);
+                    }
+                    xmlParseChunk(ctxt, chars, 0, 1);
+                    doc = ctxt->myDoc;
+                    xmlFreeParserCtxt(ctxt);
+                }
+            }

The HTML parser embedded into libxml2 also has a push interface; the +functions are just prefixed by "html" rather than "xml".

Invoking the parser: the SAX interface

The tree-building interface makes the parser memory-hungry, first loading +the document in memory and then building the tree itself. Reading a document +without building the tree is possible using the SAX interfaces (see SAX.h and +James +Henstridge's documentation). Note also that the push interface can be +limited to SAX: just use the two first arguments of +xmlCreatePushParserCtxt().

Building a tree from scratch

The other way to get an XML tree in memory is by building it. Basically +there is a set of functions dedicated to building new elements. (These are +also described in <libxml/tree.h>.) For example, here is a piece of +code that produces the XML document used in the previous examples:

    #include <libxml/tree.h>
+    xmlDocPtr doc;
+    xmlNodePtr tree, subtree;
+
+    doc = xmlNewDoc("1.0");
+    doc->children = xmlNewDocNode(doc, NULL, "EXAMPLE", NULL);
+    xmlSetProp(doc->children, "prop1", "gnome is great");
+    xmlSetProp(doc->children, "prop2", "& linux too");
+    tree = xmlNewChild(doc->children, NULL, "head", NULL);
+    subtree = xmlNewChild(tree, NULL, "title", "Welcome to Gnome");
+    tree = xmlNewChild(doc->children, NULL, "chapter", NULL);
+    subtree = xmlNewChild(tree, NULL, "title", "The Linux adventure");
+    subtree = xmlNewChild(tree, NULL, "p", "bla bla bla ...");
+    subtree = xmlNewChild(tree, NULL, "image", NULL);
+    xmlSetProp(subtree, "href", "linus.gif");

Not really rocket science ...

Traversing the tree

Basically by including "tree.h" your +code has access to the internal structure of all the elements of the tree. +The names should be somewhat simple like parent, +children, next, prev, +properties, etc... For example, still with the previous +example:

doc->children->children->children

points to the title element,

doc->children->children->next->children->children

points to the text node containing the chapter title "The Linux +adventure".

NOTE: XML allows PIs and comments to be +present before the document root, so doc->children may point +to an element which is not the document Root Element; a function +xmlDocGetRootElement() was added for this purpose.

Modifying the tree

Functions are provided for reading and writing the document content. Here +is an excerpt from the tree API:

+
xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar *name, const + xmlChar *value);
+

This sets (or changes) an attribute carried by an ELEMENT node. + The value can be NULL.

+
+
+
const xmlChar *xmlGetProp(xmlNodePtr node, const xmlChar + *name);
+

This function returns a pointer to new copy of the property + content. Note that the user must deallocate the result.

+
+

Two functions are provided for reading and writing the text associated +with elements:

+
xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc, const xmlChar + *value);
+

This function takes an "external" string and converts it to one + text node or possibly to a list of entity and text nodes. All + non-predefined entity references like &Gnome; will be stored + internally as entity nodes, hence the result of the function may not be + a single node.

+
+
+
xmlChar *xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int + inLine);
+

This function is the inverse of + xmlStringGetNodeList(). It generates a new string + containing the content of the text and entity nodes. Note the extra + argument inLine. If this argument is set to 1, the function will expand + entity references. For example, instead of returning the &Gnome; + XML encoding in the string, it will substitute it with its value (say, + "GNU Network Object Model Environment").

+
+

Saving a tree

Basically 3 options are possible:

+
void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int + *size);
+

Returns a buffer into which the document has been saved.

+
+
+
extern void xmlDocDump(FILE *f, xmlDocPtr doc);
+

Dumps a document to an open file descriptor.

+
+
+
int xmlSaveFile(const char *filename, xmlDocPtr cur);
+

Saves the document to a file. In this case, the compression + interface is triggered if it has been turned on.

+
+

Compression

The library transparently handles compression when doing file-based +accesses. The level of compression on saves can be turned on either globally +or individually for one file:

+
int xmlGetDocCompressMode (xmlDocPtr doc);
+

Gets the document compression ratio (0-9).

+
+
+
void xmlSetDocCompressMode (xmlDocPtr doc, int mode);
+

Sets the document compression ratio.

+
+
+
int xmlGetCompressMode(void);
+

Gets the default compression ratio.

+
+
+
void xmlSetCompressMode(int mode);
+

Sets the default compression ratio.

+
+

Daniel Veillard

-- cgit v1.2.3