XML Event/Callback element-wise Parser

DESCRIPTION:

Reads and processes the contents of an XML file or string by invoking user-level functions associated with different components of the XML tree. These include beginning and end of XML elements, comments, CDATA (escaped character data), entities, processing instructions, etc. This allows the caller to create the appropriate data structure from the XML document contents rather than the default tree (see ). Functions for specific tags/elements can be used in addition to the standard callback names.

USAGE:

xmlEventParse(file, handlers=xmlEventHandler(), ignoreBlanks = FALSE, addContext=TRUE,
               useTagName=TRUE, asText = FALSE, trim=TRUE, useExpat=FALSE, isURL = FALSE,
                state = NULL, replaceEntities = TRUE, validate = FALSE,
                 saxVersion = 1)

ARGUMENTS:

file
the source of the XML content. This can be a string giving the name of a file or remote URL, the XML itself, a connection object, or a function. If this is a string, and asText is TRUE, the value is the XML content. This allows one to read the content separately from parsing without having to write it to a file. If asText is FALSE and a string is passed for file, this is taken as the name of a file or remote URI. If one is using the libxml parser (i.e. not expat), this can be a URI accessed via HTTP or FTP or a compressed local file.

If a connection is given, the parser incrementally reads one line at a time by calling the function with the connection as the first argument (and 1 as the number of lines to read). The parser calls this function each time it needs more input.

If invoking the readLines function to get each line is excessively slow or inappropriate, one can provide a function as the value of fileName. Again, when the XML parser needs more content to process, it invokes this function to get a string. This function is called with a single argument, the maximum size of the string that can be returned. The function is responsible for accessing the correct connection(s), etc. which is typically done via lexical scoping/environments. This mechanism allows the user to control how the XML content is retrieved in very general ways. For example, one might read from a set of files, starting one when the contents of the previous file have been consumed. This allows for the use of hybrid connection objects.

Support for connections and functions in this form is only provided if one is using libxml2 and not libxml version 1.

handlers
a list of functions which will be invoked as the XML components in the document are encountered by the parser. The standard functions are startElement(), endElement() comment(), externalEntity(), entityDeclaration(), processingInstruction(), cdata(), text().
ignoreBlanks
logical value indicating whether text elements made up entirely of white space should be included in the resulting `tree'.
addContext
logical value indicating whether the callback functions in `handlers' should be invoked with contextual information about the parser and the position in the tree, such as node depth, path indices for the node relative the root, etc. This is not currently supported.
useTagName
logical value indicating whether the callback mechanism should look for a function matching the tag name in the startElement and endElement events, before calling the default handler functions. This allows the caller to handle different element types for a particular DTD with their own functions directly, rather than performing a second dispatch in startElement().
asText
logical value indicating that the first argument, `file', should be treated as the XML text to parse, not the name of a file. This allows the contents of documents to be retrieved from different sources (e.g. HTTP servers, XML-RPC, etc.) and still use this parser.
trim
whether to strip white space from the beginning and end of text strings.
useExpat
a logical value indicating whether to use the expat SAX parser, or to default to the libxml. If this is TRUE, the library must have been compiled with support for expat. See .
isURL
indicates whether the file argument refers to a URL (accessible via ftp or http) or a regular file on the system. If asText is TRUE, this should not be specified.
state
an optional S object that is passed to the callbacks and can be modified to communicate state between the callbacks. If this is given, the callbacks should accept an argument named .state and it should return an object that will be used as the updated value of this state object. The new value can be any S object and will be passed to the next callback where again it will be updated by that functions return value, and so on. If this not specified in the call to xmlEventParse, no .state argument is passed to the callbacks. This makes the interface compatible with previous releases. .
replaceEntities
logical value indicating whether to substitute entity references with their text directly. This should be left as False. The text still appears as the value of the node, but there is more information about its source, allowing the parse to be reversed with full reference information.
saxVersion
Which SAX version to use to interface with the C code, either 1 or 2. Both versions 1 and 2 are supported in S-Plus. This specifies which SAX interface to use in the C code. The essential difference is the number of arguments passed to the \code{startElement} handler function(s). In addition to the name of the element and the named-attributes vector, two additional arguments are provided. The first identifies the namespace of the element. This is a named character vector of length 1, with the value being the URI of the namespace and the name being the prefix that identifies that namespace within the document. For example, \code{xmlns:r="http://www.r-project.org"} would be passed as \code{c(r = "http://www.r-project.org")}. If there is no prefix because the namespace is being used as the default, the result of calling \code{\link[base]{names}} on the string is \code{""}. The fourth argument gives the collection of all the namespaces defined within this element. Again, this is a named character vector.
validate
Currently, this has no effect as the libxml2 parser uses a document structure to do validation. When implemented, it will be a logical indicating whether to use a validating parser or not, or in other words check the contents against the DTD specification. If this is true, warning messages will be displayed about errors in the DTD and/or document, but the parsing will proceed except for the presence of terminal errors.

DETAILS:

This is now implemented using the libxml parser. Originally, this was implemented via the Expat XML parser by Jim Clark ( http://www.jclark.com).

VALUE:

The return value is the final state information, if it is supplied, or the `handlers' argument if not. It is assumed that the handlers object has manipulated values stored elsewhere and that the caller knows how to extract this.

NOTE:

This requires the Expat XML parser to be installed.

AUTHOR(S):

Duncan Temple Lang

REFERENCES:

http://www.w3.org/XML, http://www.jclark.com/xml

SEE ALSO:

EXAMPLES:

fileName <- system.file("exampleData", "mtcars.xml", package="XML")

# Print the name of each XML tag encountered at the beginning of each
# tag.
xmlEventParse(fileName,
                list(startElement=function(name, ...){cat(name,"\n")}),
                useTagName=FALSE, addContext = FALSE)

# Parse the text rather than a file by reading the contents
# and making it a single string. Then call xmlEventParse
xmlText <- paste(readLines(fileName, -1),"\n",collapse="\n")
con <- xmlEventParse(xmlText, asText=TRUE)
con$getDOM()
detach.DOM()