318 lines
11 KiB
C
318 lines
11 KiB
C
#ifndef __MESSAGE_H__
|
|
#define __MESSAGE_H__
|
|
|
|
/******************************************************************************
|
|
* @file
|
|
* Provides General Message Writing Routines
|
|
*
|
|
* This module handles LibTidy's high level output routines, as well as
|
|
* provides lookup functions and management for keys used for retrieval
|
|
* of these messages.
|
|
*
|
|
* LibTidy emits two general types of output:
|
|
*
|
|
* - Reports, which contain data relating to what Tidy discovered in your
|
|
* source file, and/or what Tidy did to your source file. In some cases
|
|
* general information about your source file is emitted as well. Reports
|
|
* are emitted in the current output buffer, but LibTidy users will probably
|
|
* prefer to hook into a callback in order to take advantage of the data
|
|
* that are available in a more flexible way.
|
|
*
|
|
* - Dialogue, consisting of footnotes related to your source file, and of
|
|
* general information that's not related to your source file in particular.
|
|
* This is also written to the current output buffer when appropriate, and
|
|
* available via callbacks.
|
|
*
|
|
* Report information typically takes the form of a warning, an error, info,
|
|
* etc., and the output routines keep track of the count of these.
|
|
*
|
|
* The preferred way of handling Tidy diagnostics output is either
|
|
* - define a new output sink, or
|
|
* - use a message filter callback routine.
|
|
*
|
|
* @author HTACG, et al (consult git log)
|
|
*
|
|
* @copyright
|
|
* Copyright (c) 1998-2017 World Wide Web Consortium (Massachusetts
|
|
* Institute of Technology, European Research Consortium for Informatics
|
|
* and Mathematics, Keio University) and HTACG.
|
|
* @par
|
|
* All Rights Reserved.
|
|
* @par
|
|
* See `tidy.h` for the complete license.
|
|
*
|
|
* @date Additional updates: consult git log
|
|
*
|
|
******************************************************************************/
|
|
|
|
#include "forward.h"
|
|
#include "config.h"
|
|
|
|
/** @addtogroup internal_api */
|
|
/** @{ */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_releaseinfo Tidy Release Information
|
|
**
|
|
** These functions return information about the current release version date
|
|
** and version number. Note that the latest release date or the highest
|
|
** version number alone do not guarantee the latest Tidy release, as we may
|
|
** backport important fixes to older releases of Tidy.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Returns the release date of this instance of HTML Tidy.
|
|
*/
|
|
TY_PRIVATE ctmbstr TY_(ReleaseDate)(void);
|
|
|
|
/**
|
|
* Returns the release version of this instance of HTML Tidy.
|
|
*/
|
|
TY_PRIVATE ctmbstr TY_(tidyLibraryVersion)(void);
|
|
|
|
|
|
/** @} message_releaseinfo group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_reporting Report and Dialogue Writing Functions
|
|
**
|
|
** These simple functions perform the vast majority of Tidy's output, and
|
|
** one these should be your first choice when adding your own output.
|
|
**
|
|
** A report is typically diagnostic output that is generated each time Tidy
|
|
** detects an issue in your document or makes a change. A dialogue is a piece
|
|
** of information such as a summary, a footnote, or other non-tabular data.
|
|
** Some of these functions emit multiple reports or dialogue in order to
|
|
** effect a summary.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/** @name General Report Writing
|
|
** If one of the convenience reporting functions does not fit your required
|
|
** message signature, then this designated reporting function will fit the
|
|
** bill. Be sure to see if a message formatter exists that can handle the
|
|
** variable arguments.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* The designated report writing function. When a proper formatter exists,
|
|
* this one function can handle all report output.
|
|
*/
|
|
TY_PRIVATE void TY_(Report)(TidyDocImpl* doc, Node *element, Node *node, uint code, ...);
|
|
|
|
|
|
/** @} */
|
|
/** @name Convenience Reporting Functions
|
|
** These convenience reporting functions are able to handle the bulk of Tidy's
|
|
** necessary reporting, and avoid the danger of using a variadic if you are
|
|
** unfamiliar with Tidy.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
TY_PRIVATE void TY_(ReportAccessError)( TidyDocImpl* doc, Node* node, uint code );
|
|
TY_PRIVATE void TY_(ReportAttrError)(TidyDocImpl* doc, Node *node, AttVal *av, uint code);
|
|
TY_PRIVATE void TY_(ReportBadArgument)( TidyDocImpl* doc, ctmbstr option );
|
|
TY_PRIVATE void TY_(ReportEntityError)( TidyDocImpl* doc, uint code, ctmbstr entity, int c );
|
|
TY_PRIVATE void TY_(ReportFileError)( TidyDocImpl* doc, ctmbstr file, uint code );
|
|
TY_PRIVATE void TY_(ReportEncodingError)(TidyDocImpl* doc, uint code, uint c, Bool discarded);
|
|
TY_PRIVATE void TY_(ReportEncodingWarning)(TidyDocImpl* doc, uint code, uint encoding);
|
|
TY_PRIVATE void TY_(ReportMissingAttr)( TidyDocImpl* doc, Node* node, ctmbstr name );
|
|
TY_PRIVATE void TY_(ReportSurrogateError)(TidyDocImpl* doc, uint code, uint c1, uint c2);
|
|
TY_PRIVATE void TY_(ReportUnknownOption)( TidyDocImpl* doc, ctmbstr option );
|
|
|
|
|
|
/** @} */
|
|
/** @name General Dialogue Writing
|
|
** These functions produce dialogue output such as individual messages, or
|
|
** several messages in summary form.
|
|
*/
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* Emits a single dialogue message, and is capable of accepting a variadic
|
|
* that is passed to the correct message formatter as needed.
|
|
*/
|
|
TY_PRIVATE void TY_(Dialogue)( TidyDocImpl* doc, uint code, ... );
|
|
|
|
|
|
/** @} */
|
|
/** @name Output Dialogue Information */
|
|
/** @{ */
|
|
|
|
|
|
/**
|
|
* Outputs the footnotes and other dialogue information after document cleanup
|
|
* is complete. LibTidy users might consider capturing these individually in
|
|
* the message callback rather than capturing this entire buffer.
|
|
* Called by `tidyErrorSummary()`, in console.
|
|
* @todo: This name is a bit misleading and should probably be renamed to
|
|
* indicate its focus on printing footnotes.
|
|
*/
|
|
TY_PRIVATE void TY_(ErrorSummary)( TidyDocImpl* doc );
|
|
|
|
|
|
/**
|
|
* Outputs document HTML version and version-related information as the final
|
|
* report(s) in the report table.
|
|
* Called by `tidyRunDiagnostics()`, from console.
|
|
* Called by `tidyDocReportDoctype()`, currently unused.
|
|
*/
|
|
TY_PRIVATE void TY_(ReportMarkupVersion)( TidyDocImpl* doc );
|
|
|
|
|
|
/**
|
|
* Reports the number of warnings and errors found in the document as dialogue
|
|
* information.
|
|
* Called by `tidyRunDiagnostics()`, from console.
|
|
*/
|
|
TY_PRIVATE void TY_(ReportNumWarnings)( TidyDocImpl* doc );
|
|
|
|
|
|
/** @} */
|
|
/** @} message_reporting group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_mutinging Message Muting
|
|
**
|
|
** Message types included in the `mute` option will be be printed in
|
|
** messageOut().
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/** Maintains a list of messages not to display. */
|
|
typedef struct _mutedMessages {
|
|
tidyStrings* list; /**< A list of messages that won't be output. */
|
|
uint count; /**< Current count of the list. */
|
|
uint capacity; /**< Current capacity of the list. */
|
|
} TidyMutedMessages;
|
|
|
|
|
|
/** Frees the list of muted messages.
|
|
** @param doc The Tidy document.
|
|
*/
|
|
TY_PRIVATE void TY_(FreeMutedMessageList)( TidyDocImpl* doc );
|
|
|
|
/** Adds a new message ID to the list of muted messages.
|
|
** @param doc The Tidy document.
|
|
** @param opt The option that is defining the muted message.
|
|
** @param name The message code as a string.
|
|
*/
|
|
TY_PRIVATE void TY_(DefineMutedMessage)( TidyDocImpl* doc, const TidyOptionImpl* opt, ctmbstr name );
|
|
|
|
/** Start an iterator for muted messages.
|
|
** @param doc The Tidy document.
|
|
** @returns Returns an iterator token.
|
|
*/
|
|
TY_PRIVATE TidyIterator TY_(getMutedMessageList)( TidyDocImpl* doc );
|
|
|
|
/** Get the next priority attribute.
|
|
** @param doc The Tidy document.
|
|
** @param iter The iterator token.
|
|
** @returns The next priority attribute.
|
|
*/
|
|
TY_PRIVATE ctmbstr TY_(getNextMutedMessage)( TidyDocImpl* doc, TidyIterator* iter );
|
|
|
|
|
|
/** @} message_muting group */
|
|
|
|
|
|
/***************************************************************************//**
|
|
** @defgroup message_keydiscovery Key Discovery
|
|
**
|
|
** LibTidy users may want to use `TidyReportCallback` to enable their own
|
|
** localization lookup features. Because Tidy's report codes are enums the
|
|
** specific values can change over time. Using these functions provides the
|
|
** ability for LibTidy users to use LibTidy's enum values as strings for
|
|
** lookup purposes.
|
|
**
|
|
** @{
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* This function returns a string representing the enum value name that can
|
|
* be used as a lookup key independent of changing string values.
|
|
* `TidyReportCallback` will return this general string as the report
|
|
* message key.
|
|
*/
|
|
TY_PRIVATE ctmbstr TY_(tidyErrorCodeAsKey)(uint code);
|
|
|
|
/**
|
|
* Given an error code string, return the integer value of it, or UINT_MAX
|
|
* as an error flag.
|
|
*/
|
|
TY_PRIVATE uint TY_(tidyErrorCodeFromKey)(ctmbstr code);
|
|
|
|
|
|
/**
|
|
* Initializes the TidyIterator to point to the first item
|
|
* in Tidy's list of error codes that can be return with
|
|
* `TidyReportFilter3`.
|
|
* Items can be retrieved with getNextErrorCode();
|
|
*/
|
|
TY_PRIVATE TidyIterator TY_(getErrorCodeList)(void);
|
|
|
|
/**
|
|
* Returns the next error code having initialized the iterator
|
|
* with `getErrorCodeList()`. You can use tidyErrorCodeAsKey
|
|
* to determine the key for this value.
|
|
*/
|
|
TY_PRIVATE uint TY_(getNextErrorCode)( TidyIterator* iter );
|
|
|
|
|
|
/** @} message_keydiscovery group */
|
|
/** @} internal_api addtogroup */
|
|
|
|
|
|
|
|
/* accessibility flaws */
|
|
|
|
#define BA_MISSING_IMAGE_ALT 1
|
|
#define BA_MISSING_LINK_ALT 2
|
|
#define BA_MISSING_SUMMARY 4
|
|
#define BA_MISSING_IMAGE_MAP 8
|
|
#define BA_USING_FRAMES 16
|
|
#define BA_USING_NOFRAMES 32
|
|
#define BA_INVALID_LINK_NOFRAMES 64 /* WAI [6.5.1.4] */
|
|
#define BA_WAI (1 << 31)
|
|
|
|
/* presentation flaws */
|
|
|
|
#define USING_SPACER 1
|
|
#define USING_LAYER 2
|
|
#define USING_NOBR 4
|
|
#define USING_FONT 8
|
|
#define USING_BODY 16
|
|
|
|
/* badchar bit field */
|
|
|
|
#define BC_VENDOR_SPECIFIC_CHARS 1
|
|
#define BC_INVALID_SGML_CHARS 2
|
|
#define BC_INVALID_UTF8 4
|
|
#define BC_INVALID_UTF16 8
|
|
#define BC_ENCODING_MISMATCH 16 /* fatal error */
|
|
#define BC_INVALID_URI 32
|
|
#define BC_INVALID_NCR 64
|
|
|
|
/* other footnote bit field (temporary until formalized) */
|
|
|
|
#define FN_TRIM_EMPTY_ELEMENT 1
|
|
|
|
/* Lexer and I/O Macros */
|
|
|
|
#define REPLACED_CHAR 0
|
|
#define DISCARDED_CHAR 1
|
|
|
|
|
|
#endif /* __MESSAGE_H__ */
|