1 #ifndef __TIDY_H__ 2 #define __TIDY_H__ 3 4 /***************************************************************************//** 5 * @file 6 * Defines HTML Tidy public API implemented by LibTidy. 7 * 8 * This public interface provides the entire public API for LibTidy, and 9 * is the sole interface that you should use when implementing LibTidy in 10 * your own applications. 11 * 12 * See tidy.c as an example application implementing the public API. 13 * 14 * This API is const-correct and doesn't explicitly depend on any globals. 15 * Thus, thread-safety may be introduced without changing the interface. 16 * 17 * The API limits all exposure to internal structures and provides only 18 * accessors that return simple types such as C strings and integers, which 19 * makes it quite suitable for integration with any number of other languages. 20 * 21 * @author Dave Raggett [dsr@w3.org] 22 * @author HTACG, et al (consult git log) 23 * 24 * @remarks The contributing author(s) would like to thank all those who 25 * helped with testing, bug fixes and suggestions for improvements. 26 * This wouldn't have been possible without your help. 27 * 28 * @copyright 29 * Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts 30 * Institute of Technology, European Research Consortium for Informatics 31 * and Mathematics, Keio University). 32 * @par 33 * All Rights Reserved. 34 * @par 35 * This software and documentation is provided "as is," and the copyright 36 * holders and contributing author(s) make no representations or warranties, 37 * express or implied, including but not limited to, warranties of 38 * merchantability or fitness for any particular purpose or that the use of 39 * the software or documentation will not infringe any third party patents, 40 * copyrights, trademarks or other rights. 41 * @par 42 * The copyright holders and contributing author(s) will not be held liable 43 * for any direct, indirect, special or consequential damages arising out of 44 * any use of the software or documentation, even if advised of the 45 * possibility of such damage. 46 * @par 47 * Permission is hereby granted to use, copy, modify, and distribute this 48 * source code, or portions hereof, documentation and executables, for any 49 * purpose, without fee, subject to the following restrictions: 50 * @par 51 * 1. The origin of this source code must not be misrepresented. 52 * 2. Altered versions must be plainly marked as such and must not be 53 * misrepresented as being the original source. 54 * 3. This Copyright notice may not be removed or altered from any source 55 * or altered source distribution. 56 * @par 57 * The copyright holders and contributing author(s) specifically permit, 58 * without fee, and encourage the use of this source code as a component for 59 * supporting the Hypertext Markup Language in commercial products. If you 60 * use this source code in a product, acknowledgment is not required but 61 * would be appreciated. 62 * 63 * @date Created 2001-05-20 by Charles Reitzel 64 * @date Updated 2002-07-01 by Charles Reitzel - 1st Implementation 65 * @date Updated 2015-06-09 by Geoff R. McLane - Add more doxygen syntax 66 * @date Additional updates: consult git log 67 ******************************************************************************/ 68 69 #include "tidyplatform.h" 70 #include "tidyenum.h" 71 72 #ifdef __cplusplus 73 extern "C" { 74 #endif 75 76 /***************************************************************************//** 77 ** @defgroup internal_api Internal API 78 ** The Internal API is used exclusively within LibTidy. If you are an 79 ** HTML Tidy developer, then the internals API will be of especial 80 ** importance to you. 81 ** 82 ** @note Always check first to determine whether or not an internal API 83 ** representation exists for a public API function before invoking a 84 ** public API function internally. In most cases, the public API 85 ** functions simply call an internal function. 86 ** - - - 87 ** @note This documentation _is not_ a substitute for browsing the source 88 ** code. Although the public API is fairly well documented, the 89 ** internal API is a very long, very slow, work-in-progress. 90 ******************************************************************************/ 91 92 /***************************************************************************//** 93 ** @defgroup public_api External Public API 94 ** The Public API is the API that LibTidy programmers must access in order 95 ** to harness HTML Tidy as a library. The API limits all exposure to internal 96 ** structures and provides only accessors that return simple types such as 97 ** C strings and integers, which makes it quite suitable for integration with 98 ** any number of other languages. 99 ** @{ 100 ******************************************************************************/ 101 102 103 /* MARK: - Opaque Types */ 104 /***************************************************************************//** 105 ** @defgroup Opaque Opaque Types 106 ** 107 ** Instances of these types are returned by LibTidy API functions, however 108 ** they are opaque; you cannot see into them, and must use accessor functions 109 ** to access the contents. This ensures that interfacing to LibTidy remains 110 ** as universal as possible. 111 ** 112 ** @note Internally LibTidy developers will cast these to internal 113 ** implementation types with access to all member fields. 114 ** @{ 115 ******************************************************************************/ 116 117 /** @struct TidyDoc 118 ** Instances of this represent a Tidy document, which encapsulates everything 119 ** there is to know about a single Tidy session. Many of the API functions 120 ** return instance of TidyDoc, or expect instances as parameters. 121 */ 122 123 /** @struct TidyOption 124 ** Instances of this represent a Tidy configuration option, which contains 125 ** useful data about these options. Functions related to configuration options 126 ** return or accept instances of this type. 127 */ 128 129 /** @struct TidyNode 130 ** Single nodes of a TidyDocument are represented by this datatype. It can be 131 ** returned by various API functions, or accepted as a function argument. 132 */ 133 134 /** @struct TidyAttr 135 ** Attributes of a TidyNode are represented by this data type. The public API 136 ** functions related to attributes work with this type. 137 */ 138 139 /** @struct TidyMessage 140 ** Instances of this type represent messages generated by Tidy in reference 141 ** to your document. This API is available in some of Tidy's message callback 142 ** functions. 143 */ 144 145 /** @struct TidyMessageArgument 146 ** Instances of this type represent the arguments that compose part of the 147 ** message represented by TidyMessage. These arguments have an API to query 148 ** information about them. 149 */ 150 151 /* Prevent Doxygen from listing these as functions. */ 152 #ifndef DOXYGEN_SHOULD_SKIP_THIS 153 154 opaque_type( TidyDoc ); 155 opaque_type( TidyOption ); 156 opaque_type( TidyNode ); 157 opaque_type( TidyAttr ); 158 opaque_type( TidyMessage ); 159 opaque_type( TidyMessageArgument ); 160 161 #endif 162 163 164 /** @} end Opaque group */ 165 /* MARK: - Memory Allocation */ 166 /***************************************************************************//** 167 ** @defgroup Memory Memory Allocation 168 ** 169 ** Tidy can use a user-provided allocator for all memory allocations. If this 170 ** allocator is not provided, then a default allocator is used which simply 171 ** wraps standard C malloc()/free() calls. These wrappers call the panic() 172 ** function upon any failure. The default panic function prints an out of 173 ** memory message to **stderr**, and calls `exit(2)`. 174 ** 175 ** For applications in which it is unacceptable to abort in the case of memory 176 ** allocation, then the panic function can be replaced with one which 177 ** `longjmps()` out of the LibTidy code. For this to clean up completely, you 178 ** should be careful not to use any Tidy methods that open files as these will 179 ** not be closed before `panic()` is called. 180 ** 181 ** Calling the `xxxWithAllocator()` family (`tidyCreateWithAllocator`, 182 ** `tidyBufInitWithAllocator`, `tidyBufAllocWithAllocator`) allow setting 183 ** custom allocators. 184 ** 185 ** All parts of the document use the same allocator. Calls that require a 186 ** user-provided buffer can optionally use a different allocator. 187 ** 188 ** For reference in designing a plug-in allocator, most allocations made by 189 ** LibTidy are less than 100 bytes, corresponding to attribute names and 190 ** values, etc. 191 ** 192 ** There is also an additional class of much larger allocations which are where 193 ** most of the data from the lexer is stored. It is not currently possible to 194 ** use a separate allocator for the lexer; this would be a useful extension. 195 ** 196 ** In general, approximately 1/3rd of the memory used by LibTidy is freed 197 ** during the parse, so if memory usage is an issue then an allocator that can 198 ** reuse this memory is a good idea. 199 ** 200 ** **To create your own allocator, do something like the following:** 201 ** @code{.c} 202 ** typedef struct _MyAllocator { 203 ** TidyAllocator base; 204 ** // ...other custom allocator state... 205 ** } MyAllocator; 206 ** 207 ** void* MyAllocator_alloc(TidyAllocator *base, void *block, size_t nBytes) { 208 ** MyAllocator *self = (MyAllocator*)base; 209 ** // ... 210 ** } 211 ** // etc. 212 ** 213 ** static const TidyAllocatorVtbl MyAllocatorVtbl = { 214 ** MyAllocator_alloc, 215 ** MyAllocator_realloc, 216 ** MyAllocator_free, 217 ** MyAllocator_panic 218 ** }; 219 ** 220 ** myAllocator allocator; 221 ** TidyDoc doc; 222 ** 223 ** allocator.base.vtbl = &MyAllocatorVtbl; 224 ** //...initialise allocator specific state... 225 ** doc = tidyCreateWithAllocator(&allocator); 226 ** @endcode 227 ** 228 ** Although this looks slightly long-winded, the advantage is that to create a 229 ** custom allocator you simply need to set the vtbl pointer correctly. The vtbl 230 ** itself can reside in static/global data, and hence does not need to be 231 ** initialised each time an allocator is created, and furthermore the memory 232 ** is shared amongst all created allocators. 233 ** 234 ** @{ 235 ******************************************************************************/ 236 237 /* Forward declarations and typedefs. */ 238 struct _TidyAllocatorVtbl; 239 struct _TidyAllocator; 240 241 typedef struct _TidyAllocatorVtbl TidyAllocatorVtbl; 242 typedef struct _TidyAllocator TidyAllocator; 243 244 245 /** Tidy's built-in default allocator. */ 246 struct _TidyAllocator { 247 const TidyAllocatorVtbl *vtbl; /**< The allocator's function table. */ 248 }; 249 250 251 /** This structure is the function table for an allocator. Note that all 252 functions in this table must be provided. */ 253 struct _TidyAllocatorVtbl 254 { 255 /* Doxygen has no idea how to parse these. */ 256 #ifndef DOXYGEN_SHOULD_SKIP_THIS 257 void* (TIDY_CALL *alloc)( TidyAllocator *self, size_t nBytes ); 258 void* (TIDY_CALL *realloc)(TidyAllocator *self, void *block, size_t nBytes ); 259 void (TIDY_CALL *free)(TidyAllocator *self, void *block); 260 void (TIDY_CALL *panic)(TidyAllocator *self, ctmbstr msg); 261 #else 262 /** Called to allocate a block of nBytes of memory */ 263 void* *alloc(TidyAllocator *self, /**< The TidyAllocator to use to alloc memory. */ 264 size_t nBytes /**< The number of bytes to allocate. */ 265 ); 266 267 /** Called to resize (grow, in general) a block of memory. 268 Must support being called with `NULL`. */ 269 void* *realloc(TidyAllocator *self, /**< The TidyAllocator to use to realloc memory. */ 270 void *block, /**< The pointer to the existing block. */ 271 size_t nBytes /**< The number of bytes to allocate. */ 272 ); 273 274 /** Called to free a previously allocated block of memory. 275 */ 276 void *free(TidyAllocator *self, /**< The TidyAllocator to use to free memory. */ 277 void *block /**< The block to free. */ 278 ); 279 280 /** Called when a panic condition is detected. Must support `block == NULL`. 281 This function is not called if either alloc() or realloc() fails; it is 282 up to the allocator to do this. Currently this function can only be 283 called if an error is detected in the tree integrity via the internal 284 function CheckNodeIntegrity(). This is a situation that can only arise 285 in the case of a programming error in LibTidy. You can turn off node 286 integrity checking by defining the constant `NO_NODE_INTEGRITY_CHECK` 287 during the build. 288 **/ 289 void *panic(TidyAllocator *self, /**< The TidyAllocator to use to panic. */ 290 ctmbstr msg /**< The panic message. */ 291 ); 292 #endif /* Doxygen Fix */ 293 }; 294 295 296 /** Callback for `malloc` replacement */ 297 typedef void* (TIDY_CALL *TidyMalloc)( size_t len ); 298 299 /** Callback for `realloc` replacement */ 300 typedef void* (TIDY_CALL *TidyRealloc)( void* buf, size_t len ); 301 302 /** Callback for `free` replacement */ 303 typedef void (TIDY_CALL *TidyFree)( void* buf ); 304 305 /** Callback for out of memory panic state */ 306 typedef void (TIDY_CALL *TidyPanic)( ctmbstr mssg ); 307 308 309 /** Give Tidy a `malloc()` replacement */ 310 TIDY_EXPORT Bool TIDY_CALL tidySetMallocCall( TidyMalloc fmalloc ); 311 312 /** Give Tidy a `realloc()` replacement */ 313 TIDY_EXPORT Bool TIDY_CALL tidySetReallocCall( TidyRealloc frealloc ); 314 315 /** Give Tidy a `free()` replacement */ 316 TIDY_EXPORT Bool TIDY_CALL tidySetFreeCall( TidyFree ffree ); 317 318 /** Give Tidy an "out of memory" handler */ 319 TIDY_EXPORT Bool TIDY_CALL tidySetPanicCall( TidyPanic fpanic ); 320 321 322 /** @} end Memory group */ 323 /* MARK: - Basic Operations */ 324 /***************************************************************************//** 325 ** @defgroup Basic Basic Operations 326 ** 327 ** For an excellent example of how to invoke LibTidy, please consult 328 ** `console/tidy.c:main()` for in-depth implementation details. A simplified 329 ** example can be seen on our site: http://www.html-tidy.org/developer/ 330 ** 331 ** @{ 332 ******************************************************************************/ 333 334 /** @name Instantiation and Destruction 335 ** @{ 336 */ 337 338 /** The primary creation of a document instance. Instances of a TidyDoc are used 339 ** throughout the API as a token to represent a particular document. You must 340 ** create at least one TidyDoc instance to initialize the library and begin 341 ** interaction with the API. When done using a TidyDoc instance, be sure to 342 ** `tidyRelease(myTidyDoc);` in order to free related memory. 343 ** @result Returns a TidyDoc instance. 344 */ 345 TIDY_EXPORT TidyDoc TIDY_CALL tidyCreate(void); 346 347 /** Create a document supplying your own, custom TidyAllocator instead of using 348 ** the built-in default. See the @ref Memory module if you want to create and 349 ** use your own allocator. 350 ** @param allocator The allocator to use for creating the document. 351 ** @result Returns a TidyDoc instance. 352 */ 353 TIDY_EXPORT TidyDoc TIDY_CALL tidyCreateWithAllocator(TidyAllocator *allocator); 354 355 /** Free all memory and release the TidyDoc. The TidyDoc can not be used after 356 ** this call. 357 ** @param tdoc The TidyDoc to free. 358 */ 359 TIDY_EXPORT void TIDY_CALL tidyRelease(TidyDoc tdoc); 360 361 362 /** @} 363 ** @name Host Application Data 364 ** @{ 365 */ 366 367 368 /** Allows the host application to store a chunk of data with each TidyDoc 369 ** instance. This can be useful for callbacks, such as saving a reference to 370 ** `self` within the document. 371 */ 372 TIDY_EXPORT void TIDY_CALL tidySetAppData(TidyDoc tdoc, /**< The document in which to store the data. */ 373 void* appData /**< The pointer to a block of data to store. */ 374 ); 375 376 /** Returns the data previously stored with `tidySetAppData()`. 377 ** @param tdoc document where data has been stored. 378 ** @result The pointer to the data block previously stored. 379 */ 380 TIDY_EXPORT void* TIDY_CALL tidyGetAppData(TidyDoc tdoc); 381 382 383 /** @} 384 ** @name LibTidy Version Information 385 ** @{ 386 */ 387 388 389 /** Get the release date for the current library. 390 ** @result The string representing the release date. 391 */ 392 TIDY_EXPORT ctmbstr TIDY_CALL tidyReleaseDate(void); 393 394 /** Get the version number for the current library. 395 ** @result The string representing the version number. 396 */ 397 TIDY_EXPORT ctmbstr TIDY_CALL tidyLibraryVersion(void); 398 399 /** Get the platform for which Tidy was built. 400 ** @result The string representing the version number. 401 */ 402 TIDY_EXPORT ctmbstr TIDY_CALL tidyPlatform(void); 403 404 405 /** @} 406 ** @name Diagnostics and Repair 407 ** @{ 408 */ 409 410 411 /** Get status of current document. 412 ** @param tdoc An instance of a TidyDoc to query. 413 ** @result Returns the highest of `2` indicating that errors were present in 414 ** the document, `1` indicating warnings, and `0` in the case of 415 ** everything being okay. 416 */ 417 TIDY_EXPORT int TIDY_CALL tidyStatus( TidyDoc tdoc ); 418 419 /** Gets the version of HTML that was output, as an integer, times 100. For 420 ** example, HTML5 will return 500; HTML4.0.1 will return 401. 421 ** @param tdoc An instance of a TidyDoc to query. 422 ** @result Returns the HTML version number (x100). 423 */ 424 TIDY_EXPORT int TIDY_CALL tidyDetectedHtmlVersion( TidyDoc tdoc ); 425 426 /** Indicates whether the output document is or isn't XHTML. 427 ** @param tdoc An instance of a TidyDoc to query. 428 ** @result Returns `yes` if the document is an XHTML type. 429 */ 430 TIDY_EXPORT Bool TIDY_CALL tidyDetectedXhtml( TidyDoc tdoc ); 431 432 /** Indicates whether or not the input document was XML. If TidyXml tags is 433 ** true, or there was an XML declaration in the input document, then this 434 ** function will return yes. 435 ** @param tdoc An instance of a TidyDoc to query. 436 ** @result Returns `yes` if the input document was XML. 437 */ 438 TIDY_EXPORT Bool TIDY_CALL tidyDetectedGenericXml( TidyDoc tdoc ); 439 440 /** Indicates the number of TidyError messages that were generated. For any 441 ** value greater than `0`, output is suppressed unless TidyForceOutput is set. 442 ** @param tdoc An instance of a TidyDoc to query. 443 ** @result Returns the number of TidyError messages that were generated. 444 */ 445 TIDY_EXPORT uint TIDY_CALL tidyErrorCount( TidyDoc tdoc ); 446 447 /** Indicates the number of TidyWarning messages that were generated. 448 ** @param tdoc An instance of a TidyDoc to query. 449 ** @result Returns the number of TidyWarning messages that were generated. 450 */ 451 TIDY_EXPORT uint TIDY_CALL tidyWarningCount( TidyDoc tdoc ); 452 453 /** Indicates the number of TidyAccess messages that were generated. 454 ** @param tdoc An instance of a TidyDoc to query. 455 ** @result Returns the number of TidyAccess messages that were generated. 456 */ 457 TIDY_EXPORT uint TIDY_CALL tidyAccessWarningCount( TidyDoc tdoc ); 458 459 /** Indicates the number of configuration error messages that were generated. 460 ** @param tdoc An instance of a TidyDoc to query. 461 ** @result Returns the number of configuration error messages that were 462 ** generated. 463 */ 464 TIDY_EXPORT uint TIDY_CALL tidyConfigErrorCount( TidyDoc tdoc ); 465 466 /** Write more complete information about errors to current error sink. 467 ** @param tdoc An instance of a TidyDoc to query. 468 */ 469 TIDY_EXPORT void TIDY_CALL tidyErrorSummary( TidyDoc tdoc ); 470 471 /** Write more general information about markup to current error sink. 472 ** @param tdoc An instance of a TidyDoc to query. 473 */ 474 TIDY_EXPORT void TIDY_CALL tidyGeneralInfo( TidyDoc tdoc ); 475 476 477 /** @} 478 ** @name Configuration, File, and Encoding Operations 479 ** @{ 480 */ 481 482 483 /** Load an ASCII Tidy configuration file and set the configuration per its 484 ** contents. Reports config option errors, which can be filtered. 485 ** @result Returns 0 upon success, or any other value if there was an option error. 486 */ 487 TIDY_EXPORT int TIDY_CALL tidyLoadConfig(TidyDoc tdoc, /**< The TidyDoc to which to apply the configuration. */ 488 ctmbstr configFile /**< The complete path to the file to load. */ 489 ); 490 491 /** Load a Tidy configuration file with the specified character encoding, and 492 ** set the configuration per its contents. Reports config option errors, which can be filtered. 493 ** @result Returns 0 upon success, or any other value if there was an option error. 494 */ 495 TIDY_EXPORT int TIDY_CALL tidyLoadConfigEnc(TidyDoc tdoc, /**< The TidyDoc to which to apply the configuration. */ 496 ctmbstr configFile, /**< The complete path to the file to load. */ 497 ctmbstr charenc /**< The encoding to use. See the _enc2iana struct for valid values. */ 498 ); 499 500 /** Determine whether or not a particular file exists. On Unix systems, the use 501 ** of the tilde to represent the user's home directory is supported. 502 ** @result Returns `yes` or `no`, indicating whether or not the file exists. 503 */ 504 TIDY_EXPORT Bool TIDY_CALL tidyFileExists(TidyDoc tdoc, /**< The TidyDoc on whose behalf you are checking. */ 505 ctmbstr filename /**< The path to the file whose existence you wish to check. */ 506 ); 507 508 509 /** Set the input/output character encoding for parsing markup. Valid values 510 ** include `ascii`, `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, 511 ** `utf16le`, `utf16be`, `utf16`, `big5`, and `shiftjis`. These values are not 512 ** case sensitive. 513 ** @note This is the same as using TidySetInCharEncoding() and 514 ** TidySetOutCharEncoding() to set the same value. 515 ** @result Returns 0 upon success, or a system standard error number `EINVAL`. 516 */ 517 TIDY_EXPORT int TIDY_CALL tidySetCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ 518 ctmbstr encnam /**< The encoding name as described above. */ 519 ); 520 521 /** Set the input encoding for parsing markup. Valid values include `ascii`, 522 ** `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, `utf16le`, `utf16be`, 523 ** `utf16`, `big5`, and `shiftjis`. These values are not case sensitive. 524 ** @result Returns 0 upon success, or a system standard error number `EINVAL`. 525 */ 526 TIDY_EXPORT int TIDY_CALL tidySetInCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ 527 ctmbstr encnam /**< The encoding name as described above. */ 528 ); 529 530 /** Set the input encoding for writing markup. Valid values include `ascii`, 531 ** `latin1`, `raw`, `utf8`, `iso2022`, `mac`, `win1252`, `utf16le`, `utf16be`, 532 ** `utf16`, `big5`, and `shiftjis`. These values are not case sensitive. 533 ** @result Returns 0 upon success, or a system standard error number `EINVAL`. 534 */ 535 TIDY_EXPORT int TIDY_CALL tidySetOutCharEncoding(TidyDoc tdoc, /**< The TidyDoc for which you are setting the encoding. */ 536 ctmbstr encnam /**< The encoding name as described above. */ 537 ); 538 539 540 /** @} */ 541 /** @} end Basic group */ 542 /* MARK: - Configuration Options */ 543 /***************************************************************************//** 544 ** @defgroup Configuration Configuration Options 545 ** 546 ** Functions for getting and setting Tidy configuration options. 547 ** 548 ** @note In general, you should expect that options you set should stay set. 549 ** This isn't always the case, though, because Tidy will adjust options 550 ** for internal use during the lexing, parsing, cleaning, and printing 551 ** phases. If you require access to user configuration values at any 552 ** time after the tidyParseXXX() process, make sure to keep your own 553 ** copy, or use tidyOptResetToSnapshot() when you no longer need to 554 ** use any other tidy functions. 555 ** @{ 556 ******************************************************************************/ 557 558 /** @name Option Callback Functions 559 ** @{ 560 */ 561 562 /** This typedef represents the required signature for your provided callback 563 ** function should you wish to register one with tidySetOptionCallback(). 564 ** Your callback function will be provided with the following parameters. 565 ** Note that this is deprecated and you should instead migrate to 566 ** tidySetConfigCallback(). 567 ** @param option The option name that was provided. 568 ** @param value The option value that was provided 569 ** @return Your callback function will return `yes` if it handles the provided 570 ** option, or `no` if it does not. In the latter case, Tidy will issue 571 ** an unknown configuration option error. 572 */ 573 typedef Bool (TIDY_CALL *TidyOptCallback)(ctmbstr option, ctmbstr value); 574 575 /** Applications using TidyLib may want to augment command-line and 576 ** configuration file options. Setting this callback allows a LibTidy 577 ** application developer to examine command-line and configuration file options 578 ** after LibTidy has examined them and failed to recognize them. 579 ** Note that this is deprecated and you should instead migrate to 580 ** tidySetConfigCallback(). 581 ** @result Returns `yes` upon success. 582 */ 583 TIDY_EXPORT Bool TIDY_CALL tidySetOptionCallback(TidyDoc tdoc, /**< The document to apply the callback to. */ 584 TidyOptCallback pOptCallback /**< The name of a function of type TidyOptCallback() to serve as your callback. */ 585 ); 586 587 /** This typedef represents the required signature for your provided callback 588 ** function should you wish to register one with tidySetConfigCallback(). 589 ** Your callback function will be provided with the following parameters. 590 ** @param tdoc The document instance for which the callback was invoked. 591 ** @param option The option name that was provided. 592 ** @param value The option value that was provided 593 ** @return Your callback function will return `yes` if it handles the provided 594 ** option, or `no` if it does not. In the latter case, Tidy will issue 595 ** an unknown configuration option error. 596 */ 597 typedef Bool (TIDY_CALL *TidyConfigCallback)(TidyDoc tdoc, ctmbstr option, ctmbstr value); 598 599 /** Applications using TidyLib may want to augment command-line and 600 ** configuration file options. Setting this callback allows a LibTidy 601 ** application developer to examine command-line and configuration file options 602 ** after LibTidy has examined them and failed to recognize them. 603 ** @result Returns `yes` upon success. 604 */ 605 TIDY_EXPORT Bool TIDY_CALL tidySetConfigCallback(TidyDoc tdoc, /**< The document to apply the callback to. */ 606 TidyConfigCallback pConfigCallback /**< The name of a function of type TidyConfigCallback() to serve as your callback. */ 607 ); 608 609 610 /** This typedef represents the required signature for your provided callback 611 ** function should you wish to register one with tidySetConfigChangeCallback(). 612 ** Your callback function will be provided with the following parameters. 613 ** @param tdoc The document instance for which the callback was invoked. 614 ** @param option The option that will be changed. 615 */ 616 typedef void (TIDY_CALL *TidyConfigChangeCallback)(TidyDoc tdoc, TidyOption option); 617 618 /** Applications using TidyLib may want to be informed when changes to options 619 ** are made. Temporary changes made internally by Tidy are not reported, but 620 ** permanent changes made by Tidy (such as indent-spaces or output-encoding) 621 ** will be reported. 622 ** @note This callback is not currently implemented. 623 ** @result Returns `yes` upon success. 624 */ 625 TIDY_EXPORT Bool TIDY_CALL tidySetConfigChangeCallback(TidyDoc tdoc, /**< The document to apply the callback to. */ 626 TidyConfigChangeCallback pCallback /**< The name of a function of type TidyConfigChangeCallback() to serve as your callback. */ 627 ); 628 629 630 /** @} 631 ** @name Option ID Discovery 632 ** @{ 633 */ 634 635 /** Get ID of given Option 636 ** @param opt An instance of a TidyOption to query. 637 ** @result The TidyOptionId of the given option. 638 */ 639 TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetId( TidyOption opt ); 640 641 /** Returns the TidyOptionId (enum value) by providing the name of a Tidy 642 ** configuration option. 643 ** @param optnam The name of the option ID to retrieve. 644 ** @result The TidyOptionId of the given `optname`. 645 */ 646 TIDY_EXPORT TidyOptionId TIDY_CALL tidyOptGetIdForName(ctmbstr optnam); 647 648 /** @} 649 ** @name Getting Instances of Tidy Options 650 ** @{ 651 */ 652 653 /** Initiates an iterator for a list of TidyOption instances, which allows you 654 ** to iterate through all of the available options. In order to iterate through 655 ** the available options, initiate the iterator with this function, and then 656 ** use tidyGetNextOption() to retrieve the first and subsequent options. For 657 ** example: 658 ** @code{.c} 659 ** TidyIterator itOpt = tidyGetOptionList( tdoc ); 660 ** while ( itOpt ) { 661 ** TidyOption opt = tidyGetNextOption( tdoc, &itOpt ); 662 ** // Use other API to query or set set option values 663 ** } 664 ** @endcode 665 ** @param tdoc An instance of a TidyDoc to query. 666 ** @result Returns a TidyIterator, which is a token used to represent the 667 ** current position in a list within LibTidy. 668 */ 669 TIDY_EXPORT TidyIterator TIDY_CALL tidyGetOptionList( TidyDoc tdoc ); 670 671 /** Given a valid TidyIterator initiated with tidyGetOptionList(), returns 672 ** the instance of the next TidyOption. 673 ** @note This function will return internal-only option types including 674 ** `TidyInternalCategory`; you should *never* use these. Always ensure 675 ** that you use `tidyOptGetCategory()` before assuming that an option 676 ** is okay to use in your application. 677 ** @result An instance of TidyOption. 678 */ 679 TIDY_EXPORT TidyOption TIDY_CALL tidyGetNextOption(TidyDoc tdoc, /**< The document for which you are retrieving options. */ 680 TidyIterator* pos /**< The TidyIterator (initiated with tidyGetOptionList()) token. */ 681 ); 682 683 /** Retrieves an instance of TidyOption given a valid TidyOptionId. 684 ** @result An instance of TidyOption matching the provided TidyOptionId. 685 */ 686 TIDY_EXPORT TidyOption TIDY_CALL tidyGetOption(TidyDoc tdoc, /**< The document for which you are retrieving the option. */ 687 TidyOptionId optId /**< The TidyOptionId to retrieve. */ 688 ); 689 690 /** Returns an instance of TidyOption by providing the name of a Tidy 691 ** configuration option. 692 ** @result The TidyOption of the given `optname`. 693 */ 694 TIDY_EXPORT TidyOption TIDY_CALL tidyGetOptionByName(TidyDoc tdoc, /**< The document for which you are retrieving the option. */ 695 ctmbstr optnam /**< The name of the Tidy configuration option. */ 696 ); 697 698 /** @} 699 ** @name Information About Options 700 ** @{ 701 */ 702 703 /** Get name of given Option 704 ** @param opt An instance of a TidyOption to query. 705 ** @result The name of the given option. 706 */ 707 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetName( TidyOption opt ); 708 709 /** Get datatype of given Option 710 ** @param opt An instance of a TidyOption to query. 711 ** @result The TidyOptionType of the given option. 712 */ 713 TIDY_EXPORT TidyOptionType TIDY_CALL tidyOptGetType( TidyOption opt ); 714 715 /** Indicates that an option takes a list of items. 716 ** @param opt An instance of a TidyOption to query. 717 ** @result A bool indicating whether or not the option accepts a list. 718 */ 719 TIDY_EXPORT Bool TIDY_CALL tidyOptionIsList( TidyOption opt ); 720 721 /** Is Option read-only? Some options (mainly internal use only options) are 722 ** read-only. 723 ** @deprecated This is no longer a valid test for the public API; instead 724 ** you should test an option's availability using `tidyOptGetCategory()` 725 ** against `TidyInternalCategory`. This API will be removed! 726 ** @param opt An instance of a TidyOption to query. 727 ** @result Returns `yes` or `no` depending on whether or not the specified 728 ** option is read-only. 729 */ 730 TIDY_EXPORT Bool TIDY_CALL tidyOptIsReadOnly( TidyOption opt ); 731 732 /** Get category of given Option 733 ** @param opt An instance of a TidyOption to query. 734 ** @result The TidyConfigCategory of the specified option. 735 */ 736 TIDY_EXPORT TidyConfigCategory TIDY_CALL tidyOptGetCategory( TidyOption opt ); 737 738 /** Get default value of given Option as a string 739 ** @param opt An instance of a TidyOption to query. 740 ** @result A string indicating the default value of the specified option. 741 */ 742 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDefault( TidyOption opt ); 743 744 /** Get default value of given Option as an unsigned integer 745 ** @param opt An instance of a TidyOption to query. 746 ** @result An unsigned integer indicating the default value of the specified 747 ** option. 748 */ 749 TIDY_EXPORT ulong TIDY_CALL tidyOptGetDefaultInt( TidyOption opt ); 750 751 /** Get default value of given Option as a Boolean value 752 ** @param opt An instance of a TidyOption to query. 753 ** @result A boolean indicating the default value of the specified option. 754 */ 755 TIDY_EXPORT Bool TIDY_CALL tidyOptGetDefaultBool( TidyOption opt ); 756 757 /** Initiates an iterator for a list of TidyOption pick-list values, which 758 ** allows you iterate through all of the available option values. In order to 759 ** iterate through the available values, initiate the iterator with this 760 ** function, and then use tidyOptGetNextPick() to retrieve the first and 761 ** subsequent option values. For example: 762 ** @code{.c} 763 ** TidyIterator itOpt = tidyOptGetPickList( opt ); 764 ** while ( itOpt ) { 765 ** printf("%s", tidyOptGetNextPick( opt, &itOpt )); 766 ** } 767 ** @endcode 768 ** @param opt An instance of a TidyOption to query. 769 ** @result Returns a TidyIterator, which is a token used to represent the 770 ** current position in a list within LibTidy. 771 */ 772 TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetPickList( TidyOption opt ); 773 774 /** Given a valid TidyIterator initiated with tidyOptGetPickList(), returns a 775 ** string representing a possible option value. 776 ** @result A string containing the next pick-list option value. 777 */ 778 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextPick(TidyOption opt, /**< An instance of a TidyOption to query. */ 779 TidyIterator* pos /**< The TidyIterator (initiated with tidyOptGetPickList()) token. */ 780 ); 781 782 /** @} 783 ** @name Option Value Functions 784 ** @{ 785 */ 786 787 /** Get the current value of the option ID for the given document. 788 ** @remark The optId *must* have a @ref TidyOptionType of @ref TidyString! 789 */ 790 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetValue(TidyDoc tdoc, /**< The tidy document whose option value you wish to check. */ 791 TidyOptionId optId /**< The option ID whose value you wish to check. */ 792 ); 793 794 /** Set the option value as a string. 795 ** @remark The optId *must* have a @ref TidyOptionType of @ref TidyString! 796 ** @result Returns a bool indicating success or failure. 797 */ 798 TIDY_EXPORT Bool TIDY_CALL tidyOptSetValue(TidyDoc tdoc, /**< The tidy document for which to set the value. */ 799 TidyOptionId optId, /**< The option ID of the value to set. */ 800 ctmbstr val /**< The string value to set. */ 801 ); 802 803 /** Set named option value as a string, regardless of the @ref TidyOptionType. 804 ** @remark This is good setter if you are unsure of the type. 805 ** @result Returns a bool indicating success or failure. 806 */ 807 TIDY_EXPORT Bool TIDY_CALL tidyOptParseValue(TidyDoc tdoc, /**< The tidy document for which to set the value. */ 808 ctmbstr optnam, /**< The name of the option to set; this is the string value from the UI, e.g., `error-file`. */ 809 ctmbstr val /**< The value to set, as a string. */ 810 ); 811 812 /** Get current option value as an integer. 813 ** @result Returns the integer value of the specified option. 814 */ 815 TIDY_EXPORT ulong TIDY_CALL tidyOptGetInt(TidyDoc tdoc, /**< The tidy document for which to get the value. */ 816 TidyOptionId optId /**< The option ID to get. */ 817 ); 818 819 /** Set option value as an integer. 820 ** @result Returns a bool indicating success or failure. 821 */ 822 TIDY_EXPORT Bool TIDY_CALL tidyOptSetInt(TidyDoc tdoc, /**< The tidy document for which to set the value. */ 823 TidyOptionId optId, /**< The option ID to set. */ 824 ulong val /**< The value to set. */ 825 ); 826 827 /** Get current option value as a Boolean flag. 828 ** @result Returns a bool indicating the value. 829 */ 830 TIDY_EXPORT Bool TIDY_CALL tidyOptGetBool(TidyDoc tdoc, /**< The tidy document for which to get the value. */ 831 TidyOptionId optId /**< The option ID to get. */ 832 ); 833 834 /** Set option value as a Boolean flag. 835 ** @result Returns a bool indicating success or failure. 836 */ 837 TIDY_EXPORT Bool TIDY_CALL tidyOptSetBool(TidyDoc tdoc, /**< The tidy document for which to set the value. */ 838 TidyOptionId optId, /**< The option ID to set. */ 839 Bool val /**< The value to set. */ 840 ); 841 842 /** Reset option to default value by ID. 843 ** @result Returns a bool indicating success or failure. 844 */ 845 TIDY_EXPORT Bool TIDY_CALL tidyOptResetToDefault(TidyDoc tdoc, /**< The tidy document for which to reset the value. */ 846 TidyOptionId opt /**< The option ID to reset. */ 847 ); 848 849 /** Reset all options to their default values. 850 ** @param tdoc The tidy document for which to reset all values. 851 ** @result Returns a bool indicating success or failure. 852 */ 853 TIDY_EXPORT Bool TIDY_CALL tidyOptResetAllToDefault( TidyDoc tdoc ); 854 855 /** Take a snapshot of current config settings. These settings are stored 856 ** within the tidy document. Note, however, that snapshots do not reliably 857 ** survive the tidyParseXXX() process, as Tidy uses the snapshot mechanism 858 ** in order to store the current configuration right at the beginning of the 859 ** parsing process. 860 ** @param tdoc The tidy document for which to take a snapshot. 861 ** @result Returns a bool indicating success or failure. 862 */ 863 TIDY_EXPORT Bool TIDY_CALL tidyOptSnapshot( TidyDoc tdoc ); 864 865 /** Apply a snapshot of config settings to a document. 866 ** @param tdoc The tidy document for which to apply a snapshot. 867 ** @result Returns a bool indicating success or failure. 868 */ 869 TIDY_EXPORT Bool TIDY_CALL tidyOptResetToSnapshot( TidyDoc tdoc ); 870 871 /** Any settings different than default? 872 ** @param tdoc The tidy document to check. 873 ** @result Returns a bool indicating whether or not a difference exists. 874 */ 875 TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanDefault( TidyDoc tdoc ); 876 877 /** Any settings different than snapshot? 878 ** @param tdoc The tidy document to check. 879 ** @result Returns a bool indicating whether or not a difference exists. 880 */ 881 TIDY_EXPORT Bool TIDY_CALL tidyOptDiffThanSnapshot( TidyDoc tdoc ); 882 883 /** Copy current configuration settings from one document to another. Note 884 ** that the destination document's existing settings will be stored as that 885 ** document's snapshot prior to having its option values overwritten by the 886 ** source document's settings. 887 ** @result Returns a bool indicating success or failure. 888 */ 889 TIDY_EXPORT Bool TIDY_CALL tidyOptCopyConfig(TidyDoc tdocTo, /**< The destination tidy document. */ 890 TidyDoc tdocFrom /**< The source tidy document. */ 891 ); 892 893 /** Get character encoding name. Used with @ref TidyCharEncoding, 894 ** @ref TidyOutCharEncoding, and @ref TidyInCharEncoding. 895 ** @result The encoding name as a string for the specified option. 896 */ 897 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetEncName(TidyDoc tdoc, /**< The tidy document to query. */ 898 TidyOptionId optId /**< The option ID whose value to check. */ 899 ); 900 901 /** Get the current pick list value for the option ID, which can be useful for 902 ** enum types. 903 ** @result Returns a string indicating the current value of the specified 904 ** option. 905 */ 906 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetCurrPick(TidyDoc tdoc, /**< The tidy document to query. */ 907 TidyOptionId optId /**< The option ID whose value to check. */ 908 ); 909 910 /** Initiates an iterator for a list of user-declared tags, including autonomous 911 ** custom tags detected in the document if @ref TidyUseCustomTags is not set to 912 ** **no**. This iterator allows you to iterate through all of the custom tags. 913 ** In order to iterate through the tags, initiate the iterator with this 914 ** function, and then use tidyOptGetNextDeclTag() to retrieve the first and 915 ** subsequent tags. For example: 916 ** @code{.c} 917 ** TidyIterator itTag = tidyOptGetDeclTagList( tdoc ); 918 ** while ( itTag ) { 919 ** printf("%s", tidyOptGetNextDeclTag( tdoc, TidyBlockTags, &itTag )); 920 ** } 921 ** @endcode 922 ** @param tdoc An instance of a TidyDoc to query. 923 ** @result Returns a TidyIterator, which is a token used to represent the 924 ** current position in a list within LibTidy. 925 */ 926 TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDeclTagList( TidyDoc tdoc ); 927 928 /** Given a valid TidyIterator initiated with tidyOptGetDeclTagList(), returns a 929 ** string representing a user-declared or autonomous custom tag. 930 ** @remark Specifying optId limits the scope of the tags to one of 931 ** @ref TidyInlineTags, @ref TidyBlockTags, @ref TidyEmptyTags, or 932 ** @ref TidyPreTags. Note that autonomous custom tags (if used) are 933 ** added to one of these option types, depending on the value of 934 ** @ref TidyUseCustomTags. 935 ** @result A string containing the next tag. 936 */ 937 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextDeclTag(TidyDoc tdoc, /**< The tidy document to query. */ 938 TidyOptionId optId, /**< The option ID matching the type of tag to retrieve. */ 939 TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetDeclTagList()) token. */ 940 ); 941 942 /** Initiates an iterator for a list of priority attributes. This iterator 943 ** allows you to iterate through all of the priority attributes defined with 944 ** the `priority-attributes` configuration option. In order to iterate through 945 ** the attributes, initiate the iterator with this function, and then use 946 ** tidyOptGetNextPriorityAttr() to retrieve the first and subsequent attributes. 947 ** For example: 948 ** @code{.c} 949 ** TidyIterator itAttr = tidyOptGetPriorityAttrList( tdoc ); 950 ** while ( itAttr ) { 951 ** printf("%s", tidyOptGetNextPriorityAttr( tdoc, &itAttr )); 952 ** } 953 ** @endcode 954 ** @param tdoc An instance of a TidyDoc to query. 955 ** @result Returns a TidyIterator, which is a token used to represent the 956 ** current position in a list within LibTidy. 957 */ 958 TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetPriorityAttrList( TidyDoc tdoc ); 959 960 /** Given a valid TidyIterator initiated with tidyOptGetPriorityAttrList(), 961 ** returns a string representing a priority attribute. 962 ** @result A string containing the next tag. 963 */ 964 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextPriorityAttr(TidyDoc tdoc, /**< The tidy document to query. */ 965 TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetPriorityAttrList()) token. */ 966 ); 967 968 /** Initiates an iterator for a list of muted messages. This iterator allows 969 ** you to iterate through all of the priority attributes defined with the 970 ** `mute` configuration option. In order to iterate through the list, initiate 971 ** with this function, and then use tidyOptGetNextMutedMessage() to retrieve 972 ** the first and subsequent attributes. 973 ** For example: 974 ** @code{.c} 975 ** TidyIterator itAttr = tidyOptGetMutedMessageList( tdoc ); 976 ** while ( itAttr ) { 977 ** printf("%s", tidyOptGetNextMutedMessage( tdoc, &itAttr )); 978 ** } 979 ** @endcode 980 ** @param tdoc An instance of a TidyDoc to query. 981 ** @result Returns a TidyIterator, which is a token used to represent the 982 ** current position in a list within LibTidy. 983 */ 984 TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetMutedMessageList( TidyDoc tdoc ); 985 986 /** Given a valid TidyIterator initiated with tidyOptGetMutedMessageList(), 987 ** returns a string representing a muted message. 988 ** @result A string containing the next tag. 989 */ 990 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetNextMutedMessage(TidyDoc tdoc, /**< The tidy document to query. */ 991 TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetMutedMessageList()) token. */ 992 ); 993 994 /** @} 995 ** @name Option Documentation 996 ** @{ 997 */ 998 999 /** Get the description of the specified option. 1000 ** @result Returns a string containing a description of the given option. 1001 */ 1002 TIDY_EXPORT ctmbstr TIDY_CALL tidyOptGetDoc(TidyDoc tdoc, /**< The tidy document to query. */ 1003 TidyOption opt /**< The option ID of the option. */ 1004 ); 1005 1006 /** Initiates an iterator for a list of options related to a given option. This 1007 ** iterator allows you to iterate through all of the related options, if any. 1008 ** In order to iterate through the options, initiate the iterator with this 1009 ** function, and then use tidyOptGetNextDocLinks() to retrieve the first and 1010 ** subsequent options. For example: 1011 ** @code{.c} 1012 ** TidyIterator itOpt = tidyOptGetDocLinksList( tdoc, TidyJoinStyles ); 1013 ** while ( itOpt ) { 1014 ** TidyOption my_option = tidyOptGetNextDocLinks( tdoc, &itOpt ); 1015 ** // do something with my_option 1016 ** } 1017 ** @endcode 1018 ** @result Returns a TidyIterator, which is a token used to represent the 1019 ** current position in a list within LibTidy. 1020 */ 1021 TIDY_EXPORT TidyIterator TIDY_CALL tidyOptGetDocLinksList(TidyDoc tdoc, /**< The tidy document to query. */ 1022 TidyOption opt /**< The option whose related options you wish to find. */ 1023 ); 1024 1025 /** Given a valid TidyIterator initiated with tidyOptGetDocLinksList(), returns 1026 ** a TidyOption instance. 1027 ** @result Returns in instance of TidyOption. 1028 */ 1029 TIDY_EXPORT TidyOption TIDY_CALL tidyOptGetNextDocLinks(TidyDoc tdoc, /**< The tidy document to query. */ 1030 TidyIterator* pos /**< The TidyIterator (initiated with tidyOptGetDocLinksList()) token. */ 1031 ); 1032 1033 /** @} */ 1034 /** @} end Configuration group */ 1035 /* MARK: - I/O and Messages */ 1036 /***************************************************************************//** 1037 ** @defgroup IO I/O and Messages 1038 ** 1039 ** Tidy provides flexible I/O. By default, Tidy will define, create and use 1040 ** instances of input and output handlers for standard C buffered I/O (i.e., 1041 ** `FILE* stdin`, `FILE* stdout`, and `FILE* stderr` for content input, 1042 ** content output and diagnostic output, respectively. A `FILE* cfgFile` 1043 ** input handler will be used for config files. Command line options will 1044 ** just be set directly. 1045 ** 1046 ** @{ 1047 ******************************************************************************/ 1048 1049 /** @name Forward declarations and typedefs. 1050 ** @{ 1051 */ 1052 1053 TIDY_STRUCT struct _TidyBuffer; 1054 typedef struct _TidyBuffer TidyBuffer; 1055 1056 /** @} 1057 ** @name Input Source 1058 ** If you wish to write to your own input sources, then these types, structs, 1059 ** and functions will allow them to work seamlessly with Tidy. 1060 ** @{ 1061 */ 1062 1063 /** End of input "character" */ 1064 #define EndOfStream (~0u) 1065 1066 /** Input Callback: get next byte of input */ 1067 typedef int (TIDY_CALL *TidyGetByteFunc)( void* sourceData ); 1068 1069 /** Input Callback: unget a byte of input */ 1070 typedef void (TIDY_CALL *TidyUngetByteFunc)( void* sourceData, byte bt ); 1071 1072 /** Input Callback: is end of input? */ 1073 typedef Bool (TIDY_CALL *TidyEOFFunc)( void* sourceData ); 1074 1075 /** This type defines an input source capable of delivering raw bytes of input. 1076 */ 1077 TIDY_STRUCT 1078 typedef struct _TidyInputSource 1079 { 1080 void* sourceData; /**< Input context. Passed to callbacks. */ 1081 1082 TidyGetByteFunc getByte; /**< Pointer to "get byte" callback. */ 1083 TidyUngetByteFunc ungetByte; /**< Pointer to "unget" callback. */ 1084 TidyEOFFunc eof; /**< Pointer to "eof" callback. */ 1085 } TidyInputSource; 1086 1087 /** Facilitates user defined source by providing an entry point to marshal 1088 ** pointers-to-functions. This is needed by .NET, and possibly other language 1089 ** bindings. 1090 ** @result Returns a bool indicating success or failure. 1091 */ 1092 TIDY_EXPORT Bool TIDY_CALL tidyInitSource(TidyInputSource* source, /**< The source to populate with data. */ 1093 void* srcData, /**< The input context. */ 1094 TidyGetByteFunc gbFunc, /**< Pointer to the "get byte" callback. */ 1095 TidyUngetByteFunc ugbFunc, /**< Pointer to the "unget" callback. */ 1096 TidyEOFFunc endFunc /**< Pointer to the "eof" callback. */ 1097 ); 1098 1099 /** Helper: get next byte from input source. 1100 ** @param source A pointer to your input source. 1101 ** @result Returns a byte as an unsigned integer. 1102 */ 1103 TIDY_EXPORT uint TIDY_CALL tidyGetByte( TidyInputSource* source ); 1104 1105 /** Helper: unget byte back to input source. */ 1106 TIDY_EXPORT void TIDY_CALL tidyUngetByte(TidyInputSource* source, /**< The input source. */ 1107 uint byteValue /**< The byte to push back. */ 1108 ); 1109 1110 /** Helper: check if input source at end. 1111 ** @param source The input source. 1112 ** @result Returns a bool indicating whether or not the source is at EOF. 1113 */ 1114 TIDY_EXPORT Bool TIDY_CALL tidyIsEOF( TidyInputSource* source ); 1115 1116 /** @} 1117 ** @name Output Sink 1118 ** @{ 1119 */ 1120 1121 /** Output callback: send a byte to output */ 1122 typedef void (TIDY_CALL *TidyPutByteFunc)( void* sinkData, byte bt ); 1123 1124 /** This type defines an output destination capable of accepting raw bytes 1125 ** of output 1126 */ 1127 TIDY_STRUCT 1128 typedef struct _TidyOutputSink 1129 { 1130 void* sinkData; /**< Output context. Passed to callbacks. */ 1131 1132 TidyPutByteFunc putByte; /**< Pointer to "put byte" callback */ 1133 } TidyOutputSink; 1134 1135 /** Facilitates user defined sinks by providing an entry point to marshal 1136 ** pointers-to-functions. This is needed by .NET, and possibly other language 1137 ** bindings. 1138 ** @result Returns a bool indicating success or failure. 1139 */ 1140 TIDY_EXPORT Bool TIDY_CALL tidyInitSink(TidyOutputSink* sink, /**< The sink to populate with data. */ 1141 void* snkData, /**< The output context. */ 1142 TidyPutByteFunc pbFunc /**< Pointer to the "put byte" callback function. */ 1143 ); 1144 1145 /** Helper: send a byte to output. */ 1146 TIDY_EXPORT void TIDY_CALL tidyPutByte(TidyOutputSink* sink, /**< The output sink to send a byte. */ 1147 uint byteValue /**< The byte to be sent. */ 1148 ); 1149 1150 /** @} 1151 ** @name Emacs-compatible reporting support. 1152 ** If you work with Emacs and prefer Tidy's report output to be in a form 1153 ** that is easy for Emacs to parse, then these functions may be valuable. 1154 ** @{ 1155 */ 1156 1157 /** Set the file path to use for reports when `TidyEmacs` is being used. This 1158 ** function provides a proper interface for using the hidden, internal-only 1159 ** `TidyEmacsFile` configuration option. 1160 */ 1161 TIDY_EXPORT void TIDY_CALL tidySetEmacsFile(TidyDoc tdoc, /**< The tidy document for which you are setting the filePath. */ 1162 ctmbstr filePath /**< The path of the document that should be reported. */ 1163 ); 1164 1165 /** Get the file path to use for reports when `TidyEmacs` is being used. This 1166 ** function provides a proper interface for using the hidden, internal-only 1167 ** `TidyEmacsFile` configuration option. 1168 ** @param tdoc The tidy document for which you want to fetch the file path. 1169 ** @result Returns a string indicating the file path. 1170 */ 1171 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetEmacsFile( TidyDoc tdoc ); 1172 1173 /** @} 1174 ** @name Error Sink 1175 ** Send Tidy's output to any of several destinations with these functions. 1176 ** @{ 1177 */ 1178 1179 /** Set error sink to named file. 1180 ** @result Returns a file handle. 1181 */ 1182 TIDY_EXPORT FILE* TIDY_CALL tidySetErrorFile(TidyDoc tdoc, /**< The document to set. */ 1183 ctmbstr errfilnam /**< The file path to send output. */ 1184 ); 1185 1186 /** Set error sink to given buffer. 1187 ** @result Returns 0 upon success or a standard error number. 1188 */ 1189 TIDY_EXPORT int TIDY_CALL tidySetErrorBuffer(TidyDoc tdoc, /**< The document to set. */ 1190 TidyBuffer* errbuf /**< The TidyBuffer to collect output. */ 1191 ); 1192 1193 /** Set error sink to given generic sink. 1194 ** @result Returns 0 upon success or a standard error number. 1195 */ 1196 TIDY_EXPORT int TIDY_CALL tidySetErrorSink(TidyDoc tdoc, /**< The document to set. */ 1197 TidyOutputSink* sink /**< The TidyOutputSink to collect output. */ 1198 ); 1199 1200 /** @} 1201 ** @name Error and Message Callbacks - TidyReportFilter 1202 ** A simple callback to filter or collect messages by diagnostic level, 1203 ** for example, TidyInfo, TidyWarning, etc. Its name reflects its original 1204 ** purpose as a filter, by which your application can inform LibTidy whether 1205 ** or not to output a particular report. 1206 ** 1207 ** @{ 1208 */ 1209 1210 /** This typedef represents the required signature for your provided callback 1211 ** function should you wish to register one with tidySetReportFilter(). 1212 ** Your callback function will be provided with the following parameters. 1213 ** @param tdoc Indicates the tidy document the message comes from. 1214 ** @param lvl Specifies the TidyReportLevel of the message. 1215 ** @param line Indicates the line number in the source document the message applies to. 1216 ** @param col Indicates the column in the source document the message applies to. 1217 ** @param mssg Specifies the complete message as Tidy would emit it. 1218 ** @return Your callback function will return `yes` if Tidy should include the 1219 ** report in its own output sink, or `no` if Tidy should suppress it. 1220 */ 1221 typedef Bool (TIDY_CALL *TidyReportFilter)( TidyDoc tdoc, TidyReportLevel lvl, uint line, uint col, ctmbstr mssg ); 1222 1223 /** This function informs Tidy to use the specified callback to send reports. */ 1224 TIDY_EXPORT Bool TIDY_CALL tidySetReportFilter(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ 1225 TidyReportFilter filtCallback /**< A pointer to your callback function of type TidyReportFilter. */ 1226 ); 1227 1228 /** @} 1229 ** @name Error and Message Callbacks - TidyReportCallback 1230 ** A simple callback to filter or collect messages reported by Tidy. 1231 ** Unlike TidyReportFilter, more data are provided (including a `va_list`), 1232 ** making this callback suitable for applications that provide more 1233 ** sophisticated handling of reports. 1234 ** @remark The use of a `va_list` may preclude using this callback from 1235 ** non-C-like languages, which is uncharacteristic of Tidy. For more 1236 ** flexibility, consider using TidyMessageCallback instead. 1237 ** @note This callback was previously `TidyMessageFilter3` in older versions 1238 ** of LibTidy. 1239 ** @{ 1240 */ 1241 1242 /** This typedef represents the required signature for your provided callback 1243 ** function should you wish to register one with tidySetReportCallback(). 1244 ** Your callback function will be provided with the following parameters. 1245 ** @param tdoc Indicates the tidy document the message comes from. 1246 ** @param lvl Specifies the TidyReportLevel of the message. 1247 ** @param line Indicates the line number in the source document the message applies to. 1248 ** @param col Indicates the column in the source document the message applies to. 1249 ** @param code Specifies the message code representing the message. Note that 1250 ** this code is a string value that the API promises to hold constant, 1251 ** as opposed to an enum value that can change at any time. Although 1252 ** this is intended so that you can look up your own application's 1253 ** strings, you can retrieve Tidy's format string with this code by 1254 ** using tidyErrorCodeFromKey() and then the tidyLocalizedString() 1255 ** family of functions. 1256 ** @param args Is a `va_list` of arguments used to fill Tidy's message format string. 1257 ** @return Your callback function will return `yes` if Tidy should include the 1258 ** report in its own output sink, or `no` if Tidy should suppress it. 1259 */ 1260 typedef Bool (TIDY_CALL *TidyReportCallback)( TidyDoc tdoc, TidyReportLevel lvl, 1261 uint line, uint col, ctmbstr code, va_list args ); 1262 1263 /** This function informs Tidy to use the specified callback to send reports. */ 1264 TIDY_EXPORT Bool TIDY_CALL tidySetReportCallback(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ 1265 TidyReportCallback filtCallback /**< A pointer to your callback function of type TidyReportCallback. */ 1266 ); 1267 1268 /** @} 1269 ** @name Error and Message Callbacks - TidyMessageCallback 1270 ** A sophisticated and extensible callback to filter or collect messages 1271 ** reported by Tidy. It returns only an opaque type `TidyMessage` for every 1272 ** report and dialogue message, and this message can be queried with the 1273 ** TidyMessageCallback API, below. Note that unlike the older filters, this 1274 ** callback exposes *all* output that LibTidy emits (excluding the console 1275 ** application, which is a client of LibTidy). 1276 */ 1277 1278 /** This typedef represents the required signature for your provided callback 1279 ** function should you wish to register one with tidySetMessageCallback(). 1280 ** Your callback function will be provided with the following parameters. 1281 ** @param tmessage An opaque type used as a token against which other API 1282 ** calls can be made. 1283 ** @return Your callback function will return `yes` if Tidy should include the 1284 ** report in its own output sink, or `no` if Tidy should suppress it. 1285 */ 1286 typedef Bool (TIDY_CALL *TidyMessageCallback)( TidyMessage tmessage ); 1287 1288 /** This function informs Tidy to use the specified callback to send reports. */ 1289 TIDY_EXPORT Bool TIDY_CALL tidySetMessageCallback(TidyDoc tdoc, /**< The tidy document for which the callback applies. */ 1290 TidyMessageCallback filtCallback /**< A pointer to your callback function of type TidyMessageCallback. */ 1291 ); 1292 1293 /** @name TidyMessageCallback API 1294 ** When using `TidyMessageCallback` you will be supplied with a TidyMessage 1295 ** object, which is used as a token to be interrogated with the following 1296 ** API before the callback returns. 1297 ** @remark Upon returning from the callback, this object is destroyed so do 1298 ** not attempt to copy it, or keep it around, or use it in any way. 1299 ** 1300 ** @{ 1301 */ 1302 1303 /** Get the tidy document this message comes from. 1304 ** @param tmessage Specify the message that you are querying. 1305 ** @result Returns the TidyDoc that generated the message. 1306 */ 1307 TIDY_EXPORT TidyDoc TIDY_CALL tidyGetMessageDoc( TidyMessage tmessage ); 1308 1309 /** Get the message code. 1310 ** @param tmessage Specify the message that you are querying. 1311 ** @result Returns a code representing the message. This code can be used 1312 ** directly with the localized strings API; however we never make 1313 ** any guarantees about the value of these codes. For code stability 1314 ** don't store this value in your own application. Instead use the 1315 ** enum field or use the message key string value. 1316 */ 1317 TIDY_EXPORT uint TIDY_CALL tidyGetMessageCode( TidyMessage tmessage ); 1318 1319 /** Get the message key string. 1320 ** @param tmessage Specify the message that you are querying. 1321 ** @result Returns a string representing the message. This string is intended 1322 ** to be stable by the LibTidy API, and is suitable for use as a key 1323 ** in your own applications. 1324 */ 1325 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageKey( TidyMessage tmessage ); 1326 1327 /** Get the line number the message applies to. 1328 ** @param tmessage Specify the message that you are querying. 1329 ** @result Returns the line number, if any, that generated the message. 1330 */ 1331 TIDY_EXPORT int TIDY_CALL tidyGetMessageLine( TidyMessage tmessage ); 1332 1333 /** Get the column the message applies to. 1334 ** @param tmessage Specify the message that you are querying. 1335 ** @result Returns the column number, if any, that generated the message. 1336 */ 1337 TIDY_EXPORT int TIDY_CALL tidyGetMessageColumn( TidyMessage tmessage ); 1338 1339 /** Get the TidyReportLevel of the message. 1340 ** @param tmessage Specify the message that you are querying. 1341 ** @result Returns a TidyReportLevel indicating the severity or status of the 1342 ** message. 1343 */ 1344 TIDY_EXPORT TidyReportLevel TIDY_CALL tidyGetMessageLevel( TidyMessage tmessage ); 1345 1346 1347 /** Get the muted status of the message, that is, whether or not the 1348 ** current configuration indicated that this message should be muted. 1349 ** @param tmessage Specify the message that you are querying. 1350 ** @result Returns a Bool indicating that the config indicates muting this 1351 ** message. 1352 */ 1353 TIDY_EXPORT Bool TIDY_CALL tidyGetMessageIsMuted( TidyMessage tmessage ); 1354 1355 /** Get the default format string, which is the format string for the message 1356 ** in Tidy's default localization (en_us). 1357 ** @param tmessage Specify the message that you are querying. 1358 ** @result Returns the default localization format string of the message. 1359 */ 1360 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageFormatDefault( TidyMessage tmessage ); 1361 1362 /** Get the localized format string. If a localized version of the format string 1363 ** doesn't exist, then the default version will be returned. 1364 ** @param tmessage Specify the message that you are querying. 1365 ** @result Returns the localized format string of the message. 1366 */ 1367 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageFormat( TidyMessage tmessage ); 1368 1369 /** Get the message with the format string already completed, in Tidy's 1370 ** default localization. 1371 ** @param tmessage Specify the message that you are querying. 1372 ** @result Returns the message in the default localization. 1373 */ 1374 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageDefault( TidyMessage tmessage ); 1375 1376 /** Get the message with the format string already completed, in Tidy's 1377 ** current localization. 1378 ** @param tmessage Specify the message that you are querying. 1379 ** @result Returns the message in the current localization. 1380 */ 1381 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessage( TidyMessage tmessage ); 1382 1383 /** Get the position part part of the message in the default language. 1384 ** @param tmessage Specify the message that you are querying. 1385 ** @result Returns the positional part of a string as Tidy would display it 1386 ** in the console application. 1387 */ 1388 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePosDefault( TidyMessage tmessage ); 1389 1390 /** Get the position part part of the message in the current language. 1391 ** @param tmessage Specify the message that you are querying. 1392 ** @result Returns the positional part of a string as Tidy would display it 1393 ** in the console application. 1394 */ 1395 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePos( TidyMessage tmessage ); 1396 1397 /** Get the prefix part of a message in the default language. 1398 ** @param tmessage Specify the message that you are querying. 1399 ** @result Returns the message prefix part of a string as Tidy would display 1400 ** it in the console application. 1401 */ 1402 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePrefixDefault( TidyMessage tmessage ); 1403 1404 /** Get the prefix part of a message in the current language. 1405 ** @param tmessage Specify the message that you are querying. 1406 ** @result Returns the message prefix part of a string as Tidy would display 1407 ** it in the console application. 1408 */ 1409 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessagePrefix( TidyMessage tmessage ); 1410 1411 /** Get the complete message as Tidy would emit it in the default localization. 1412 ** @param tmessage Specify the message that you are querying. 1413 ** @result Returns the complete message just as Tidy would display it on the 1414 ** console. 1415 */ 1416 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageOutputDefault( TidyMessage tmessage ); 1417 1418 /** Get the complete message as Tidy would emit it in the current localization. 1419 ** @param tmessage Specify the message that you are querying. 1420 ** @result Returns the complete message just as Tidy would display it on the 1421 ** console. 1422 */ 1423 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetMessageOutput( TidyMessage tmessage ); 1424 1425 /** @} end subgroup TidyMessageCallback API */ 1426 1427 /** @name TidyMessageCallback Arguments API 1428 ** When using `TidyMessageCallback` you will be supplied with a TidyMessage 1429 ** object which can be used as a token against which to query using this API. 1430 ** This API deals strictly with _arguments_ that a message may or may not have; 1431 ** these are the same arguments that Tidy would apply to a format string in 1432 ** order to fill in the placeholder fields and deliver a complete report or 1433 ** dialogue string to you. 1434 ** 1435 ** @{ 1436 */ 1437 1438 /** Initiates an iterator for a list of arguments related to a given message. 1439 ** This iterator allows you to iterate through all of the arguments, if any. 1440 ** In order to iterate through the arguments, initiate the iterator with this 1441 ** function, and then use tidyGetNextMessageArgument() to retrieve the first 1442 ** and subsequent arguments. For example: 1443 ** @code{.c} 1444 ** TidyIterator itArg = tidyGetMessageArguments( tmessage ); 1445 ** while ( itArg ) { 1446 ** TidyMessageArgument my_arg = tidyGetNextMessageArgument( tmessage, &itArg ); 1447 ** // do something with my_arg, such as inspect its value or format 1448 ** } 1449 ** @endcode 1450 ** @param tmessage The message about whose arguments you wish to query. 1451 ** @result Returns a TidyIterator, which is a token used to represent the 1452 ** current position in a list within LibTidy. 1453 */ 1454 TIDY_EXPORT TidyIterator TIDY_CALL tidyGetMessageArguments( TidyMessage tmessage ); 1455 1456 /** Given a valid TidyIterator initiated with tidyGetMessageArguments(), returns 1457 ** an instance of the opaque type TidyMessageArgument, which serves as a token 1458 ** against which the remaining argument API functions may be used to query 1459 ** information. 1460 ** @result Returns an instance of TidyMessageArgument. 1461 */ 1462 TIDY_EXPORT TidyMessageArgument TIDY_CALL tidyGetNextMessageArgument(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1463 TidyIterator* iter /**< The TidyIterator (initiated with tidyOptGetDocLinksList()) token. */ 1464 ); 1465 1466 /** Returns the `TidyFormatParameterType` of the given message argument. 1467 ** @result Returns the type of parameter of type TidyFormatParameterType. 1468 */ 1469 TIDY_EXPORT TidyFormatParameterType TIDY_CALL tidyGetArgType(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1470 TidyMessageArgument* arg /**< The argument that you are querying. */ 1471 ); 1472 1473 /** Returns the format specifier of the given message argument. The memory for 1474 ** this string is cleared upon termination of the callback, so do be sure to 1475 ** make your own copy. 1476 ** @result Returns the format specifier string of the given argument. 1477 */ 1478 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgFormat(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1479 TidyMessageArgument* arg /**< The argument that you are querying. */ 1480 ); 1481 1482 /** Returns the string value of the given message argument. An assertion 1483 ** will be generated if the argument type is not a string. 1484 ** @result Returns the string value of the given argument. 1485 */ 1486 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetArgValueString(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1487 TidyMessageArgument* arg /**< The argument that you are querying. */ 1488 ); 1489 1490 /** Returns the unsigned integer value of the given message argument. An 1491 ** assertion will be generated if the argument type is not an unsigned int. 1492 ** @result Returns the unsigned integer value of the given argument. 1493 */ 1494 TIDY_EXPORT uint TIDY_CALL tidyGetArgValueUInt(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1495 TidyMessageArgument* arg /**< The argument that you are querying. */ 1496 ); 1497 1498 /** Returns the integer value of the given message argument. An assertion 1499 ** will be generated if the argument type is not an integer. 1500 ** @result Returns the integer value of the given argument. 1501 */ 1502 TIDY_EXPORT int TIDY_CALL tidyGetArgValueInt(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1503 TidyMessageArgument* arg /**< The argument that you are querying. */ 1504 ); 1505 1506 /** 1507 * Returns the double value of the given message argument. An assertion 1508 * will be generated if the argument type is not a double. 1509 ** @result Returns the double value of the given argument. 1510 */ 1511 TIDY_EXPORT double TIDY_CALL tidyGetArgValueDouble(TidyMessage tmessage, /**< The message whose arguments you want to access. */ 1512 TidyMessageArgument* arg /**< The argument that you are querying. */ 1513 ); 1514 1515 /** @} end subgroup TidyMessageCallback Arguments API */ 1516 1517 /** @name Printing 1518 ** LibTidy applications can somewhat track the progress of the tidying process 1519 ** by using this provided callback. It relates where something in the source 1520 ** document ended up in the output. 1521 ** @{ 1522 */ 1523 1524 /** This typedef represents the required signature for your provided callback 1525 ** function should you wish to register one with tidySetMessageCallback(). 1526 ** Your callback function will be provided with the following parameters. 1527 ** @param tdoc Indicates the source tidy document. 1528 ** @param line Indicates the line in the source document at this point in the process. 1529 ** @param col Indicates the column in the source document at this point in the process. 1530 ** @param destLine Indicates the line number in the output document at this point in the process. 1531 */ 1532 typedef void (TIDY_CALL *TidyPPProgress)( TidyDoc tdoc, uint line, uint col, uint destLine ); 1533 1534 /** This function informs Tidy to use the specified callback for tracking the 1535 ** pretty-printing process progress. 1536 */ 1537 TIDY_EXPORT Bool TIDY_CALL tidySetPrettyPrinterCallback(TidyDoc tdoc, 1538 TidyPPProgress callback 1539 ); 1540 1541 /** @} */ 1542 /** @} end IO group */ 1543 /* MARK: - Document Parse */ 1544 /***************************************************************************//** 1545 ** @defgroup Parse Document Parse 1546 ** 1547 ** Functions for parsing markup from a given input source, as well as string 1548 ** and filename functions for added convenience. HTML/XHTML version determined 1549 ** from input. 1550 ** 1551 ** @{ 1552 ******************************************************************************/ 1553 1554 /** Parse markup in named file. 1555 ** @result Returns the highest of `2` indicating that errors were present in 1556 ** the document, `1` indicating warnings, and `0` in the case of 1557 ** everything being okay. 1558 */ 1559 TIDY_EXPORT int TIDY_CALL tidyParseFile(TidyDoc tdoc, /**< The tidy document to use for parsing. */ 1560 ctmbstr filename /**< The filename to parse. */ 1561 ); 1562 1563 /** Parse markup from the standard input. 1564 ** @param tdoc The tidy document to use for parsing. 1565 ** @result Returns the highest of `2` indicating that errors were present in 1566 ** the document, `1` indicating warnings, and `0` in the case of 1567 ** everything being okay. 1568 */ 1569 TIDY_EXPORT int TIDY_CALL tidyParseStdin( TidyDoc tdoc ); 1570 1571 /** Parse markup in given string. Note that the supplied string is of type 1572 ** `ctmbstr` based on `char` and therefore doesn't support the use of 1573 ** UTF-16 strings. Use `tidyParseBuffer()` if parsing multibyte strings. 1574 ** @result Returns the highest of `2` indicating that errors were present in 1575 ** the document, `1` indicating warnings, and `0` in the case of 1576 ** everything being okay. 1577 */ 1578 TIDY_EXPORT int TIDY_CALL tidyParseString(TidyDoc tdoc, /**< The tidy document to use for parsing. */ 1579 ctmbstr content /**< The string to parse. */ 1580 ); 1581 1582 /** Parse markup in given buffer. 1583 ** @result Returns the highest of `2` indicating that errors were present in 1584 ** the document, `1` indicating warnings, and `0` in the case of 1585 ** everything being okay. 1586 */ 1587 TIDY_EXPORT int TIDY_CALL tidyParseBuffer(TidyDoc tdoc, /**< The tidy document to use for parsing. */ 1588 TidyBuffer* buf /**< The TidyBuffer containing data to parse. */ 1589 ); 1590 1591 /** Parse markup in given generic input source. 1592 ** @result Returns the highest of `2` indicating that errors were present in 1593 ** the document, `1` indicating warnings, and `0` in the case of 1594 ** everything being okay. 1595 */ 1596 TIDY_EXPORT int TIDY_CALL tidyParseSource(TidyDoc tdoc, /**< The tidy document to use for parsing. */ 1597 TidyInputSource* source /**< A TidyInputSource containing data to parse. */ 1598 ); 1599 1600 1601 /** @} End Parse group */ 1602 /* MARK: - Diagnostics and Repair */ 1603 /***************************************************************************//** 1604 ** @defgroup Clean Diagnostics and Repair 1605 ** 1606 ** After parsing the document, you can use these functions to attempt cleanup, 1607 ** repair, get additional diagnostics, and determine the document type. 1608 ** @{ 1609 ******************************************************************************/ 1610 1611 /** Execute configured cleanup and repair operations on parsed markup. 1612 ** @param tdoc The tidy document to use. 1613 ** @result An integer representing the status. 1614 */ 1615 TIDY_EXPORT int TIDY_CALL tidyCleanAndRepair( TidyDoc tdoc ); 1616 1617 /** Reports the document type and diagnostic statistics on parsed and repaired 1618 ** markup. You must call tidyCleanAndRepair() before using this function. 1619 ** @param tdoc The tidy document to use. 1620 ** @result An integer representing the status. 1621 */ 1622 TIDY_EXPORT int TIDY_CALL tidyRunDiagnostics( TidyDoc tdoc ); 1623 1624 /** Reports the document type into the output sink. 1625 ** @param tdoc The tidy document to use. 1626 ** @result An integer representing the status. 1627 */ 1628 TIDY_EXPORT int TIDY_CALL tidyReportDoctype( TidyDoc tdoc ); 1629 1630 1631 /** @} end Clean group */ 1632 /* MARK: - Document Save Functions */ 1633 /***************************************************************************//** 1634 ** @defgroup Save Document Save Functions 1635 ** 1636 ** Save currently parsed document to the given output sink. File name 1637 ** and string/buffer functions provided for convenience. 1638 ** 1639 ** @{ 1640 ******************************************************************************/ 1641 1642 /** Save the tidy document to the named file. 1643 ** @result An integer representing the status. 1644 */ 1645 TIDY_EXPORT int TIDY_CALL tidySaveFile(TidyDoc tdoc, /**< The tidy document to save. */ 1646 ctmbstr filename /**< The destination file name. */ 1647 ); 1648 1649 /** Save the tidy document to standard output (FILE*). 1650 ** @param tdoc The tidy document to save. 1651 ** @result An integer representing the status. 1652 */ 1653 TIDY_EXPORT int TIDY_CALL tidySaveStdout( TidyDoc tdoc ); 1654 1655 /** Save the tidy document to given TidyBuffer object. 1656 ** @result An integer representing the status. 1657 */ 1658 TIDY_EXPORT int TIDY_CALL tidySaveBuffer(TidyDoc tdoc, /**< The tidy document to save. */ 1659 TidyBuffer* buf /**< The buffer to place the output. */ 1660 ); 1661 1662 /** Save the tidy document to an application buffer. If TidyShowMarkup and the 1663 ** document has no errors, or TidyForceOutput, then the current document (per 1664 ** the current configuration) will be pretty printed to this application 1665 ** buffer. The document byte length (not character length) will be placed into 1666 ** *buflen. The document will not be null terminated. If the buffer is not big 1667 ** enough, ENOMEM will be returned, else the actual document status. 1668 ** @result An integer representing the status. 1669 */ 1670 TIDY_EXPORT int TIDY_CALL tidySaveString(TidyDoc tdoc, /**< The tidy document to save. */ 1671 tmbstr buffer, /**< The buffer to save to. */ 1672 uint* buflen /**< [out] The byte length written. */ 1673 ); 1674 1675 /** Save to given generic output sink. 1676 ** @result An integer representing the status. 1677 */ 1678 TIDY_EXPORT int TIDY_CALL tidySaveSink(TidyDoc tdoc, /**< The tidy document to save. */ 1679 TidyOutputSink* sink /**< The output sink to save to. */ 1680 ); 1681 1682 /** Save current settings to named file. Only writes non-default values. 1683 ** @result An integer representing the status. 1684 */ 1685 TIDY_EXPORT int TIDY_CALL tidyOptSaveFile(TidyDoc tdoc, /**< The tidy document to save. */ 1686 ctmbstr cfgfil /**< The filename to save the configuration to. */ 1687 ); 1688 1689 /** Save current settings to given output sink. Only non-default values are 1690 ** written. 1691 ** @result An integer representing the status. 1692 */ 1693 TIDY_EXPORT int TIDY_CALL tidyOptSaveSink(TidyDoc tdoc, /**< The tidy document to save. */ 1694 TidyOutputSink* sink /**< The output sink to save the configuration to. */ 1695 ); 1696 1697 1698 /** @} end Save group */ 1699 /* MARK: - Document Tree */ 1700 /***************************************************************************//** 1701 ** @defgroup Tree Document Tree 1702 ** 1703 ** A parsed (and optionally repaired) document is represented by Tidy as a 1704 ** tree, much like a W3C DOM. This tree may be traversed using these 1705 ** functions. The following snippet gives a basic idea how these functions 1706 ** can be used. 1707 ** 1708 ** @code{.c} 1709 ** void dumpNode( TidyNode tnod, int indent ) { 1710 ** TidyNode child; 1711 ** 1712 ** for ( child = tidyGetChild(tnod); child; child = tidyGetNext(child) ) { 1713 ** ctmbstr name; 1714 ** switch ( tidyNodeGetType(child) ) { 1715 ** case TidyNode_Root: name = "Root"; break; 1716 ** case TidyNode_DocType: name = "DOCTYPE"; break; 1717 ** case TidyNode_Comment: name = "Comment"; break; 1718 ** case TidyNode_ProcIns: name = "Processing Instruction"; break; 1719 ** case TidyNode_Text: name = "Text"; break; 1720 ** case TidyNode_CDATA: name = "CDATA"; break; 1721 ** case TidyNode_Section: name = "XML Section"; break; 1722 ** case TidyNode_Asp: name = "ASP"; break; 1723 ** case TidyNode_Jste: name = "JSTE"; break; 1724 ** case TidyNode_Php: name = "PHP"; break; 1725 ** case TidyNode_XmlDecl: name = "XML Declaration"; break; 1726 ** 1727 ** case TidyNode_Start: 1728 ** case TidyNode_End: 1729 ** case TidyNode_StartEnd: 1730 ** default: 1731 ** name = tidyNodeGetName( child ); 1732 ** break; 1733 ** } 1734 ** assert( name != NULL ); 1735 ** printf( "\%*.*sNode: \%s\\n", indent, indent, " ", name ); 1736 ** dumpNode( child, indent + 4 ); 1737 ** } 1738 ** } 1739 ** 1740 ** void dumpDoc( TidyDoc tdoc ) { 1741 ** dumpNode( tidyGetRoot(tdoc), 0 ); 1742 ** } 1743 ** 1744 ** void dumpBody( TidyDoc tdoc ) { 1745 ** dumpNode( tidyGetBody(tdoc), 0 ); 1746 ** } 1747 ** @endcode 1748 ** 1749 ** @{ 1750 ******************************************************************************/ 1751 1752 /** @name Nodes for Document Sections 1753 ** @{ 1754 */ 1755 1756 /** Get the root node. 1757 ** @param tdoc The document to query. 1758 ** @result Returns a tidy node. 1759 */ 1760 TIDY_EXPORT TidyNode TIDY_CALL tidyGetRoot( TidyDoc tdoc ); 1761 1762 /** Get the HTML node. 1763 ** @param tdoc The document to query. 1764 ** @result Returns a tidy node. 1765 */ 1766 TIDY_EXPORT TidyNode TIDY_CALL tidyGetHtml( TidyDoc tdoc ); 1767 1768 /** Get the HEAD node. 1769 ** @param tdoc The document to query. 1770 ** @result Returns a tidy node. 1771 */ 1772 TIDY_EXPORT TidyNode TIDY_CALL tidyGetHead( TidyDoc tdoc ); 1773 1774 /** Get the BODY node. 1775 ** @param tdoc The document to query. 1776 ** @result Returns a tidy node. 1777 */ 1778 TIDY_EXPORT TidyNode TIDY_CALL tidyGetBody( TidyDoc tdoc ); 1779 1780 /** @} 1781 ** @name Relative Nodes 1782 ** @{ 1783 */ 1784 1785 /** Get the parent of the indicated node. 1786 ** @param tnod The node to query. 1787 ** @result Returns a tidy node. 1788 */ 1789 TIDY_EXPORT TidyNode TIDY_CALL tidyGetParent( TidyNode tnod ); 1790 1791 /** Get the child of the indicated node. 1792 ** @param tnod The node to query. 1793 ** @result Returns a tidy node. 1794 */ 1795 TIDY_EXPORT TidyNode TIDY_CALL tidyGetChild( TidyNode tnod ); 1796 1797 /** Get the next sibling node. 1798 ** @param tnod The node to query. 1799 ** @result Returns a tidy node. 1800 */ 1801 TIDY_EXPORT TidyNode TIDY_CALL tidyGetNext( TidyNode tnod ); 1802 1803 /** Get the previous sibling node. 1804 ** @param tnod The node to query. 1805 ** @result Returns a tidy node. 1806 */ 1807 TIDY_EXPORT TidyNode TIDY_CALL tidyGetPrev( TidyNode tnod ); 1808 1809 /** @} 1810 ** @name Miscellaneous Node Functions 1811 ** @{ 1812 */ 1813 1814 /** Remove the indicated node. 1815 ** @result Returns the next tidy node. 1816 */ 1817 TIDY_EXPORT TidyNode TIDY_CALL tidyDiscardElement(TidyDoc tdoc, /**< The tidy document from which to remove the node. */ 1818 TidyNode tnod /**< The node to remove */ 1819 ); 1820 1821 /** @} 1822 ** @name Node Attribute Functions 1823 ** @{ 1824 */ 1825 1826 /** Get the first attribute. 1827 ** @param tnod The node for which to get attributes. 1828 ** @result Returns an instance of TidyAttr. 1829 */ 1830 TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrFirst( TidyNode tnod ); 1831 1832 /** Get the next attribute. 1833 ** @param tattr The current attribute, so the next one can be returned. 1834 ** @result Returns and instance of TidyAttr. 1835 */ 1836 TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrNext( TidyAttr tattr ); 1837 1838 /** Get the name of a TidyAttr instance. 1839 ** @param tattr The tidy attribute to query. 1840 ** @result Returns a string indicating the name of the attribute. 1841 */ 1842 TIDY_EXPORT ctmbstr TIDY_CALL tidyAttrName( TidyAttr tattr ); 1843 1844 /** Get the value of a TidyAttr instance. 1845 ** @param tattr The tidy attribute to query. 1846 ** @result Returns a string indicating the value of the attribute. 1847 */ 1848 TIDY_EXPORT ctmbstr TIDY_CALL tidyAttrValue( TidyAttr tattr ); 1849 1850 /** Discard an attribute. */ 1851 TIDY_EXPORT void TIDY_CALL tidyAttrDiscard(TidyDoc itdoc, /**< The tidy document from which to discard the attribute. */ 1852 TidyNode tnod, /**< The node from which to discard the attribute. */ 1853 TidyAttr tattr /**< The attribute to discard. */ 1854 ); 1855 1856 /** Get the attribute ID given a tidy attribute. 1857 ** @param tattr The attribute to query. 1858 ** @result Returns the TidyAttrId of the given attribute. 1859 **/ 1860 TIDY_EXPORT TidyAttrId TIDY_CALL tidyAttrGetId( TidyAttr tattr ); 1861 1862 /** Indicates whether or not a given attribute is an event attribute. 1863 ** @param tattr The attribute to query. 1864 ** @result Returns a bool indicating whether or not the attribute is an event. 1865 **/ 1866 TIDY_EXPORT Bool TIDY_CALL tidyAttrIsEvent( TidyAttr tattr ); 1867 1868 /** Get an instance of TidyAttr by specifying an attribute ID. 1869 ** @result Returns a TidyAttr instance. 1870 */ 1871 TIDY_EXPORT TidyAttr TIDY_CALL tidyAttrGetById(TidyNode tnod, /**< The node to query. */ 1872 TidyAttrId attId /**< The attribute ID to find. */ 1873 ); 1874 1875 /** @} 1876 ** @name Additional Node Interrogation 1877 ** @{ 1878 */ 1879 1880 /** Get the type of node. 1881 ** @param tnod The node to query. 1882 ** @result Returns the type of node as TidyNodeType. 1883 */ 1884 TIDY_EXPORT TidyNodeType TIDY_CALL tidyNodeGetType( TidyNode tnod ); 1885 1886 /** Get the name of the node. 1887 ** @param tnod The node to query. 1888 ** @result Returns a string indicating the name of the node. 1889 */ 1890 TIDY_EXPORT ctmbstr TIDY_CALL tidyNodeGetName( TidyNode tnod ); 1891 1892 /** Indicates whether or not a node is a text node. 1893 ** @param tnod The node to query. 1894 ** @result Returns a bool indicating whether or not the node is a text node. 1895 */ 1896 TIDY_EXPORT Bool TIDY_CALL tidyNodeIsText( TidyNode tnod ); 1897 1898 /** Indicates whether or not the node is a propriety type. 1899 ** @result Returns a bool indicating whether or not the node is a proprietary type. 1900 */ 1901 TIDY_EXPORT Bool TIDY_CALL tidyNodeIsProp(TidyDoc tdoc, /**< The document to query. */ 1902 TidyNode tnod /**< The node to query */ 1903 ); 1904 1905 /** Indicates whether or not a node represents and HTML header element, such 1906 ** as h1, h2, etc. 1907 ** @param tnod The node to query. 1908 ** @result Returns a bool indicating whether or not the node is an HTML header. 1909 */ 1910 TIDY_EXPORT Bool TIDY_CALL tidyNodeIsHeader( TidyNode tnod ); 1911 1912 /** Indicates whether or not the node has text. 1913 ** @result Returns the type of node as TidyNodeType. 1914 */ 1915 TIDY_EXPORT Bool TIDY_CALL tidyNodeHasText(TidyDoc tdoc, /**< The document to query. */ 1916 TidyNode tnod /**< The node to query. */ 1917 ); 1918 1919 /** Gets the text of a node and places it into the given TidyBuffer. The text will be terminated with a `TidyNewline`. 1920 ** If you want the raw utf-8 stream see `tidyNodeGetValue()`. 1921 ** @result Returns a bool indicating success or not. 1922 */ 1923 TIDY_EXPORT Bool TIDY_CALL tidyNodeGetText(TidyDoc tdoc, /**< The document to query. */ 1924 TidyNode tnod, /**< The node to query. */ 1925 TidyBuffer* buf /**< [out] A TidyBuffer used to receive the node's text. */ 1926 ); 1927 1928 /** Get the value of the node. This copies the unescaped value of this node into 1929 ** the given TidyBuffer at UTF-8. 1930 ** @result Returns a bool indicating success or not. 1931 */ 1932 TIDY_EXPORT Bool TIDY_CALL tidyNodeGetValue(TidyDoc tdoc, /**< The document to query */ 1933 TidyNode tnod, /**< The node to query */ 1934 TidyBuffer* buf /**< [out] A TidyBuffer used to receive the node's value. */ 1935 ); 1936 1937 /** Get the tag ID of the node. 1938 ** @param tnod The node to query. 1939 ** @result Returns the tag ID of the node as TidyTagId. 1940 */ 1941 TIDY_EXPORT TidyTagId TIDY_CALL tidyNodeGetId( TidyNode tnod ); 1942 1943 /** Get the line number where the node occurs. 1944 ** @param tnod The node to query. 1945 ** @result Returns the line number. 1946 */ 1947 TIDY_EXPORT uint TIDY_CALL tidyNodeLine( TidyNode tnod ); 1948 1949 /** Get the column location of the node. 1950 ** @param tnod The node to query. 1951 ** @result Returns the column location of the node. 1952 */ 1953 TIDY_EXPORT uint TIDY_CALL tidyNodeColumn( TidyNode tnod ); 1954 1955 1956 /** @} */ 1957 /** @} end Tree group */ 1958 /* MARK: - Message Key Management */ 1959 /***************************************************************************//** 1960 ** @defgroup MessagesKeys Message Key Management 1961 ** 1962 ** These functions serve to manage message codes, i.e., codes that are used 1963 ** Tidy and communicated via its callback filters to represent reports and 1964 ** dialogue that Tidy emits. 1965 ** 1966 ** @remark These codes only reflect complete messages, and are specifically 1967 ** distinct from the internal codes that are used to lookup individual 1968 ** strings for localization purposes. 1969 ** 1970 ** @{ 1971 ******************************************************************************/ 1972 1973 /** 1974 ** Given a message code, return the text key that represents it. 1975 ** @param code The error code to lookup. 1976 ** @result The string representing the error code. 1977 */ 1978 TIDY_EXPORT ctmbstr TIDY_CALL tidyErrorCodeAsKey(uint code); 1979 1980 /** 1981 ** Given a text key representing a message code, return the uint that 1982 ** represents it. 1983 ** 1984 ** @remark We establish that for external purposes, the API will ensure that 1985 ** string keys remain consistent. *Never* count on the integer value 1986 ** of a message code. Always use this function to ensure that the 1987 ** integer is valid if you need one. 1988 ** @param code The string representing the error code. 1989 ** @result Returns an integer that represents the error code, which can be 1990 ** used to lookup Tidy's built-in strings. If the provided string does 1991 ** not have a matching message code, then UINT_MAX will be returned. 1992 */ 1993 TIDY_EXPORT uint TIDY_CALL tidyErrorCodeFromKey(ctmbstr code); 1994 1995 /** Initiates an iterator for a list of message codes available in Tidy. 1996 ** This iterator allows you to iterate through all of the code. In orde to 1997 ** iterate through the codes, initiate the iterator with this function, and 1998 ** then use getNextErrorCode() to retrieve the first and subsequent codes. 1999 ** For example: 2000 ** @code{.c} 2001 ** TidyIterator itMessage = getErrorCodeList(); 2002 ** while ( itMessage ) { 2003 ** uint code = getNextErrorCode( &itMessage ); 2004 ** // do something with the code, such as lookup a string. 2005 ** } 2006 ** @endcode 2007 ** @result Returns a TidyIterator, which is a token used to represent the 2008 ** current position in a list within LibTidy. 2009 */ 2010 TIDY_EXPORT TidyIterator TIDY_CALL getErrorCodeList(void); 2011 2012 /** Given a valid TidyIterator initiated with getErrorCodeList(), returns 2013 ** an instance of the opaque type TidyMessageArgument, which serves as a token 2014 ** against which the remaining argument API functions may be used to query 2015 ** information. 2016 ** @param iter The TidyIterator (initiated with getErrorCodeList()) token. 2017 ** @result Returns a message code. 2018 */ 2019 TIDY_EXPORT uint TIDY_CALL getNextErrorCode( TidyIterator* iter ); 2020 2021 2022 /** @} end MessagesKeys group */ 2023 /* MARK: - Localization Support */ 2024 /***************************************************************************//** 2025 ** @defgroup Localization Localization Support 2026 ** 2027 ** These functions help manage localization in Tidy. 2028 ** 2029 ** @{ 2030 ******************************************************************************/ 2031 2032 2033 /** @name Tidy's Locale 2034 ** @{ 2035 */ 2036 2037 /** Tells Tidy to use a different language for output. 2038 ** @param languageCode A Windows or POSIX language code, and must match 2039 ** a TIDY_LANGUAGE for an installed language. 2040 ** @result Indicates that a setting was applied, but not necessarily the 2041 ** specific request, i.e., true indicates a language and/or region 2042 ** was applied. If es_mx is requested but not installed, and es is 2043 ** installed, then es will be selected and this function will return 2044 ** true. However the opposite is not true; if es is requested but 2045 ** not present, Tidy will not try to select from the es_XX variants. 2046 */ 2047 TIDY_EXPORT Bool TIDY_CALL tidySetLanguage( ctmbstr languageCode ); 2048 2049 /** Gets the current language used by Tidy. 2050 ** @result Returns a string indicating the currently set language. 2051 */ 2052 TIDY_EXPORT ctmbstr TIDY_CALL tidyGetLanguage(void); 2053 2054 /** @} 2055 ** @name Locale Mappings 2056 ** @{ 2057 */ 2058 2059 /** @struct tidyLocaleMapItem 2060 ** Represents an opaque type we can use for tidyLocaleMapItem, which 2061 ** is used to iterate through the language list, and used to access 2062 ** the windowsName() and the posixName(). 2063 */ 2064 /* Prevent Doxygen from listing this as a function. */ 2065 #ifndef DOXYGEN_SHOULD_SKIP_THIS 2066 opaque_type(tidyLocaleMapItem); 2067 #endif 2068 2069 /** Initiates an iterator for a list of Tidy's Windows<->POSIX locale mappings. 2070 ** This iterator allows you to iterate through this list. In order to 2071 ** iterate through the list, initiate the iterator with this function, and then 2072 ** use getNextWindowsLanguage() to retrieve the first and subsequent codes. 2073 ** For example: 2074 ** @code{.c} 2075 ** TidyIterator itList = getWindowsLanguageList(); 2076 ** while ( itList ) { 2077 ** tidyLocaleMapItem *item = getNextWindowsLanguage( &itList ); 2078 ** // do something such as get the TidyLangWindowsName(item). 2079 ** } 2080 ** @endcode 2081 ** @result Returns a TidyIterator, which is a token used to represent the 2082 ** current position in a list within LibTidy. 2083 */ 2084 TIDY_EXPORT TidyIterator TIDY_CALL getWindowsLanguageList(void); 2085 2086 /** Given a valid TidyIterator initiated with getWindowsLanguageList(), returns 2087 ** a pointer to a tidyLocaleMapItem, which can be further interrogated with 2088 ** TidyLangWindowsName() or TidyLangPosixName(). 2089 ** @param iter The TidyIterator (initiated with getWindowsLanguageList()) token. 2090 ** @result Returns a pointer to a tidyLocaleMapItem. 2091 */ 2092 TIDY_EXPORT const tidyLocaleMapItem* TIDY_CALL getNextWindowsLanguage( TidyIterator* iter ); 2093 2094 /** Given a `tidyLocaleMapItem`, return the Windows name. 2095 ** @param item An instance of tidyLocaleMapItem to query. 2096 ** @result Returns a string with the Windows name of the mapping. 2097 */ 2098 TIDY_EXPORT ctmbstr TIDY_CALL TidyLangWindowsName( const tidyLocaleMapItem *item ); 2099 2100 /** Given a `tidyLocaleMapItem`, return the POSIX name. 2101 ** @param item An instance of tidyLocaleMapItem to query. 2102 ** @result Returns a string with the POSIX name of the mapping. 2103 */ 2104 TIDY_EXPORT ctmbstr TIDY_CALL TidyLangPosixName( const tidyLocaleMapItem *item ); 2105 2106 /** @} 2107 ** @name Getting Localized Strings 2108 ** @{ 2109 */ 2110 2111 /** Provides a string given `messageType` in the current localization for 2112 ** `quantity`. Some strings have one or more plural forms, and this function 2113 ** will ensure that the correct singular or plural form is returned for the 2114 ** specified quantity. 2115 ** @result Returns the desired string. 2116 */ 2117 TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedStringN(uint messageType, /**< The message type. */ 2118 uint quantity /**< The quantity. */ 2119 ); 2120 2121 /** Provides a string given `messageType` in the current localization for the 2122 ** single case. 2123 ** @param messageType The message type. 2124 ** @result Returns the desired string. 2125 */ 2126 TIDY_EXPORT ctmbstr TIDY_CALL tidyLocalizedString( uint messageType ); 2127 2128 /** Provides a string given `messageType` in the default localization (which 2129 ** is `en`). 2130 ** @param messageType The message type. 2131 ** @result Returns the desired string. 2132 */ 2133 TIDY_EXPORT ctmbstr TIDY_CALL tidyDefaultString( uint messageType ); 2134 2135 /** Initiates an iterator for a list of string key codes available in Tidy. 2136 ** This iterator allows you to iterate through all of the codes. In order to 2137 ** iterate through the codes, initiate the iterator with this function, and 2138 ** then use getNextStringKey() to retrieve the first and subsequent codes. 2139 ** For example: 2140 ** @code{.c} 2141 ** TidyIterator itKey = getErrorCodeList(); 2142 ** while ( itKey ) { 2143 ** uint code = getNextStringKey( &itKey ); 2144 ** // do something with the code, such as lookup a string. 2145 ** } 2146 ** @endcode 2147 ** @remark These are provided for documentation generation purposes, and 2148 ** probably aren't of much use to the average LibTidy implementor. 2149 ** @result Returns a TidyIterator, which is a token used to represent the 2150 ** current position in a list within LibTidy. 2151 */ 2152 TIDY_EXPORT TidyIterator TIDY_CALL getStringKeyList(void); 2153 2154 /** Given a valid TidyIterator initiated with getStringKeyList(), returns 2155 ** an unsigned integer representing the next key value. 2156 ** @remark These are provided for documentation generation purposes, and 2157 ** probably aren't of much use to the average LibTidy implementor. 2158 ** @param iter The TidyIterator (initiated with getStringKeyList()) token. 2159 ** @result Returns a message code. 2160 */ 2161 TIDY_EXPORT uint TIDY_CALL getNextStringKey( TidyIterator* iter ); 2162 2163 /** @} 2164 ** @name Available Languages 2165 ** @{ 2166 */ 2167 2168 /** Initiates an iterator for a list of Tidy's installed languages. This 2169 ** iterator allows you to iterate through this list. In order to iterate 2170 ** through the list, initiate the iterator with this function, and then use 2171 ** use getNextInstalledLanguage() to retrieve the first and subsequent strings. 2172 ** For example: 2173 ** @code{.c} 2174 ** TidyIterator itList = getInstalledLanguageList(); 2175 ** while ( itList ) { 2176 ** printf("%s", getNextInstalledLanguage( &itList )); 2177 ** } 2178 ** @endcode 2179 ** @result Returns a TidyIterator, which is a token used to represent the 2180 ** current position in a list within LibTidy. 2181 */ 2182 TIDY_EXPORT TidyIterator TIDY_CALL getInstalledLanguageList(void); 2183 2184 /** Given a valid TidyIterator initiated with getInstalledLanguageList(), 2185 ** returns a string representing a language name that is installed in Tidy. 2186 ** @param iter The TidyIterator (initiated with getInstalledLanguageList()) 2187 ** token. 2188 ** @result Returns a string indicating the installed language. 2189 */ 2190 TIDY_EXPORT ctmbstr TIDY_CALL getNextInstalledLanguage( TidyIterator* iter ); 2191 2192 /** @} */ 2193 2194 /** @} end MessagesKeys group */ 2195 /** @} end public_api group */ 2196 2197 2198 #ifdef __cplusplus 2199 } /* extern "C" */ 2200 #endif 2201 #endif /* __TIDY_H__ */ 2202 2203 /* 2204 * local variables: 2205 * mode: c 2206 * indent-tabs-mode: nil 2207 * c-basic-offset: 4 2208 * eval: (c-set-offset 'substatement-open 0) 2209 * end: 2210 */ 2211