HTML Tidy 5.8.0
The HTACG Tidy HTML Project
Loading...
Searching...
No Matches
message.h
Go to the documentation of this file.
1#ifndef __MESSAGE_H__
2#define __MESSAGE_H__
3
4/******************************************************************************
5 * @file
6 * Provides General Message Writing Routines
7 *
8 * This module handles LibTidy's high level output routines, as well as
9 * provides lookup functions and management for keys used for retrieval
10 * of these messages.
11 *
12 * LibTidy emits two general types of output:
13 *
14 * - Reports, which contain data relating to what Tidy discovered in your
15 * source file, and/or what Tidy did to your source file. In some cases
16 * general information about your source file is emitted as well. Reports
17 * are emitted in the current output buffer, but LibTidy users will probably
18 * prefer to hook into a callback in order to take advantage of the data
19 * that are available in a more flexible way.
20 *
21 * - Dialogue, consisting of footnotes related to your source file, and of
22 * general information that's not related to your source file in particular.
23 * This is also written to the current output buffer when appropriate, and
24 * available via callbacks.
25 *
26 * Report information typically takes the form of a warning, an error, info,
27 * etc., and the output routines keep track of the count of these.
28 *
29 * The preferred way of handling Tidy diagnostics output is either
30 * - define a new output sink, or
31 * - use a message filter callback routine.
32 *
33 * @author HTACG, et al (consult git log)
34 *
35 * @copyright
36 * Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
37 * Institute of Technology, European Research Consortium for Informatics
38 * and Mathematics, Keio University) and HTACG.
39 * @par
40 * All Rights Reserved.
41 * @par
42 * See `tidy.h` for the complete license.
43 *
44 * @date Additional updates: consult git log
45 *
46 ******************************************************************************/
47
48#include "forward.h"
49#include "config.h"
50
51/** @addtogroup internal_api */
52/** @{ */
53
54
55/***************************************************************************//**
56 ** @defgroup message_releaseinfo Tidy Release Information
57 **
58 ** These functions return information about the current release version date
59 ** and version number. Note that the latest release date or the highest
60 ** version number alone do not guarantee the latest Tidy release, as we may
61 ** backport important fixes to older releases of Tidy.
62 **
63 ** @{
64 ******************************************************************************/
65
66/**
67 * Returns the release date of this instance of HTML Tidy.
68 */
69TY_PRIVATE ctmbstr TY_(ReleaseDate)(void);
70
71/**
72 * Returns the release version of this instance of HTML Tidy.
73 */
75
76
77/** @} message_releaseinfo group */
78
79
80/***************************************************************************//**
81 ** @defgroup message_reporting Report and Dialogue Writing Functions
82 **
83 ** These simple functions perform the vast majority of Tidy's output, and
84 ** one these should be your first choice when adding your own output.
85 **
86 ** A report is typically diagnostic output that is generated each time Tidy
87 ** detects an issue in your document or makes a change. A dialogue is a piece
88 ** of information such as a summary, a footnote, or other non-tabular data.
89 ** Some of these functions emit multiple reports or dialogue in order to
90 ** effect a summary.
91 **
92 ** @{
93 ******************************************************************************/
94
95/** @name General Report Writing
96 ** If one of the convenience reporting functions does not fit your required
97 ** message signature, then this designated reporting function will fit the
98 ** bill. Be sure to see if a message formatter exists that can handle the
99 ** variable arguments.
100 */
101/** @{ */
102
103
104/**
105 * The designated report writing function. When a proper formatter exists,
106 * this one function can hanle all report output.
107 */
108TY_PRIVATE void TY_(Report)(TidyDocImpl* doc, Node *element, Node *node, uint code, ...);
109
110
111/** @} */
112/** @name Convenience Reporting Functions
113 ** These convenience reporting functions are able to handle the bulk of Tidy's
114 ** necessary reporting, and avoid the danger of using a variadic if you are
115 ** unfamiliar with Tidy.
116 */
117/** @{ */
118
119
120TY_PRIVATE void TY_(ReportAccessError)( TidyDocImpl* doc, Node* node, uint code );
121TY_PRIVATE void TY_(ReportAttrError)(TidyDocImpl* doc, Node *node, AttVal *av, uint code);
122TY_PRIVATE void TY_(ReportBadArgument)( TidyDocImpl* doc, ctmbstr option );
123TY_PRIVATE void TY_(ReportEntityError)( TidyDocImpl* doc, uint code, ctmbstr entity, int c );
124TY_PRIVATE void TY_(ReportFileError)( TidyDocImpl* doc, ctmbstr file, uint code );
125TY_PRIVATE void TY_(ReportEncodingError)(TidyDocImpl* doc, uint code, uint c, Bool discarded);
126TY_PRIVATE void TY_(ReportEncodingWarning)(TidyDocImpl* doc, uint code, uint encoding);
127TY_PRIVATE void TY_(ReportMissingAttr)( TidyDocImpl* doc, Node* node, ctmbstr name );
128TY_PRIVATE void TY_(ReportSurrogateError)(TidyDocImpl* doc, uint code, uint c1, uint c2);
129TY_PRIVATE void TY_(ReportUnknownOption)( TidyDocImpl* doc, ctmbstr option );
130
131
132/** @} */
133/** @name General Dialogue Writing
134 ** These functions produce dialogue output such as individual messages, or
135 ** several messages in summary form.
136 */
137/** @{ */
138
139
140/**
141 * Emits a single dialogue message, and is capable of accepting a variadic
142 * that is passed to the correct message formatter as needed.
143 */
144TY_PRIVATE void TY_(Dialogue)( TidyDocImpl* doc, uint code, ... );
145
146
147/** @} */
148/** @name Output Dialogue Information */
149/** @{ */
150
151
152/**
153 * Outputs the footnotes and other dialogue information after document cleanup
154 * is complete. LibTidy users might consider capturing these individually in
155 * the message callback rather than capturing this entire buffer.
156 * Called by `tidyErrorSummary()`, in console.
157 * @todo: This name is a bit misleading and should probably be renamed to
158 * indicate its focus on printing footnotes.
159 */
160TY_PRIVATE void TY_(ErrorSummary)( TidyDocImpl* doc );
161
162
163/**
164 * Outputs document HTML version and version-related information as the final
165 * report(s) in the report table.
166 * Called by `tidyRunDiagnostics()`, from console.
167 * Called by `tidyDocReportDoctype()`, currently unused.
168 */
169TY_PRIVATE void TY_(ReportMarkupVersion)( TidyDocImpl* doc );
170
171
172/**
173 * Reports the number of warnings and errors found in the document as dialogue
174 * inforation.
175 * Called by `tidyRunDiagnostics()`, from console.
176 */
177TY_PRIVATE void TY_(ReportNumWarnings)( TidyDocImpl* doc );
178
179
180/** @} */
181/** @} message_reporting group */
182
183
184/***************************************************************************//**
185 ** @defgroup message_mutinging Message Muting
186 **
187 ** Message types included in the `mute` option will be be printed in
188 ** messageOut().
189 **
190 ** @{
191 ******************************************************************************/
192
193/** Maintains a list of messages not to display. */
194typedef struct _mutedMessages {
195 tidyStrings* list; /**< A list of messages that won't be output. */
196 uint count; /**< Current count of the list. */
197 uint capacity; /**< Current capacity of the list. */
199
200
201/** Frees the list of muted messages.
202 ** @param doc The Tidy document.
203 */
204TY_PRIVATE void TY_(FreeMutedMessageList)( TidyDocImpl* doc );
205
206/** Adds a new message ID to the list of muted messages.
207 ** @param doc The Tidy document.
208 ** @param opt The option that is defining the muted message.
209 ** @param name The message code as a string.
210 */
211TY_PRIVATE void TY_(DefineMutedMessage)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
212
213/** Start an iterator for muted messages.
214 ** @param doc The Tidy document.
215 ** @returns Returns an iterator token.
216 */
217TY_PRIVATE TidyIterator TY_(getMutedMessageList)( TidyDocImpl* doc );
218
219/** Get the next priority attribute.
220 ** @param doc The Tidy document.
221 ** @param iter The iterator token.
222 ** @returns The next priority attribute.
223 */
224TY_PRIVATE ctmbstr TY_(getNextMutedMessage)( TidyDocImpl* doc, TidyIterator* iter );
225
226
227/** @} message_muting group */
228
229
230/***************************************************************************//**
231 ** @defgroup message_keydiscovery Key Discovery
232 **
233 ** LibTidy users may want to use `TidyReportCallback` to enable their own
234 ** localization lookup features. Because Tidy's report codes are enums the
235 ** specific values can change over time. Using these functions provides the
236 ** ability for LibTidy users to use LibTidy's enum values as strings for
237 ** lookup purposes.
238 **
239 ** @{
240 ******************************************************************************/
241
242/**
243 * This function returns a string representing the enum value name that can
244 * be used as a lookup key independent of changing string values.
245 * `TidyReportCallback` will return this general string as the report
246 * message key.
247 */
249
250/**
251 * Given an error code string, return the integer value of it, or UINT_MAX
252 * as an error flag.
253 */
255
256
257/**
258 * Initializes the TidyIterator to point to the first item
259 * in Tidy's list of error codes that can be return with
260 * `TidyReportFilter3`.
261 * Items can be retrieved with getNextErrorCode();
262 */
263TY_PRIVATE TidyIterator TY_(getErrorCodeList)(void);
264
265/**
266 * Returns the next error code having initialized the iterator
267 * with `getErrorCodeList()`. You can use tidyErrorCodeAsKey
268 * to determine the key for this value.
269 */
270TY_PRIVATE uint TY_(getNextErrorCode)( TidyIterator* iter );
271
272
273/** @} message_keydiscovery group */
274/** @} internal_api addtogroup */
275
276
277
278/* accessibility flaws */
279
280#define BA_MISSING_IMAGE_ALT 1
281#define BA_MISSING_LINK_ALT 2
282#define BA_MISSING_SUMMARY 4
283#define BA_MISSING_IMAGE_MAP 8
284#define BA_USING_FRAMES 16
285#define BA_USING_NOFRAMES 32
286#define BA_INVALID_LINK_NOFRAMES 64 /* WAI [6.5.1.4] */
287#define BA_WAI (1 << 31)
288
289/* presentation flaws */
290
291#define USING_SPACER 1
292#define USING_LAYER 2
293#define USING_NOBR 4
294#define USING_FONT 8
295#define USING_BODY 16
296
297/* badchar bit field */
298
299#define BC_VENDOR_SPECIFIC_CHARS 1
300#define BC_INVALID_SGML_CHARS 2
301#define BC_INVALID_UTF8 4
302#define BC_INVALID_UTF16 8
303#define BC_ENCODING_MISMATCH 16 /* fatal error */
304#define BC_INVALID_URI 32
305#define BC_INVALID_NCR 64
306
307/* other footnote bit field (temporary until formalized) */
308
309#define FN_TRIM_EMPTY_ELEMENT 1
310
311/* Lexer and I/O Macros */
312
313#define REPLACED_CHAR 0
314#define DISCARDED_CHAR 1
315
316
317#endif /* __MESSAGE_H__ */
Read configuration files and manage configuration properties.
#define TY_PRIVATE
Definition forward.h:29
#define TY_(str)
Definition forward.h:23
ctmbstr TIDY_CALL tidyLibraryVersion(void)
Get the version number for the current library.
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.
uint capacity
Current capacity of the list.
Definition message.h:197
uint count
Current count of the list.
Definition message.h:196
tidyStrings * list
A list of messages that won't be output.
Definition message.h:195
Maintains a list of messages not to display.
Definition message.h:194
tidyStrings
The enumeration contains a list of every possible string that Tidy and the console application can ou...
Definition tidyenum.h:1442
Bool
Definition tidyplatform.h:647
unsigned int uint
Definition tidyplatform.h:569
const tmbchar * ctmbstr
Definition tidyplatform.h:609