From 13122e8862e0b7292cb11bfc4c8bbc58516d2911 Mon Sep 17 00:00:00 2001 From: Jim Derry Date: Thu, 16 Mar 2017 16:46:01 -0400 Subject: [PATCH] Added tidyErrorCodeFromKey() Added tidyGetMessageDoc() Improved the Public API documentation. --- include/tidy.h | 2723 ++++++++++++++++++++++++++++-------------- include/tidybuffio.h | 13 +- src/message.c | 16 + src/message.h | 6 + src/messageobj.c | 5 + src/messageobj.h | 31 +- src/tidylib.c | 12 + 7 files changed, 1891 insertions(+), 915 deletions(-) diff --git a/include/tidy.h b/include/tidy.h index 5b46af8..967036f 100644 --- a/include/tidy.h +++ b/include/tidy.h @@ -1,60 +1,70 @@ #ifndef __TIDY_H__ #define __TIDY_H__ -/** @file tidy.h - Defines HTML Tidy API implemented by LibTidy. - - Public interface is const-correct and doesn't explicitly depend on any - globals. Thus, thread-safety may be introduced without changing the - interface. - - Copyright (c) 1998-2016 World Wide Web Consortium - (Massachusetts Institute of Technology, European Research - Consortium for Informatics and Mathematics, Keio University). - All Rights Reserved. - - Contributing Author(s): - - Dave Raggett - - The contributing author(s) would like to thank all those who helped with - testing, bug fixes and suggestions for improvements. This wouldn't have been - possible without your help. - - COPYRIGHT NOTICE: - - This software and documentation is provided "as is," and the copyright holders - and contributing author(s) make no representations or warranties, express or - implied, including but not limited to, warranties of merchantability or - fitness for any particular purpose or that the use of the software or - documentation will not infringe any third party patents, copyrights, - trademarks or other rights. - - The copyright holders and contributing author(s) will not be held liable for - any direct, indirect, special or consequential damages arising out of any use - of the software or documentation, even if advised of the possibility of such - damage. - - Permission is hereby granted to use, copy, modify, and distribute this source - code, or portions hereof, documentation and executables, for any purpose, - without fee, subject to the following restrictions: - - 1. The origin of this source code must not be misrepresented. - 2. Altered versions must be plainly marked as such and must not be - misrepresented as being the original source. - 3. This Copyright notice may not be removed or altered from any source or - altered source distribution. - - The copyright holders and contributing author(s) specifically permit, without -  fee, and encourage the use of this source code as a component for supporting - the Hypertext Markup Language in commercial products. If you use this source - code in a product, acknowledgment is not required but would be appreciated. - - Created 2001-05-20 by Charles Reitzel - Updated 2002-07-01 by Charles Reitzel - 1st Implementation - Updated 2015-06-09 by Geoff R. McLane - Add more doxygen syntax - Additional updates: consult git log - -*/ +/***************************************************************************//** + * @file + * Defines HTML Tidy public API implemented by LibTidy. + * + * This public interface provides the entire public API for LibTidy, and + * is the sole interface that you should use when implementing LibTidy in + * your own applications. + * + * See tidy.c as an example application implementing the public API. + * + * This API is const-correct and doesn't explicitly depend on any globals. + * Thus, thread-safety may be introduced without changing the interface. + * + * The API limits all exposure to internal structures and provides only + * accessors that return simple types such as C strings and integers, which + * makes it quite suitable for integration with any number of other languages. + * + * @author Dave Raggett [dsr@w3.org] + * @author HTACG, et al (consult git log) + * + * @remarks The contributing author(s) would like to thank all those who + * helped with testing, bug fixes and suggestions for improvements. + * This wouldn't have been possible without your help. + * + * @copyright + * Copyright (c) 1998-2016 World Wide Web Consortium (Massachusetts + * Institute of Technology, European Research Consortium for Informatics + * and Mathematics, Keio University). + * @par + * All Rights Reserved. + * @par + * This software and documentation is provided "as is," and the copyright + * holders and contributing author(s) make no representations or warranties, + * express or implied, including but not limited to, warranties of + * merchantability or fitness for any particular purpose or that the use of + * the software or documentation will not infringe any third party patents, + * copyrights, trademarks or other rights. + * @par + * The copyright holders and contributing author(s) will not be held liable + * for any direct, indirect, special or consequential damages arising out of + * any use of the software or documentation, even if advised of the + * possibility of such damage. + * @par + * Permission is hereby granted to use, copy, modify, and distribute this + * source code, or portions hereof, documentation and executables, for any + * purpose, without fee, subject to the following restrictions: + * @par + * 1. The origin of this source code must not be misrepresented. + * 2. Altered versions must be plainly marked as such and must not be + * misrepresented as being the original source. + * 3. This Copyright notice may not be removed or altered from any source + * or altered source distribution. + * @par + * The copyright holders and contributing author(s) specifically permit, + * without fee, and encourage the use of this source code as a component for + * supporting the Hypertext Markup Language in commercial products. If you + * use this source code in a product, acknowledgment is not required but + * would be appreciated. + * + * @date Created 2001-05-20 by Charles Reitzel + * @date Updated 2002-07-01 by Charles Reitzel - 1st Implementation + * @date Updated 2015-06-09 by Geoff R. McLane - Add more doxygen syntax + * @date Additional updates: consult git log + ******************************************************************************/ #include "tidyplatform.h" #include "tidyenum.h" @@ -62,449 +72,874 @@ #ifdef __cplusplus extern "C" { #endif + +/***************************************************************************//** + ** @defgroup internal_api Internal API + ** The Internal API is used exclusively within LibTidy. If you are an + ** HTML Tidy developer, then the internals API will be of especial + ** importance to you. + ** + ** @note Always check first to determine whether or not an internal API + ** representation exists for a public API function before invoking a + ** public API function internally. In most cases, the public API + ** functions simply call an internal function. + ** - - - + ** @note This documention _is not_ a substitute for browsing the source + ** code. Although the public API is fairly well documented, the + ** internal API is a very long, very slow, work-in-progress. + ******************************************************************************/ -/** @defgroup Opaque Opaque Types -** -** These instances of these types are available for use in your programs, -** however their internal details are opaque. These items should be accessed -** with LibTidy's accessor functions. -** -** Internally LibTidy will cast these to internal implementation types. -** Cast to implementation types within lib. -** -** This reduces inter-dependencies and conflicts with application code. -** @{ -*/ +/***************************************************************************//** + ** @defgroup public_api External Public API + ** The Public API is the API that LibTidy programmers must access in order + ** to harness HTML Tidy as a library. The API limits all exposure to internal + ** structures and provides only accessors that return simple types such as + ** C strings and integers, which makes it quite suitable for integration with + ** any number of other languages. + ** @{ + ******************************************************************************/ + + +/* MARK: - Opaque Types */ +/***************************************************************************//** + ** @defgroup Opaque Opaque Types + ** + ** Instances of these types are returned by LibTidy API functions, however + ** they are opaque; you cannot see into them, and must use accessor functions + ** to access the contents. This ensures that interfacing to LibTidy remains + ** as universal as possible. + ** + ** @note Internally LibTidy developers will cast these to internal + ** implementation types with access to all member fields. + ** @{ + ******************************************************************************/ /** @struct TidyDoc -** Opaque document datatype -*/ -opaque_type( TidyDoc ); + ** Instances of this represent a Tidy document, which encapsulates everything + ** there is to know about a single Tidy session. Many of the API functions + ** return instance of TidyDoc, or expect instances as parameters. + */ /** @struct TidyOption -** Opaque option datatype -*/ -opaque_type( TidyOption ); + ** Instances of this represent a Tidy configuration option, which contains + ** useful data about these options. Functions related to configuration options + ** return or accept instances of this type. + */ /** @struct TidyNode -** Opaque node datatype -*/ -opaque_type( TidyNode ); + ** Single nodes of a TidyDocument are represented by this datatype. It can be + ** returned by various API functions, or accepted as a function argument. + */ /** @struct TidyAttr -** Opaque attribute datatype -*/ -opaque_type( TidyAttr ); + ** Attributes of a TidyNode are represented by this data type. The public API + ** functions related to attributes work with this type. + */ /** @struct TidyMessage -** Opaque messsage record datatype + ** Instances of this type represent messages generated by Tidy in reference + ** to your document. This API is available in some of Tidy's message callback + ** functions. */ -opaque_type( TidyMessage ); /** @struct TidyMessageArgument -** Opaque message argument datatype + ** Instances of this type represent the arguments that compose part of the + ** message represented by TidyMessage. These arguments have an API to query + ** information about them. */ + +/* Prevent Doxygen from listing these as functions. */ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + +opaque_type( TidyDoc ); +opaque_type( TidyOption ); +opaque_type( TidyNode ); +opaque_type( TidyAttr ); +opaque_type( TidyMessage ); opaque_type( TidyMessageArgument ); -/** @} end Opaque group */ +#endif +/** @} end Opaque group */ +/* MARK: - Memory Allocation */ +/***************************************************************************//** + ** @defgroup Memory Memory Allocation + ** + ** Tidy can use a user-provided allocator for all memory allocations. If this + ** allocator is not provided, then a default allocator is used which simply + ** wraps standard C malloc()/free() calls. These wrappers call the panic() + ** function upon any failure. The default panic function prints an out of + ** memory message to **stderr**, and calls `exit(2)`. + ** + ** For applications in which it is unacceptable to abort in the case of memory + ** allocation, then the panic function can be replaced with one which + ** `longjmps()` out of the LibTidy code. For this to clean up completely, you + ** should be careful not to use any Tidy methods that open files as these will + ** not be closed before `panic()` is called. + ** + ** Calling the `xxxWithAllocator()` family (`tidyCreateWithAllocator`, + ** `tidyBufInitWithAllocator`, `tidyBufAllocWithAllocator`) allow setting + ** custom allocators. + ** + ** All parts of the document use the same allocator. Calls that require a + ** user-provided buffer can optionally use a different allocator. + ** + ** For reference in designing a plug-in allocator, most allocations made by + ** LibTidy are less than 100 bytes, corresponding to attribute names and + ** values, etc. + ** + ** There is also an additional class of much larger allocations which are where + ** most of the data from the lexer is stored. It is not currently possible to + ** use a separate allocator for the lexer; this would be a useful extension. + ** + ** In general, approximately 1/3rd of the memory used by LibTidy is freed + ** during the parse, so if memory usage is an issue then an allocator that can + ** reuse this memory is a good idea. + ** + ** **To create your own allocator, do something like the following:** + ** @code{.c} + ** typedef struct _MyAllocator { + ** TidyAllocator base; + ** // ...other custom allocator state... + ** } MyAllocator; + ** + ** void* MyAllocator_alloc(TidyAllocator *base, void *block, size_t nBytes) { + ** MyAllocator *self = (MyAllocator*)base; + ** // ... + ** } + ** // etc. + ** + ** static const TidyAllocatorVtbl MyAllocatorVtbl = { + ** MyAllocator_alloc, + ** MyAllocator_realloc, + ** MyAllocator_free, + ** MyAllocator_panic + ** }; + ** + ** myAllocator allocator; + ** TidyDoc doc; + ** + ** allocator.base.vtbl = &MyAllocatorVtbl; + ** //...initialise allocator specific state... + ** doc = tidyCreateWithAllocator(&allocator); + ** @endcode + ** + ** Although this looks slightly long-winded, the advantage is that to create a + ** custom allocator you simply need to set the vtbl pointer correctly. The vtbl + ** itself can reside in static/global data, and hence does not need to be + ** initialised each time an allocator is created, and furthermore the memory + ** is shared amongst all created allocators. + ** + ** @{ + ******************************************************************************/ + +/* Forward declarations and typedefs. */ +struct _TidyAllocatorVtbl; +struct _TidyAllocator; + +typedef struct _TidyAllocatorVtbl TidyAllocatorVtbl; +typedef struct _TidyAllocator TidyAllocator; + + +/** Tidy's built-in default allocator. */ +struct _TidyAllocator { + const TidyAllocatorVtbl *vtbl; /**< The allocator's function table. */ +}; + + +/** This structure is the function table for an allocator. Note that all + functions in this table must be provided. */ +struct _TidyAllocatorVtbl +{ +/* Doxygen has no idea how to parse these. */ +#ifndef DOXYGEN_SHOULD_SKIP_THIS + void* (TIDY_CALL *alloc)( TidyAllocator *self, size_t nBytes ); + void* (TIDY_CALL *realloc)(TidyAllocator *self, void *block, size_t nBytes ); + void (TIDY_CALL *free)(TidyAllocator *self, void *block); + void (TIDY_CALL *panic)(TidyAllocator *self, ctmbstr msg); +#else + /** Called to allocate a block of nBytes of memory */ + void* *alloc(TidyAllocator *self, /**< The TidyAllocator to use to alloc memory. */ + size_t nBytes /**< The number of bytes to allocate. */ + ); + + /** Called to resize (grow, in general) a block of memory. + Must support being called with `NULL`. */ + void* *realloc(TidyAllocator *self, /**< The TidyAllocator to use to realloc memory. */ + void *block, /**< The pointer to the existing block. */ + size_t nBytes /**< The number of bytes to allocate. */ + ); + + /** Called to free a previously allocated block of memory. + */ + void *free(TidyAllocator *self, /**< The TidyAllocator to use to free memory. */ + void *block /**< The block to free. */ + ); + + /** Called when a panic condition is detected. Must support `block == NULL`. + This function is not called if either alloc() or realloc() fails; it is + up to the allocator to do this. Currently this function can only be + called if an error is detected in the tree integrity via the internal + function CheckNodeIntegrity(). This is a situation that can only arise + in the case of a programming error in LibTidy. You can turn off node + integrity checking by defining the constant `NO_NODE_INTEGRITY_CHECK` + during the build. + **/ + void *panic(TidyAllocator *self, /**< The TidyAllocator to use to panic. */ + ctmbstr msg /**< The panic message. */ + ); +#endif /* Doxygen Fix */ +}; + + +/** Callback for `malloc` replacement */ +typedef void* (TIDY_CALL *TidyMalloc)( size_t len ); + +/** Callback for `realloc` replacement */ +typedef void* (TIDY_CALL *TidyRealloc)( void* buf, size_t len ); + +/** Callback for `free` replacement */ +typedef void (TIDY_CALL *TidyFree)( void* buf ); + +/** Callback for out of memory panic state */ +typedef void (TIDY_CALL *TidyPanic)( ctmbstr mssg ); + + +/** Give Tidy a `malloc()` replacement */ +TIDY_EXPORT Bool TIDY_CALL tidySetMallocCall( TidyMalloc fmalloc ); + +/** Give Tidy a `realloc()` replacement */ +TIDY_EXPORT Bool TIDY_CALL tidySetReallocCall( TidyRealloc frealloc ); + +/** Give Tidy a `free()` replacement */ +TIDY_EXPORT Bool TIDY_CALL tidySetFreeCall( TidyFree ffree ); + +/** Give Tidy an "out of memory" handler */ +TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic ); + + +/** @} end Memory group */ +/* MARK: - Basic Operations */ +/***************************************************************************//** + ** @defgroup Basic Basic Operations + ** + ** For an excellent example of how to invoke LibTidy, please consult + ** `console/tidy.c:main()` for in-depth implementation details. A simplified + ** example can be seen on our site: http://www.html-tidy.org/developer/ + ** + ** @{ + ******************************************************************************/ + +/** @name Instantiation and Destruction + ** @{ + */ + +/** The primary creation of a document instance. Instances of a TidyDoc are used + ** throughout the API as a token to represent a particular document. When done + ** using a TidyDoc instance, be sure to `tidyRelease(myTidyDoc);` in order + ** to free related memory. + ** @result Returns a TidyDoc instance. + */ +TIDY_EXPORT TidyDoc TIDY_CALL tidyCreate(void); + +/** Create a document supplying your own, custom TidyAllocator instead of using + ** the built-in default. See the @ref Memory module if you want to create and + ** use your own allocator. + ** @param allocator The allocator to use for creating the document. + ** @result Returns a TidyDoc instance. + */ +TIDY_EXPORT TidyDoc TIDY_CALL tidyCreateWithAllocator(TidyAllocator *allocator); + +/** Free all memory and release the TidyDoc. The TidyDoc can not be used after + ** this call. + ** @param tdoc The TidyDoc to free. + */ +TIDY_EXPORT void TIDY_CALL tidyRelease(TidyDoc tdoc); + + +/** @} + ** @name Host Application Data + ** @{ + */ + + +/** Allows the host application to store a chunk of data with each TidyDoc + ** instance. This can be useful for callbacks, such as saving a reference to + ** `self` within the document. + */ +TIDY_EXPORT void TIDY_CALL tidySetAppData(TidyDoc tdoc, /**< The document in which to store the data. */ + void* appData /**< The pointer to a block of data to store. */ + ); + +/** Returns the data previously stored with `tidySetAppData()`. + ** @param tdoc document where data has been stored. + ** @result The pointer to the data block previously stored. + */ +TIDY_EXPORT void* TIDY_CALL tidyGetAppData(TidyDoc tdoc); + + +/** @} + ** @name LibTidy Version Information + ** @{ + */ + + +/** Get the release date for the current library. + ** @result The string representing the release date. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyReleaseDate(void); + +/** Get the version number for the current library. + ** @result The string representing the version number. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyLibraryVersion(void); + + +/** @} + ** @name Diagnostics and Repair + ** @{ + */ + + +/** Get status of current document. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ +TIDY_EXPORT int TIDY_CALL tidyStatus( TidyDoc tdoc ); + +/** This function is supposed to return the detected HTML version; however it + ** isn't currently implemented. + ** @note TODO: This function currently does nothing. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the value `0`. + */ +TIDY_EXPORT int TIDY_CALL tidyDetectedHtmlVersion( TidyDoc tdoc ); + +/** This function is supposed to return a Bool indicating whether or not the + ** input document is XHTML; however it isn't currently implemented. + ** @note TODO: This function currently does nothing. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the value `no`. + */ +TIDY_EXPORT Bool TIDY_CALL tidyDetectedXhtml( TidyDoc tdoc ); + +/** This function is supposed to return a Bool indicating whether or not the + ** input document is generic XML (i.e., not XHTL or HTML); however it isn't + ** currently implemented. + ** @note TODO: This function currently does nothing. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the value `no`. + */ +TIDY_EXPORT Bool TIDY_CALL tidyDetectedGenericXml( TidyDoc tdoc ); + +/** Indicates the number of TidyError messages that were generated. For any + ** value greater than `0`, output is suppressed unless TidyForceOutput is set. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the number of TidyError messages that were generated. + */ +TIDY_EXPORT uint TIDY_CALL tidyErrorCount( TidyDoc tdoc ); + +/** Indicates the number of TidyWarning messages that were generated. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the number of TidyWarning messages that were generated. + */ +TIDY_EXPORT uint TIDY_CALL tidyWarningCount( TidyDoc tdoc ); + +/** Indicates the number of TidyAccess messages that were generated. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the number of TidyAccess messages that were generated. + */ +TIDY_EXPORT uint TIDY_CALL tidyAccessWarningCount( TidyDoc tdoc ); + +/** Indicates the number of configuration error messages that were generated. + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns the number of configuration error messages that were + ** generated. + */ +TIDY_EXPORT uint TIDY_CALL tidyConfigErrorCount( TidyDoc tdoc ); + +/** Write more complete information about errors to current error sink. + ** @param tdoc An instance of a TidyDoc to query. + */ +TIDY_EXPORT void TIDY_CALL tidyErrorSummary( TidyDoc tdoc ); + +/** Write more general information about markup to current error sink. + ** @param tdoc An instance of a TidyDoc to query. + */ +TIDY_EXPORT void TIDY_CALL tidyGeneralInfo( TidyDoc tdoc ); + + +/** @} + ** @name Configuration, File, and Encoding Operations + ** @{ + */ + + +/** Load an ASCII Tidy configuration file and set the configuration per its + ** contents. + ** @result Returns 0 upon success, or any other value if there was an error. + */ +TIDY_EXPORT int TIDY_CALL tidyLoadConfig(TidyDoc tdoc, /**< The TidyDoc to which to apply the configuration. */ + ctmbstr configFile /**< The complete path to the file to load. */ + ); + +/** Load a Tidy configuration file with the specified character encoding, and + ** set the configuration per its contents. + ** @result Returns 0 upon success, or any other value if there was an error. + */ +TIDY_EXPORT int TIDY_CALL tidyLoadConfigEnc(TidyDoc tdoc, /**< The TidyDoc to which to apply the configuration. */ + ctmbstr configFile, /**< The complete path to the file to load. */ + ctmbstr charenc /**< The encodingto use. See the _enc2iana struct for valid values. */ + ); + +/** Determine whether or not a particular file exists. On Unix systems, the use + ** of the tilde to represent the user's home directory is supported. + ** @result Returns `yes` or `no`, indicating whether or not the file exists. + */ +TIDY_EXPORT Bool TIDY_CALL tidyFileExists(TidyDoc tdoc, /**< The TidyDoc on whose behalf you are checking. */ + ctmbstr filename /**< The path to the file whose existence you wish to check. */ + ); + + +/** Set the input/output character encoding for parsing markup. Valid values + ** include `ascii`, `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, + ** `utf16le`, `utf16be`, `utf16`, `big5`, and `shiftjis`. These values are not + ** case sensitive. + ** @note This is the same as using TidySetInCharEncoding() and + ** TidySetOutCharEncoding() to set the same value. + ** @result Returns 0 upon success, or a system standard error number `EINVAL`. + */ +TIDY_EXPORT int TIDY_CALL tidySetCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ + ctmbstr encnam /**< The encoding name as described above. */ + ); + +/** Set the input encoding for parsing markup. Valid values include `ascii`, + ** `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, `utf16le`, `utf16be`, + ** `utf16`, `big5`, and `shiftjis`. These values are not case sensitive. + ** @result Returns 0 upon success, or a system standard error number `EINVAL`. + */ +TIDY_EXPORT int TIDY_CALL tidySetInCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ + ctmbstr encnam /**< The encoding name as described above. */ + ); + +/** Set the input encoding for writing markup. Valid values include `ascii`, + ** `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, `utf16le`, `utf16be`, + ** `utf16`, `big5`, and `shiftjis`. These values are not case sensitive. + ** @result Returns 0 upon success, or a system standard error number `EINVAL`. + */ +TIDY_EXPORT int TIDY_CALL tidySetOutCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ + ctmbstr encnam /**< The encoding name as described above. */ + ); + + +/** @} */ +/** @} end Basic group */ +/* MARK: - Configuration Options */ +/***************************************************************************//** + ** @defgroup Configuration Configuration Options + ** + ** Functions for getting and setting Tidy configuration options. + ** @{ + ******************************************************************************/ + +/** @name Option Callback Functions + ** @{ + */ + +/** This typedef represents the required signature for your provided callback + ** function should you wish to register one with tidySetOptionCallback(). + ** Your callback function will be provided with the following parameters. + ** @param option The option name that was provided. + ** @param value The option value that was provided + ** @return Your callback function will return `yes` if it handles the provided + ** option, or `no` if it does not. In the latter case, Tidy will issue + ** an unknown configuration option error. + */ +typedef Bool (TIDY_CALL *TidyOptCallback)(ctmbstr option, ctmbstr value); + +/** Applications using TidyLib may want to augment command-line and + ** configuration file options. Setting this callback allows a LibTidy + ** application developer to examine command-line and configuration file options + ** after LibTidy has examined them and failed to recognize them. + ** @result Returns `yes` upon success. + */ +TIDY_EXPORT Bool TIDY_CALL tidySetOptionCallback(TidyDoc tdoc, /**< The document to apply the callback to. */ + TidyOptCallback pOptCallback /**< The name of a function of type TidyOptCallback() to serve as your callback. */ + ); + +/** @} + ** @name Option ID Discovery + ** @{ + */ + +/** Get ID of given Option + ** @param opt An instance of a TidyOption to query. + ** @result The TidyOptionId of the given option. + */ +TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetId( TidyOption opt ); + +/** Returns the TidyOptionId (enum value) by providing the name of a Tidy + ** configuration option. + ** @param optnam The name of the option ID to retrieve. + ** @result The TidyOptionId of the given `optname`. + */ +TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetIdForName(ctmbstr optnam); + +/** @} + ** @name Getting Instances of Tidy Options + ** @{ + */ + +/** Initiates an iterator for a list of TidyOption instances, which allows you + ** to iterate through all of the available options. In order to iterate through + ** the available options, initiate the iterator with this function, and then + ** use tidyGetNextOption() to retrieve the first and subsequent options. For + ** example: + ** @code{.c} + ** TidyIterator itOpt = tidyGetOptionList( tdoc ); + ** while ( itOpt ) { + ** TidyOption opt = tidyGetNextOption( tdoc, &itOpt ); + ** // Use other API to query or set set option values + ** } + ** @endcode + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ +TIDY_EXPORT TidyIterator TIDY_CALL tidyGetOptionList( TidyDoc tdoc ); + +/** Given a valid TidyIterator initiated with tidyGetOptionList(), returns + ** the instance of the next TidyOption. + ** @note This function will return internal-only option types including + ** `TidyInternalCategory`; you should *never* use these. Always ensure + ** that you use `tidyOptGetCategory()` before assuming that an option + ** is okay to use in your application. + ** @result An instance of TidyOption. + */ +TIDY_EXPORT TidyOption TIDY_CALL tidyGetNextOption(TidyDoc tdoc, /**< The document for which you are retrieving options. */ + TidyIterator* pos /**< The TidyIterator (initiated with tidyGetOptionList()) token. */ + ); + +/** Retrieves an instance of TidyOption given a valid TidyOptionId. + ** @result An instance of TidyOption matching the provided TidyOptionId. + */ +TIDY_EXPORT TidyOption TIDY_CALL tidyGetOption(TidyDoc tdoc, /**< The document for which you are retrieving the option. */ + TidyOptionId optId /**< The TidyOptionId to retrieve. */ + ); + +/** Returns an instance of TidyOption by providing the name of a Tidy + ** configuration option. + ** @result The TidyOption of the given `optname`. + */ +TIDY_EXPORT TidyOption TIDY_CALL tidyGetOptionByName(TidyDoc tdoc, /**< The document for which you are retrieving the option. */ + ctmbstr optnam /**< The name of the Tidy configuration option. */ + ); + +/** @} + ** @name Information About Options + ** @{ + */ + +/** Get name of given Option + ** @param opt An instance of a TidyOption to query. + ** @result The name of the given option. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetName( TidyOption opt ); + +/** Get datatype of given Option + ** @param opt An instance of a TidyOption to query. + ** @result the TidyOptionType of the given option. + */ +TIDY_EXPORT TidyOptionType TIDY_CALL tidyOptGetType( TidyOption opt ); + +/** Is Option read-only? Some options (mainly internal use only options) are + ** read-only. + ** @param opt An instance of a TidyOption to query. + ** @result Returns `yes` or `no` depending on whether or not the specified + ** option is read-only. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptIsReadOnly( TidyOption opt ); + +/** Get category of given Option + ** @param opt An instance of a TidyOption to query. + ** @result The TidyConfigCategory of the specified option. + */ +TIDY_EXPORT TidyConfigCategory TIDY_CALL tidyOptGetCategory( TidyOption opt ); + +/** Get default value of given Option as a string + ** @param opt An instance of a TidyOption to query. + ** @result A string indicating the default value of the specified option. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDefault( TidyOption opt ); + +/** Get default value of given Option as an unsigned integer + ** @param opt An instance of a TidyOption to query. + ** @result An unsigned integer indicating the default value of the specified + ** option. + */ +TIDY_EXPORT ulong TIDY_CALL tidyOptGetDefaultInt( TidyOption opt ); + +/** Get default value of given Option as a Boolean value + ** @param opt An instance of a TidyOption to query. + ** @result A boolean indicating the default value of the specified option. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptGetDefaultBool( TidyOption opt ); + +/** Initiates an iterator for a list of TidyOption pick-list values, which + ** allows you iterate through all of the available option values. In order to + ** iterate through the available values, initiate the iterator with this + ** function, and then use tidyOptGetNextPick() to retrieve the first and + ** subsequent option values. For example: + ** @code{.c} + ** TidyIterator itOpt = tidyOptGetPickList( opt ); + ** while ( itOpt ) { + ** printf("%s", tidyOptGetNextPick( opt, &itOpt )); + ** } + ** @endcode + ** @param opt An instance of a TidyOption to query. + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ +TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetPickList( TidyOption opt ); + +/** Given a valid TidyIterator initiated with tidyOptGetPickList(), returns a + ** string representing a possible option value. + ** @result A string containing the next pick-list option value. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextPick(TidyOption opt, /**< An instance of a TidyOption to query. */ + TidyIterator* pos /**< The TidyIterator (initiated with tidyOptGetPickList()) token. */ + ); + +/** @} + ** @name Option Value Functions + ** @{ + */ + +/** Get the current value of the option ID for the given document. + ** @remark The optId *must* have a @ref TidyOptionType of @ref TidyString! + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetValue(TidyDoc tdoc, /**< The tidy document whose option value you wish to check. */ + TidyOptionId optId /**< The option ID whose value you wish to check. */ + ); + +/** Set the option value as a string. + ** @remark The optId *must* have a @ref TidyOptionType of @ref TidyString! + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptSetValue(TidyDoc tdoc, /**< The tidy document for which to set the value. */ + TidyOptionId optId, /**< The option ID of the value to set. */ + ctmbstr val /**< The string value to set. */ + ); + +/** Set named option value as a string, regardless of the @ref TidyOptionType. + ** @remark This is good setter if you are unsure of the type. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptParseValue(TidyDoc tdoc, /**< The tidy document for which to set the value. */ + ctmbstr optnam, /**< The name of the option to set. */ + ctmbstr val /**< The value to set, as a string. */ + ); + +/** Get current option value as an integer. + ** @result Returns the integer value of the specified option. + */ +TIDY_EXPORT ulong TIDY_CALL tidyOptGetInt(TidyDoc tdoc, /**< The tidy document for which to get the value. */ + TidyOptionId optId /**< The option ID to get. */ + ); + +/** Set option value as an integer. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptSetInt(TidyDoc tdoc, /**< The tidy document for which to set the value. */ + TidyOptionId optId, /**< The option ID to set. */ + ulong val /**< The value to set. */ + ); + +/** Get current option value as a Boolean flag. + ** @result Returns a bool indicating the value. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptGetBool(TidyDoc tdoc, /**< The tidy document for which to get the value. */ + TidyOptionId optId /**< The option ID to get. */ + ); + +/** Set option value as a Boolean flag. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptSetBool(TidyDoc tdoc, /**< The tidy document for which to set the value. */ + TidyOptionId optId, /**< The option ID to set. */ + Bool val /**< The value to set. */ + ); + +/** Reset option to default value by ID. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptResetToDefault(TidyDoc tdoc, /**< The tidy document for which to reset the value. */ + TidyOptionId opt /**< The option ID to reset. */ + ); + +/** Reset all options to their default values. + ** @param tdoc The tidy document for which to reset all values. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptResetAllToDefault( TidyDoc tdoc ); + +/** Take a snapshot of current config settings. + ** @param tdoc The tidy document for which to take a snapshot. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptSnapshot( TidyDoc tdoc ); + +/** Apply a snapshot of config settings to a document, such as after document + ** processing. This will ensure that any values which Tidy may have changed + ** are back to the intended configuration. + ** @param tdoc The tidy document for which to apply a snapshot. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptResetToSnapshot( TidyDoc tdoc ); + +/** Any settings different than default? + ** @param tdoc The tidy document to check. + ** @result Returns a bool indicating whether or not a difference exists. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanDefault( TidyDoc tdoc ); + +/** Any settings different than snapshot? + ** @param tdoc The tidy document to check. + ** @result Returns a bool indicating whether or not a difference exists. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanSnapshot( TidyDoc tdoc ); + +/** Copy current configuration settings from one document to another. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyOptCopyConfig(TidyDoc tdocTo, /**< The destination tidy document. */ + TidyDoc tdocFrom /**< The source tidy document. */ + ); + +/** Get character encoding name. Used with @ref TidyCharEncoding, + ** @ref TidyOutCharEncoding, and @ref TidyInCharEncoding. + ** @result The encoding name as a string for the specified option. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetEncName(TidyDoc tdoc, /**< The tidy document to query. */ + TidyOptionId optId /**< The option ID whose value to check. */ + ); + +/** Get the current pick list value for the option ID, which can be useful for + ** enum types. + ** @result Returns a string indicating the current value of the specified + ** option. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetCurrPick(TidyDoc tdoc, /**< The tidy document to query. */ + TidyOptionId optId /**< The option ID whose value to check. */ + ); + +/** Initiates an iterator for a list of user-declared tags, including autonomous + ** custom tags detected in the document if @ref TidyUseCustomTags is not set to + ** **no**. This iterator allows you to iterate through all of the custom tags. + ** In order to iterate through the tags, initiate the iterator with this + ** function, and then use tidyOptGetNextDeclTag() to retrieve the first and + ** subsequent tags. For example: + ** @code{.c} + ** TidyIterator itTag = tidyOptGetDeclTagList( tdoc ); + ** while ( itTag ) { + ** printf("%s", tidyOptGetNextDeclTag( tdoc, TidyBlockTags, &itTag )); + ** } + ** @endcode + ** @param tdoc An instance of a TidyDoc to query. + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ +TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDeclTagList( TidyDoc tdoc ); + +/** Given a valid TidyIterator initiated with tidyOptGetDeclTagList(), returns a + ** string representing a user-declared or autonomous custom tag. + ** @remark Specifying optId limits the scope of the tags to one of + ** @ref TidyInlineTags, @ref TidyBlockTags, @ref TidyEmptyTags, or + ** @ref TidyPreTags. Note that autonomous custom tags (if used) are + ** added to one of these option types, depending on the value of + ** @ref TidyUseCustomTags. + ** @result A string containing the next tag. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextDeclTag(TidyDoc tdoc, /**< The tidy document to query. */ + TidyOptionId optId, /**< The option ID matching the type of tag to retrieve. */ + TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetDeclTagList()) token. */ + ); + +/** @} + ** @name Option Documentation + ** @{ + */ + +/** Get the description of the specified option. + ** @result Returns a string containing a description of the given option. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDoc(TidyDoc tdoc, /**< The tidy document to query. */ + TidyOption opt /**< The option ID of the option. */ + ); + +/** Initiates an iterator for a list of options related to a given option. This + ** iterator allows you to iterate through all of the related options, if any. + ** In order to iterate through the options, initiate the iterator with this + ** function, and then use tidyOptGetNextDocLinks() to retrieve the first and + ** subsequent options. For example: + ** @code{.c} + ** TidyIterator itOpt = tidyOptGetDocLinksList( tdoc, TidyJoinStyles ); + ** while ( itOpt ) { + ** TidyOption my_option = tidyOptGetNextDocLinks( tdoc, &itOpt ); + ** // do something with my_option + ** } + ** @endcode + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ +TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDocLinksList(TidyDoc tdoc, /**< The tidy document to query. */ + TidyOption opt /**< The option whose related options you wish to find. */ + ); + +/** Given a valid TidyIterator initiated with tidyOptGetDocLinksList(), returns + ** a TidyOption instance. + ** @result Returns in instane of TidyOption. + */ +TIDY_EXPORT TidyOption TIDY_CALL tidyOptGetNextDocLinks(TidyDoc tdoc, /**< The tidy document to query. */ + TidyIterator* pos /**< The TidyIterator (initiated with tidyOptGetDocLinksList()) token. */ + ); + +/** @} */ +/** @} end Configuration group */ +/* MARK: - I/O and Messages */ +/***************************************************************************//** + ** @defgroup IO I/O and Messages + ** + ** Tidy provides flexible I/O. By default, Tidy will define, create and use + ** instances of input and output handlers for standard C buffered I/O (i.e., + ** `FILE* stdin`, `FILE* stdout`, and `FILE* stderr` for content input, + ** content output and diagnostic output, respectively. A `FILE* cfgFile` + ** input handler will be used for config files. Command line options will + ** just be set directly. + ** + ** @{ + ******************************************************************************/ + +/** @name Forward declarations and typedefs. + ** @{ + */ + TIDY_STRUCT struct _TidyBuffer; typedef struct _TidyBuffer TidyBuffer; - -/** @defgroup Memory Memory Allocation -** -** Tidy uses a user provided allocator for all memory allocations. If this -** allocator is not provided, then a default allocator is used which simply -** wraps standard C malloc/free calls. These wrappers call the panic function -** upon any failure. The default panic function prints an out of memory message -** to stderr, and calls exit(2). -** -** For applications in which it is unacceptable to abort in the case of memory -** allocation, then the panic function can be replaced with one which longjmps() -** out of the LibTidy code. For this to clean up completely, you should be -** careful not to use any tidy methods that open files as these will not be -** closed before panic() is called. -** -** TODO: associate file handles with tidyDoc and ensure that tidyDocRelease() -** can close them all. -** -** Calling the xWithAllocator() family (tidyCreateWithAllocator, -** tidyBufInitWithAllocator, tidyBufAllocWithAllocator) allow setting custom -** allocators. -** -** All parts of the document use the same allocator. Calls that require a user -** provided buffer can optionally use a different allocator. -** -** For reference in designing a plug-in allocator, most allocations made by -** LibTidy are less than 100 bytes, corresponding to attribute names and -** values, etc. -** -** There is also an additional class of much larger allocations which are where -** most of the data from the lexer is stored. It is not currently possible to -** use a separate allocator for the lexer; this would be a useful extension. -** -** In general, approximately 1/3rd of the memory used by LibTidy is freed during -** the parse, so if memory usage is an issue then an allocator that can reuse -** this memory is a good idea. -** -** @{ -*/ - -/** Prototype for the allocator's function table */ -struct _TidyAllocatorVtbl; -/** The allocators function table */ -typedef struct _TidyAllocatorVtbl TidyAllocatorVtbl; - -/** Prototype for the allocator */ -struct _TidyAllocator; -/** The allocator **/ -typedef struct _TidyAllocator TidyAllocator; - -/** An allocator's function table. All functions here must be provided. +/** @} + ** @name Input Source + ** If you wish to write to your own input sources, then these types, structs, + ** and functions will allow them to work seamlessly with Tidy. + ** @{ */ -struct _TidyAllocatorVtbl { - /** Called to allocate a block of nBytes of memory */ - void* (TIDY_CALL *alloc)( TidyAllocator *self, size_t nBytes ); - /** Called to resize (grow, in general) a block of memory. - Must support being called with NULL. - */ - void* (TIDY_CALL *realloc)( TidyAllocator *self, void *block, size_t nBytes ); - /** Called to free a previously allocated block of memory */ - void (TIDY_CALL *free)( TidyAllocator *self, void *block); - /** Called when a panic condition is detected. Must support block == NULL. - This function is not called if either alloc or realloc fails; it is up - to the allocator to do this. Currently this function can only be called - if an error is detected in the tree integrity via the internal function - CheckNodeIntegrity(). This is a situation that can only arise in the - case of a programming error in LibTidy. You can turn off node integrity - checking by defining the constant NO_NODE_INTEGRITY_CHECK during the - build. - **/ - void (TIDY_CALL *panic)( TidyAllocator *self, ctmbstr msg ); -}; -/** An allocator. To create your own allocator, do something like - the following: - \code - typedef struct _MyAllocator { - TidyAllocator base; - ...other custom allocator state... - } MyAllocator; - - void* MyAllocator_alloc(TidyAllocator *base, void *block, size_t nBytes) - { - MyAllocator *self = (MyAllocator*)base; - ... - } - (etc) +/** End of input "character" */ +#define EndOfStream (~0u) - static const TidyAllocatorVtbl MyAllocatorVtbl = { - MyAllocator_alloc, - MyAllocator_realloc, - MyAllocator_free, - MyAllocator_panic - }; - - myAllocator allocator; - TidyDoc doc; - - allocator.base.vtbl = &MyAllocatorVtbl; - ...initialise allocator specific state... - doc = tidyCreateWithAllocator(&allocator); - \endcode - - Although this looks slightly long winded, the advantage is that to create - a custom allocator you simply need to set the vtbl pointer correctly. - The vtbl itself can reside in static/global data, and hence does not - need to be initialised each time an allocator is created, and furthermore - the memory is shared amongst all created allocators. -*/ -struct _TidyAllocator { - const TidyAllocatorVtbl *vtbl; -}; - -/** Callback for "malloc" replacement */ -typedef void* (TIDY_CALL *TidyMalloc)( size_t len ); -/** Callback for "realloc" replacement */ -typedef void* (TIDY_CALL *TidyRealloc)( void* buf, size_t len ); -/** Callback for "free" replacement */ -typedef void (TIDY_CALL *TidyFree)( void* buf ); -/** Callback for "out of memory" panic state */ -typedef void (TIDY_CALL *TidyPanic)( ctmbstr mssg ); - - -/** Give Tidy a malloc() replacement */ -TIDY_EXPORT Bool TIDY_CALL tidySetMallocCall( TidyMalloc fmalloc ); -/** Give Tidy a realloc() replacement */ -TIDY_EXPORT Bool TIDY_CALL tidySetReallocCall( TidyRealloc frealloc ); -/** Give Tidy a free() replacement */ -TIDY_EXPORT Bool TIDY_CALL tidySetFreeCall( TidyFree ffree ); -/** Give Tidy an "out of memory" handler */ -TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic ); - -/** @} end Memory group */ - -/** @defgroup Basic Basic Operations -** -** For an excellent example of how to invoke LibTidy, please consult -** `console/tidy.c:main()` for in-depth implementation details. A simplified -** example can be seen on our site: http://www.html-tidy.org/developer/ -** -** There used to be an example built into the documentation right here, but -** as it was formatted for Doxygen rather than a developer, it was unreadable -** and so has been removed. -** -** @{ -*/ - -/** The primary creation of a TidyDoc. This must be the first call before most - ** of the Tidy API which require the TidyDoc parameter. When completed, - ** tidyRelease( TidyDoc tdoc ); should be called to release all memory - */ -TIDY_EXPORT TidyDoc TIDY_CALL tidyCreate(void); - -/** Create a Tidoc supplying the TidyAllocator. - ** See the TidyAllocator structure for creating an allocator - */ -TIDY_EXPORT TidyDoc TIDY_CALL tidyCreateWithAllocator( TidyAllocator *allocator ); - -/** Free all memory and release the TidyDoc. - ** TidyDoc can not be used after this call. - */ -TIDY_EXPORT void TIDY_CALL tidyRelease( TidyDoc tdoc ); - -/** Let application store a chunk of data w/ each Tidy instance. -** Useful for callbacks. -*/ -TIDY_EXPORT void TIDY_CALL tidySetAppData( TidyDoc tdoc, void* appData ); - -/** Get application data set previously */ -TIDY_EXPORT void* TIDY_CALL tidyGetAppData( TidyDoc tdoc ); - -/** Get release date (version) for current library - */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyReleaseDate(void); - -/** Get version number for the current library */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyLibraryVersion(void); - -/* Diagnostics and Repair -*/ - -/** Get status of current document. */ -TIDY_EXPORT int TIDY_CALL tidyStatus( TidyDoc tdoc ); - -/** Detected HTML version: 0, 2, 3 or 4 */ -TIDY_EXPORT int TIDY_CALL tidyDetectedHtmlVersion( TidyDoc tdoc ); - -/** Input is XHTML? */ -TIDY_EXPORT Bool TIDY_CALL tidyDetectedXhtml( TidyDoc tdoc ); - -/** Input is generic XML (not HTML or XHTML)? */ -TIDY_EXPORT Bool TIDY_CALL tidyDetectedGenericXml( TidyDoc tdoc ); - -/** Number of Tidy errors encountered. If > 0, output is suppressed -** unless TidyForceOutput is set. -*/ -TIDY_EXPORT uint TIDY_CALL tidyErrorCount( TidyDoc tdoc ); - -/** Number of Tidy warnings encountered. */ -TIDY_EXPORT uint TIDY_CALL tidyWarningCount( TidyDoc tdoc ); - -/** Number of Tidy accessibility warnings encountered. */ -TIDY_EXPORT uint TIDY_CALL tidyAccessWarningCount( TidyDoc tdoc ); - -/** Number of Tidy configuration errors encountered. */ -TIDY_EXPORT uint TIDY_CALL tidyConfigErrorCount( TidyDoc tdoc ); - -/* Get/Set configuration options -*/ -/** Load an ASCII Tidy configuration file */ -TIDY_EXPORT int TIDY_CALL tidyLoadConfig( TidyDoc tdoc, ctmbstr configFile ); - -/** Load a Tidy configuration file with the specified character encoding */ -TIDY_EXPORT int TIDY_CALL tidyLoadConfigEnc( TidyDoc tdoc, ctmbstr configFile, - ctmbstr charenc ); - -TIDY_EXPORT Bool TIDY_CALL tidyFileExists( TidyDoc tdoc, ctmbstr filename ); - - -/** Set the input/output character encoding for parsing markup. -** Values include: ascii, latin1, raw, utf8, iso2022, mac, -** win1252, utf16le, utf16be, utf16, big5 and shiftjis. Case in-sensitive. -*/ -TIDY_EXPORT int TIDY_CALL tidySetCharEncoding( TidyDoc tdoc, ctmbstr encnam ); - -/** Set the input encoding for parsing markup. -** As for tidySetCharEncoding but only affects the input encoding -**/ -TIDY_EXPORT int TIDY_CALL tidySetInCharEncoding( TidyDoc tdoc, ctmbstr encnam ); - -/** Set the output encoding. -**/ -TIDY_EXPORT int TIDY_CALL tidySetOutCharEncoding( TidyDoc tdoc, ctmbstr encnam ); - -/** @} end Basic group */ - - -/** @defgroup Configuration Configuration Options -** -** Functions for getting and setting Tidy configuration options. -** @{ -*/ - -/** Applications using TidyLib may want to augment command-line and -** configuration file options. Setting this callback allows an application -** developer to examine command-line and configuration file options after -** TidyLib has examined them and failed to recognize them. -**/ - -typedef Bool (TIDY_CALL *TidyOptCallback)( ctmbstr option, ctmbstr value ); - -TIDY_EXPORT Bool TIDY_CALL tidySetOptionCallback( TidyDoc tdoc, TidyOptCallback pOptCallback ); - -/** Get option ID by name */ -TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetIdForName( ctmbstr optnam ); - -/** Get iterator for list of option */ -/** -Example: -
-TidyIterator itOpt = tidyGetOptionList( tdoc );
-while ( itOpt )
-{
-  TidyOption opt = tidyGetNextOption( tdoc, &itOpt );
-  .. get/set option values ..
-}
-
-*/ - -TIDY_EXPORT TidyIterator TIDY_CALL tidyGetOptionList( TidyDoc tdoc ); -/** Get next Option. Note that this function will return option types - including `TidyInternalCategory`; you should *never* use these! -*/ -TIDY_EXPORT TidyOption TIDY_CALL tidyGetNextOption( TidyDoc tdoc, TidyIterator* pos ); - -/** Lookup option by ID */ -TIDY_EXPORT TidyOption TIDY_CALL tidyGetOption( TidyDoc tdoc, TidyOptionId optId ); -/** Lookup option by name */ -TIDY_EXPORT TidyOption TIDY_CALL tidyGetOptionByName( TidyDoc tdoc, ctmbstr optnam ); - -/** Get ID of given Option */ -TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetId( TidyOption opt ); - -/** Get name of given Option */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetName( TidyOption opt ); - -/** Get datatype of given Option */ -TIDY_EXPORT TidyOptionType TIDY_CALL tidyOptGetType( TidyOption opt ); - -/** Is Option read-only? */ -TIDY_EXPORT Bool TIDY_CALL tidyOptIsReadOnly( TidyOption opt ); - -/** Get category of given Option */ -TIDY_EXPORT TidyConfigCategory TIDY_CALL tidyOptGetCategory( TidyOption opt ); - -/** Get default value of given Option as a string */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDefault( TidyOption opt ); - -/** Get default value of given Option as an unsigned integer */ -TIDY_EXPORT ulong TIDY_CALL tidyOptGetDefaultInt( TidyOption opt ); - -/** Get default value of given Option as a Boolean value */ -TIDY_EXPORT Bool TIDY_CALL tidyOptGetDefaultBool( TidyOption opt ); - -/** Iterate over Option "pick list" */ -TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetPickList( TidyOption opt ); -/** Get next string value of Option "pick list" */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextPick( TidyOption opt, TidyIterator* pos ); - -/** Get string Option current value. Note, the optID "must" be a type 'TidyString'! */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetValue( TidyDoc tdoc, TidyOptionId optId ); -/** Set Option value as a string */ -TIDY_EXPORT Bool TIDY_CALL tidyOptSetValue( TidyDoc tdoc, TidyOptionId optId, ctmbstr val ); -/** Set named Option value as a string. Good if not sure of type. */ -TIDY_EXPORT Bool TIDY_CALL tidyOptParseValue( TidyDoc tdoc, ctmbstr optnam, ctmbstr val ); - -/** Get current Option value as an integer */ -TIDY_EXPORT ulong TIDY_CALL tidyOptGetInt( TidyDoc tdoc, TidyOptionId optId ); -/** Set Option value as an integer */ -TIDY_EXPORT Bool TIDY_CALL tidyOptSetInt( TidyDoc tdoc, TidyOptionId optId, ulong val ); - -/** Get current Option value as a Boolean flag */ -TIDY_EXPORT Bool TIDY_CALL tidyOptGetBool( TidyDoc tdoc, TidyOptionId optId ); -/** Set Option value as a Boolean flag */ -TIDY_EXPORT Bool TIDY_CALL tidyOptSetBool( TidyDoc tdoc, TidyOptionId optId, Bool val ); - -/** Reset option to default value by ID */ -TIDY_EXPORT Bool TIDY_CALL tidyOptResetToDefault( TidyDoc tdoc, TidyOptionId opt ); -/** Reset all options to their default values */ -TIDY_EXPORT Bool TIDY_CALL tidyOptResetAllToDefault( TidyDoc tdoc ); - -/** Take a snapshot of current config settings */ -TIDY_EXPORT Bool TIDY_CALL tidyOptSnapshot( TidyDoc tdoc ); -/** Reset config settings to snapshot (after document processing) */ -TIDY_EXPORT Bool TIDY_CALL tidyOptResetToSnapshot( TidyDoc tdoc ); - -/** Any settings different than default? */ -TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanDefault( TidyDoc tdoc ); -/** Any settings different than snapshot? */ -TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanSnapshot( TidyDoc tdoc ); - -/** Copy current configuration settings from one document to another */ -TIDY_EXPORT Bool TIDY_CALL tidyOptCopyConfig( TidyDoc tdocTo, TidyDoc tdocFrom ); - -/** Get character encoding name. Used with TidyCharEncoding, -** TidyOutCharEncoding, TidyInCharEncoding */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetEncName( TidyDoc tdoc, TidyOptionId optId ); - -/** Get current pick list value for option by ID. Useful for enum types. */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetCurrPick( TidyDoc tdoc, TidyOptionId optId); - -/** Iterate over user declared tags as configured. If `custom-tags` is not -** **no**, then autonomous custom tags will be included in the results. -*/ -TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDeclTagList( TidyDoc tdoc ); -/** Get next declared tag of specified type: TidyInlineTags, TidyBlockTags, -** TidyEmptyTags, TidyPreTags. Note that even when using `custom-tags`, -** TidyCustomTags is not an option here, as autonomous custom tags are -** added to one of the existing types, and TidyCustomTags is defined as -** internal API. -*/ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextDeclTag( TidyDoc tdoc, - TidyOptionId optId, - TidyIterator* iter ); -/** Get option description */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDoc( TidyDoc tdoc, TidyOption opt ); - -/** Iterate over a list of related options */ -TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDocLinksList( TidyDoc tdoc, - TidyOption opt ); -/** Get next related option */ -TIDY_EXPORT TidyOption TIDY_CALL tidyOptGetNextDocLinks( TidyDoc tdoc, - TidyIterator* pos ); - -/** @} end Configuration group */ - -/** @defgroup IO I/O and Messages -** -** By default, Tidy will define, create and use -** instances of input and output handlers for -** standard C buffered I/O (i.e. FILE* stdin, -** FILE* stdout and FILE* stderr for content -** input, content output and diagnostic output, -** respectively. A FILE* cfgFile input handler -** will be used for config files. Command line -** options will just be set directly. -** -** @{ -*/ - -/***************** - Input Source -*****************/ /** Input Callback: get next byte of input */ typedef int (TIDY_CALL *TidyGetByteFunc)( void* sourceData ); @@ -514,628 +949,1118 @@ typedef void (TIDY_CALL *TidyUngetByteFunc)( void* sourceData, byte bt ); /** Input Callback: is end of input? */ typedef Bool (TIDY_CALL *TidyEOFFunc)( void* sourceData ); -/** End of input "character" */ -#define EndOfStream (~0u) - -/** TidyInputSource - Delivers raw bytes of input -*/ +/** This type defines an input source capable of delivering raw bytes of input. + */ TIDY_STRUCT typedef struct _TidyInputSource { - /* Instance data */ - void* sourceData; /**< Input context. Passed to callbacks */ + void* sourceData; /**< Input context. Passed to callbacks. */ - /* Methods */ - TidyGetByteFunc getByte; /**< Pointer to "get byte" callback */ - TidyUngetByteFunc ungetByte; /**< Pointer to "unget" callback */ - TidyEOFFunc eof; /**< Pointer to "eof" callback */ + TidyGetByteFunc getByte; /**< Pointer to "get byte" callback. */ + TidyUngetByteFunc ungetByte; /**< Pointer to "unget" callback. */ + TidyEOFFunc eof; /**< Pointer to "eof" callback. */ } TidyInputSource; -/** Facilitates user defined source by providing -** an entry point to marshal pointers-to-functions. -** Needed by .NET and possibly other language bindings. -*/ -TIDY_EXPORT Bool TIDY_CALL tidyInitSource( TidyInputSource* source, - void* srcData, - TidyGetByteFunc gbFunc, - TidyUngetByteFunc ugbFunc, - TidyEOFFunc endFunc ); +/** Facilitates user defined source by providing an entry point to marshal + ** pointers-to-functions. This is needed by .NET, and possibly other language + ** bindings. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyInitSource(TidyInputSource* source, /**< The source to populate with data. */ + void* srcData, /**< The input context. */ + TidyGetByteFunc gbFunc, /**< Pointer to the "get byte" callback. */ + TidyUngetByteFunc ugbFunc, /**< Pointer to the "unget" callback. */ + TidyEOFFunc endFunc /**< Pointer to the "eof" callback. */ + ); -/** Helper: get next byte from input source */ +/** Helper: get next byte from input source. + ** @param source A pointer to your input source. + ** @result Returns a byte as an unsigned integer. + */ TIDY_EXPORT uint TIDY_CALL tidyGetByte( TidyInputSource* source ); -/** Helper: unget byte back to input source */ -TIDY_EXPORT void TIDY_CALL tidyUngetByte( TidyInputSource* source, uint byteValue ); +/** Helper: unget byte back to input source. */ +TIDY_EXPORT void TIDY_CALL tidyUngetByte(TidyInputSource* source, /**< The input source. */ + uint byteValue /**< The byte to push back. */ + ); -/** Helper: check if input source at end */ +/** Helper: check if input source at end. + ** @param source The input source. + ** @result Returns a bool indicating whether or not the source is at EOF. + */ TIDY_EXPORT Bool TIDY_CALL tidyIsEOF( TidyInputSource* source ); +/** @} + ** @name Output Sink + ** @{ + */ -/**************** - Output Sink -****************/ /** Output callback: send a byte to output */ typedef void (TIDY_CALL *TidyPutByteFunc)( void* sinkData, byte bt ); - -/** TidyOutputSink - accepts raw bytes of output -*/ +/** This type defines an output destination capable of accepting raw bytes + ** of output + */ TIDY_STRUCT typedef struct _TidyOutputSink { - /* Instance data */ - void* sinkData; /**< Output context. Passed to callbacks */ + void* sinkData; /**< Output context. Passed to callbacks. */ - /* Methods */ TidyPutByteFunc putByte; /**< Pointer to "put byte" callback */ } TidyOutputSink; -/** Facilitates user defined sinks by providing -** an entry point to marshal pointers-to-functions. -** Needed by .NET and possibly other language bindings. -*/ -TIDY_EXPORT Bool TIDY_CALL tidyInitSink( TidyOutputSink* sink, - void* snkData, - TidyPutByteFunc pbFunc ); +/** Facilitates user defined sinks by providing an entry point to marshal + ** pointers-to-functions. This is needed by .NET, and possibly other language + ** bindings. + ** @result Returns a bool indicating success or failure. + */ +TIDY_EXPORT Bool TIDY_CALL tidyInitSink(TidyOutputSink* sink, /**< The sink to populate with data. */ + void* snkData, /**< The output context. */ + TidyPutByteFunc pbFunc /**< Pointer to the "put byte" callback function. */ + ); -/** Helper: send a byte to output */ -TIDY_EXPORT void TIDY_CALL tidyPutByte( TidyOutputSink* sink, uint byteValue ); +/** Helper: send a byte to output. */ +TIDY_EXPORT void TIDY_CALL tidyPutByte(TidyOutputSink* sink, /**< The output sink to send a byte. */ + uint byteValue /**< The byte to be sent. */ + ); +/** @} + ** @name Emacs-compatible reporting support. + ** If you work with Emacs and prefer Tidy's report output to be in a form + ** that is easy for Emacs to parse, then these functions may be valuable. + ** @{ + */ - /**************** - Emacs File - ****************/ - /** Set the file path to use for reports when `TidyEmacs` is being used. This - ** function provides a proper interface for using the hidden, internal-only - ** `TidyEmacsFile` configuration option. - */ - TIDY_EXPORT void TIDY_CALL tidySetEmacsFile( TidyDoc tdoc, ctmbstr filePath ); +/** Set the file path to use for reports when `TidyEmacs` is being used. This + ** function provides a proper interface for using the hidden, internal-only + ** `TidyEmacsFile` configuration option. + */ +TIDY_EXPORT void TIDY_CALL tidySetEmacsFile(TidyDoc tdoc, /**< The tidy document for which you are setting the filePath. */ + ctmbstr filePath /**< The path of the document that should be reported. */ + ); - /** Get the file path to use for reports when `TidyEmacs` is being used. This - ** function provides a proper interface for using the hidden, internal-only - ** `TidyEmacsFile` configuration option. - */ - TIDY_EXPORT ctmbstr TIDY_CALL tidyGetEmacsFile( TidyDoc tdoc ); +/** Get the file path to use for reports when `TidyEmacs` is being used. This + ** function provides a proper interface for using the hidden, internal-only + ** `TidyEmacsFile` configuration option. + ** @param tdoc The tidy document for which you want to fetch the file path. + ** @result Returns a string indicating the file path. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyGetEmacsFile( TidyDoc tdoc ); - -/**************** - Errors -****************/ -/** Callback to filter messages by diagnostic level: -** info, warning, etc. Just set diagnostic output -** handler to redirect all diagnostics output. Return true -** to proceed with output, false to cancel. ->>>>>>> next -*/ -typedef Bool (TIDY_CALL *TidyReportFilter)( TidyDoc tdoc, TidyReportLevel lvl, - uint line, uint col, ctmbstr mssg ); +/** @} + ** @name Error Sink + ** Send Tidy's output to any of several destinations with these functions. + ** @{ + */ -TIDY_EXPORT Bool TIDY_CALL tidySetReportFilter( TidyDoc tdoc, - TidyReportFilter filtCallback ); +/** Set error sink to named file. + ** @result Returns a file handle. + */ +TIDY_EXPORT FILE* TIDY_CALL tidySetErrorFile(TidyDoc tdoc, /**< The document to set. */ + ctmbstr errfilnam /**< The file path to send output. */ + ); -/** The `TidyReportCallback` is a simple filtering mechanism that provides -** the TidyDoc instance, the report level, line and column location, as well -** as a string code (see `tidyErrorFilterKeyItem` type for applicable codes) -** to look up your own strings, and a va_list of arguments that you can use -** to fill in your own strings. -*/ +/** Set error sink to given buffer. + ** @result Returns 0 upon success or a standard error number. + */ +TIDY_EXPORT int TIDY_CALL tidySetErrorBuffer(TidyDoc tdoc, /**< The document to set. */ + TidyBuffer* errbuf /**< The TidyBuffer to collect output. */ + ); + +/** Set error sink to given generic sink. + ** @result Returns 0 upon success or a standard error number. + */ +TIDY_EXPORT int TIDY_CALL tidySetErrorSink(TidyDoc tdoc, /**< The document to set. */ + TidyOutputSink* sink /**< The TidyOutputSink to collect output. */ + ); + +/** @} + ** @name Error and Message Callbacks - TidyReportFilter + ** A simple callback to filter or collect messages by diagnostic level, + ** for example, TidyInfo, TidyWarning, etc. Its name reflects its original + ** purpose as a filter, by which your application can inform LibTidy whether + ** or not to output a particular report. + ** + ** @{ + */ + +/** This typedef represents the required signature for your provided callback + ** function should you wish to register one with tidySetReportFilter(). + ** Your callback function will be provided with the following parameters. + ** @param tdoc Indicates the tidy document the message comes from. + ** @param lvl Specifies the TidyReportLevel of the message. + ** @param line Indicates the line number in the source document the message applies to. + ** @param col Indicates the column in the source document the message applies to. + ** @param mssg Specifies the complete message as Tidy would emit it. + ** @return Your callback function will return `yes` if Tidy should include the + ** report in its own output sink, or `no` if Tidy should suppress it. + */ +typedef Bool (TIDY_CALL *TidyReportFilter)( TidyDoc tdoc, TidyReportLevel lvl, uint line, uint col, ctmbstr mssg ); + +/** This function informs Tidy to use the specified callback to send reports. */ +TIDY_EXPORT Bool TIDY_CALL tidySetReportFilter(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ + TidyReportFilter filtCallback /**< A pointer to your callback function of type TidyReportFilter. */ + ); + +/** @} + ** @name Error and Message Callbacks - TidyReportCallback + ** A simple callback to filter or collect messages reported by Tidy. + ** Unlike TidyReportFilter, more data are provided (including a `va_list`), + ** making this callback suitable for applications that provide more + ** sophisticated handling of reports. + ** @remark The use of a `va_list` may preclude using this callback from + ** non-C-like languages, which is uncharacteristic of Tidy. For more + ** flexibility, consider using TidyMessageCallback instead. + ** @note This callback was previously `TidyMessageFilter3` in older versions + ** of LibTidy. + ** @{ + */ + +/** This typedef represents the required signature for your provided callback + ** function should you wish to register one with tidySetReportCallback(). + ** Your callback function will be provided with the following parameters. + ** @param tdoc Indicates the tidy document the message comes from. + ** @param lvl Specifies the TidyReportLevel of the message. + ** @param line Indicates the line number in the source document the message applies to. + ** @param col Indicates the column in the source document the message applies to. + ** @param code Specifies the message code representing the message. Note that + ** this code is a string value that the API promises to hold constant, + ** as opposed to an enum value that can change at any time. Although + ** this is intended so that you can look up your own application's + ** strings, you can retrieve Tidy's format string with this code by + ** using tidyErrorCodeFromKey() and then the tidyLocalizedString() + ** family of functions. + ** @param args Is a `va_list` of arguments used to fill Tidy's message format string. + ** @return Your callback function will return `yes` if Tidy should include the + ** report in its own output sink, or `no` if Tidy should suppress it. + */ typedef Bool (TIDY_CALL *TidyReportCallback)( TidyDoc tdoc, TidyReportLevel lvl, uint line, uint col, ctmbstr code, va_list args ); -TIDY_EXPORT Bool TIDY_CALL tidySetReportCallback( TidyDoc tdoc, - TidyReportCallback filtCallback ); +/** This function informs Tidy to use the specified callback to send reports. */ +TIDY_EXPORT Bool TIDY_CALL tidySetReportCallback(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ + TidyReportCallback filtCallback /**< A pointer to your callback function of type TidyReportCallback. */ + ); -/** The `TidyMessageCallback` is an advanced filtering mechanism that provides -** great flexibility and exposure to reports and dialogue emitted by Tidy. -** it returns only the opaque type `TidyMessage` which can be queried with the -** message callback API, below. Note that unlike the older filters, this -** callback exposes *all* output that `LibTidy` emits (excluding the console -** application, which is a client of `LibTidy`). +/** @} + ** @name Error and Message Callbacks - TidyMessageCallback + ** A sophisticated and extensible callback to filter or collect messages + ** reported by Tidy. It returns only an opaque type `TidyMessage` for every + ** report and dialogue message, and this message can be queried with the +** TidyMessageCallback API, below. Note that unlike the older filters, this +** callback exposes *all* output that LibTidy emits (excluding the console +** application, which is a client of LibTidy). */ + +/** This typedef represents the required signature for your provided callback + ** function should you wish to register one with tidySetMessageCallback(). + ** Your callback function will be provided with the following parameters. + ** @param tmessage An opaque type used as a token against which other API + ** calls can be made. + ** @return Your callback function will return `yes` if Tidy should include the + ** report in its own output sink, or `no` if Tidy should suppress it. + */ typedef Bool (TIDY_CALL *TidyMessageCallback)( TidyMessage tmessage ); -TIDY_EXPORT Bool TIDY_CALL tidySetMessageCallback( TidyDoc tdoc, - TidyMessageCallback filtCallback ); +/** This function informs Tidy to use the specified callback to send reports. */ +TIDY_EXPORT Bool TIDY_CALL tidySetMessageCallback(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ + TidyMessageCallback filtCallback /**< A pointer to your callback function of type TidyMessageCallback. */ + ); +/** @name TidyMessageCallback API + ** When using `TidyMessageCallback` you will be supplied with a TidyMessage + ** object, which is used as a token to be interrogated with the following + ** API before the callback returns. + ** @remark Upon returning from the callback, this object is destroyed so do + ** not attempt to copy it, or keep it around, or use it in any way. + ** + ** @{ + */ -/** Set error sink to named file */ -TIDY_EXPORT FILE* TIDY_CALL tidySetErrorFile( TidyDoc tdoc, ctmbstr errfilnam ); -/** Set error sink to given buffer */ -TIDY_EXPORT int TIDY_CALL tidySetErrorBuffer( TidyDoc tdoc, TidyBuffer* errbuf ); -/** Set error sink to given generic sink */ -TIDY_EXPORT int TIDY_CALL tidySetErrorSink( TidyDoc tdoc, TidyOutputSink* sink ); +/** Get the tidy document this message comes from. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the TidyDoc that generated the message. + */ +TIDY_EXPORT TidyDoc TIDY_CALL tidyGetMessageDoc( TidyMessage tmessage ); - -/*************************** -** TidyMessageCallback API -** When using `TidyMessageCallback` you will be supplied with a valid -** TidyMessage object. This object can be interrogated with the following -** API before the callback returns. Upon returning from the callback, this -** object is destroyed so do not attempt to keep it around. -****************************/ - -/** get the message key string. */ +/** Get the message key string. + ** @param tmessage Specify the message that you are querying. + ** @result Returns a string representing the message. This string is intended + ** to be stable by the LibTidy API, and is suitable for use as a key + ** in your own applications. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageKey( TidyMessage tmessage ); -/** get the line number the message applies to. */ +/** Get the line number the message applies to. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the line number, if any, that generated the message. + */ TIDY_EXPORT int TIDY_CALL tidyGetMessageLine( TidyMessage tmessage ); -/** get the column the message applies to. */ +/** Get the column the message applies to. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the column number, if any, that generated the message. + */ TIDY_EXPORT int TIDY_CALL tidyGetMessageColumn( TidyMessage tmessage ); -/** get the TidyReportLevel of the message. */ +/** Get the TidyReportLevel of the message. + ** @param tmessage Specify the message that you are querying. + ** @result Returns a TidyReportLevel indicating the severity or status of the + ** message. + */ TIDY_EXPORT TidyReportLevel TIDY_CALL tidyGetMessageLevel( TidyMessage tmessage ); -/** the built-in format string */ +/** Get the default format string, which is the format string for the message + ** in Tidy's default localization (en_us). + ** @param tmessage Specify the message that you are querying. + ** @result Returns the default localization format string of the message. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageFormatDefault( TidyMessage tmessage ); -/** the localized format string */ +/** Get the localized format string. If a localized version of the format string + ** doesn't exist, then the default version will be returned. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the localized format string of the message. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageFormat( TidyMessage tmessage ); -/** the message, formatted, default language */ +/** Get the message with the format string already completed, in Tidy's + ** default localization. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the message in the default localization. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageDefault( TidyMessage tmessage ); -/** the message, formatted, localized */ +/** Get the message with the format string already completed, in Tidy's + ** current localization. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the message in the current localization. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessage( TidyMessage tmessage ); -/** the position part, default language */ +/** Get the position part part of the message in the default language. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the positional part of a string as Tidy would display it + ** in the console application. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePosDefault( TidyMessage tmessage ); -/** the position part, localized */ +/** Get the position part part of the message in the current language. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the positional part of a string as Tidy would display it + ** in the console application. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePos( TidyMessage tmessage ); -/** the prefix part, default language */ +/** Get the prefix part of a message in the default language. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the message prefix part of a string as Tidy would display + ** it in the console application. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePrefixDefault( TidyMessage tmessage ); -/** the prefix part, localized */ +/** Get the prefix part of a message in the current language. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the message prefix part of a string as Tidy would display + ** it in the console application. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePrefix( TidyMessage tmessage ); -/** Get the message as Tidy would emit it in the default localization. */ +/** Get the complete message as Tidy would emit it in the default localization. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the complete message just as Tidy would display it on the + ** console. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageOutputDefault( TidyMessage tmessage ); -/** Get the message as Tidy would emit it in the currently-set localization. */ +/** Get the complete message as Tidy would emit it in the current localization. + ** @param tmessage Specify the message that you are querying. + ** @result Returns the complete message just as Tidy would display it on the + ** console. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageOutput( TidyMessage tmessage ); +/** @} end subgroup TidyMessageCallback API */ -/*************************** -** TidyMessageCallback Arguments API -** When using `TidyMessageCallback` you will be supplied with a valid -** TidyMessage object, which may have arguments that can be interrogated -** with this API. -****************************/ - -/** - * Initializes the TidyIterator to point to the first item in the message's - * argument. Use `TY_(getNextMEssageArgument)` to get an opaque instance of - * `TidyMessageArgument` for which the subsequent interrogators will be of use. +/** @name TidyMessageCallback Arguments API + ** When using `TidyMessageCallback` you will be supplied with a TidyMessage + ** object which can be used as a token against which to query using this API. + ** This API deals strictly with _arguments_ that a message may or may not have; + ** these are the same arguments that Tidy would apply to a format string in + ** order to fill in the placeholder fields and deliver a complete report or + ** dialogue string to you. + ** + ** @{ + */ + +/** Initiates an iterator for a list of arguments related to a given message. + ** This iterator allows you to iterate through all of the arguments, if any. + ** In order to iterate through the arguments, initiate the iterator with this + ** function, and then use tidyGetNextMessageArgument() to retrieve the first + ** and subsequent arguments. For example: + ** @code{.c} + ** TidyIterator itArg = tidyGetMessageArguments( tmessage ); + ** while ( itArg ) { + ** TidyMessageArgument my_arg = tidyGetNextMessageArgument( tmessage, &itArg ); + ** // do something with my_arg, such as inspect its value or format + ** } + ** @endcode + ** TODO: The internal iterator can be made to hold a reference to the + ** TidyMessage so that we don't have to specify it all the time in + ** these API functions. In addition the TidyMessageArgument should be + ** made to do that same, so that we can simplify those signatures, too. + ** @param tmessage The message about whose arguments you wish to query. + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. */ TIDY_EXPORT TidyIterator TIDY_CALL tidyGetMessageArguments( TidyMessage tmessage ); -/** - * Returns the next `TidyMessageArgument`, which can be interrogated with - * the API, and advances the iterator. +/** Given a valid TidyIterator initiated with tidyGetMessageArguments(), returns + ** an instance of the opaque type TidyMessageArgument, which serves as a token + ** against which the remaining argument API functions may be used to query + ** information. + ** @result Returns an instance of TidyMessageArgument. */ -TIDY_EXPORT TidyMessageArgument TIDY_CALL tidyGetNextMessageArgument( TidyMessage tmessage, TidyIterator* iter ); +TIDY_EXPORT TidyMessageArgument TIDY_CALL tidyGetNextMessageArgument(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetDocLinksList()) token. */ + ); -/** - * Returns the `TidyFormatParameterType` of the given message argument. +/** Returns the `TidyFormatParameterType` of the given message argument. + ** @result Returns the type of parameter of type TidyFormatParameterType. */ -TIDY_EXPORT TidyFormatParameterType TIDY_CALL tidyGetArgType( TidyMessage tmessage, TidyMessageArgument* arg ); +TIDY_EXPORT TidyFormatParameterType TIDY_CALL tidyGetArgType(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); - -/** - * Returns the format specifier of the given message argument. The memory for - * this string is cleared upon termination of the callback, so do be sure to - * make your own copy. +/** Returns the format specifier of the given message argument. The memory for + ** this string is cleared upon termination of the callback, so do be sure to + ** make your own copy. + ** @result Returns the format specifier string of the given argument. */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgFormat( TidyMessage tmessage, TidyMessageArgument* arg ); +TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgFormat(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); - -/** - * Returns the string value of the given message argument. An assertion - * will be generated if the argument type is not a string. +/** Returns the string value of the given message argument. An assertion + ** will be generated if the argument type is not a string. + ** @result Returns the string value of the given argument. */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgValueString( TidyMessage tmessage, TidyMessageArgument* arg ); +TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgValueString(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); - -/** - * Returns the unsigned integer value of the given message argument. An - * assertion will be generated if the argument type is not an unsigned - * integer. +/** Returns the unsigned integer value of the given message argument. An + ** assertion will be generated if the argument type is not an unsigned int. + ** @result Returns the unsigned integer value of the given argument. */ -TIDY_EXPORT uint TIDY_CALL tidyGetArgValueUInt( TidyMessage tmessage, TidyMessageArgument* arg ); +TIDY_EXPORT uint TIDY_CALL tidyGetArgValueUInt(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); - -/** - * Returns the integer value of the given message argument. An assertion - * will be generated if the argument type is not an integer. +/** Returns the integer value of the given message argument. An assertion + ** will be generated if the argument type is not an integer. + ** @result Returns the integer value of the given argument. */ -TIDY_EXPORT int TIDY_CALL tidyGetArgValueInt( TidyMessage tmessage, TidyMessageArgument* arg ); - +TIDY_EXPORT int TIDY_CALL tidyGetArgValueInt(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); /** * Returns the double value of the given message argument. An assertion * will be generated if the argument type is not a double. + ** @result Returns the double value of the given argument. */ -TIDY_EXPORT double TIDY_CALL tidyGetArgValueDouble( TidyMessage tmessage, TidyMessageArgument* arg ); +TIDY_EXPORT double TIDY_CALL tidyGetArgValueDouble(TidyMessage tmessage, /**< The message whose arguments you want to access. */ + TidyMessageArgument* arg /**< The argument that you are querying. */ + ); +/** @} end subgroup TidyMessageCallback Arguments API */ + +/** @name Printing + ** LibTidy applications can somewhat track the progress of the tidying process + ** by using this provided callback. It relates where something in the source + ** document ended up in the output. + ** @{ + */ -/**************** - Printing -****************/ -/** Callback to track the progress of the pretting printing process. -** -*/ +/** This typedef represents the required signature for your provided callback + ** function should you wish to register one with tidySetMessageCallback(). + ** Your callback function will be provided with the following parameters. + ** @param tdoc Indicates the source tidy document. + ** @param line Indicates the line in the source document at this point in the process. + ** @param column Indicates the column in the source document at this point in the process. + ** @param destLine Indicates the line number in the output document at this point in the process. + ** @return Your callback function will return `yes` if Tidy should include the + ** report in its own output sink, or `no` if Tidy should suppress it. + */ typedef void (TIDY_CALL *TidyPPProgress)( TidyDoc tdoc, uint line, uint col, uint destLine ); -TIDY_EXPORT Bool TIDY_CALL tidySetPrettyPrinterCallback( TidyDoc tdoc, - TidyPPProgress callback ); +/** This function informs Tidy to use the specified callback for tracking the + ** pretty-printing process progress. + */ +TIDY_EXPORT Bool TIDY_CALL tidySetPrettyPrinterCallback(TidyDoc tdoc, + TidyPPProgress callback + ); +/** @} */ /** @} end IO group */ +/* MARK: - Document Parse */ +/***************************************************************************//** + ** @defgroup Parse Document Parse + ** + ** Functions for parsing markup from a given input source, as well as string + ** and filename functions for added convenience. HTML/XHTML version determined + ** from input. + ** + ** @{ + ******************************************************************************/ -/* TODO: Catalog all messages for easy translation -TIDY_EXPORT ctmbstr tidyLookupMessage( int errorNo ); -*/ +/** Parse markup in named file. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ +TIDY_EXPORT int TIDY_CALL tidyParseFile(TidyDoc tdoc, /**< The tidy document to use for parsing. */ + ctmbstr filename /**< The filename to parse. */ + ); - - -/** @defgroup Parse Document Parse -** -** Parse markup from a given input source. String and filename -** functions added for convenience. HTML/XHTML version determined -** from input. -** @{ -*/ - -/** Parse markup in named file */ -TIDY_EXPORT int TIDY_CALL tidyParseFile( TidyDoc tdoc, ctmbstr filename ); - -/** Parse markup from the standard input */ +/** Parse markup from the standard input. + ** @param tdoc The tidy document to use for parsing. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ TIDY_EXPORT int TIDY_CALL tidyParseStdin( TidyDoc tdoc ); -/** Parse markup in given string */ -TIDY_EXPORT int TIDY_CALL tidyParseString( TidyDoc tdoc, ctmbstr content ); +/** Parse markup in given string. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ +TIDY_EXPORT int TIDY_CALL tidyParseString(TidyDoc tdoc, /**< The tidy document to use for parsing. */ + ctmbstr content /**< The string to parse. */ + ); -/** Parse markup in given buffer */ -TIDY_EXPORT int TIDY_CALL tidyParseBuffer( TidyDoc tdoc, TidyBuffer* buf ); +/** Parse markup in given buffer. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ +TIDY_EXPORT int TIDY_CALL tidyParseBuffer(TidyDoc tdoc, /**< The tidy document to use for parsing. */ + TidyBuffer* buf /**< The TidyBuffer containing data to parse. */ + ); + +/** Parse markup in given generic input source. + ** @result Returns the highest of `2` indicating that errors were present in + ** the docment, `1` indicating warnings, and `0` in the case of + ** everything being okay. + */ +TIDY_EXPORT int TIDY_CALL tidyParseSource(TidyDoc tdoc, /**< The tidy document to use for parsing. */ + TidyInputSource* source /**< A TidyInputSource containing data to parse. */ + ); -/** Parse markup in given generic input source */ -TIDY_EXPORT int TIDY_CALL tidyParseSource( TidyDoc tdoc, TidyInputSource* source); /** @} End Parse group */ +/* MARK: - Diagnostics and Repair */ +/***************************************************************************//** + ** @defgroup Clean Diagnostics and Repair + ** + ** After parsing the document, you can use these functions to attempt cleanup, + ** repair, get additional diagnostics, and determine the document type. + ** @{ + ******************************************************************************/ - -/** @defgroup Clean Diagnostics and Repair -** -** @{ -*/ -/** Execute configured cleanup and repair operations on parsed markup */ +/** Execute configured cleanup and repair operations on parsed markup. + ** @param tdoc The tidy document to use. + ** @result An integer representing the status. + */ TIDY_EXPORT int TIDY_CALL tidyCleanAndRepair( TidyDoc tdoc ); -/** Run configured diagnostics on parsed and repaired markup. -** Must call tidyCleanAndRepair() first. -*/ +/** Run configured diagnostics on parsed and repaired markup. You must call + ** tidyCleanAndRepair() before using this function. + ** @param tdoc The tidy document to use. + ** @result An integer representing the status. + */ TIDY_EXPORT int TIDY_CALL tidyRunDiagnostics( TidyDoc tdoc ); +/** Reports the document type into the output sink. + ** @param tdoc The tidy document to use. + ** @result An integer representing the status. + */ TIDY_EXPORT int TIDY_CALL tidyReportDoctype( TidyDoc tdoc ); + /** @} end Clean group */ +/* MARK: - Document Save Functions */ +/***************************************************************************//** + ** @defgroup Save Document Save Functions + ** + ** Save currently parsed document to the given output sink. File name + ** and string/buffer functions provided for convenience. + ** + ** @{ + ******************************************************************************/ +/** Save the tidy document to the named file. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidySaveFile(TidyDoc tdoc, /**< The tidy document to save. */ + ctmbstr filename /**< The destination file name. */ + ); -/** @defgroup Save Document Save Functions -** -** Save currently parsed document to the given output sink. File name -** and string/buffer functions provided for convenience. -** @{ -*/ - -/** Save to named file */ -TIDY_EXPORT int TIDY_CALL tidySaveFile( TidyDoc tdoc, ctmbstr filename ); - -/** Save to standard output (FILE*) */ +/** Save the tidy document to standard output (FILE*). + ** @param tdoc The tidy document to save. + ** @result An integer representing the status. + */ TIDY_EXPORT int TIDY_CALL tidySaveStdout( TidyDoc tdoc ); -/** Save to given TidyBuffer object */ -TIDY_EXPORT int TIDY_CALL tidySaveBuffer( TidyDoc tdoc, TidyBuffer* buf ); +/** Save the tidy document to given TidyBuffer object. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidySaveBuffer(TidyDoc tdoc, /**< The tidy document to save. */ + TidyBuffer* buf /**< The buffer to place the output. */ + ); -/** Save document to application buffer. If TidyShowMarkup and -** the document has no errors, or TidyForceOutput, the current -** document, per the current configuration, will be Pretty Printed -** to the application buffer. The document byte length, -** not character length, will be placed in *buflen. The document -** will not be null terminated. If the buffer is not big enough, -** ENOMEM will be returned, else the actual document status. -*/ -TIDY_EXPORT int TIDY_CALL tidySaveString( TidyDoc tdoc, - tmbstr buffer, uint* buflen ); +/** Save the tidy document to an application buffer. If TidyShowMarkup and the + ** document has no errors, or TidyForceOutput, then the current document (per + ** the current configuration) will be pretty printed to this application + ** buffer. The document byte length (not character length) will be placed into + ** *buflen. The document will not be null terminated. If the buffer is not big + ** enough, ENOMEM will be returned, else the actual document status. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidySaveString(TidyDoc tdoc, /**< The tidy document to save. */ + tmbstr buffer, /**< The buffer to save to. */ + uint* buflen /**< [out] The byte length written. */ + ); + +/** Save to given generic output sink. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidySaveSink(TidyDoc tdoc, /**< The tidy document to save. */ + TidyOutputSink* sink /**< The output sink to save to. */ + ); + +/** Save current settings to named file. Only writes non-default values. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidyOptSaveFile(TidyDoc tdoc, /**< The tidy document to save. */ + ctmbstr cfgfil /**< The filename to save the configuration to. */ + ); + +/** Save current settings to given output sink. Only non-default values are + ** written. + ** @result An integer representing the status. + */ +TIDY_EXPORT int TIDY_CALL tidyOptSaveSink(TidyDoc tdoc, /**< The tidy document to save. */ + TidyOutputSink* sink /**< The output sink to save the configuration to. */ + ); -/** Save to given generic output sink */ -TIDY_EXPORT int TIDY_CALL tidySaveSink( TidyDoc tdoc, TidyOutputSink* sink ); /** @} end Save group */ +/* MARK: - Document Tree */ +/***************************************************************************//** + ** @defgroup Tree Document Tree + ** + ** A parsed (and optionally repaired) document is represented by Tidy as a + ** tree, much like a W3C DOM. This tree may be traversed using these + ** functions. The following snippet gives a basic idea how these functions + ** can be used. + ** + ** @code{.c} + ** void dumpNode( TidyNode tnod, int indent ) { + ** TidyNode child; + ** + ** for ( child = tidyGetChild(tnod); child; child = tidyGetNext(child) ) { + ** ctmbstr name; + ** switch ( tidyNodeGetType(child) ) { + ** case TidyNode_Root: name = "Root"; break; + ** case TidyNode_DocType: name = "DOCTYPE"; break; + ** case TidyNode_Comment: name = "Comment"; break; + ** case TidyNode_ProcIns: name = "Processing Instruction"; break; + ** case TidyNode_Text: name = "Text"; break; + ** case TidyNode_CDATA: name = "CDATA"; break; + ** case TidyNode_Section: name = "XML Section"; break; + ** case TidyNode_Asp: name = "ASP"; break; + ** case TidyNode_Jste: name = "JSTE"; break; + ** case TidyNode_Php: name = "PHP"; break; + ** case TidyNode_XmlDecl: name = "XML Declaration"; break; + ** + ** case TidyNode_Start: + ** case TidyNode_End: + ** case TidyNode_StartEnd: + ** default: + ** name = tidyNodeGetName( child ); + ** break; + ** } + ** assert( name != NULL ); + ** printf( "\%*.*sNode: \%s\\n", indent, indent, " ", name ); + ** dumpNode( child, indent + 4 ); + ** } + ** } + ** + ** void dumpDoc( TidyDoc tdoc ) { + ** dumpNode( tidyGetRoot(tdoc), 0 ); + ** } + ** + ** void dumpBody( TidyDoc tdoc ) { + ** dumpNode( tidyGetBody(tdoc), 0 ); + ** } + ** @endcode + ** + ** @{ + ******************************************************************************/ +/** @name Nodes for Document Sections + ** @{ + */ -/** @addtogroup Basic -** @{ -*/ -/** Save current settings to named file. - Only non-default values are written. */ -TIDY_EXPORT int TIDY_CALL tidyOptSaveFile( TidyDoc tdoc, ctmbstr cfgfil ); - -/** Save current settings to given output sink. - Only non-default values are written. */ -TIDY_EXPORT int TIDY_CALL tidyOptSaveSink( TidyDoc tdoc, TidyOutputSink* sink ); - - -/* Error reporting functions -*/ - -/** Write more complete information about errors to current error sink. */ -TIDY_EXPORT void TIDY_CALL tidyErrorSummary( TidyDoc tdoc ); - -/** Write more general information about markup to current error sink. */ -TIDY_EXPORT void TIDY_CALL tidyGeneralInfo( TidyDoc tdoc ); - -/** @} end Basic group (again) */ - - -/** @defgroup Tree Document Tree -** -** A parsed and, optionally, repaired document is -** represented by Tidy as a Tree, much like a W3C DOM. -** This tree may be traversed using these functions. -** The following snippet gives a basic idea how these -** functions can be used. -** -
-void dumpNode( TidyNode tnod, int indent )
-{
-  TidyNode child;
-
-  for ( child = tidyGetChild(tnod); child; child = tidyGetNext(child) )
-  {
-    ctmbstr name;
-    switch ( tidyNodeGetType(child) )
-    {
-    case TidyNode_Root:       name = "Root";                    break;
-    case TidyNode_DocType:    name = "DOCTYPE";                 break;
-    case TidyNode_Comment:    name = "Comment";                 break;
-    case TidyNode_ProcIns:    name = "Processing Instruction";  break;
-    case TidyNode_Text:       name = "Text";                    break;
-    case TidyNode_CDATA:      name = "CDATA";                   break;
-    case TidyNode_Section:    name = "XML Section";             break;
-    case TidyNode_Asp:        name = "ASP";                     break;
-    case TidyNode_Jste:       name = "JSTE";                    break;
-    case TidyNode_Php:        name = "PHP";                     break;
-    case TidyNode_XmlDecl:    name = "XML Declaration";         break;
-
-    case TidyNode_Start:
-    case TidyNode_End:
-    case TidyNode_StartEnd:
-    default:
-      name = tidyNodeGetName( child );
-      break;
-    }
-    assert( name != NULL );
-    printf( "\%*.*sNode: \%s\\n", indent, indent, " ", name );
-    dumpNode( child, indent + 4 );
-  }
-}
-
-void dumpDoc( TidyDoc tdoc )
-{
-  dumpNode( tidyGetRoot(tdoc), 0 );
-}
-
-void dumpBody( TidyDoc tdoc )
-{
-  dumpNode( tidyGetBody(tdoc), 0 );
-}
-
- -@{ - -*/ - +/** Get the root node. + ** @param tdoc The document to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetRoot( TidyDoc tdoc ); + +/** Get the HTML node. + ** @param tdoc The document to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetHtml( TidyDoc tdoc ); + +/** Get the HEAD node. + ** @param tdoc The document to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetHead( TidyDoc tdoc ); + +/** Get the BODY node. + ** @param tdoc The document to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetBody( TidyDoc tdoc ); -/* remove a node */ -TIDY_EXPORT TidyNode TIDY_CALL tidyDiscardElement( TidyDoc tdoc, TidyNode tnod ); +/** @} + ** @name Relative Nodes + ** @{ + */ -/* parent / child */ +/** Get the parent of the indicated node. + ** @param tnod The node to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetParent( TidyNode tnod ); + +/** Get the child of the indicated node. + ** @param tnod The node to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetChild( TidyNode tnod ); -/* siblings */ +/** Get the next sibling node. + ** @param tnod The node to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetNext( TidyNode tnod ); + +/** Get the previous sibling node. + ** @param tnod The node to query. + ** @result Returns a tidy node. + */ TIDY_EXPORT TidyNode TIDY_CALL tidyGetPrev( TidyNode tnod ); -/* Iterate over attribute values */ +/** @} + ** @name Miscellaneous Node Functions + ** @{ + */ + +/** Remove the indicated node. + ** @result Returns the next tidy node. + */ +TIDY_EXPORT TidyNode TIDY_CALL tidyDiscardElement(TidyDoc tdoc, /**< The tidy document from which to remove the node. */ + TidyNode tnod /**< The node to remove */ + ); + +/** @} + ** @name Node Attribute Functions + ** @{ + */ + +/** Get the first attribute. + ** @param tnod The node for which to get attributes. + ** @result Returns an instance of TidyAttr. + */ TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrFirst( TidyNode tnod ); + +/** Get the next attribute. + ** @param tattr The current attribute, so the next one can be returned. + ** @result Returns and instance of TidyAttr. + */ TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrNext( TidyAttr tattr ); +/** Get the name of a TidyAttr instance. + ** @param tattr The tidy attribute to query. + ** @result Returns a string indicating the name of the attribute. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyAttrName( TidyAttr tattr ); + +/** Get the value of a TidyAttr instance. + ** @param tattr The tidy attribute to query. + ** @result Returns a string indicating the value of the attribute. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyAttrValue( TidyAttr tattr ); -TIDY_EXPORT void TIDY_CALL tidyAttrDiscard( TidyDoc itdoc, TidyNode tnod, TidyAttr tattr ); +/** Discard an attribute. */ +TIDY_EXPORT void TIDY_CALL tidyAttrDiscard(TidyDoc itdoc, /**< The tidy document from which to discard the attribute. */ + TidyNode tnod, /**< The node from which to discard the attribute. */ + TidyAttr tattr /**< The attribute to discard. */ + ); -/** @} end Tree group */ +/** Get the attribute ID given a tidy attribute. + ** @param tattr The attribute to query. + ** @result Returns the TidyAttrId of the given attribute. + **/ +TIDY_EXPORT TidyAttrId TIDY_CALL tidyAttrGetId( TidyAttr tattr ); +/** Indicates whether or not a given attribute is an event attribute. + ** @param tattr The attribute to query. + ** @result Returns a bool indicating whether or not the attribute is an event. + **/ +TIDY_EXPORT Bool TIDY_CALL tidyAttrIsEvent( TidyAttr tattr ); -/** @defgroup NodeAsk Node Interrogation -** -** Get information about any givent node. -** @{ -*/ +/** Get an instance of TidyAttr by specifying an attribute ID. + ** @result Returns a TidyAttr instance. + */ +TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrGetById(TidyNode tnod, /**< The node to query. */ + TidyAttrId attId /**< The attribute ID to find. */ + ); -/* Node info */ +/** @} + ** @name Additional Node Interrogation + ** @{ + */ + +/** Get the type of node. + ** @param tnod The node to query. + ** @result Returns the type of node as TidyNodeType. + */ TIDY_EXPORT TidyNodeType TIDY_CALL tidyNodeGetType( TidyNode tnod ); + +/** Get the name of the node. + ** @param tnod The node to query. + ** @result Returns a string indicating the name of the node. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyNodeGetName( TidyNode tnod ); +/** Indicates whether or not a node is a text node. + ** @param tnod The node to query. + ** @result Returns a bool indicating whether or not the node is a text node. + */ TIDY_EXPORT Bool TIDY_CALL tidyNodeIsText( TidyNode tnod ); -TIDY_EXPORT Bool TIDY_CALL tidyNodeIsProp( TidyDoc tdoc, TidyNode tnod ); -TIDY_EXPORT Bool TIDY_CALL tidyNodeIsHeader( TidyNode tnod ); /* h1, h2, ... */ -TIDY_EXPORT Bool TIDY_CALL tidyNodeHasText( TidyDoc tdoc, TidyNode tnod ); -TIDY_EXPORT Bool TIDY_CALL tidyNodeGetText( TidyDoc tdoc, TidyNode tnod, TidyBuffer* buf ); +/** Indicates whether or not the node is a propriety type. + ** @result Returns a bool indicating whether or not the node is a proprietary type. + */ +TIDY_EXPORT Bool TIDY_CALL tidyNodeIsProp(TidyDoc tdoc, /**< The document to query. */ + TidyNode tnod /**< The node to query */ + ); -/* Copy the unescaped value of this node into the given TidyBuffer as UTF-8 */ -TIDY_EXPORT Bool TIDY_CALL tidyNodeGetValue( TidyDoc tdoc, TidyNode tnod, TidyBuffer* buf ); +/** Indicates whether or not a node represents and HTML header element, such + ** as h1, h2, etc. + ** @param tnod The node to query. + ** @result Returns a bool indicating whether or not the node is an HTML header. + */ +TIDY_EXPORT Bool TIDY_CALL tidyNodeIsHeader( TidyNode tnod ); +/** Indicates whether or not the node has text. + ** @result Returns the type of node as TidyNodeType. + */ +TIDY_EXPORT Bool TIDY_CALL tidyNodeHasText(TidyDoc tdoc, /**< The document to query. */ + TidyNode tnod /**< The node to query. */ + ); + +/** Gets the text of a node and places it into the given TidyBuffer. + ** @result Returns a bool indicating success or not. + */ +TIDY_EXPORT Bool TIDY_CALL tidyNodeGetText(TidyDoc tdoc, /**< The document to query. */ + TidyNode tnod, /**< The node to query. */ + TidyBuffer* buf /**< [out] A TidyBuffer used to receive the node's text. */ + ); + +/** Get the value of the node. This copies the unescaped value of this node into + ** the given TidyBuffer at UTF-8. + ** @result Returns a bool indicating success or not. + */ +TIDY_EXPORT Bool TIDY_CALL tidyNodeGetValue(TidyDoc tdoc, /**< The document to query */ + TidyNode tnod, /**< The node to query */ + TidyBuffer* buf /**< [out] A TidyBuffer used to receive the node's value. */ + ); + +/** Get the tag ID of the node. + ** @param tnod The node to query. + ** @result Returns the tag ID of the node as TidyTagId. + */ TIDY_EXPORT TidyTagId TIDY_CALL tidyNodeGetId( TidyNode tnod ); +/** Get the line number where the node occurs. + ** @param tnod The node to query. + ** @result Returns the line number. + */ TIDY_EXPORT uint TIDY_CALL tidyNodeLine( TidyNode tnod ); + +/** Get the column location of the node. + ** @param tnod The node to query. + ** @result Returns the column location of the node. + */ TIDY_EXPORT uint TIDY_CALL tidyNodeColumn( TidyNode tnod ); -/** @} End NodeAsk group */ +/** @} */ +/** @} end Tree group */ +/* MARK: - Message Key Management */ +/***************************************************************************//** + ** @defgroup MessagesKeys Message Key Management + ** + ** These functions serve to manage message codes, i.e., codes that are used + ** Tidy and communicated via its callback filters to represent reports and + ** dialogue that Tidy emits. + ** + ** @remark These codes only reflect complete messages, and are specifically + ** distinct from the internal codes that are used to lookup individual + ** strings for localization purposes. + ** + ** @{ + ******************************************************************************/ -/** @defgroup Attribute Attribute Interrogation and Retrieval -** -** Get information about attributes, and retrieve them from nodes. -** @{ -*/ - -TIDY_EXPORT TidyAttrId TIDY_CALL tidyAttrGetId( TidyAttr tattr ); -TIDY_EXPORT Bool TIDY_CALL tidyAttrIsEvent( TidyAttr tattr ); - -TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrGetById( TidyNode tnod, TidyAttrId attId ); - -/** @} end Attribute group */ - - -/** @defgroup MessagesKeys Message Key Management -** -** These functions serve to manage message codes. To-do is to rename them -** so they reflect messages and not errors. -** @{ -*/ - +/** + ** Given a message code, return the text key that represents it. + ** @param code The error code to lookup. + ** @result The string representing the error code. + */ TIDY_EXPORT ctmbstr TIDY_CALL tidyErrorCodeAsKey(uint code); + +/** + ** Given a text key representing a message code, return the uint that + ** represents it. + ** + ** @remark We establish that for external purposes, the API will ensure that + ** string keys remain consistent. *Never* count on the integer value + ** of a message code. Always use this function to ensure that the + ** integer is valid if you need one. + ** @param code The string representing the error code. + ** @result Returns an integer that represents the error code, which can be + ** used to lookup Tidy's built-in strings. If the provided string does + ** not have a matching message code, then UINT_MAX will be returned. + */ +TIDY_EXPORT uint TIDY_CALL tidyErrorCodeFromKey(ctmbstr code); + +/** Initiates an iterator for a list of message codes available in Tidy. + ** This iterator allows you to iterate through all of the code. In orde to + ** iterate through the codes, initiate the iterator with this function, and + ** then use getNextErrorCode() to retrieve the first and subsequent codes. + ** For example: + ** @code{.c} + ** TidyIterator itMessage = getErrorCodeList(); + ** while ( itMessage ) { + ** uint code = getNextErrorCode( &itMessage ); + ** // do something with the code, such as lookup a string. + ** } + ** @endcode + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ TIDY_EXPORT TidyIterator TIDY_CALL getErrorCodeList(); + +/** Given a valid TidyIterator initiated with getErrorCodeList(), returns + ** an instance of the opaque type TidyMessageArgument, which serves as a token + ** against which the remaining argument API functions may be used to query + ** information. + ** @param iter The TidyIterator (initiated with getErrorCodeList()) token. + ** @result Returns a message code. + */ TIDY_EXPORT uint TIDY_CALL getNextErrorCode( TidyIterator* iter ); -/** @} end MessagesKeys group */ - - -/** @defgroup Localization Localization Support -** -** These functions help manage localization in Tidy. - ** @{ -*/ - -/** - ** Determines the current locale without affecting the C locale. - ** Tidy has always used the default C locale, and at this point - ** in its development we're not going to tamper with that. - ** @param result The buffer to use to return the string. - ** Returns NULL on failure. - ** @return The same buffer for convenience. +/** @} end MessagesKeys group */ +/* MARK: - Localization Support */ +/***************************************************************************//** + ** @defgroup Localization Localization Support + ** + ** These functions help manage localization in Tidy. + ** + ** @{ + ******************************************************************************/ + + +/** @name Tidy's Locale + ** @{ + */ + +/** Determines the current locale without affecting the C locale. + ** @param result The buffer to use to return the string, or NULL on failure. + ** @return The same buffer for convenience. */ TIDY_EXPORT tmbstr TIDY_CALL tidySystemLocale(tmbstr result); -/** - * Tells Tidy to use a different language for output. - * @param languageCode A Windows or POSIX language code, and must match - * a TIDY_LANGUAGE for an installed language. - * @result Indicates that a setting was applied, but not necessarily the - * specific request, i.e., true indicates a language and/or region - * was applied. If es_mx is requested but not installed, and es is - * installed, then es will be selected and this function will return - * true. However the opposite is not true; if es is requested but - * not present, Tidy will not try to select from the es_XX variants. +/** Tells Tidy to use a different language for output. + ** @param languageCode A Windows or POSIX language code, and must match + ** a TIDY_LANGUAGE for an installed language. + ** @result Indicates that a setting was applied, but not necessarily the + ** specific request, i.e., true indicates a language and/or region + ** was applied. If es_mx is requested but not installed, and es is + ** installed, then es will be selected and this function will return + ** true. However the opposite is not true; if es is requested but + ** not present, Tidy will not try to select from the es_XX variants. */ TIDY_EXPORT Bool TIDY_CALL tidySetLanguage( ctmbstr languageCode ); -/** - * Gets the current language used by Tidy. +/** Gets the current language used by Tidy. + ** @result Returns a string indicating the currently set language. */ TIDY_EXPORT ctmbstr TIDY_CALL tidyGetLanguage(); -/** - * Provides a string given `messageType` in the current - * localization for `quantity`. +/** @} + ** @name Locale Mappings + ** @{ */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedStringN( uint messageType, uint quantity ); -/** - * Provides a string given `messageType` in the current - * localization for the single case. - */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedString( uint messageType ); - -/** - * Provides a string given `messageType` in the default - * localization (which is `en`). - */ -TIDY_EXPORT ctmbstr TIDY_CALL tidyDefaultString( uint messageType ); - -/* - * Initializes the TidyIterator to point to the first item - * in Tidy's list of localization string keys. Note that - * these are provided for documentation generation purposes - * and probably aren't useful for LibTidy implementors. - */ -TIDY_EXPORT TidyIterator TIDY_CALL getStringKeyList(); - -/* - * Provides the next key value in Tidy's list of localized - * strings. Note that these are provided for documentation - * generation purposes and probably aren't useful to - * libtidy implementors. - */ -TIDY_EXPORT uint TIDY_CALL getNextStringKey( TidyIterator* iter ); - -/** - * Define an opaque type we can use for tidyLocaleMapItem, which - * is used to iterate through the language list, and used to access - * the windowsName() and the posixName(). +/** @struct tidyLocalMapItem + ** Represents an opaque type we can use for tidyLocaleMapItem, which + ** is used to iterate through the language list, and used to access + ** the windowsName() and the posixName(). */ +/* Prevent Doxygen from listing this as a function. */ +#ifndef DOXYGEN_SHOULD_SKIP_THIS opaque_type(tidyLocaleMapItem); +#endif -/** - * Initializes the TidyIterator to point to the first item - * in Tidy's structure of Windows<->POSIX local mapping. - * Items can be retrieved with getNextWindowsLanguage(); +/** Initiates an iterator for a list of Tidy's Windows<->POSIX locale mappings. + ** This iterator allows you to iterate through this list. In order to + ** iterate through the list, initiate the iterator with this function, and then + ** use getNextWindowsLanguage() to retrieve the first and subsequent codes. + ** For example: + ** @code{.c} + ** TidyIterator itList = getWindowsLanguageList(); + ** while ( itList ) { + ** tidyLocaleMapItem *item = getNextWindowsLanguage( &itList ); + ** // do something such as get the TidyLangWindowsName(item). + ** } + ** @endcode + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. */ TIDY_EXPORT TidyIterator TIDY_CALL getWindowsLanguageList(); -/** - * Returns the next record of type `localeMapItem` in - * Tidy's structure of Windows<->POSIX local mapping. +/** Given a valid TidyIterator initiated with getWindowsLanguageList(), returns + ** a pointer to a tidyLocaleMapItem, which can be further interrogated with + ** TidyLangWindowsName() or TidyLangPosixName(). + ** @param iter The TidyIterator (initiated with getWindowsLanguageList()) token. + ** @result Returns a pointer to a tidyLocaleMapItem. */ TIDY_EXPORT const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter ); -/** - * Given a `tidyLocalMapItem`, return the Windows name. +/** Given a `tidyLocalMapItem`, return the Windows name. + ** @param item An instance of tidyLocalMapItem to query. + ** @result Returns a string with the Windows name of the mapping. */ TIDY_EXPORT const ctmbstr TIDY_CALL TidyLangWindowsName( const tidyLocaleMapItem *item ); -/** - * Given a `tidyLocalMapItem`, return the POSIX name. +/** Given a `tidyLocalMapItem`, return the POSIX name. + ** @param item An instance of tidyLocalMapItem to query. + ** @result Returns a string with the POSIX name of the mapping. */ TIDY_EXPORT const ctmbstr TIDY_CALL TidyLangPosixName( const tidyLocaleMapItem *item ); -/** - * Initializes the TidyIterator to point to the first item - * in Tidy's list of installed language codes. - * Items can be retrieved with getNextInstalledLanguage(); +/** @} + ** @name Getting Localized Strings + ** @{ + */ + +/** Provides a string given `messageType` in the current localization for + ** `quantity`. Some strings have one or more plural forms, and this function + ** will ensure that the correct singular or plural form is returned for the + ** specified quantity. + ** @result Returns the desired string. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedStringN(uint messageType, /**< The message type. */ + uint quantity /**< The quantity. */ + ); + +/** Provides a string given `messageType` in the current localization for the + ** single case. + ** @param messageType The message type. + ** @result Returns the desired string. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedString( uint messageType ); + +/** Provides a string given `messageType` in the default localization (which + ** is `en`). + ** @param messageType The message type. + ** @result Returns the desired string. + */ +TIDY_EXPORT ctmbstr TIDY_CALL tidyDefaultString( uint messageType ); + +/** Initiates an iterator for a list of string key codes available in Tidy. + ** This iterator allows you to iterate through all of the codes. In order to + ** iterate through the codes, initiate the iterator with this function, and + ** then use getNextStringKey() to retrieve the first and subsequent codes. + ** For example: + ** @code{.c} + ** TidyIterator itKey = getErrorCodeList(); + ** while ( itKey ) { + ** uint code = getNextStringKey( &itKey ); + ** // do something with the code, such as lookup a string. + ** } + ** @endcode + ** @remark These are provided for documentation generation purposes, and + ** probably aren't of much use to the average LibTidy implementor. + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. + */ +TIDY_EXPORT TidyIterator TIDY_CALL getStringKeyList(); + +/** Given a valid TidyIterator initiated with getStringKeyList(), returns + ** an unsigned integer representing the next key value. + ** @remark These are provided for documentation generation purposes, and + ** probably aren't of much use to the average LibTidy implementor. + ** @param iter The TidyIterator (initiated with getStringKeyList()) token. + ** @result Returns a message code. + */ +TIDY_EXPORT uint TIDY_CALL getNextStringKey( TidyIterator* iter ); + +/** @} + ** @name Available Languages + ** @{ + */ + +/** Initiates an iterator for a list of Tidy's installed languages. This + ** iterator allows you to iterate through this list. In order to iterate + ** through the list, initiate the iterator with this function, and then use + ** use getNextInstalledLanguage() to retrieve the first and subsequent strings. + ** For example: + ** @code{.c} + ** TidyIterator itList = getInstalledLanguageList(); + ** while ( itList ) { + ** printf("%s", getNextInstalledLanguage( &itList )); + ** } + ** @endcode + ** @result Returns a TidyIterator, which is a token used to represent the + ** current position in a list within LibTidy. */ TIDY_EXPORT TidyIterator TIDY_CALL getInstalledLanguageList(); -/** - * Returns the next installed language. +/** Given a valid TidyIterator initiated with getInstalledLanguageList(), + ** returns a string representing a language name that is installed in Tidy. + ** @param iter The TidyIterator (initiated with getInstalledLanguageList()) + ** token. + ** @result Returns a string indicating the installed language. */ TIDY_EXPORT ctmbstr TIDY_CALL getNextInstalledLanguage( TidyIterator* iter ); - +/** @} */ /** @} end MessagesKeys group */ - +/** @} end public_api group */ + #ifdef __cplusplus } /* extern "C" */ diff --git a/include/tidybuffio.h b/include/tidybuffio.h index 5ecfcc4..7410da7 100644 --- a/include/tidybuffio.h +++ b/include/tidybuffio.h @@ -18,15 +18,18 @@ extern "C" { #endif -/** TidyBuffer - A chunk of memory */ +/** A TidyBuffer is chunk of memory that can be used for multiple I/O purposes + ** within Tidy. + ** @ingroup IO + */ TIDY_STRUCT struct _TidyBuffer { TidyAllocator* allocator; /**< Memory allocator */ - byte* bp; /**< Pointer to bytes */ - uint size; /**< # bytes currently in use */ - uint allocated; /**< # bytes allocated */ - uint next; /**< Offset of current input position */ + byte* bp; /**< Pointer to bytes */ + uint size; /**< Number of bytes currently in use */ + uint allocated; /**< Number of bytes allocated */ + uint next; /**< Offset of current input position */ }; /** Initialize data structure using the default allocator */ diff --git a/src/message.c b/src/message.c index 794c079..c9dbe35 100755 --- a/src/message.c +++ b/src/message.c @@ -8,6 +8,7 @@ #include "message.h" #include "messageobj.h" +#include "limits.h" #include "tidy-int.h" #include "lexer.h" #include "streamio.h" @@ -958,6 +959,21 @@ ctmbstr TY_(tidyErrorCodeAsKey)(uint code) } +/** + * Given an error code string, return its uint. + */ +uint TY_(tidyErrorCodeFromKey)(ctmbstr code) +{ + uint i = 0; + while (tidyErrorFilterKeysStruct[i].key) { + if ( strcmp(tidyErrorFilterKeysStruct[i].key, code) == 0 ) + return tidyErrorFilterKeysStruct[i].value; + i++; + } + return UINT_MAX; +} + + /** * Determines the number of error codes used by Tidy. */ diff --git a/src/message.h b/src/message.h index 08aed6a..25a96f0 100644 --- a/src/message.h +++ b/src/message.h @@ -103,6 +103,12 @@ void TY_(ReportNumWarnings)( TidyDocImpl* doc ); */ ctmbstr TY_(tidyErrorCodeAsKey)(uint code); +/** + * Given an error code string, return the integer value of it, or UINT_MAX + * as an error flag. + */ +uint TY_(tidyErrorCodeFromKey)(ctmbstr code); + /** * Initializes the TidyIterator to point to the first item diff --git a/src/messageobj.c b/src/messageobj.c index 7f7536d..532497a 100644 --- a/src/messageobj.c +++ b/src/messageobj.c @@ -264,6 +264,11 @@ void TY_(tidyMessageRelease)( TidyMessageImpl *message ) *********************************************************************/ +TidyDocImpl* TY_(getMessageDoc)( TidyMessageImpl message ) +{ + return message.tidyDoc; +} + ctmbstr TY_(getMessageKey)( TidyMessageImpl message ) { return message.messageKey; diff --git a/src/messageobj.h b/src/messageobj.h index 8f810b9..1e541ce 100644 --- a/src/messageobj.h +++ b/src/messageobj.h @@ -1,22 +1,28 @@ #ifndef messageobj_h #define messageobj_h -/****************************************************************************** +/**************************************************************************//** + * @file messageobj.h * Provides an external, extensible API for message reporting. * - * This module implements the `TidyMessageImpl` structure (declared in + * This module implements the `_TidyMessageImpl` structure (declared in * `tidy-int.h`) in order to abstract the reporting of reports and dialogue * from the rest of Tidy, and to enable a robust and extensible API for * message interrogation by LibTidy users. * - * (c) 2017 HTACG - * See tidy.h for the copyright notice. + * @author Jim Derry + * @copyright Copyright (c) 2017 HTACG. See tidy.h for license. + * @date Created 2017-March-10 + * ******************************************************************************/ #include "forward.h" +/** @addtogroup internal_api */ +/** @{ */ -/** @name Message Creation and Releasing */ + +/** @defgroup messageobj_instantiation Message Creation and Releasing */ /** @{ */ @@ -51,11 +57,14 @@ TidyMessageImpl *TY_(tidyMessageCreateWithLexer)( TidyDocImpl *doc, void TY_(tidyMessageRelease)( TidyMessageImpl *message ); -/** @} */ -/** @name Report and Dialogue API */ +/** @} end messageobj_instantiation group */ +/** @defgroup messageobj_message_api Report and Dialogue API */ /** @{ */ +/** get the document the message came from. */ +TidyDocImpl* TY_(getMessageDoc)( TidyMessageImpl message ); + /** get the message key string. */ ctmbstr TY_(getMessageKey)( TidyMessageImpl message ); @@ -99,8 +108,8 @@ ctmbstr TY_(getMessageOutputDefault)( TidyMessageImpl message ); ctmbstr TY_(getMessageOutput)( TidyMessageImpl message ); -/** @} */ -/** @name Report Arguments Interrogation API */ +/** @} end messageobj_message_api group */ +/** @defgroup messageobj_args_api Report Arguments Interrogation API */ /** @{ */ /** @@ -160,7 +169,7 @@ int TY_(getArgValueInt)( TidyMessageImpl message, TidyMessageArgument* arg ); double TY_(getArgValueDouble)( TidyMessageImpl message, TidyMessageArgument* arg ); - -/** @} */ +/** @} end messageobj_args_api group */ +/** @} end internal_api group */ #endif /* messageobj_h */ diff --git a/src/tidylib.c b/src/tidylib.c index 8b8acfd..06e3594 100755 --- a/src/tidylib.c +++ b/src/tidylib.c @@ -701,6 +701,13 @@ Bool TIDY_CALL tidySetMessageCallback( TidyDoc tdoc, TidyMessageCallback filt ) return no; } +TidyDoc TIDY_CALL tidyGetMessageDoc( TidyMessage tmessage ) +{ + TidyMessageImpl *message = tidyMessageToImpl(tmessage); + TidyDocImpl* doc = TY_(getMessageDoc)(*message); + return tidyImplToDoc(doc); +} + ctmbstr TIDY_CALL tidyGetMessageKey( TidyMessage tmessage ) { TidyMessageImpl *message = tidyMessageToImpl(tmessage); @@ -2490,6 +2497,11 @@ ctmbstr TIDY_CALL tidyErrorCodeAsKey(uint code) return TY_(tidyErrorCodeAsKey)( code ); } +uint TIDY_CALL tidyErrorCodeFromKey(ctmbstr code) +{ + return TY_(tidyErrorCodeFromKey)( code ); +} + TidyIterator TIDY_CALL getErrorCodeList() { return TY_(getErrorCodeList)();