HTML Tidy  5.9.15
The HTACG Tidy HTML Project
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  */
69 TY_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 handle all report output.
107  */
108 TY_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 
120 TY_PRIVATE void TY_(ReportAccessError)( TidyDocImpl* doc, Node* node, uint code );
121 TY_PRIVATE void TY_(ReportAttrError)(TidyDocImpl* doc, Node *node, AttVal *av, uint code);
122 TY_PRIVATE void TY_(ReportBadArgument)( TidyDocImpl* doc, ctmbstr option );
123 TY_PRIVATE void TY_(ReportEntityError)( TidyDocImpl* doc, uint code, ctmbstr entity, int c );
124 TY_PRIVATE void TY_(ReportFileError)( TidyDocImpl* doc, ctmbstr file, uint code );
125 TY_PRIVATE void TY_(ReportEncodingError)(TidyDocImpl* doc, uint code, uint c, Bool discarded);
126 TY_PRIVATE void TY_(ReportEncodingWarning)(TidyDocImpl* doc, uint code, uint encoding);
127 TY_PRIVATE void TY_(ReportMissingAttr)( TidyDocImpl* doc, Node* node, ctmbstr name );
128 TY_PRIVATE void TY_(ReportSurrogateError)(TidyDocImpl* doc, uint code, uint c1, uint c2);
129 TY_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  */
144 TY_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  */
160 TY_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  */
169 TY_PRIVATE void TY_(ReportMarkupVersion)( TidyDocImpl* doc );
170 
171 
172 /**
173  * Reports the number of warnings and errors found in the document as dialogue
174  * information.
175  * Called by `tidyRunDiagnostics()`, from console.
176  */
177 TY_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. */
194 typedef 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  */
204 TY_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  */
211 TY_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  */
217 TY_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  */
224 TY_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  */
263 TY_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  */
270 TY_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:1454
Bool
Definition: tidyplatform.h:662
unsigned int uint
Definition: tidyplatform.h:576
const tmbchar * ctmbstr
Definition: tidyplatform.h:624