HTML Tidy  5.7.0
The HTACG Tidy HTML Project
messageobj.h
Go to the documentation of this file.
1 #ifndef messageobj_h
2 #define messageobj_h
3 
4 /**************************************************************************//**
5  * @file
6  * Provides an external, extensible API for message reporting.
7  *
8  * This module implements the `_TidyMessageImpl` structure (declared in
9  * `tidy-int.h`) in order to abstract the reporting of reports and dialogue
10  * from the rest of Tidy, and to enable a robust and extensible API for
11  * message interrogation by LibTidy users.
12  *
13  * @author Jim Derry
14  * @copyright Copyright (c) 2017 HTACG. See tidy.h for license.
15  * @date Created 2017-March-10
16  *
17  ******************************************************************************/
18 
19 #include "forward.h"
20 
21 /** @addtogroup internal_api */
22 /** @{ */
23 
24 
25 /** @defgroup messageobj_instantiation Message Creation and Releasing */
26 /** @{ */
27 
28 
29 /** Creates a TidyMessageImpl, but without line numbers, such as used for
30  ** information report output.
31  */
32 TidyMessageImpl *TY_(tidyMessageCreate)( TidyDocImpl *doc,
33  uint code,
34  TidyReportLevel level,
35  ... );
36 
37 /** Creates a TidyMessageImpl, using the line and column from the provided
38  ** Node as the message position source.
39  */
40 TidyMessageImpl *TY_(tidyMessageCreateWithNode)( TidyDocImpl *doc,
41  Node *node,
42  uint code,
43  TidyReportLevel level,
44  ... );
45 
46 /** Creates a TidyMessageImpl, using the line and column from the provided
47  ** document's Lexer as the message position source.
48  */
49 TidyMessageImpl *TY_(tidyMessageCreateWithLexer)( TidyDocImpl *doc,
50  uint code,
51  TidyReportLevel level,
52  ... );
53 
54 /** Deallocates a TidyMessageImpl in order to free up its allocated memory
55  ** when you're done using it.
56  */
57 void TY_(tidyMessageRelease)( TidyMessageImpl *message );
58 
59 
60 /** @} end messageobj_instantiation group */
61 /** @defgroup messageobj_message_api Report and Dialogue API */
62 /** @{ */
63 
64 
65 /** get the document the message came from. */
66 TidyDocImpl* TY_(getMessageDoc)( TidyMessageImpl message );
67 
68 /** get the message key code. */
69 uint TY_(getMessageCode)( TidyMessageImpl message );
70 
71 /** get the message key string. */
72 ctmbstr TY_(getMessageKey)( TidyMessageImpl message );
73 
74 /** get the line number the message applies to. */
75 int TY_(getMessageLine)( TidyMessageImpl message );
76 
77 /** get the column the message applies to. */
78 int TY_(getMessageColumn)( TidyMessageImpl message );
79 
80 /** get the TidyReportLevel of the message. */
81 TidyReportLevel TY_(getMessageLevel)( TidyMessageImpl message );
82 
83 /** get whether or not the message was muted by the configuration. */
84 Bool TY_(getMessageIsMuted)( TidyMessageImpl message );
85 
86 /** the built-in format string */
87 ctmbstr TY_(getMessageFormatDefault)( TidyMessageImpl message );
88 
89 /** the localized format string */
90 ctmbstr TY_(getMessageFormat)( TidyMessageImpl message );
91 
92 /** the message, formatted, default language */
93 ctmbstr TY_(getMessageDefault)( TidyMessageImpl message );
94 
95 /** the message, formatted, localized */
96 ctmbstr TY_(getMessage)( TidyMessageImpl message );
97 
98 /** the position part, default language */
99 ctmbstr TY_(getMessagePosDefault)( TidyMessageImpl message );
100 
101 /** the position part, localized */
102 ctmbstr TY_(getMessagePos)( TidyMessageImpl message );
103 
104 /** the prefix part, default language */
105 ctmbstr TY_(getMessagePrefixDefault)( TidyMessageImpl message );
106 
107 /** the prefix part, localized */
108 ctmbstr TY_(getMessagePrefix)( TidyMessageImpl message );
109 
110 /** the complete message, as would be output in the CLI */
111 ctmbstr TY_(getMessageOutputDefault)( TidyMessageImpl message );
112 
113 /* the complete message, as would be output in the CLI, localized */
114 ctmbstr TY_(getMessageOutput)( TidyMessageImpl message );
115 
116 
117 /** @} end messageobj_message_api group */
118 /** @defgroup messageobj_args_api Report Arguments Interrogation API */
119 /** @{ */
120 
121 /**
122  * Initializes the TidyIterator to point to the first item in the message's
123  * argument. Use `TY_(getNextMEssageArgument)` to get an opaque instance of
124  * `TidyMessageArgument` for which the subsequent interrogators will be of use.
125  */
126 TidyIterator TY_(getMessageArguments)( TidyMessageImpl message );
127 
128 /**
129  * Returns the next `TidyMessageArgument`, for the given message, which can
130  * then be interrogated with the API, and advances the iterator.
131  */
132 TidyMessageArgument TY_(getNextMessageArgument)( TidyMessageImpl message, TidyIterator* iter );
133 
134 
135 /**
136  * Returns the `TidyFormatParameterType` of the given message argument.
137  */
138 TidyFormatParameterType TY_(getArgType)( TidyMessageImpl message, TidyMessageArgument* arg );
139 
140 
141 /**
142  * Returns the format specifier of the given message argument. The memory for
143  * this string is cleared upon termination of the callback, so do be sure to
144  * make your own copy.
145  */
146 ctmbstr TY_(getArgFormat)( TidyMessageImpl message, TidyMessageArgument* arg );
147 
148 
149 /**
150  * Returns the string value of the given message argument. An assertion
151  * will be generated if the argument type is not a string.
152  */
153 ctmbstr TY_(getArgValueString)( TidyMessageImpl message, TidyMessageArgument* arg );
154 
155 
156 /**
157  * Returns the unsigned integer value of the given message argument. An
158  * assertion will be generated if the argument type is not an unsigned
159  * integer.
160  */
161 uint TY_(getArgValueUInt)( TidyMessageImpl message, TidyMessageArgument* arg );
162 
163 
164 /**
165  * Returns the integer value of the given message argument. An assertion
166  * will be generated if the argument type is not an integer.
167  */
168 int TY_(getArgValueInt)( TidyMessageImpl message, TidyMessageArgument* arg );
169 
170 
171 /**
172  * Returns the double value of the given message argument. An assertion
173  * will be generated if the argument type is not a double.
174  */
175 double TY_(getArgValueDouble)( TidyMessageImpl message, TidyMessageArgument* arg );
176 
177 
178 /** @} end messageobj_args_api group */
179 /** @} end internal_api group */
180 
181 #endif /* messageobj_h */
TidyReportLevel
Message severity level, used throughout LibTidy to indicate the severity or status of a message...
Definition: tidyenum.h:1375
const tmbchar * ctmbstr
Definition: tidyplatform.h:594
Bool
Definition: tidyplatform.h:631
TidyFormatParameterType
Indicates the data type of a format string parameter used when Tidy emits reports and dialogue as par...
Definition: tidyenum.h:1395
unsigned int uint
Definition: tidyplatform.h:554
Instances of this type represent the arguments that compose part of the message represented by TidyMe...
#define TY_(str)
Definition: forward.h:23