TclXML Parser

TclXML is an open source XML parser written in Tcl. Altair Accelerator ships TclXML with it, so no 3rd party installation is needed to use TclXML. For detailed information, please go to http://tclxml.sourceforge.net/tclxml.html.

The goal of the TclXML package is to provide an API for Tcl scripts that allows "Plug-and-Play" parser implementations; e.g. an application will be able to use different parser implementations without change to the application code.

The TclXML package provides a streaming, or "event-based", interface to an XML document. An application using TclXML creates a parser "object", sets a number of callback scripts and then instructs the parser to parse an XML document. The parser scans the XML document's text and as it finds certain constructs, such as the start/end of elements, character data, and so on, it invokes the appropriate callback script.

Parser Object (::xml::parser)

The ::xml::parser command creates an XML parser object. The return value of the command is the name of the newly created parser.

The parser scans an XML document's syntactical structure, evaluating callback scripts for each feature found. At the very least the parser will normalise the document and check the document for well-formedness. If the document is not well-formed then the -errorcommand option will be evaluated. Some parser classes may perform additional functions, such as validation. Additional features provided by the various parser classes are described in the section Parser Classes.

Parsing is performed synchronously. The command blocks until the entire document has been parsed. Parsing may be terminated by an application callback, see the section Callback Return Codes. Incremental parsing is also supported by using the -final configuration option.

The following table lists all options to the parser object. To find a complete explanation on all script arguments, please find online documentation at http://tclxml.sourceforge.net/tclxml.html.

Application Example

# Import 'xml' Tcl package
package require xml

set indent 0 ; # Global indentation variable, for pretty printing

# Declare various callback procedures which will be used by parser
# to crudely pretty print an XML tree.

# Define callback for when an XML element start tag is encountered
proc startCmd {name attlist args} {
    global indent
    puts [format "%[expr $indent * 4]s<$name $attlist $args>" ""]
    incr indent
}

# Define callback for when an XML element end tag is encountered
proc endCmd {name args} {
    global indent
    incr indent -1
    puts [format "%[expr $indent * 4]s</$name $args>" ""]
}

# Define callback for when an XML element's CDATA is encountered
proc cdataCmd {data args} {
    global indent
    puts [format "%[expr $indent * 4]s$data $args" ""]
}

# Create XML parser object with certain callbacks
set parser [::xml::parser  -ignorewhitespace 1  -elementstartcommand startCmd  -elementendcommand endCmd  -characterdatacommand cdataCmd]

# Open XML file for parsing or read from stdin
if {$argc} {
    set file [shift]
    if {![file exists $file]} {
        VovFatalError "The specified file '$file' does not exist"
    }
    set fp [open $file "r"]
    $parser parse [read $fp]
    close $fp
} else {
    VovMessage "Waiting for STDIN"
    $parser parse [read stdin]
}