|
|
/* ************************************************************************* xslsearch.h - public functions for searching ------------------- begin : Fri Dec 7 2001 copyright : (C) 2001 by Keith Isdale email : k_isdale@tpg.com.au ************************************************************************* */ /*************************************************************************** * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published by * * the Free Software Foundation; either version 2 of the License, or * * (at your option) any later version. * * * ************************************************************************* */ /** * Provide a searching support * * @short search support * * @author Keith Isdale*/ /* We want skip most of these includes when building documentation*/ /* what types of searches are there */ /* keep kdoc happy */ enum SearchEnum { SEARCH_BREAKPOINT = 400, SEARCH_NODE, SEARCH_XSL, SEARCH_VARIABLE }; /* define a common structure to be used when searching */ typedef struct _searchInfo searchInfo; typedef searchInfo *searchInfoPtr; struct _searchInfo { int found; /* found is 1 if search is finished */ int type; /* what type of search see SearchEnum */ int error; /* did an error occur */ void *data; /* extra data to pass to walkFunc */ }; /* data to pass to via searchInfoPtr when searching for break points */ typedef struct _breakPointSearchData breakPointSearchData; typedef breakPointSearchData *breakPointSearchDataPtr; struct _breakPointSearchData { int id; /* what id to look for, * if -1 then ignore */ xmlChar *templateName; /* template to look for * if NULL then ignore */ breakPointPtr breakPtr; /* the break point found by search */ }; /* data to pass via searchInfoPtr when searching for nodes */ typedef struct _nodeSearchData nodeSearchData; typedef nodeSearchData *nodeSearchDataPtr; struct _nodeSearchData { long lineNo; /* what line number to look for * if < 0 then ignore */ xmlChar *url; /* what URl to look for * if NULL then ignore */ int fileSearch; /* if true then we are trying * to match a file name */ xmlChar *nameInput; /* what file/node name are we * trying to match */ xmlChar *guessedNameMatch; /* possible name match */ xmlChar *absoluteNameMatch; /* full name match */ xmlNodePtr node; /* the node that the match * occured in */ }; /* data to pass to via searchInfoPtr when searching for variables points */ typedef struct _variableSearchData variableSearchData; typedef variableSearchData *variableSearchDataPtr; struct _variableSearchData { xmlChar *name; xmlChar *nameURI; xmlChar *select; /* new value to adopt if any */ }; /** * Initialize the search module * * @returns 1 if search structures have been initialized properly and all * memory required has been obtained, * 0 otherwise */ int searchInit(void); /** * Free all memory used by the search module */ void searchFree(void); /** * Create a new search * * @returns valid search info pointer if successful * NULL otherwise * * @param type What type of search is required */ searchInfoPtr searchNewInfo(SearchEnum type); /** * Free memory used by @p info * * @param info A valid search info * */ void searchFreeInfo(searchInfoPtr info); /** * Empty the seach dataBase of its contents * * @returns 1 on success, * 0 otherwise */ int searchEmpty(void); /** * Return the document used for seaching ie the search dataBase * * @returns the document used for searching * Dangerous function to use! Does NOT return a copy of * search data so don't free it */ xmlDocPtr searchDoc(void); /** * Get the topmost node in the search dataBase * * @returns The topmost xml node in search dataBase. * Dangerous function to use! Does NOT return a copy of * search root node so don't free it */ xmlNodePtr searchRootNode(void); /** * Add a node to the search dataBase * * @returns 1 if able to add @p node to top node in search dataBase, * 0 otherwise * * @param node Is valid */ int searchAdd(xmlNodePtr node); /** * Save the search dataBase to @p fileName * * @returns 1 on success, * 0 otherwise * * @param fileName Valid file name */ int searchSave(const xmlChar * fileName); /** * Send query as parameter for execution of search.xsl using * data stored in @p tempFile * * @returns 1 on success, * 0 otherwise * * @param query The Query to run. If NULL then @p query defaults to "//search/ *" * @param tempFile Where do we load the search dataBase from to execute * query. If @p tempFile is NULL default is "search.data" * @param outputFile Where do we store the result. If NULL * then default to "searchresult.html" */ int searchQuery(const xmlChar * tempFile, const xmlChar * outputFile, const xmlChar * query); /** * Update the search dataBase * * @returns 1 if able to update the search dataBase, * 0 otherwise * @param styleCtxt Not used * @param style Is valid * @param data Not used but MUST be NULL for the moment * @param variableTypes What types of variables to look */ int updateSearchData(xsltTransformContextPtr styleCtxt, xsltStylesheetPtr style, void *data, VariableTypeEnum variableTypes); /** * Test if break point matches criteria given by @p data. If so then * set @p data->found to 1 and stores reference to break point found in * @p data->data->node * otherwise @p data is unchanged * * @param payload A valid breakPointPtr * @param data The criteria to look for and a valid searchInfoPtr of * type SEARCH_BREAKPOINT * @param name Not used * */ void scanForBreakPoint(void *payload, void *data, xmlChar * name); /** * Test if node matches criteria given by @p data if so then * set @p data->found to 1 and stores reference to node found in * @p data->data->node. * otherwise @p data is unchanged * * @param payload A valid xmlNodePtr * @param data The criteria to look for and a valid searchInfo of * type SEARCH_NODE * @param name Not used */ void scanForNode(void *payload, void *data, xmlChar * name); /** * Find the closest line number in file specified that can be a point * * @returns The node at line number specified if successful, * NULL otherwise * * @param ctxt Valid ctxt to look into * @param url Non-null, non-empty file name that has been loaded by * debugger * @param lineNumber @p lineNumber >= 0 and is available in @p url */ xmlNodePtr findNodeByLineNo(xsltTransformContextPtr ctxt, const xmlChar * url, long lineNumber); /** * Find a template node * * @returns The template node found if successful, * NULL otherwise * * @param style A Valid stylesheet collection to look into * @param name Valid template name to look for */ xmlNodePtr findTemplateNode(xsltStylesheetPtr style, const xmlChar * name); /** * Find the breakpoint at template with "match" or "name" equal * to templateName * * @returns The break point that matches @p templateName * NULL otherwise * * @param templateName Valid template name to look for */ breakPointPtr findBreakPointByName(const xmlChar * templateName); /** * Find a break point by its id * * @returns The break point with given the break point id if found, * NULL otherwise * * @param id The break point id to look for */ breakPointPtr findBreakPointById(int id); /** * Find nodes in search dataBase using an xpath query * * @returns The nodes that match the given query on success, * NULL otherwise * * @param query The xpath query to run, see docs/en/search.dtd for more details */ xmlXPathObjectPtr findNodesByQuery(const xmlChar * query); /** * Walks through all break points calling walkFunc for each. The payload * sent to walkFunc is of type breakPointPtr * * @param walkFunc The function to callback for each break point found * @param data The extra data to pass onto @p walkFunc */ void walkBreakPoints(xmlHashScanner walkFunc, void *data); /** * Walks through all templates found in @p style calling walkFunc for each. * The payload of walkFunc is of type xsltTemplatePtr * * @param walkFunc The function to callback for each template found * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkTemplates(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Walks through all stylesheets found in @p style calling walkFunc for * each. The payload sent to walkFunc is of type xsltStylesheetPtr * * @param walkFunc The function to callback for each stylesheet found * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkStylesheets(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Call walkFunc for each global variable found in @p style. The payload * sent to walkFunc is of type xmlNodePtr * * @param walkFunc The function to callback for each gobal variable found * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkGlobals(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Walks through all local variables found in @p style calling * walkFunc for each. The payload of walkFunc is of type xmlNodePtr * * @param walkFunc The function to callback for each local variable found * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkLocals(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Walks through all included stylesheets found in @p style, * calling walkFunc for each. The payload of walkFunc is of * type xmlNodePtr * * @param walkFunc The function to callback for each included stylesheet * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkIncludes(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Walks through all xsl:include calling walkFunc for each. The payload * of walkFunc is of type xmlNodePtr * * @param walkFunc The function to callback for each xsl:include instruction found * @param data The extra data to pass onto @p walkFunc * @param style The stylesheet to start from */ void walkIncludeInst(xmlHashScanner walkFunc, void *data, xsltStylesheetPtr style); /** * Call walkFunc for each child of @p node the payload sent to walkFunc is * a xmlNodePtr * * @param walkFunc The function to callback for each child/sibling found * @param data The extra data to pass onto @p walkFunc * @param node Valid xmlNodePtr */ void walkChildNodes(xmlHashScanner walkFunc, void *data, xmlNodePtr node); /** * Convert @p breakPtr into search dataBase format * * @returns @p breakPtr as a new xmlNode in search dataBase format * if successful, * NULL otherwise * * @param breakPtr Is valid */ xmlNodePtr searchBreakPointNode(breakPointPtr breakPtr); /** * Convert @p templateNode into search dataBase format * * @returns @p templNode as a new xmlNode in search dataBase format * if successful, * NULL otherwise * * @param templNode A valid template node */ xmlNodePtr searchTemplateNode(xmlNodePtr templNode); /** * Convert @p globalVariable into search dataBase format * * @returns @p globalVariable as a new xmlNode in search dataBase * format if successful, * NULL otherwise * * @param globalVariable A valid xmlNodePtr node * */ xmlNodePtr searchGlobalNode(xmlNodePtr globalVariable); /** * Convert @p localVariable into search dataBase format * * @returns @p localVariable as a new xmlNode in search dataBase * format if successful, * NULL otherwise * * @param localVariable Is valid * */ xmlNodePtr searchLocalNode(xmlNodePtr localVariable); /** * Convert @p style into search dataBase format * * @returns @p style as a new xmlNode in search dataBase format if successful, * NULL otherwise * * @param style Is valid */ xmlNodePtr searchSourceNode(xsltStylesheetPtr style); /** * Convert @p include into search dataBase format * * @returns @p include as a new xmlNode in search dataBase format * if successful, * NULL otherwise * * @param include Is a valid xsl:include instruction * */ xmlNodePtr searchIncludeNode(xmlNodePtr include); /** *Convert @p include into search dataBase format * * @returns @p callStackItem as a new xmlNode in search dataBase * format if successful, * NULL otherwise * @param callStackItem Is valid */ xmlNodePtr searchCallStackNode(callPointPtr callStackItem); /** * Find documentation comment that applies to @p sourceNode. If found convert comment * into search dataBase format required * * Returns Documentation comment for @node as a new xmlNode in search dataBase format * if successful, * NULL otherwise * * @param node Is valid */ xmlNodePtr searchCommentNode(xmlNodePtr node);
Generated by: keith on linux on Thu Aug 1 20:53:44 2002, using kdoc 2.0a53. |