HTML Tidy  5.8.0
The HTACG Tidy HTML Project
tidy.h
Go to the documentation of this file.
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 
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. */
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. */
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 */
311 
312 /** Give Tidy a `realloc()` replacement */
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  */
393 
394 /** Get the version number for the current library.
395  ** @result The string representing the version number.
396  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
1761 
1762 /** Get the HTML node.
1763  ** @param tdoc The document to query.
1764  ** @result Returns a tidy node.
1765  */
1767 
1768 /** Get the HEAD node.
1769  ** @param tdoc The document to query.
1770  ** @result Returns a tidy node.
1771  */
1773 
1774 /** Get the BODY node.
1775  ** @param tdoc The document to query.
1776  ** @result Returns a tidy node.
1777  */
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  */
1790 
1791 /** Get the child of the indicated node.
1792  ** @param tnod The node to query.
1793  ** @result Returns a tidy node.
1794  */
1796 
1797 /** Get the next sibling node.
1798  ** @param tnod The node to query.
1799  ** @result Returns a tidy node.
1800  */
1802 
1803 /** Get the previous sibling node.
1804  ** @param tnod The node to query.
1805  ** @result Returns a tidy node.
1806  */
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  */
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  */
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  */
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  */
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  **/
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  **/
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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
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  */
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  */
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  */
int TIDY_CALL tidySetInCharEncoding(TidyDoc tdoc, ctmbstr encnam)
Set the input encoding for parsing markup.
void *TIDY_CALL tidyGetAppData(TidyDoc tdoc)
Returns the data previously stored with tidySetAppData().
int TIDY_CALL tidySetCharEncoding(TidyDoc tdoc, ctmbstr encnam)
Set the input/output character encoding for parsing markup.
void TIDY_CALL tidyGeneralInfo(TidyDoc tdoc)
Write more general information about markup to current error sink.
uint TIDY_CALL tidyWarningCount(TidyDoc tdoc)
Indicates the number of TidyWarning messages that were generated.
int TIDY_CALL tidyLoadConfig(TidyDoc tdoc, ctmbstr configFile)
Load an ASCII Tidy configuration file and set the configuration per its contents.
uint TIDY_CALL tidyErrorCount(TidyDoc tdoc)
Indicates the number of TidyError messages that were generated.
void TIDY_CALL tidyErrorSummary(TidyDoc tdoc)
Write more complete information about errors to current error sink.
uint TIDY_CALL tidyAccessWarningCount(TidyDoc tdoc)
Indicates the number of TidyAccess messages that were generated.
TidyDoc TIDY_CALL tidyCreate(void)
The primary creation of a document instance.
ctmbstr TIDY_CALL tidyLibraryVersion(void)
Get the version number for the current library.
Bool TIDY_CALL tidyDetectedGenericXml(TidyDoc tdoc)
Indicates whether or not the input document was XML.
int TIDY_CALL tidyDetectedHtmlVersion(TidyDoc tdoc)
Gets the version of HTML that was output, as an integer, times 100.
int TIDY_CALL tidySetOutCharEncoding(TidyDoc tdoc, ctmbstr encnam)
Set the input encoding for writing markup.
void TIDY_CALL tidySetAppData(TidyDoc tdoc, void *appData)
Allows the host application to store a chunk of data with each TidyDoc instance.
ctmbstr TIDY_CALL tidyPlatform(void)
Get the platform for which Tidy was built.
ctmbstr TIDY_CALL tidyReleaseDate(void)
Get the release date for the current library.
Bool TIDY_CALL tidyFileExists(TidyDoc tdoc, ctmbstr filename)
Determine whether or not a particular file exists.
uint TIDY_CALL tidyConfigErrorCount(TidyDoc tdoc)
Indicates the number of configuration error messages that were generated.
int TIDY_CALL tidyLoadConfigEnc(TidyDoc tdoc, ctmbstr configFile, ctmbstr charenc)
Load a Tidy configuration file with the specified character encoding, and set the configuration per i...
void TIDY_CALL tidyRelease(TidyDoc tdoc)
Free all memory and release the TidyDoc.
Bool TIDY_CALL tidyDetectedXhtml(TidyDoc tdoc)
Indicates whether the output document is or isn't XHTML.
int TIDY_CALL tidyStatus(TidyDoc tdoc)
Get status of current document.
TidyDoc TIDY_CALL tidyCreateWithAllocator(TidyAllocator *allocator)
Create a document supplying your own, custom TidyAllocator instead of using the built-in default.
int TIDY_CALL tidyCleanAndRepair(TidyDoc tdoc)
Execute configured cleanup and repair operations on parsed markup.
int TIDY_CALL tidyRunDiagnostics(TidyDoc tdoc)
Reports the document type and diagnostic statistics on parsed and repaired markup.
int TIDY_CALL tidyReportDoctype(TidyDoc tdoc)
Reports the document type into the output sink.
TidyOption TIDY_CALL tidyGetOption(TidyDoc tdoc, TidyOptionId optId)
Retrieves an instance of TidyOption given a valid TidyOptionId.
TidyOptionType TIDY_CALL tidyOptGetType(TidyOption opt)
Get datatype of given Option.
ctmbstr TIDY_CALL tidyOptGetCurrPick(TidyDoc tdoc, TidyOptionId optId)
Get the current pick list value for the option ID, which can be useful for enum types.
TidyIterator TIDY_CALL tidyOptGetPriorityAttrList(TidyDoc tdoc)
Initiates an iterator for a list of priority attributes.
Bool(TIDY_CALL * TidyOptCallback)(ctmbstr option, ctmbstr value)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:573
Bool TIDY_CALL tidyOptDiffThanDefault(TidyDoc tdoc)
Any settings different than default?
Bool TIDY_CALL tidyOptGetBool(TidyDoc tdoc, TidyOptionId optId)
Get current option value as a Boolean flag.
Bool TIDY_CALL tidyOptCopyConfig(TidyDoc tdocTo, TidyDoc tdocFrom)
Copy current configuration settings from one document to another.
ctmbstr TIDY_CALL tidyOptGetValue(TidyDoc tdoc, TidyOptionId optId)
Get the current value of the option ID for the given document.
TidyOption TIDY_CALL tidyGetNextOption(TidyDoc tdoc, TidyIterator *pos)
Given a valid TidyIterator initiated with tidyGetOptionList(), returns the instance of the next TidyO...
TidyConfigCategory TIDY_CALL tidyOptGetCategory(TidyOption opt)
Get category of given Option.
TidyOption TIDY_CALL tidyOptGetNextDocLinks(TidyDoc tdoc, TidyIterator *pos)
Given a valid TidyIterator initiated with tidyOptGetDocLinksList(), returns a TidyOption instance.
Bool TIDY_CALL tidyOptResetToDefault(TidyDoc tdoc, TidyOptionId opt)
Reset option to default value by ID.
Bool TIDY_CALL tidySetConfigCallback(TidyDoc tdoc, TidyConfigCallback pConfigCallback)
Applications using TidyLib may want to augment command-line and configuration file options.
TidyIterator TIDY_CALL tidyOptGetPickList(TidyOption opt)
Initiates an iterator for a list of TidyOption pick-list values, which allows you iterate through all...
ctmbstr TIDY_CALL tidyOptGetEncName(TidyDoc tdoc, TidyOptionId optId)
Get character encoding name.
Bool TIDY_CALL tidyOptSnapshot(TidyDoc tdoc)
Take a snapshot of current config settings.
TidyOptionId TIDY_CALL tidyOptGetIdForName(ctmbstr optnam)
Returns the TidyOptionId (enum value) by providing the name of a Tidy configuration option.
TidyOptionId TIDY_CALL tidyOptGetId(TidyOption opt)
Get ID of given Option.
TidyIterator TIDY_CALL tidyOptGetDeclTagList(TidyDoc tdoc)
Initiates an iterator for a list of user-declared tags, including autonomous custom tags detected in ...
Bool TIDY_CALL tidyOptIsReadOnly(TidyOption opt)
Is Option read-only? Some options (mainly internal use only options) are read-only.
void(TIDY_CALL * TidyConfigChangeCallback)(TidyDoc tdoc, TidyOption option)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:616
ctmbstr TIDY_CALL tidyOptGetNextPriorityAttr(TidyDoc tdoc, TidyIterator *iter)
Given a valid TidyIterator initiated with tidyOptGetPriorityAttrList(), returns a string representing...
Bool TIDY_CALL tidyOptDiffThanSnapshot(TidyDoc tdoc)
Any settings different than snapshot?
ulong TIDY_CALL tidyOptGetInt(TidyDoc tdoc, TidyOptionId optId)
Get current option value as an integer.
Bool TIDY_CALL tidyOptResetAllToDefault(TidyDoc tdoc)
Reset all options to their default values.
TidyIterator TIDY_CALL tidyOptGetMutedMessageList(TidyDoc tdoc)
Initiates an iterator for a list of muted messages.
Bool(TIDY_CALL * TidyConfigCallback)(TidyDoc tdoc, ctmbstr option, ctmbstr value)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:597
ctmbstr TIDY_CALL tidyOptGetNextMutedMessage(TidyDoc tdoc, TidyIterator *iter)
Given a valid TidyIterator initiated with tidyOptGetMutedMessageList(), returns a string representing...
TidyIterator TIDY_CALL tidyGetOptionList(TidyDoc tdoc)
Initiates an iterator for a list of TidyOption instances, which allows you to iterate through all of ...
Bool TIDY_CALL tidySetOptionCallback(TidyDoc tdoc, TidyOptCallback pOptCallback)
Applications using TidyLib may want to augment command-line and configuration file options.
ctmbstr TIDY_CALL tidyOptGetDefault(TidyOption opt)
Get default value of given Option as a string.
Bool TIDY_CALL tidySetConfigChangeCallback(TidyDoc tdoc, TidyConfigChangeCallback pCallback)
Applications using TidyLib may want to be informed when changes to options are made.
Bool TIDY_CALL tidyOptionIsList(TidyOption opt)
Indicates that an option takes a list of items.
Bool TIDY_CALL tidyOptSetBool(TidyDoc tdoc, TidyOptionId optId, Bool val)
Set option value as a Boolean flag.
ctmbstr TIDY_CALL tidyOptGetNextDeclTag(TidyDoc tdoc, TidyOptionId optId, TidyIterator *iter)
Given a valid TidyIterator initiated with tidyOptGetDeclTagList(), returns a string representing a us...
Bool TIDY_CALL tidyOptParseValue(TidyDoc tdoc, ctmbstr optnam, ctmbstr val)
Set named option value as a string, regardless of the TidyOptionType.
ctmbstr TIDY_CALL tidyOptGetNextPick(TidyOption opt, TidyIterator *pos)
Given a valid TidyIterator initiated with tidyOptGetPickList(), returns a string representing a possi...
Bool TIDY_CALL tidyOptSetInt(TidyDoc tdoc, TidyOptionId optId, ulong val)
Set option value as an integer.
Bool TIDY_CALL tidyOptGetDefaultBool(TidyOption opt)
Get default value of given Option as a Boolean value.
Bool TIDY_CALL tidyOptResetToSnapshot(TidyDoc tdoc)
Apply a snapshot of config settings to a document.
TidyOption TIDY_CALL tidyGetOptionByName(TidyDoc tdoc, ctmbstr optnam)
Returns an instance of TidyOption by providing the name of a Tidy configuration option.
TidyIterator TIDY_CALL tidyOptGetDocLinksList(TidyDoc tdoc, TidyOption opt)
Initiates an iterator for a list of options related to a given option.
ctmbstr TIDY_CALL tidyOptGetName(TidyOption opt)
Get name of given Option.
Bool TIDY_CALL tidyOptSetValue(TidyDoc tdoc, TidyOptionId optId, ctmbstr val)
Set the option value as a string.
ulong TIDY_CALL tidyOptGetDefaultInt(TidyOption opt)
Get default value of given Option as an unsigned integer.
ctmbstr TIDY_CALL tidyOptGetDoc(TidyDoc tdoc, TidyOption opt)
Get the description of the specified option.
void * sourceData
Input context.
Definition: tidy.h:1080
void * sinkData
Output context.
Definition: tidy.h:1130
TidyGetByteFunc getByte
Pointer to "get byte" callback.
Definition: tidy.h:1082
TidyEOFFunc eof
Pointer to "eof" callback.
Definition: tidy.h:1084
TidyUngetByteFunc ungetByte
Pointer to "unget" callback.
Definition: tidy.h:1083
TidyPutByteFunc putByte
Pointer to "put byte" callback.
Definition: tidy.h:1132
TidyMessageArgument TIDY_CALL tidyGetNextMessageArgument(TidyMessage tmessage, TidyIterator *iter)
Given a valid TidyIterator initiated with tidyGetMessageArguments(), returns an instance of the opaqu...
void(TIDY_CALL * TidyPutByteFunc)(void *sinkData, byte bt)
Output callback: send a byte to output.
Definition: tidy.h:1122
void TIDY_CALL tidySetEmacsFile(TidyDoc tdoc, ctmbstr filePath)
Set the file path to use for reports when TidyEmacs is being used.
void TIDY_CALL tidyUngetByte(TidyInputSource *source, uint byteValue)
Helper: unget byte back to input source.
TidyFormatParameterType TIDY_CALL tidyGetArgType(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the TidyFormatParameterType of the given message argument.
Bool(TIDY_CALL * TidyEOFFunc)(void *sourceData)
Input Callback: is end of input?
Definition: tidy.h:1073
Bool TIDY_CALL tidyGetMessageIsMuted(TidyMessage tmessage)
Get the muted status of the message, that is, whether or not the current configuration indicated that...
int TIDY_CALL tidyGetMessageColumn(TidyMessage tmessage)
Get the column the message applies to.
int TIDY_CALL tidyGetArgValueInt(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the integer value of the given message argument.
void(TIDY_CALL * TidyUngetByteFunc)(void *sourceData, byte bt)
Input Callback: unget a byte of input.
Definition: tidy.h:1070
void TIDY_CALL tidyPutByte(TidyOutputSink *sink, uint byteValue)
Helper: send a byte to output.
TidyDoc TIDY_CALL tidyGetMessageDoc(TidyMessage tmessage)
Get the tidy document this message comes from.
ctmbstr TIDY_CALL tidyGetMessageOutputDefault(TidyMessage tmessage)
Get the complete message as Tidy would emit it in the default localization.
int TIDY_CALL tidyGetMessageLine(TidyMessage tmessage)
Get the line number the message applies to.
Bool TIDY_CALL tidyIsEOF(TidyInputSource *source)
Helper: check if input source at end.
ctmbstr TIDY_CALL tidyGetMessageDefault(TidyMessage tmessage)
Get the message with the format string already completed, in Tidy's default localization.
Bool TIDY_CALL tidySetReportFilter(TidyDoc tdoc, TidyReportFilter filtCallback)
This function informs Tidy to use the specified callback to send reports.
ctmbstr TIDY_CALL tidyGetMessagePrefixDefault(TidyMessage tmessage)
Get the prefix part of a message in the default language.
int TIDY_CALL tidySetErrorBuffer(TidyDoc tdoc, TidyBuffer *errbuf)
Set error sink to given buffer.
TidyIterator TIDY_CALL tidyGetMessageArguments(TidyMessage tmessage)
Initiates an iterator for a list of arguments related to a given message.
FILE *TIDY_CALL tidySetErrorFile(TidyDoc tdoc, ctmbstr errfilnam)
Set error sink to named file.
void(TIDY_CALL * TidyPPProgress)(TidyDoc tdoc, uint line, uint col, uint destLine)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:1532
ctmbstr TIDY_CALL tidyGetMessageKey(TidyMessage tmessage)
Get the message key string.
ctmbstr TIDY_CALL tidyGetMessagePos(TidyMessage tmessage)
Get the position part part of the message in the current language.
Bool TIDY_CALL tidyInitSink(TidyOutputSink *sink, void *snkData, TidyPutByteFunc pbFunc)
Facilitates user defined sinks by providing an entry point to marshal pointers-to-functions.
TidyReportLevel TIDY_CALL tidyGetMessageLevel(TidyMessage tmessage)
Get the TidyReportLevel of the message.
Bool(TIDY_CALL * TidyMessageCallback)(TidyMessage tmessage)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:1286
double TIDY_CALL tidyGetArgValueDouble(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the double value of the given message argument.
ctmbstr TIDY_CALL tidyGetMessagePosDefault(TidyMessage tmessage)
Get the position part part of the message in the default language.
Bool(TIDY_CALL * TidyReportCallback)(TidyDoc tdoc, TidyReportLevel lvl, uint line, uint col, ctmbstr code, va_list args)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:1260
int(TIDY_CALL * TidyGetByteFunc)(void *sourceData)
Input Callback: get next byte of input.
Definition: tidy.h:1067
uint TIDY_CALL tidyGetArgValueUInt(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the unsigned integer value of the given message argument.
ctmbstr TIDY_CALL tidyGetMessageFormatDefault(TidyMessage tmessage)
Get the default format string, which is the format string for the message in Tidy's default localizat...
ctmbstr TIDY_CALL tidyGetArgFormat(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the format specifier of the given message argument.
uint TIDY_CALL tidyGetMessageCode(TidyMessage tmessage)
Get the message code.
ctmbstr TIDY_CALL tidyGetMessageFormat(TidyMessage tmessage)
Get the localized format string.
Bool TIDY_CALL tidyInitSource(TidyInputSource *source, void *srcData, TidyGetByteFunc gbFunc, TidyUngetByteFunc ugbFunc, TidyEOFFunc endFunc)
Facilitates user defined source by providing an entry point to marshal pointers-to-functions.
ctmbstr TIDY_CALL tidyGetMessage(TidyMessage tmessage)
Get the message with the format string already completed, in Tidy's current localization.
Bool TIDY_CALL tidySetPrettyPrinterCallback(TidyDoc tdoc, TidyPPProgress callback)
This function informs Tidy to use the specified callback for tracking the pretty-printing process pro...
Bool TIDY_CALL tidySetReportCallback(TidyDoc tdoc, TidyReportCallback filtCallback)
This function informs Tidy to use the specified callback to send reports.
ctmbstr TIDY_CALL tidyGetMessageOutput(TidyMessage tmessage)
Get the complete message as Tidy would emit it in the current localization.
int TIDY_CALL tidySetErrorSink(TidyDoc tdoc, TidyOutputSink *sink)
Set error sink to given generic sink.
uint TIDY_CALL tidyGetByte(TidyInputSource *source)
Helper: get next byte from input source.
ctmbstr TIDY_CALL tidyGetEmacsFile(TidyDoc tdoc)
Get the file path to use for reports when TidyEmacs is being used.
Bool(TIDY_CALL * TidyReportFilter)(TidyDoc tdoc, TidyReportLevel lvl, uint line, uint col, ctmbstr mssg)
This typedef represents the required signature for your provided callback function should you wish to...
Definition: tidy.h:1221
Bool TIDY_CALL tidySetMessageCallback(TidyDoc tdoc, TidyMessageCallback filtCallback)
This function informs Tidy to use the specified callback to send reports.
ctmbstr TIDY_CALL tidyGetMessagePrefix(TidyMessage tmessage)
Get the prefix part of a message in the current language.
ctmbstr TIDY_CALL tidyGetArgValueString(TidyMessage tmessage, TidyMessageArgument *arg)
Returns the string value of the given message argument.
This type defines an input source capable of delivering raw bytes of input.
Definition: tidy.h:1079
This type defines an output destination capable of accepting raw bytes of output.
Definition: tidy.h:1129
A TidyBuffer is chunk of memory that can be used for multiple I/O purposes within Tidy.
Definition: tidybuffio.h:37
ctmbstr TIDY_CALL getNextInstalledLanguage(TidyIterator *iter)
Given a valid TidyIterator initiated with getInstalledLanguageList(), returns a string representing a...
TidyIterator TIDY_CALL getStringKeyList(void)
Initiates an iterator for a list of string key codes available in Tidy.
ctmbstr TIDY_CALL tidyLocalizedString(uint messageType)
Provides a string given messageType in the current localization for the single case.
ctmbstr TIDY_CALL TidyLangWindowsName(const tidyLocaleMapItem *item)
Given a tidyLocaleMapItem, return the Windows name.
ctmbstr TIDY_CALL tidyDefaultString(uint messageType)
Provides a string given messageType in the default localization (which is en).
TidyIterator TIDY_CALL getInstalledLanguageList(void)
Initiates an iterator for a list of Tidy's installed languages.
uint TIDY_CALL getNextStringKey(TidyIterator *iter)
Given a valid TidyIterator initiated with getStringKeyList(), returns an unsigned integer representin...
ctmbstr TIDY_CALL TidyLangPosixName(const tidyLocaleMapItem *item)
Given a tidyLocaleMapItem, return the POSIX name.
ctmbstr TIDY_CALL tidyLocalizedStringN(uint messageType, uint quantity)
Provides a string given messageType in the current localization for quantity.
Bool TIDY_CALL tidySetLanguage(ctmbstr languageCode)
Tells Tidy to use a different language for output.
TidyIterator TIDY_CALL getWindowsLanguageList(void)
Initiates an iterator for a list of Tidy's Windows<->POSIX locale mappings.
const tidyLocaleMapItem *TIDY_CALL getNextWindowsLanguage(TidyIterator *iter)
Given a valid TidyIterator initiated with getWindowsLanguageList(), returns a pointer to a tidyLocale...
ctmbstr TIDY_CALL tidyGetLanguage(void)
Gets the current language used by Tidy.
Represents an opaque type we can use for tidyLocaleMapItem, which is used to iterate through the lang...
void * free(TidyAllocator *self, void *block)
Called to free a previously allocated block of memory.
void ** alloc(TidyAllocator *self, size_t nBytes)
Called to allocate a block of nBytes of memory.
void * panic(TidyAllocator *self, ctmbstr msg)
Called when a panic condition is detected.
const TidyAllocatorVtbl * vtbl
The allocator's function table.
Definition: tidy.h:247
void ** realloc(TidyAllocator *self, void *block, size_t nBytes)
Called to resize (grow, in general) a block of memory.
Bool TIDY_CALL tidySetReallocCall(TidyRealloc frealloc)
Give Tidy a realloc() replacement.
Bool TIDY_CALL tidySetFreeCall(TidyFree ffree)
Give Tidy a free() replacement.
void *(TIDY_CALL * TidyMalloc)(size_t len)
Callback for malloc replacement.
Definition: tidy.h:297
void *(TIDY_CALL * TidyRealloc)(void *buf, size_t len)
Callback for realloc replacement.
Definition: tidy.h:300
void(TIDY_CALL * TidyFree)(void *buf)
Callback for free replacement.
Definition: tidy.h:303
Bool TIDY_CALL tidySetPanicCall(TidyPanic fpanic)
Give Tidy an "out of memory" handler.
Bool TIDY_CALL tidySetMallocCall(TidyMalloc fmalloc)
Give Tidy a malloc() replacement.
void(TIDY_CALL * TidyPanic)(ctmbstr mssg)
Callback for out of memory panic state.
Definition: tidy.h:306
Tidy's built-in default allocator.
Definition: tidy.h:246
This structure is the function table for an allocator.
Definition: tidy.h:254
uint TIDY_CALL getNextErrorCode(TidyIterator *iter)
Given a valid TidyIterator initiated with getErrorCodeList(), returns an instance of the opaque type ...
uint TIDY_CALL tidyErrorCodeFromKey(ctmbstr code)
Given a text key representing a message code, return the uint that represents it.
ctmbstr TIDY_CALL tidyErrorCodeAsKey(uint code)
Given a message code, return the text key that represents it.
TidyIterator TIDY_CALL getErrorCodeList(void)
Initiates an iterator for a list of message codes available in Tidy.
Attributes of a TidyNode are represented by this data type.
Instances of this represent a Tidy document, which encapsulates everything there is to know about a s...
Instances of this type represent messages generated by Tidy in reference to your document.
Instances of this type represent the arguments that compose part of the message represented by TidyMe...
Single nodes of a TidyDocument are represented by this datatype.
Instances of this represent a Tidy configuration option, which contains useful data about these optio...
int TIDY_CALL tidyParseString(TidyDoc tdoc, ctmbstr content)
Parse markup in given string.
int TIDY_CALL tidyParseFile(TidyDoc tdoc, ctmbstr filename)
Parse markup in named file.
int TIDY_CALL tidyParseStdin(TidyDoc tdoc)
Parse markup from the standard input.
int TIDY_CALL tidyParseBuffer(TidyDoc tdoc, TidyBuffer *buf)
Parse markup in given buffer.
int TIDY_CALL tidyParseSource(TidyDoc tdoc, TidyInputSource *source)
Parse markup in given generic input source.
int TIDY_CALL tidySaveFile(TidyDoc tdoc, ctmbstr filename)
Save the tidy document to the named file.
int TIDY_CALL tidySaveStdout(TidyDoc tdoc)
Save the tidy document to standard output (FILE*).
int TIDY_CALL tidySaveBuffer(TidyDoc tdoc, TidyBuffer *buf)
Save the tidy document to given TidyBuffer object.
int TIDY_CALL tidyOptSaveFile(TidyDoc tdoc, ctmbstr cfgfil)
Save current settings to named file.
int TIDY_CALL tidyOptSaveSink(TidyDoc tdoc, TidyOutputSink *sink)
Save current settings to given output sink.
int TIDY_CALL tidySaveSink(TidyDoc tdoc, TidyOutputSink *sink)
Save to given generic output sink.
int TIDY_CALL tidySaveString(TidyDoc tdoc, tmbstr buffer, uint *buflen)
Save the tidy document to an application buffer.
uint TIDY_CALL tidyNodeColumn(TidyNode tnod)
Get the column location of the node.
TidyNode TIDY_CALL tidyGetParent(TidyNode tnod)
Get the parent of the indicated node.
TidyNode TIDY_CALL tidyGetChild(TidyNode tnod)
Get the child of the indicated node.
Bool TIDY_CALL tidyNodeGetText(TidyDoc tdoc, TidyNode tnod, TidyBuffer *buf)
Gets the text of a node and places it into the given TidyBuffer.
Bool TIDY_CALL tidyAttrIsEvent(TidyAttr tattr)
Indicates whether or not a given attribute is an event attribute.
Bool TIDY_CALL tidyNodeIsProp(TidyDoc tdoc, TidyNode tnod)
Indicates whether or not the node is a propriety type.
TidyTagId TIDY_CALL tidyNodeGetId(TidyNode tnod)
Get the tag ID of the node.
ctmbstr TIDY_CALL tidyAttrName(TidyAttr tattr)
Get the name of a TidyAttr instance.
TidyAttrId TIDY_CALL tidyAttrGetId(TidyAttr tattr)
Get the attribute ID given a tidy attribute.
Bool TIDY_CALL tidyNodeIsText(TidyNode tnod)
Indicates whether or not a node is a text node.
Bool TIDY_CALL tidyNodeHasText(TidyDoc tdoc, TidyNode tnod)
Indicates whether or not the node has text.
TidyAttr TIDY_CALL tidyAttrGetById(TidyNode tnod, TidyAttrId attId)
Get an instance of TidyAttr by specifying an attribute ID.
ctmbstr TIDY_CALL tidyNodeGetName(TidyNode tnod)
Get the name of the node.
void TIDY_CALL tidyAttrDiscard(TidyDoc itdoc, TidyNode tnod, TidyAttr tattr)
Discard an attribute.
TidyNode TIDY_CALL tidyGetNext(TidyNode tnod)
Get the next sibling node.
Bool TIDY_CALL tidyNodeIsHeader(TidyNode tnod)
Indicates whether or not a node represents and HTML header element, such as h1, h2,...
TidyAttr TIDY_CALL tidyAttrFirst(TidyNode tnod)
Get the first attribute.
Bool TIDY_CALL tidyNodeGetValue(TidyDoc tdoc, TidyNode tnod, TidyBuffer *buf)
Get the value of the node.
TidyNode TIDY_CALL tidyGetPrev(TidyNode tnod)
Get the previous sibling node.
TidyNode TIDY_CALL tidyGetBody(TidyDoc tdoc)
Get the BODY node.
TidyAttr TIDY_CALL tidyAttrNext(TidyAttr tattr)
Get the next attribute.
TidyNode TIDY_CALL tidyGetHead(TidyDoc tdoc)
Get the HEAD node.
uint TIDY_CALL tidyNodeLine(TidyNode tnod)
Get the line number where the node occurs.
TidyNode TIDY_CALL tidyDiscardElement(TidyDoc tdoc, TidyNode tnod)
Remove the indicated node.
TidyNodeType TIDY_CALL tidyNodeGetType(TidyNode tnod)
Get the type of node.
TidyNode TIDY_CALL tidyGetRoot(TidyDoc tdoc)
Get the root node.
TidyNode TIDY_CALL tidyGetHtml(TidyDoc tdoc)
Get the HTML node.
ctmbstr TIDY_CALL tidyAttrValue(TidyAttr tattr)
Get the value of a TidyAttr instance.
TidyReportLevel
Message severity level, used throughout LibTidy to indicate the severity or status of a message.
Definition: tidyenum.h:1402
TidyConfigCategory
Categories of Tidy configuration options, which are used mostly by user interfaces to sort Tidy optio...
Definition: tidyenum.h:699
TidyOptionId
Option IDs are used used to get and/or set configuration option values and retrieve their description...
Definition: tidyenum.h:573
TidyNodeType
Node types.
Definition: tidyenum.h:836
TidyAttrId
Known HTML attributes.
Definition: tidyenum.h:1020
TidyTagId
Known HTML element types.
Definition: tidyenum.h:857
TidyFormatParameterType
Indicates the data type of a format string parameter used when Tidy emits reports and dialogue as par...
Definition: tidyenum.h:1422
TidyOptionType
A Tidy configuration option can have one of these data types.
Definition: tidyenum.h:706
Separated public enumerations header providing important indentifiers for LibTidy and internal users,...
Platform specific definitions, specifics, and headers.
Bool
Definition: tidyplatform.h:647
#define TIDY_STRUCT
Definition: tidyplatform.h:600
opaque_type(TidyIterator)
#define TIDY_CALL
Definition: tidyplatform.h:615
unsigned int uint
Definition: tidyplatform.h:569
const tmbchar * ctmbstr
Definition: tidyplatform.h:609
tmbchar * tmbstr
Definition: tidyplatform.h:608