libxslt Reference Manual |
---|
xsltutils - set of utilities for the XSLT engine
interfaces for the utilities module of the XSLT engine. things like message handling, profiling, and other generally useful routines.
Author(s): Daniel Veillard
#define IS_XSLT_REAL_NODE; #define IS_XSLT_ELEM; #define IS_XSLT_NAME; #define XSLT_TODO; #define XSLT_STRANGE; #define XSLT_TIMESTAMP_TICS_PER_SEC; #define XSLT_TRACE; typedef enum xsltDebugTraceCodes; typedef enum xsltDebugStatusCodes; int xsltSaveResultToFile (FILE * file,
xmlDocPtr result,
xsltStylesheetPtr style); void xsltSetGenericErrorFunc (void * ctx,
xmlGenericErrorFunc handler); int xsltSetDebuggerCallbacks (int no,
void * block); int xsltSaveResultTo (xmlOutputBufferPtr buf,
xmlDocPtr result,
xsltStylesheetPtr style); void xsltTransformError (xsltTransformContextPtr ctxt,
xsltStylesheetPtr style,
xmlNodePtr node,
const char * msg,
... ...); int xslAddCall (xsltTemplatePtr templ,
xmlNodePtr source); void xsltDocumentSortFunction (xmlNodeSetPtr list); const xmlChar * xsltGetQNameURI2 (xsltStylesheetPtr style,
xmlNodePtr node,
const xmlChar ** name); xmlXPathObjectPtr * xsltComputeSortResult (xsltTransformContextPtr ctxt,
xmlNodePtr sort); void xsltPrintErrorContext (xsltTransformContextPtr ctxt,
xsltStylesheetPtr style,
xmlNodePtr node); int xsltGetUTF8Char (const unsigned char * utf,
int * len); void xsltDefaultSortFunction (xsltTransformContextPtr ctxt,
xmlNodePtr * sorts,
int nbsorts); int xsltSaveResultToFd (int fd,
xmlDocPtr result,
xsltStylesheetPtr style); void xsltSetCtxtSortFunc (xsltTransformContextPtr ctxt,
xsltSortFunc handler); xmlChar * xsltGetNsProp (xmlNodePtr node,
const xmlChar * name,
const xmlChar * nameSpace); const xmlChar * xsltGetCNsProp (xsltStylesheetPtr style,
xmlNodePtr node,
const xmlChar * name,
const xmlChar * nameSpace); const xmlChar * xsltGetQNameURI (xmlNodePtr node,
xmlChar ** name); typedef int xsltAddCallCallback (xsltTemplatePtr templ,
xmlNodePtr source); void xsltCalibrateAdjust (long delta); void xsltSaveProfiling (xsltTransformContextPtr ctxt,
FILE * output); int xsltSaveResultToString (xmlChar ** doc_txt_ptr,
int * doc_txt_len,
xmlDocPtr result,
xsltStylesheetPtr style); const xmlChar * xsltSplitQName (xmlDictPtr dict,
const xmlChar * name,
const xmlChar ** prefix); void xsltDoSortFunction (xsltTransformContextPtr ctxt,
xmlNodePtr * sorts,
int nbsorts); xsltDebugTraceCodes xsltDebugGetDefaultTrace (void); void xsltMessage (xsltTransformContextPtr ctxt,
xmlNodePtr node,
xmlNodePtr inst); int xsltGetDebuggerStatus (void); long xsltTimestamp (void); void xsltSetTransformErrorFunc (xsltTransformContextPtr ctxt,
void * ctx,
xmlGenericErrorFunc handler); xmlXPathCompExprPtr xsltXPathCompile (xsltStylesheetPtr style,
const xmlChar * str); void xsltDebugSetDefaultTrace (xsltDebugTraceCodes val); void xsltSetGenericDebugFunc (void * ctx,
xmlGenericErrorFunc handler); xmlXPathCompExprPtr xsltXPathCompileFlags (xsltStylesheetPtr style,
const xmlChar * str,
int flags); int xsltSetCtxtParseOptions (xsltTransformContextPtr ctxt,
int options); void xsltSetDebuggerStatus (int value); void xslDropCall (void); void xsltSetSortFunc (xsltSortFunc handler); typedef void xsltHandleDebuggerCallback (xmlNodePtr cur,
xmlNodePtr node,
xsltTemplatePtr templ,
xsltTransformContextPtr ctxt); int xsltSaveResultToFilename (const char * URL,
xmlDocPtr result,
xsltStylesheetPtr style,
int compression); typedef void xsltDropCallCallback (void); xmlDocPtr xsltGetProfileInformation (xsltTransformContextPtr ctxt);
#define IS_XSLT_REAL_NODE;
Check that a node is a 'real' one: document, element, text or attribute.
#define XSLT_TIMESTAMP_TICS_PER_SEC;
Sampling precision for profiling
enum xsltDebugStatusCodes { XSLT_DEBUG_NONE = 0 /* no debugging allowed */ XSLT_DEBUG_INIT = 1 XSLT_DEBUG_STEP = 2 XSLT_DEBUG_STEPOUT = 3 XSLT_DEBUG_NEXT = 4 XSLT_DEBUG_STOP = 5 XSLT_DEBUG_CONT = 6 XSLT_DEBUG_RUN = 7 XSLT_DEBUG_RUN_RESTART = 8 XSLT_DEBUG_QUIT = 9 };
enum xsltDebugTraceCodes { XSLT_TRACE_ALL = -1 XSLT_TRACE_NONE = 0 XSLT_TRACE_COPY_TEXT = 1 XSLT_TRACE_PROCESS_NODE = 2 XSLT_TRACE_APPLY_TEMPLATE = 4 XSLT_TRACE_COPY = 8 XSLT_TRACE_COMMENT = 16 XSLT_TRACE_PI = 32 XSLT_TRACE_COPY_OF = 64 XSLT_TRACE_VALUE_OF = 128 XSLT_TRACE_CALL_TEMPLATE = 256 XSLT_TRACE_APPLY_TEMPLATES = 512 XSLT_TRACE_CHOOSE = 1024 XSLT_TRACE_IF = 2048 XSLT_TRACE_FOR_EACH = 4096 XSLT_TRACE_STRIP_SPACES = 8192 XSLT_TRACE_TEMPLATES = 16384 XSLT_TRACE_KEYS = 32768 XSLT_TRACE_VARIABLES = 65536 };
int xsltAddCallCallback (xsltTemplatePtr templ,
xmlNodePtr source)
templ: | |
source: | |
Returns: |
void xsltHandleDebuggerCallback (xmlNodePtr cur,
xmlNodePtr node,
xsltTemplatePtr templ,
xsltTransformContextPtr ctxt)
cur: | |
node: | |
templ: | |
ctxt: |
int xslDebugStatus;
xmlGenericErrorFunc xsltGenericDebug;
void * xsltGenericDebugContext;
xmlGenericErrorFunc xsltGenericError;
void * xsltGenericErrorContext;
int xslAddCall (xsltTemplatePtr templ,
xmlNodePtr source)
Add template "call" to call stack
templ: | current template being applied |
source: | the source node being processed |
Returns: | : 1 on sucess 0 otherwise an error may be printed if WITH_XSLT_DEBUG_BREAKPOINTS is defined |
void xsltCalibrateAdjust (long delta)
Used for to correct the calibration for xsltTimestamp()
delta: | a negative dealy value found |
xmlXPathObjectPtr * xsltComputeSortResult (xsltTransformContextPtr ctxt,
xmlNodePtr sort)
reorder the current node list accordingly to the set of sorting requirement provided by the array of nodes.
ctxt: | a XSLT process context |
sort: | node list |
Returns: | a ordered XPath nodeset or NULL in case of error. |
xsltDebugTraceCodes xsltDebugGetDefaultTrace (void)
Get the current default debug tracing level mask
Returns: | the current default debug tracing level mask |
void xsltDebugSetDefaultTrace (xsltDebugTraceCodes val)
Set the default debug tracing level mask
val: | tracing level mask |
void xsltDefaultSortFunction (xsltTransformContextPtr ctxt,
xmlNodePtr * sorts,
int nbsorts)
reorder the current node list accordingly to the set of sorting requirement provided by the arry of nodes.
ctxt: | a XSLT process context |
sorts: | array of sort nodes |
nbsorts: | the number of sorts in the array |
void xsltDoSortFunction (xsltTransformContextPtr ctxt,
xmlNodePtr * sorts,
int nbsorts)
reorder the current node list accordingly to the set of sorting requirement provided by the arry of nodes. This is a wrapper function, the actual function used is specified using xsltSetCtxtSortFunc() to set the context specific sort function, or xsltSetSortFunc() to set the global sort function. If a sort function is set on the context, this will get called. Otherwise the global sort function is called.
ctxt: | a XSLT process context |
sorts: | array of sort nodes |
nbsorts: | the number of sorts in the array |
void xsltDocumentSortFunction (xmlNodeSetPtr list)
reorder the current node list @list accordingly to the document order This function is slow, obsolete and should not be used anymore.
list: | the node set |
const xmlChar * xsltGetCNsProp (xsltStylesheetPtr style,
xmlNodePtr node,
const xmlChar * name,
const xmlChar * nameSpace)
Similar to xmlGetNsProp() but with a slightly different semantic Search and get the value of an attribute associated to a node This attribute has to be anchored in the namespace specified, or has no namespace and the element is in that namespace. This does the entity substitution. This function looks in DTD attribute declaration for #FIXED or default declaration values unless DTD use has been turned off.
style: | the stylesheet |
node: | the node |
name: | the attribute name |
nameSpace: | the URI of the namespace |
Returns: | the attribute value or NULL if not found. The string is allocated in the stylesheet dictionary. |
int xsltGetDebuggerStatus (void)
Get xslDebugStatus.
Returns: | the value of xslDebugStatus. |
xmlChar * xsltGetNsProp (xmlNodePtr node,
const xmlChar * name,
const xmlChar * nameSpace)
Similar to xmlGetNsProp() but with a slightly different semantic Search and get the value of an attribute associated to a node This attribute has to be anchored in the namespace specified, or has no namespace and the element is in that namespace. This does the entity substitution. This function looks in DTD attribute declaration for #FIXED or default declaration values unless DTD use has been turned off.
node: | the node |
name: | the attribute name |
nameSpace: | the URI of the namespace |
Returns: | the attribute value or NULL if not found. It's up to the caller to free the memory. |
xmlDocPtr xsltGetProfileInformation (xsltTransformContextPtr ctxt)
This function should be called after the transformation completed to extract template processing profiling information if available. The information is returned as an XML document tree like <?xml version="1.0"?> <profile> <template rank="1" match="*" name="" mode="" calls="6" time="48" average="8"/> <template rank="2" match="item2|item3" name="" mode="" calls="10" time="30" average="3"/> <template rank="3" match="item1" name="" mode="" calls="5" time="17" average="3"/> </profile> The caller will need to free up the returned tree with xmlFreeDoc()
ctxt: | a transformation context |
Returns: | the xmlDocPtr corresponding to the result or NULL if not available. |
const xmlChar * xsltGetQNameURI (xmlNodePtr node,
xmlChar ** name)
This function analyzes @name, if the name contains a prefix, the function seaches the associated namespace in scope for it. It will also replace @name value with the NCName, the old value being freed. Errors in the prefix lookup are signalled by setting @name to NULL. NOTE: the namespace returned is a pointer to the place where it is defined and hence has the same lifespan as the document holding it.
node: | the node holding the QName |
name: | pointer to the initial QName value |
Returns: | the namespace URI if there is a prefix, or NULL if @name is not prefixed. |
const xmlChar * xsltGetQNameURI2 (xsltStylesheetPtr style,
xmlNodePtr node,
const xmlChar ** name)
This function is similar to xsltGetQNameURI, but is used when @name is a dictionary entry.
style: | stylesheet pointer |
node: | the node holding the QName |
name: | pointer to the initial QName value |
Returns: | the namespace URI if there is a prefix, or NULL if @name is not prefixed. |
int xsltGetUTF8Char (const unsigned char * utf,
int * len)
Read one UTF8 Char from @utf Function copied from libxml2 xmlGetUTF8Char() ... to discard ultimately and use the original API
utf: | a sequence of UTF-8 encoded bytes |
len: | a pointer to @bytes len |
Returns: | the char value or -1 in case of error and update @len with the number of bytes used |
void xsltMessage (xsltTransformContextPtr ctxt,
xmlNodePtr node,
xmlNodePtr inst)
Process and xsl:message construct
ctxt: | an XSLT processing context |
node: | The current node |
inst: | The node containing the message instruction |
void xsltPrintErrorContext (xsltTransformContextPtr ctxt,
xsltStylesheetPtr style,
xmlNodePtr node)
Display the context of an error.
ctxt: | the transformation context |
style: | the stylesheet |
node: | the current node being processed |
void xsltSaveProfiling (xsltTransformContextPtr ctxt,
FILE * output)
Save the profiling information on @output
ctxt: | an XSLT context |
output: | a FILE * for saving the information |
int xsltSaveResultTo (xmlOutputBufferPtr buf,
xmlDocPtr result,
xsltStylesheetPtr style)
Save the result @result obtained by applying the @style stylesheet to an I/O output channel @buf
buf: | an output buffer |
result: | the result xmlDocPtr |
style: | the stylesheet |
Returns: | the number of byte written or -1 in case of failure. |
int xsltSaveResultToFd (int fd,
xmlDocPtr result,
xsltStylesheetPtr style)
Save the result @result obtained by applying the @style stylesheet to an open file descriptor This does not close the descriptor.
fd: | a file descriptor |
result: | the result xmlDocPtr |
style: | the stylesheet |
Returns: | the number of bytes written or -1 in case of failure. |
int xsltSaveResultToFile (FILE * file,
xmlDocPtr result,
xsltStylesheetPtr style)
Save the result @result obtained by applying the @style stylesheet to an open FILE * I/O. This does not close the FILE @file
file: | a FILE * I/O |
result: | the result xmlDocPtr |
style: | the stylesheet |
Returns: | the number of bytes written or -1 in case of failure. |
int xsltSaveResultToFilename (const char * URL,
xmlDocPtr result,
xsltStylesheetPtr style,
int compression)
Save the result @result obtained by applying the @style stylesheet to a file or @URL
URL: | a filename or URL |
result: | the result xmlDocPtr |
style: | the stylesheet |
compression: | the compression factor (0 - 9 included) |
Returns: | the number of byte written or -1 in case of failure. |
int xsltSaveResultToString (xmlChar ** doc_txt_ptr,
int * doc_txt_len,
xmlDocPtr result,
xsltStylesheetPtr style)
Save the result @result obtained by applying the @style stylesheet to a new allocated string.
doc_txt_ptr: | Memory pointer for allocated XML text |
doc_txt_len: | Length of the generated XML text |
result: | the result xmlDocPtr |
style: | the stylesheet |
Returns: | 0 in case of success and -1 in case of error |
int xsltSetCtxtParseOptions (xsltTransformContextPtr ctxt,
int options)
Change the default parser option passed by the XSLT engine to the parser when using document() loading.
ctxt: | a XSLT process context |
options: | a combination of libxml2 xmlParserOption |
Returns: | the previous options or -1 in case of error |
void xsltSetCtxtSortFunc (xsltTransformContextPtr ctxt,
xsltSortFunc handler)
Function to set the handler for XSLT sorting for the specified context. If the handler is NULL, then the global sort function will be called
ctxt: | a XSLT process context |
handler: | the new handler function |
int xsltSetDebuggerCallbacks (int no,
void * block)
This function allow to plug a debugger into the XSLT library @block points to a block of memory containing the address of @no callback routines.
no: | number of callbacks |
block: | the block of callbacks |
Returns: | 0 in case of success and -1 in case of error |
void xsltSetDebuggerStatus (int value)
This function sets the value of xslDebugStatus.
value: | the value to be set |
void xsltSetGenericDebugFunc (void * ctx,
xmlGenericErrorFunc handler)
Function to reset the handler and the error context for out of context error messages. This simply means that @handler will be called for subsequent error messages while not parsing or validating. And @ctx will be passed as first argument to @handler One can simply force messages to be emitted to another FILE * than stderr by setting @ctx to this file handle and @handler to NULL.
ctx: | the new error handling context |
handler: | the new handler function |
void xsltSetGenericErrorFunc (void * ctx,
xmlGenericErrorFunc handler)
Function to reset the handler and the error context for out of context error messages. This simply means that @handler will be called for subsequent error messages while not parsing nor validating. And @ctx will be passed as first argument to @handler One can simply force messages to be emitted to another FILE * than stderr by setting @ctx to this file handle and @handler to NULL.
ctx: | the new error handling context |
handler: | the new handler function |
void xsltSetSortFunc (xsltSortFunc handler)
Function to reset the global handler for XSLT sorting. If the handler is NULL, the default sort function will be used.
handler: | the new handler function |
void xsltSetTransformErrorFunc (xsltTransformContextPtr ctxt,
void * ctx,
xmlGenericErrorFunc handler)
Function to reset the handler and the error context for out of context error messages specific to a given XSLT transromation. This simply means that @handler will be called for subsequent error messages while running the transformation.
ctxt: | the XSLT transformation context |
ctx: | the new error handling context |
handler: | the new handler function |
const xmlChar * xsltSplitQName (xmlDictPtr dict,
const xmlChar * name,
const xmlChar ** prefix)
Split QNames into prefix and local names, both allocated from a dictionary.
dict: | a dictionary |
name: | the full QName |
prefix: | the return value |
Returns: | the localname or NULL in case of error. |
long xsltTimestamp (void)
Used for gathering profiling data
Returns: | the number of tenth of milliseconds since the beginning of the profiling |
void xsltTransformError (xsltTransformContextPtr ctxt,
xsltStylesheetPtr style,
xmlNodePtr node,
const char * msg,
... ...)
Display and format an error messages, gives file, line, position and extra parameters, will use the specific transformation context if available
ctxt: | an XSLT transformation context |
style: | the XSLT stylesheet used |
node: | the current node in the stylesheet |
msg: | the message to display/transmit |
...: | extra parameters for the message display |
xmlXPathCompExprPtr xsltXPathCompile (xsltStylesheetPtr style,
const xmlChar * str)
Compile an XPath expression
style: | the stylesheet |
str: | the XPath expression |
Returns: | the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object. |
xmlXPathCompExprPtr xsltXPathCompileFlags (xsltStylesheetPtr style,
const xmlChar * str,
int flags)
Compile an XPath expression
style: | the stylesheet |
str: | the XPath expression |
flags: | extra compilation flags to pass down to libxml2 XPath |
Returns: | the xmlXPathCompExprPtr resulting from the compilation or NULL. the caller has to free the object. |