debugXML: Tree debugging APIs

## debugXML

debugXML - Tree debugging APIs

Interfaces to a set of routines used for debugging the tree produced by the XML parser.

Author(s): Daniel Veillard

## Synopsis

    typedef struct _xmlShellCtxt xmlShellCtxt;
    typedef xmlShellCtxt * xmlShellCtxtPtr;
    void	xmlDebugDumpAttrList		(FILE * output,
    					 xmlAttrPtr attr,
    					 int depth);
    void	xmlLsOneNode			(FILE * output,
    					 xmlNodePtr node);
    typedef char * xmlShellReadlineFunc		(char * prompt);
    int	xmlShellSave			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    const char *	xmlBoolToText		(int boolval);
    int	xmlShellWrite			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    int	xmlShellDu			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr tree,
    					 xmlNodePtr node2);
    int	xmlShellValidate		(xmlShellCtxtPtr ctxt,
    					 char * dtd,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    int	xmlDebugCheckDocument		(FILE * output,
    					 xmlDocPtr doc);
    void	xmlShellPrintXPathResult	(xmlXPathObjectPtr list);
    typedef int xmlShellCmd			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    int	xmlShellLoad			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    void	xmlDebugDumpString		(FILE * output,
    					 const xmlChar * str);
    int	xmlShellBase			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    int	xmlShellCat			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    void	xmlDebugDumpDTD			(FILE * output,
    					 xmlDtdPtr dtd);
    void	xmlDebugDumpNode		(FILE * output,
    					 xmlNodePtr node,
    					 int depth);
    void	xmlDebugDumpEntities		(FILE * output,
    					 xmlDocPtr doc);
    void	xmlShellPrintNode		(xmlNodePtr node);
    int	xmlShellPwd			(xmlShellCtxtPtr ctxt,
    					 char * buffer,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    void	xmlDebugDumpNodeList		(FILE * output,
    					 xmlNodePtr node,
    					 int depth);
    void	xmlDebugDumpAttr		(FILE * output,
    					 xmlAttrPtr attr,
    					 int depth);
    void	xmlDebugDumpDocument		(FILE * output,
    					 xmlDocPtr doc);
    int	xmlLsCountNode			(xmlNodePtr node);
    void	xmlShellPrintXPathError		(int errorType,
    					 const char * arg);
    int	xmlShellDir			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    void	xmlDebugDumpOneNode		(FILE * output,
    					 xmlNodePtr node,
    					 int depth);
    int	xmlShellList			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2);
    void	xmlDebugDumpDocumentHead	(FILE * output,
    					 xmlDocPtr doc);
    void	xmlShell			(xmlDocPtr doc,
    					 char * filename,
    					 xmlShellReadlineFunc input,
    					 FILE * output);

## Description

## Details

### Structure xmlShellCtxt

    struct _xmlShellCtxt {
        char *	filename
        xmlDocPtr	doc
        xmlNodePtr	node
        xmlXPathContextPtr	pctxt
        int	loaded
        FILE *	output
        xmlShellReadlineFunc	input
    } xmlShellCtxt;

### Typedef xmlShellCtxtPtr

    xmlShellCtxt * xmlShellCtxtPtr;

### Function type xmlShellCmd

    int	xmlShellCmd			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

This is a generic signature for the XML shell functions.

`ctxt`: | a shell context
`arg`: | a string argument
`node`: | a first node
`node2`: | a second node
`Returns`: | an int, negative returns indicating errors.

### Function type xmlShellReadlineFunc

    char *	xmlShellReadlineFunc		(char * prompt)

This is a generic signature for the XML shell input function.

`prompt`: | a string prompt
`Returns`: | a string which will be freed by the Shell.

### xmlBoolToText ()

    const char *	xmlBoolToText		(int boolval)

Convenient way to turn bool into text

`boolval`: | a bool to turn into text
`Returns`: | a pointer to either "True" or "False"

### xmlDebugCheckDocument ()

    int	xmlDebugCheckDocument		(FILE * output,
    					 xmlDocPtr doc)

Check the document for potential content problems, and output the errors to @output

`output`: | the FILE * for the output
`doc`: | the document
`Returns`: | the number of errors found

### xmlDebugDumpAttr ()

    void	xmlDebugDumpAttr		(FILE * output,
    					 xmlAttrPtr attr,
    					 int depth)

Dumps debug information for the attribute

`output`: | the FILE * for the output
`attr`: | the attribute
`depth`: | the indentation level.

### xmlDebugDumpAttrList ()

    void	xmlDebugDumpAttrList		(FILE * output,
    					 xmlAttrPtr attr,
    					 int depth)

Dumps debug information for the attribute list

`output`: | the FILE * for the output
`attr`: | the attribute list
`depth`: | the indentation level.

### xmlDebugDumpDTD ()

    void	xmlDebugDumpDTD			(FILE * output,
    					 xmlDtdPtr dtd)

Dumps debug information for the DTD

`output`: | the FILE * for the output
`dtd`: | the DTD

### xmlDebugDumpDocument ()

    void	xmlDebugDumpDocument		(FILE * output,
    					 xmlDocPtr doc)

Dumps debug information for the document, it's recursive

`output`: | the FILE * for the output
`doc`: | the document

### xmlDebugDumpDocumentHead ()

    void	xmlDebugDumpDocumentHead	(FILE * output,
    					 xmlDocPtr doc)

Dumps debug information concerning the document, not recursive

`output`: | the FILE * for the output
`doc`: | the document

### xmlDebugDumpEntities ()

    void	xmlDebugDumpEntities		(FILE * output,
    					 xmlDocPtr doc)

Dumps debug information for all the entities in use by the document

`output`: | the FILE * for the output
`doc`: | the document

### xmlDebugDumpNode ()

    void	xmlDebugDumpNode		(FILE * output,
    					 xmlNodePtr node,
    					 int depth)

Dumps debug information for the element node, it is recursive

`output`: | the FILE * for the output
`node`: | the node
`depth`: | the indentation level.

### xmlDebugDumpNodeList ()

    void	xmlDebugDumpNodeList		(FILE * output,
    					 xmlNodePtr node,
    					 int depth)

Dumps debug information for the list of element node, it is recursive

`output`: | the FILE * for the output
`node`: | the node list
`depth`: | the indentation level.

### xmlDebugDumpOneNode ()

    void	xmlDebugDumpOneNode		(FILE * output,
    					 xmlNodePtr node,
    					 int depth)

Dumps debug information for the element node, it is not recursive

`output`: | the FILE * for the output
`node`: | the node
`depth`: | the indentation level.

### xmlDebugDumpString ()

    void	xmlDebugDumpString		(FILE * output,
    					 const xmlChar * str)

Dumps information about the string, shorten it if necessary

`output`: | the FILE * for the output
`str`: | the string

### xmlLsCountNode ()

    int	xmlLsCountNode			(xmlNodePtr node)

Count the children of @node.

`node`: | the node to count
`Returns`: | the number of children of @node.

### xmlLsOneNode ()

    void	xmlLsOneNode			(FILE * output,
    					 xmlNodePtr node)

Dump to @output the type and name of @node.

`output`: | the FILE * for the output
`node`: | the node to dump

### xmlShell ()

    void	xmlShell			(xmlDocPtr doc,
    					 char * filename,
    					 xmlShellReadlineFunc input,
    					 FILE * output)

Implements the XML shell This allow to load, validate, view, modify and save a document using a environment similar to a UNIX commandline.

`doc`: | the initial document
`filename`: | the output buffer
`input`: | the line reading function
`output`: | the output FILE*, defaults to stdout if NULL

### xmlShellBase ()

    int	xmlShellBase			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "base" dumps the current XML base of the node

`ctxt`: | the shell context
`arg`: | unused
`node`: | a node
`node2`: | unused
`Returns`: | 0

### xmlShellCat ()

    int	xmlShellCat			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "cat" dumps the serialization node content (XML or HTML).

`ctxt`: | the shell context
`arg`: | unused
`node`: | a node
`node2`: | unused
`Returns`: | 0

### xmlShellDir ()

    int	xmlShellDir			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "dir" dumps information about the node (namespace, attributes, content).

`ctxt`: | the shell context
`arg`: | unused
`node`: | a node
`node2`: | unused
`Returns`: | 0

### xmlShellDu ()

    int	xmlShellDu			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr tree,
    					 xmlNodePtr node2)

Implements the XML shell function "du" show the structure of the subtree under node @tree If @tree is null, the command works on the current node.

`ctxt`: | the shell context
`arg`: | unused
`tree`: | a node defining a subtree
`node2`: | unused
`Returns`: | 0 or -1 in case of error

### xmlShellList ()

    int	xmlShellList			(xmlShellCtxtPtr ctxt,
    					 char * arg,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "ls" Does an Unix like listing of the given node (like a directory)

`ctxt`: | the shell context
`arg`: | unused
`node`: | a node
`node2`: | unused
`Returns`: | 0

### xmlShellLoad ()

    int	xmlShellLoad			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "load" loads a new document specified by the filename

`ctxt`: | the shell context
`filename`: | the file name
`node`: | unused
`node2`: | unused
`Returns`: | 0 or -1 if loading failed

### xmlShellPrintNode ()

    void	xmlShellPrintNode		(xmlNodePtr node)

Print node to the output FILE

`node`: | a non-null node to print to the output FILE

### xmlShellPrintXPathError ()

    void	xmlShellPrintXPathError		(int errorType,
    					 const char * arg)

Print the xpath error to libxml default error channel

`errorType`: | valid xpath error id
`arg`: | the argument that cause xpath to fail

### xmlShellPrintXPathResult ()

    void	xmlShellPrintXPathResult	(xmlXPathObjectPtr list)

Prints result to the output FILE

`list`: | a valid result generated by an xpath evaluation

### xmlShellPwd ()

    int	xmlShellPwd			(xmlShellCtxtPtr ctxt,
    					 char * buffer,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "pwd" Show the full path from the root to the node, if needed building thumblers when similar elements exists at a given ancestor level. The output is compatible with XPath commands.

`ctxt`: | the shell context
`buffer`: | the output buffer
`node`: | a node
`node2`: | unused
`Returns`: | 0 or -1 in case of error

### xmlShellSave ()

    int	xmlShellSave			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "save" Write the current document to the filename, or it's original name

`ctxt`: | the shell context
`filename`: | the file name (optional)
`node`: | unused
`node2`: | unused
`Returns`: | 0 or -1 in case of error

### xmlShellValidate ()

    int	xmlShellValidate		(xmlShellCtxtPtr ctxt,
    					 char * dtd,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "validate" Validate the document, if a DTD path is provided, then the validation is done against the given DTD.

`ctxt`: | the shell context
`dtd`: | the DTD URI (optional)
`node`: | unused
`node2`: | unused
`Returns`: | 0 or -1 in case of error

### xmlShellWrite ()

    int	xmlShellWrite			(xmlShellCtxtPtr ctxt,
    					 char * filename,
    					 xmlNodePtr node,
    					 xmlNodePtr node2)

Implements the XML shell function "write" Write the current node to the filename, it saves the serialization of the subtree under the @node specified

`ctxt`: | the shell context
`filename`: | the file name
`node`: | a node in the tree
`node2`: | unused
`Returns`: | 0 or -1 in case of error