From a7e9d3f37d5e9fba4b9acaa43e7c12b6d9a669ae Mon Sep 17 00:00:00 2001 From: Mike Hommey Date: Thu, 8 Jun 2006 10:59:26 +0200 Subject: Load /tmp/libxml2-2.6.26 into libxml2/branches/upstream/current. --- doc/library.html | 137 +++++++++++++++++++++++++++---------------------------- 1 file changed, 67 insertions(+), 70 deletions(-) (limited to 'doc/library.html') diff --git a/doc/library.html b/doc/library.html index b5faade..afe4d77 100644 --- a/doc/library.html +++ b/doc/library.html @@ -7,27 +7,25 @@ H1 {font-family: Verdana,Arial,Helvetica} H2 {font-family: Verdana,Arial,Helvetica} H3 {font-family: Verdana,Arial,Helvetica} A:link, A:visited, A:active { text-decoration: underline } -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);
+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 +gettingbootstrappedusing the XML tollkit from the C language. It is not +intended tobeextensive. I hope the automatically generated documents will +providethecompleteness required, but as a separate set of documents. The +interfacesofthe XML parser are by principle low level, Those interested in a +higherlevelAPI should look at DOM.

The parser interfaces +forXMLareseparated from the HTMLparserinterfaces. Let's have a +look at how the XML parser can becalled:

Invoking the parser : the pull method

Usually, the first thing to do is to read an XML input. The +parseracceptsdocuments either from in-memory strings or from files. The +functionsaredefined 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.

+

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,
+
The parser returns a pointer to the document structure (or NULL in
+caseoffailure).
Invoking the parser: the push method
In order for the application to keep the control when the document
+isbeingfetched (which is common for GUI based programs) libxml2 provides
+apushinterface, too, as of version 1.8.3. Here are the interfacefunctions:
xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
                                          void *user_data,
                                          const char *chunk,
                                          int size,
@@ -54,17 +52,17 @@ int              xmlParseChunk          (xmlParserCtxtPtr ctxt,
                     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>
+            }
The HTML parser embedded into libxml2 also has a push
+interface;thefunctions are just prefixed by "html" rather than "xml".
Invoking the parser: the SAX interface
The tree-building interface makes the parser memory-hungry,
+firstloadingthe document in memory and then building the tree itself. Reading
+adocumentwithout building the tree is possible using the SAX interfaces
+(seeSAX.h andJamesHenstridge'sdocumentation).
+Note also that the push interface can belimited to SAX:just use the two first
+arguments ofxmlCreatePushParserCtxt().
Building a tree from scratch
The other way to get an XML tree in memory is by building
+it.Basicallythere is a set of functions dedicated to building new
+elements.(These arealso described in <libxml/tree.h>.) For example,
+here is apiece ofcode that produces the XML document used in the previous
+examples:
    #include <libxml/tree.h>
     xmlDocPtr doc;
     xmlNodePtr tree, subtree;
 
@@ -78,59 +76,58 @@ code that produces the XML document used in the previous examples:
    #
     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.

+    xmlSetProp(subtree, "href", "linus.gif");
Not really rocket science ...
Traversing the tree
Basically by including"tree.h"yourcode
+has access to the internal structure of all the elementsof the tree.The names
+should be somewhat simple
+likeparent,children,
+next,prev,properties,
+etc... For example, stillwith the previousexample:
doc->children->children->children
points to the title element,
doc->children->children->next->children->children
points to the text node containing the chapter title
+"TheLinuxadventure".
NOTE: XML allows PIs and
+commentstobepresent before the document root, so
+doc->childrenmaypointto an element which is not the document
+Root Element; afunctionxmlDocGetRootElement()was added for this
+purpose.
Modifying the tree
Functions are provided for reading and writing the document content.Hereis
+an excerpt from the tree API:
xmlAttrPtr xmlSetProp(xmlNodePtr node, const xmlChar
+  *name,constxmlChar *value);

+    
This sets (or changes) an attribute carried by an ELEMENT
+      node.Thevalue 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.

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

+    
This function returns a pointer to new copy of thepropertycontent.
+      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.

+
Two functions are provided for reading and writing the text
+associatedwithelements:
xmlNodePtr xmlStringGetNodeList(xmlDocPtr doc,
+  constxmlChar*value);

+    
This function takes an "external" string and converts it toonetext
+      node or possibly to a list of entity and text nodes.Allnon-predefined
+      entity references like &Gnome; will bestoredinternally as entity
+      nodes, hence the result of the function maynot bea 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").

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

+    
This function is the inverseofxmlStringGetNodeList().
+      It generates a newstringcontaining the content of the text and entity
+      nodes. Note theextraargument inLine. If this argument is set to 1, the
+      function willexpandentity references.  For example, instead of
+      returning the&Gnome;XML encoding in the string, it will substitute
+      it with itsvalue (say,"GNU Network Object Model Environment").

     

-
Saving a tree
Basically 3 options are possible:
void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int
-  *size);

+
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.

+    
Saves the document to a file. In this case,
+      thecompressioninterface 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);

+
Compression
The library transparently handles compression when
+doingfile-basedaccesses. The level of compression on saves can be turned on
+eithergloballyor individually for one file:
int  xmlGetDocCompressMode (xmlDocPtr doc);

     
Gets the document compression ratio (0-9).

     

 
void xmlSetDocCompressMode (xmlDocPtr doc, int mode);

-- 
cgit v1.2.3